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 = n_traits, unique = FALSE) 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 by default)

Shared low-rank loadings plus the default trait-specific Psi companion: \(\boldsymbol\Sigma = \boldsymbol\Lambda \boldsymbol\Lambda^\top + \boldsymbol\Psi\). \(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. This is a standard multivariate response covariance 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(), indep(), phylo_dep(), spatial_dep(), extract_Sigma().

Examples

# Three traits on 40 units (3 replicate observations per unit); the
# between-unit trait covariance is rank one plus a diagonal.
sim <- simulate_unit_trait(
  n_units = 40, n_obs_per_unit = 3, n_traits = 3,
  Lambda_B = matrix(c(0.9, 0.5, -0.4), ncol = 1),
  psi_B = c(0.2, 0.2, 0.2), seed = 1
)
df <- sim$data
n_traits <- nlevels(df$trait)

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

# The mathematically equivalent decomposition: a full-rank,
# loadings-only latent term reaches the same log-likelihood.
fit_lat <- gllvmTMB(
  value ~ 0 + trait + latent(0 + trait | unit, d = n_traits, unique = FALSE),
  data = df, trait = "trait", unit = "unit"
)
c(dep = logLik(fit), latent = logLik(fit_lat))
#>       dep    latent 
#> -469.7462 -469.7462 
# }

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