Skip to contents

Full unstructured phylogenetic trait covariance: phylo_dep(0 + trait | species)

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

Canonical name for the full unstructured cross-trait phylogenetic covariance \(\boldsymbol\Sigma_{\text{phy}} \otimes \mathbf{A}\), with \(T(T+1)/2\) free parameters (\(\boldsymbol\Sigma_{\text{phy}}\) parameterised via Cholesky for PSD-ness). Mathematically identical to phylo_latent(species, d = T) standalone; the keyword choice is documentary.

Usage

phylo_dep(formula, tree = NULL, vcv = NULL)

Arguments

formula

0 + trait | species style formula. The LHS must be 0 + trait (the trait factor); the RHS is the species column.

tree

An ape::phylo object. Canonical.

vcv

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

Value

A formula marker; never evaluated.

Details

$$\mathrm{vec}(\mathbf P) \sim \mathcal{N}(\mathbf 0,\, \boldsymbol\Sigma_{\text{phy}} \otimes \mathbf{A}_{\text{phy}}).$$

Use phylo_dep() when you want an explicit full-unstructured cross-trait phylogenetic covariance fit. Use phylo_latent() paired with phylo_unique() for the rank-reduced paired phylogenetic decomposition. Use phylo_indep() for the marginal-only per-trait variance fit.

Mutual exclusion with phylo_latent() / phylo_unique() / phylo_indep()

Combining phylo_dep(0 + trait | species) with phylo_latent is over-parameterised; combining with phylo_unique or phylo_indep is redundant (phylo_dep already includes the diagonal). The parser raises cli::cli_abort() in any of these cases.

Pass the phylogeny via tree = phylo (canonical, sparse \(\mathbf{A}^{-1}\)) or vcv = Cphy ([Superseded], dense). See phylo_latent() for the full discussion of the two paths.

See also

phylo_latent(), phylo_unique(), phylo_indep(), dep(), spatial_dep(), extract_Sigma().

Examples

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