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

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). Registered native family/link rows compose in one complete-response ordinary unit-tier block. The loadings-only unique = FALSE form admits ranks through the number of logical responses; automatic Psi additionally requires that its physical loading, latent-predictor, and engine-free diagonal parameters pass a necessary joint mean-covariance dimension screen. Passing that screen is not a recovery or interval-calibration certificate. Bounded rank-2/rank-3 checks exercise every supported family, but broad composition recovery and interval calibration remain partial. Retained recovery and interval claims remain limited to their named cells. Source-specific *_latent(..., lv = ~ x) forms are parsed and then fail loud (not yet fittable). Where it is admitted, the fit is experimental and exploratory: extract the coefficients with extract_lv_effects(), whose default type = "axis_effect" output is rotation-dependent (an intrinsic latent-axis indeterminacy, not a defect – see extract_lv_effects() for the rotation-invariant type = "trait_effect" alternative). Repeated-sampling interval evidence is cell-specific; do not infer an interval claim for the mixed-response programme from its point-recovery evidence.

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(), extract_lv_effects() for predictor-informed latent-score coefficients.

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)
} # }