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, A = NULL, Ainv = NULL, rho = 1)

Arguments

formula

0 + trait | species style formula, an admitted intercept-and-slope form, or the Gaussian slope-only response-column form 0 + x1 + ... | trait.

tree

An ape::phylo object. Canonical.

vcv

A tip-only phylogenetic correlation matrix (n_species x n_species). Legacy alias of A =.

A

Tip-level relatedness matrix (n_species x n_species) – alias of vcv =, aligned with the animal_* family's argument naming.

Ainv

Sparse precision matrix (inverse of A).

rho

Source strength: a number in [0,1] fixes rho * K + (1-rho) * diag(diag(K)) on the legacy-resolved source scale. Omitted or explicit 1 preserves the existing model. NULL estimates strength for one Gaussian structured trait-intercept block with complete replicated multivariate observations and no competing ordinary covariance. Estimated latent terms require rank one and at least four traits. The same strength applies to the entire latent-plus-Psi covariance. This parameter is not a variance-share summary. Fixed attenuation and the admitted Gaussian estimator have implementation checks; recovery is regime-specific.

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(..., unique = TRUE) for the rank-reduced paired phylogenetic decomposition. Use phylo_indep() for the marginal-only per-trait variance fit.

Slope-only response-column form

In a Gaussian long-format model, phylo_dep(0 + lat + temp | trait) gives response-column slope deviations with a full positive-definite covariance among predictors. Fixed column intercepts remain 0 + trait in the main formula; this term never adds a random intercept. Retrieve the predictor covariance with extract_Sigma(fit, level = "column_slope"). Use phylo_indep() for a diagonal predictor covariance. The helper phylo_slope(lat + temp | trait) is an alias for this full route.

Mutual exclusion with phylo_latent() / phylo_indep()

Combining phylo_dep(0 + trait | species) with phylo_latent is over-parameterised; combining with 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_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,
    trait      = "trait",
    unit       = "species",
    cluster    = "species",
    phylo_tree = tree
  )
} # }