Skip to contents

Latent-factor (reduced-rank) random effect: latent(0 + trait | g, d = K)

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

Canonical name for a reduced-rank latent-factor random effect at a grouping g. Formerly rr(0 + trait | g, d = K) – same engine, new name. The "rr" alias still works for backward compat but emits a one-shot deprecation warning per session.

Usage

latent(formula, d = 1, unique = TRUE, common = FALSE, lv = NULL)

Arguments

formula

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

d

Integer; number of latent factors.

unique

Logical; TRUE (default) auto-includes the diagonal trait-specific \(\boldsymbol\Psi\) companion (\(\boldsymbol\Sigma = \boldsymbol\Lambda\boldsymbol\Lambda^\top + \boldsymbol\Psi\)). Set FALSE for the loadings-only / rotation-invariant subset. The former argument name residual is retained as a soft-deprecated alias.

common

Logical; FALSE (default) estimates one diagonal \(\boldsymbol\Psi\) variance per trait. TRUE ties the default ordinary diagonal \(\boldsymbol\Psi\) companion to one shared variance across traits. Only applies when unique = TRUE.

lv

One-sided formula for predictor-informed latent-score means. Runtime support is limited to ordinary unit-tier latent(..., lv = ~ x), and only Gaussian and pure binomial (logit/probit/cloglog) fits are currently admitted (partial coverage, supported for the ordinary-latent case). Source-specific *_latent(..., lv = ~ x) forms are parsed and then fail loud (not yet fittable).

Value

A formula marker; never evaluated.

Details

Used inside a gllvmTMB() formula:

value ~ 0 + trait + latent(0 + trait | unit, d = 2)

By default, ordinary latent() now fits the canonical decomposition \(\boldsymbol\Sigma = \boldsymbol\Lambda \boldsymbol\Lambda^\top + \boldsymbol\Psi\), with the diagonal \(\boldsymbol\Psi\) companion included automatically:

value ~ 0 + trait + latent(0 + trait | unit, d = 2)

Set unique = FALSE for the loadings-only subset. For a scalar diagonal \(\boldsymbol\Psi\) companion shared across traits, use common = TRUE; this replaces the older two-term spelling for ordinary intercept-only latent terms.

See also

indep(), phylo_latent(), diag_re, extract_Sigma().

Examples

if (FALSE) { # \dontrun{
# Long-format stacked traits: a 2-factor latent random effect at `site`.
# Ordinary latent() carries its diagonal Psi by default
# (Sigma = Lambda Lambda^T + diag(psi)).
df <- simulate_site_trait(
  n_sites = 30, n_species = 4, n_traits = 4,
  mean_species_per_site = 4, seed = 42
)$data
fit <- gllvmTMB(
  value ~ 0 + trait + latent(0 + trait | site, d = 2),
  data = df, unit = "site"
)
extract_Sigma(fit)
} # }