Skip to contents

Full unstructured trait covariance: dep(0 + trait | g)

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

Canonical name for the always-alone full-unstructured trait covariance term. Fits a full \(T \times T\) \(\boldsymbol\Sigma\) with \(T(T+1)/2\) free parameters via a Cholesky parameterisation \(\boldsymbol\Sigma = \mathbf{L}\mathbf{L}^\top\). Mathematically identical to latent(0 + trait | g, d = T) standalone (where \(T\) is the number of traits) — the engine's existing packed-triangular \(\boldsymbol\Lambda\) at full rank IS the Cholesky factor of an unstructured \(\boldsymbol\Sigma\). The keyword choice is documentary: dep declares user intent that the full unstructured trait covariance is the model.

Usage

dep(formula)

Arguments

formula

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

Value

A formula marker; never evaluated.

Details

This completes the structural-mode quartet:

Decomposition (latent + unique)

Shared low-rank loadings plus trait-specific residual: \(\boldsymbol\Sigma = \boldsymbol\Lambda \boldsymbol\Lambda^\top + \mathbf S\). \(TK + T\) parameters (rotation-removed).

Marginal (indep standalone)

Per-trait variance with identity correlation: \(\boldsymbol\Sigma = \mathrm{diag}(\sigma^2_t)\). \(T\) parameters.

Full / unstructured (dep standalone)

Free unstructured \(\boldsymbol\Sigma\), PSD via Cholesky. \(T(T+1)/2\) parameters.

Use dep() when you want to commit to the full unstructured interpretation explicitly. Maintainer's framing: this is just a standard multivariate response model. Computational scope: tractable for \(T \le \sim 30\) with the default optimiser; for larger \(T\), prefer latent(d = K) with \(K \ll T\) as the rank-reduced approximation.

Mutual exclusion

Combining dep(0 + trait | g) with latent(0 + trait | g, d = K) on the same grouping is over-parameterised. Combining dep with unique or indep on the same grouping is redundant (dep standalone already includes the trait-level diagonal). The parser raises cli::cli_abort() in any of these cases.

See also

latent(), unique(), indep(), phylo_dep(), spatial_dep(), extract_Sigma().

Examples

if (FALSE) { # \dontrun{
# Full unstructured trait covariance fit:
fit <- gllvmTMB(value ~ 0 + trait + dep(0 + trait | site),
                data = df, unit = "site")

# The mathematically-equivalent decomposition form (full rank):
fit <- gllvmTMB(value ~ 0 + trait + latent(0 + trait | site, d = T),
                data = df, unit = "site")

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