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

# Three traits on 50 units with trait-specific between-unit variances
# and no between-unit trait correlation.
sim <- simulate_unit_trait(
  n_units = 50, n_obs_per_unit = 3, n_traits = 3,
  psi_B = c(0.8, 0.5, 0.3), seed = 1
)
df <- sim$data

# \donttest{
# Marginal-only fit (per-trait variance, identity correlation):
fit <- gllvmTMB(value ~ 0 + trait + indep(0 + trait | unit),
                data = df, trait = "trait", unit = "unit")
extract_Sigma(fit)$Sigma
#>           trait_1   trait_2   trait_3
#> trait_1 0.5539444 0.0000000 0.0000000
#> trait_2 0.0000000 0.3447209 0.0000000
#> trait_3 0.0000000 0.0000000 0.2015235

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

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