Skip to contents

Reduced-rank phylogenetic latent factors: phylo_latent(species, d = K)

Source: R/brms-sugar.R
phylo_latent.Rd

Canonical name for the reduced-rank phylogenetic random effect. Formerly phylo_rr(species, d = K) – same engine, new name.

Usage

phylo_latent(species, d = 1, tree = NULL, vcv = NULL)

Arguments

species

Unquoted column name for the species factor.

d

Integer; number of phylogenetic latent factors.

tree

An ape::phylo object. Canonical. Use this if you have a tree.

vcv

A tip-only phylogenetic correlation matrix (n_species x n_species). Legacy / superseded.

Value

A formula marker; never evaluated.

Details

Two phylogeny inputs: tree = (canonical) and vcv = (legacy)

Pass the phylogeny inside the keyword via one of two arguments:

  • tree = phylo (canonical, recommended) – the full ape::phylo object. Triggers the sparse \(\mathbf{A}^{-1}\) path (Hadfield & Nakagawa 2010, appendix eqs. 26-29) which scales linearly in n_species. About 24x faster than the dense path at n_species = 1000 on the published benchmark.

  • vcv = Cphy ([Superseded]) – a tip-only n_species x n_species correlation matrix. Forces the dense O(n^2) memory / O(n^3) Cholesky path. Provided for users who have a Cphy in hand and no Newick tree (e.g. comparing against nlme::corPagel); soft deprecation in 0.2.0.

Both arguments give the same MLE – they differ only in computational cost. Internal-node ancestral states are estimated as latent random effects on the sparse path; on the dense path only tip-level loadings are estimated.

See vignette("phylogenetic-gllvm") for the benchmark and dev/design/01-phylo-api-canonical-tree.md for the technical justification.

References

Hadfield JD, Nakagawa S (2010). General quantitative genetic methods for comparative biology: phylogenies, taxonomies and multi-trait models for continuous and categorical characters. J. Evol. Biol. 23: 494-508. doi:10.1111/j.1420-9101.2009.01915.x

See also

phylo_scalar(), phylo_unique(), phylo_indep(), phylo_dep(), phylo_rr() (deprecated alias).

Examples

if (FALSE) { # \dontrun{
  tree <- ape::rcoal(20); tree$tip.label <- paste0("sp", seq_len(20))
  sim <- simulate_site_trait(
    n_sites = 1, n_species = 20, n_traits = 4,
    mean_species_per_site = 20,
    Cphy = ape::vcv(tree, corr = TRUE),
    sigma2_phy = rep(0.3, 4), seed = 1
  )
  sim$data$species <- factor(sim$data$species, levels = tree$tip.label)
  fit <- gllvmTMB(
    value ~ 0 + trait + phylo_latent(species, d = 2),
    data = sim$data, phylo_tree = tree
  )
} # }