Phylogenetic correlation matrix from a tree

Convert a phylogeny into the correlation matrix used as a random- effect structure in phylogenetic meta-analysis (metafor::rma.mv) or phylogenetic mixed models (MCMCglmm, brms, etc.).

Usage

pr_phylo_cor(x, corr = TRUE, ...)

Arguments

x

A phylo object, a multiPhylo, or a pr_tree_result (the $tree slot is extracted). For multiPhylo input, returns a list of correlation matrices.

corr

Logical. Pass through to ape::vcv(). TRUE (default) returns a correlation matrix (diagonal = 1); FALSE returns the variance-covariance matrix.

...

Additional arguments forwarded to ape::vcv().

Value

A square symmetric matrix with row/column names equal to the tip labels. For multiPhylo input, a list of such matrices.

Details

Wraps ape::vcv() with corr = TRUE. Designed to slot in after pr_get_tree() when the goal is meta-analysis, where typically:

1. Topology comes from Open Tree of Life (source = "rotl") because the species span many higher taxa.

2. Polytomies are resolved at random (resolve_polytomies = TRUE).

3. Branch lengths are computed via Grafen's method (branch_lengths = "grafen") because rotl's edge lengths are unit-length placeholders.

4. The correlation matrix is computed once and reused as random = ~1|species's R = list(species = phy_cor) in metafor::rma.mv() (or random = ~species with cov.formula = ~ phylo in MCMCglmm).

The correlation matrix has the property that, for a Brownian-motion model on a tree with branch lengths in time units, two species' off-diagonal entry equals the time from root to their MRCA divided by the time from root to tip. So an ultrametric tree always has diagonal = 1 (every tip is the same distance from the root).

For meta-analysis with rotl topology + Grafen's method, the resulting matrix is the standard Pagel's lambda = 1 phylogenetic correlation that metafor::rma.mv() accepts directly.

References

Paradis, E., & Schliep, K. (2019). ape 5.0: an environment for modern phylogenetics and evolutionary analyses in R. Bioinformatics, 35(3), 526–528. doi:10.1093/bioinformatics/bty633

Cinar, O., Nakagawa, S., & Viechtbauer, W. (2022). Phylogenetic multilevel meta-analysis: a simulation study on the importance of modelling the phylogeny. Methods in Ecology and Evolution, 13(2), 383–395. doi:10.1111/2041-210X.13760

See also

pr_get_tree() (use with branch_lengths = "grafen" and resolve_polytomies = TRUE for the meta-analysis path); ape::vcv() for the underlying computation.

Examples

set.seed(1)
tr <- ape::rcoal(5)             # ultrametric, bifurcating
phy_cor <- pr_phylo_cor(tr)
dim(phy_cor)
#> [1] 5 5
all(diag(phy_cor) == 1)
#> [1] TRUE

# \donttest{
  # End-to-end meta-analysis prep
  if (requireNamespace("rotl", quietly = TRUE)) {
    res <- try(pr_get_tree(c("Homo sapiens", "Pan troglodytes",
                             "Mus musculus", "Rattus norvegicus"),
                           source             = "rotl",
                           resolve_polytomies = TRUE,
                           branch_lengths     = "grafen"),
               silent = TRUE)
    if (!inherits(res, "try-error")) {
      phy_cor <- pr_phylo_cor(res)
      # phy_cor can now be supplied to downstream meta-analysis models.
    }
  }
#> Warning: Dropping singleton nodes with labels: mrcaott42ott30082, Glires ott392220, mrcaott42ott29157, Rodentia ott864593, mrcaott42ott10477, mrcaott42ott38834, mrcaott42ott48903, mrcaott42ott254702, Myomorpha ott7067181, Muroidea ott839752, mrcaott42ott45197, mrcaott42ott55942, mrcaott42ott102, mrcaott102ott739, Muridae ott816256, mrcaott102ott283439, mrcaott102ott38119, mrcaott102ott125766, mrcaott102ott456651, mrcaott102ott1729, mrcaott102ott23039, mrcaott102ott289304, mrcaott102ott185328, mrcaott102ott542525, mrcaott102ott348560, mrcaott102ott542521, mrcaott102ott321218, mrcaott8118ott211375, mrcaott8118ott606407, mrcaott8118ott993024, mrcaott8118ott106790, mrcaott8118ott366063, mrcaott8118ott167547, mrcaott8118ott106786, mrcaott8118ott92106, mrcaott92106ott577539, mrcaott92106ott182319, Primatomorpha ott6520519, Primates ott913935, mrcaott786ott3428, Haplorrhini ott702152, Simiiformes ott386195, Catarrhini ott842867, mrcaott786ott3607729, mrcaott786ott83926, mrcaott83926ott3607702, mrcaott83926ott96938, mrcaott83926ott6145147, mrcaott83926ott3607728, mrcaott83926ott770295, mrcaott83926ott3607876, mrcaott83926ott3607873, Homininae ott312031, mrcaott83926ott3607687, mrcaott83926ott3607716, mrcaott83926ott3607689, mrcaott83926ott3607732, Homo ott770309, mrcaott83926ott3607678, mrcaott83926ott3607671, mrcaott83926ott3607681, mrcaott83926ott3607676, Pan ott417957
# }