Suggest a lambda_constraint matrix for a reduced-rank GLLVM

Produces a sensible default constraint matrix M that resolves the rotational ambiguity of the reduced-rank loadings Lambda in models of the form value ~ 0 + trait + latent(0 + trait | site, d = K) + .... The matrix is returned in the format expected by gllvmTMB()'s lambda_constraint argument: NA in free entries, numeric in pinned entries.

Usage

suggest_lambda_constraint(
  fit_or_formula,
  data = NULL,
  level = c("unit", "unit_obs", "B", "W"),
  convention = c("lower_triangular", "pin_top_one", "none"),
  trait = "trait",
  unit = "site",
  site = NULL
)

Arguments

fit_or_formula

Either a fitted gllvmTMB_multi object 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: "B" (between-site, default) or "W" (within-site).

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 apply post-hoc rotation (e.g. varimax) 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.

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,
  lambda_constraint = list(B = sug$constraint)
)
} # }