Suggest a lambda_constraint matrix for a reduced-rank fit

Produces a default constraint matrix M for the reduced-rank loadings Lambda in a fit returned by gllvmTMB() or in a formula-data pair that will be passed to gllvmTMB(). The matrix is returned in the format expected by the lambda_constraint argument: NA in free entries, numeric values in pinned entries.

Usage

suggest_lambda_constraint(
  fit_or_formula,
  data = NULL,
  level = "unit",
  convention = c("lower_triangular", "pin_top_one", "none", "varimax_threshold",
    "wald_retention", "profile_retention"),
  trait = "trait",
  unit = "site",
  threshold = 0.3,
  retention_prob = 0.9,
  sigma_d2 = 1,
  site = NULL
)

Arguments

fit_or_formula

Either a fitted multivariate model returned by gllvmTMB() or a formula. If a formula, data must also be supplied.

data

A data frame. Required when fit_or_formula is a formula; ignored when it is a fit.

level

Which loading matrix to constrain: "unit" (between-unit, default) or "unit_obs" (within-unit). Deprecated aliases "B" and "W" are still accepted with a warning.

convention

One of:

"lower_triangular" (default)

Pin every upper-triangular entry to 0, i.e. M[i, j] = 0 for j > i. Removes the rotational ambiguity completely. Pins K(K-1)/2 entries.

"pin_top_one"

Single-anchor convention: M[1, 1] = 1, rest NA. Sets the scale of factor 1; does NOT remove rotational ambiguity.

"none"

All-NA matrix – no pins. Useful if you plan to rotate the fitted loadings after fitting instead.

trait, unit

Name of the trait and unit (site) columns. Forwarded when fit_or_formula is a formula and the data does not already use defaults.

threshold

Salience threshold on the standardised loading \(\rho = \Lambda / \sqrt{\Lambda^2 + \sigma_d^2}\). Used by "varimax_threshold" and "wald_retention". Comrey-Lee 1992 convention: 0.30 = "fair" salience (default). Raise to 0.40 for "good" / 0.50 for "very good".

retention_prob

Retention probability for "wald_retention" and "profile_retention":

• "wald_retention": pin entry if Pr(|Lambda| > threshold) < retention_prob.

• "profile_retention": pin entry if a profile LRT fails to reject H0: Lambda = 0 at significance level 1 - retention_prob.

Default 0.90 follows the applied-EFA bootstrap convention; the stricter BSEM 0.95 often over-prunes at moderate sample sizes and produces non-PD refits.

sigma_d2

Link-implicit residual variance on the link scale, used by "wald_retention" to compute Pr(|Lambda| > threshold) from the standardised \(\rho\). Defaults to 1 (probit / ordinal_probit). Use \(\pi^2/3\) for logit, \(\pi^2/6\) for cloglog, or the fitted residual variance for Gaussian.

site

Deprecated alias for unit. Emits a one-shot warning and maps to unit.

Value

A list with components:

constraint

A T x K matrix with NA in free entries and 0 (or 1, for "pin_top_one") in pinned entries. Has trait names as rownames and "f1", ..., "fK" as colnames.

convention

The chosen convention.

d

The number of factors K.

n_pins

Number of pinned entries.

note

A short explanation of what was pinned and why.

usage_hint

An example call as a string showing how to use the returned matrix with gllvmTMB().

Examples

if (FALSE) { # \dontrun{
sug <- suggest_lambda_constraint(
  value ~ 0 + trait + latent(0 + trait | site, d = 2),
  data = my_data
)
fit <- gllvmTMB(
  value ~ 0 + trait + latent(0 + trait | site, d = 2),
  data              = my_data,
  trait             = "trait",
  unit              = "site",
  lambda_constraint = list(unit = sug$constraint)
)
} # }