Skip to contents

Per-trait marginal variance: indep(0 + trait | g)

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

Canonical name for the always-alone marginal-only per-trait diagonal variance term, producing \(\boldsymbol\Sigma = \mathrm{diag}(\sigma^2_t)\) with identity off-diagonals.

Usage

indep(formula, common = FALSE)

Arguments

formula

0 + trait | g style formula (LHS is the trait factor, typically 0 + trait; RHS is the grouping factor).

common

FALSE (default) for trait-specific marginal variances; TRUE to tie all traits to one shared variance at this grouping tier.

Value

A formula marker; never evaluated.

Details

The package's covstruct API organises around two mutually exclusive modes, distinguished by convention:

Decomposition (latent by default)

Shared cross-trait covariance plus the default trait-specific Psi companion: \(\boldsymbol\Sigma = \boldsymbol\Lambda \boldsymbol\Lambda^\top + \boldsymbol\Psi\).

Marginal (indep standalone)

Per-trait total variance with no cross-trait decomposition: \(\boldsymbol\Sigma = \mathrm{diag}(\sigma^2_t)\).

Use indep() when you want to commit to the marginal-only interpretation explicitly. Ordinary latent() now carries the diagonal Psi companion by default when you want the cross-trait decomposition.

For a scalar marginal-only tier with one variance shared by all traits, use common = TRUE. This is the non-deprecated standalone replacement for the legacy scalar diagonal spelling when no latent() term is paired on the same grouping.

Mutual exclusion with latent()

Combining indep(0 + trait | g) with latent(0 + trait | g, d = K) on the same grouping is over-parameterised (the model cannot decide whether trait variance lives in the shared component or the marginal component). The parser raises a cli::cli_abort() in this case. Combining indep with unique on the same grouping is similarly redundant and also errors.

See also

latent(), phylo_indep(), spatial_indep(), extract_Sigma().

Examples

if (FALSE) { # \dontrun{
# Marginal-only fit (per-trait variance, identity correlation):
fit <- gllvmTMB(value ~ 0 + trait + indep(0 + trait | site),
                data = df, trait = "trait", unit = "site")

# Scalar marginal-only fit (one shared variance across traits):
fit <- gllvmTMB(value ~ 0 + trait + indep(0 + trait | site, common = TRUE),
                data = df, trait = "trait", unit = "site")

# ERROR: indep + latent on the same grouping is over-parameterised.
# gllvmTMB(value ~ 0 + trait +
#           indep(0 + trait | site) +
#           latent(0 + trait | site, d = 2), data = df)
} # }