Skip to contents

Per-trait phylogenetic marginal variance: phylo_indep(0 + trait | species)

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

Canonical name for T per-trait phylogenetic variances coupled by the phylo correlation matrix \(\mathbf A\); standalone = T univariate phylogenetic mixed models stacked.

Usage

phylo_indep(
  formula,
  tree = NULL,
  vcv = NULL,
  A = NULL,
  Ainv = NULL,
  common = FALSE,
  rho = 1
)

Arguments

formula

Intercept-only 0 + trait | species, the supported intercept-and-slope form described above, or the Gaussian long-format 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) for the ordinary forms. For the slope-only response-column form it is instead n_traits x n_traits, with row names matching the resolved RHS trait levels. Legacy alias of A =.

A

Tip-level relatedness matrix (n_species x n_species) for the ordinary forms; for the slope-only response-column form, the corresponding trait-level matrix. Alias of vcv =, aligned with the animal_* family's argument naming.

Ainv

Sparse precision matrix (inverse of A).

common

FALSE (default) for a separate phylogenetic variance per trait; TRUE ties all traits to one shared phylogenetic variance (intercept-only). phylo_indep(0 + trait | species, common = TRUE) is the canonical one-shared-variance spelling and fits the same model as the soft-deprecated phylo_scalar(species).

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

Each trait \(t\) gets its own variance \(\sigma^2_{\text{phy},t}\) on the same phylogenetic correlation matrix \(\mathbf A_{\text{phy}}\); trait-specific random vectors are otherwise independent.

$$\mathbf p_t \sim \mathcal{N}(\mathbf 0,\, \sigma^2_{\text{phy},t}\,\mathbf A_{\text{phy}}), \qquad t = 1, \dots, T.$$

Use phylo_indep() for an explicit marginal-only phylogenetic fit (no cross-trait phylogenetic decomposition). Use phylo_latent(..., unique = TRUE) for the paired phylogenetic decomposition \(\boldsymbol\Sigma_{\text{phy}} = \boldsymbol\Lambda_{\text{phy}}\boldsymbol\Lambda_{\text{phy}}^\top + \boldsymbol\Psi_{\text{phy}}\).

Mutual exclusion with phylo_latent()

Combining phylo_indep(0 + trait | species) with phylo_latent(species, d = K) is over-parameterised and the parser raises a cli::cli_abort().

Intercept-and-slope form

A single-covariate random regression uses phylo_indep(1 + x | species) in wide syntax or phylo_indep(0 + trait + (0 + trait):x | species) in explicit long syntax. It estimates independent trait-specific intercept–slope blocks. The intercept–slope correlation is estimated within each trait; cross-trait blocks are structurally zero.

Slope-only response-column form

For a long-format Gaussian model, phylo_indep(0 + lat + temp | trait) adds response-column deviations to the fixed slopes without adding a random intercept. The phylogeny is indexed by the response-column factor on the right of |; indep makes the covariance among lat and temp slopes diagonal. With slope coefficient matrix \(\mathbf B\) (rows are response columns and columns are predictors), let \(\mathbf b=\mathrm{vec}(\mathbf B^\mathsf{T})\) order coefficients by response column: lat, temp for column 1, then lat, temp for column 2, and so on. Then \(\mathrm{Cov}(\mathbf b) = \mathbf A_{\mathrm{phy}} \otimes \mathrm{diag}(\sigma^2_{\mathrm{lat}}, \sigma^2_{\mathrm{temp}})\). (The native implementation stores the permutation-equivalent column-major vector.) Retrieve that predictor-basis covariance with extract_Sigma(fit, level = "column_slope"). It is not a trait-level \(\boldsymbol\Sigma\). This V1 route requires bare finite numeric predictors, exactly the resolved trait column on the RHS, and Gaussian responses; wide-format and non-Gaussian column slopes are planned work.

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.

References

  • Williams et al. (2025) Phylogenetic generalised linear mixed models for multi-trait comparative analyses. bioRxiv 2025.12.20.695312. The marginal phylo_indep + indep standalone form stacked across traits matches their PGLMM Eq. 3.

See also

phylo_latent(), phylo_dep(), indep(), spatial_indep(), extract_Sigma().

Examples

if (FALSE) { # \dontrun{
library(ape)
tree <- rcoal(20); tree$tip.label <- paste0("sp", 1:20)
fit <- gllvmTMB(value ~ 0 + trait +
                  phylo_indep(0 + trait | species, tree = tree),
                data    = df,
                trait   = "trait",
                unit    = "species",
                cluster = "species")
} # }