PairwiseQuartets()

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: Quartet
-Version: 1.2.7
+Version: 1.3.0
 Title: Comparison of Phylogenetic Trees Using Quartet and Split Measures
 Description: Calculates the number of four-taxon subtrees consistent with a pair
   of cladograms, calculating the symmetric quartet distance of Bandelt & Dress
@@ -46,6 +46,7 @@ Suggests:
   Rcpp,
   rmarkdown,
   testthat,
+  TreeDist,
   usethis,
   vdiffr,
 Config/Needs/check:

NAMESPACE

@@ -36,6 +36,7 @@ export(PairSharedQuartetStatus)
 export(PairSharedSplitStatus)
 export(PairsQuartetDistance)
 export(PairsTripletDistance)
+export(PairwiseQuartets)
 export(PlotQuartet)
 export(QuartetAgreement)
 export(QuartetDistance)

NEWS.md

@@ -1,3 +1,7 @@
+# Quartet v1.3.0 (2025-01-16)
+
+- `PairwiseQuartets()` compares quartet statuses between all pairs of trees.
+
 # Quartet v1.2.7 (2024-10-31)
 
 - `VizualizeQuartet()` now returns calculation results.

Quartet.Rproj

@@ -1,4 +1,5 @@
 Version: 1.0
+ProjectId: 69de0ca2-bd58-49e4-8173-98d3d2d703f4
 
 RestoreWorkspace: Yes
 SaveWorkspace: No

R/PairwiseQuartets.R

@@ -0,0 +1,40 @@
+#' Pairwise quartet distances
+#' 
+#' Computes the quartet distance between each pair of trees in a list.
+#' 
+#' @inheritParams QuartetStatus
+#' @param Measure a function that calculates tree similarity or difference
+#' from quartet statuses. Default is [`QuartetDivergence()`].
+#' @return a matrix specifying the distance between each tree and
+#' each other tree in the `trees`.
+#' 
+#' @template MRS
+#' 
+#' @examples
+#' data("sq_trees")
+#' # Calculate the status of each quartet relative to the first entry in 
+#' # sq_trees
+#' sq_status <- QuartetStatus(sq_trees)
+#' 
+#' # Calculate Estabrook et al's similarity measures:
+#' SimilarityMetrics(sq_status)
+#' 
+#' # Compare trees that include a subset of the taxa 1..10
+#' library("TreeTools", quietly = TRUE, warn.conflict = FALSE)
+#' QuartetStatus(BalancedTree(1:5), BalancedTree(3:8), nTip = 10)
+#' 
+#' # If all taxa studied occur in `trees` or `cf`, set `nTip = TRUE`
+#' QuartetStatus(BalancedTree(1:5), BalancedTree(3:10), nTip = TRUE)
+#'  
+#' @family element-by-element comparisons
+#' @seealso 
+#' - Use splits (groups/clades defined by nodes or edges of the tree) instead
+#'   of quartets as the unit of comparison: [`SplitStatus()`].
+#'  
+#' - Generate distance metrics from quartet statuses: [`SimilarityMetrics()`].
+#' 
+#' @references \insertAllCited{}
+#' @export
+PairwiseQuartets <- function(trees, Measure = QuartetDivergence) {
+  Measure(ManyToManyQuartetAgreement(trees))
+}

R/tqDist.r

@@ -60,7 +60,8 @@
 #' - Use splits (groups/clades defined by nodes or edges of the tree) instead
 #'   of quartets as the unit of comparison: [`SplitStatus()`].
 #'  
-#' - Generate distance metrics from quartet statuses: [`SimilarityMetrics()`].
+#' - Generate distance metrics from quartet statuses: [`SimilarityMetrics()`],
+#' `[PairwiseQuartets()]`.
 #' 
 #' @references \insertAllCited{}
 #'
@@ -249,8 +250,8 @@ ManyToManyQuartetAgreement <- function (trees, nTip = NULL) {
   }
 }
 
-#' @describeIn QuartetStatus Agreement of each quartet in trees in one list with
-#' each quartet in trees in a second list.
+#' @describeIn QuartetStatus Agreement of each quartet in trees in `trees1` with
+#' each quartet in trees in `trees2`.
 #' @param trees1,trees2 List or `multiPhylo` objects containing
 #'   trees of class `phylo`.
 #' @return `TwoListQuartetAgreement()` returns a three-dimensional array listing,

tests/testthat/test-PairwiseQuartets.R

@@ -0,0 +1,6 @@
+test_that("PairwiseQuartets() works", {
+  expect_equal(PairwiseQuartets(sq_trees),
+               QuartetDivergence(ManyToManyQuartetAgreement(sq_trees)))
+  expect_equal(PairwiseQuartets(sq_trees, DoNotConflict),
+               DoNotConflict(ManyToManyQuartetAgreement(sq_trees)))
+})

vignettes/Using-Quartet.Rmd

@@ -131,6 +131,33 @@ status <- TwoListQuartetAgreement(forest[1:4], forest[5:6])
 QuartetDivergence(status, similarity = FALSE)
 ```
 
+## Pairwise comparison
+
+To compute distances between all pairs of trees in a list, use the `PairwiseQuartets()` function:
+
+```{r allpairs}
+PairwiseQuartets(forest)
+# equivalent to QuartetDivergence(ManyToManyQuartetAgreement(forest))
+```
+
+This function can help to summarise sets of trees:
+
+```{r treedist}
+# Map distances between trees
+forestDist <- PairwiseQuartets(forest)
+mapping <- cmdscale(as.dist(forestDist))
+plot(mapping, asp = 1, axes = FALSE, frame.plot = FALSE,
+     xlab = "", ylab = "", col = seq_along(forest), type = "n")
+text(mapping, names(forest))
+
+# The TreeDist library is used to compute the median tree
+if (requireNamespace("TreeDist", quietly = TRUE)) {
+  library("TreeDist")
+  # Plot the median tree:
+  plot(median(forest, distance = PairwiseQuartets))
+}
+```
+
 ## Trees with different tip labels
 
 "Quartet" can compare trees of different sizes or with non-identical sets of