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

if (FALSE) { # \dontrun{
  # End-to-end meta-analysis prep
  res <- pr_get_tree(c("Homo sapiens", "Pan troglodytes",
                       "Mus musculus", "Rattus norvegicus"),
                     source             = "rotl",
                     resolve_polytomies = TRUE,
                     branch_lengths     = "grafen")
  phy_cor <- pr_phylo_cor(res)
  # phy_cor can now be supplied to downstream meta-analysis models.
} # }