Compare several lambda_constraint suggestions — suggest_lambda

Runs suggest_lambda_constraint() under several conventions and returns a compact comparison table. This is the convenience layer for exploratory loading workflows where the analyst wants to see the cheap point-threshold suggestion beside uncertainty-aware Wald or profile-retention suggestions before choosing the matrix to pass to lambda_constraint.

Usage

suggest_lambda_constraints(
  fit_or_formula,
  data = NULL,
  level = "unit",
  methods = c("varimax_threshold", "wald_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.

methods

Character vector of conventions to run. Accepted values are the same as the convention argument of suggest_lambda_constraint().

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 of class gllvmTMB_lambda_constraint_suggestions with:

summary: A data frame with one row per method and columns for decision basis, cost, number of pinned/free entries, and the helper note.
suggestions: A named list of the full suggest_lambda_constraint() return objects, one per method.
recommended_method: The highest-evidence method among the requested methods. By default this is "wald_retention"; if "profile_retention" is requested, it is recommended because it uses likelihood-ratio refits rather than the baseline Hessian.
recommended: The full suggestion object for recommended_method.

Details

The default compares varimax_threshold and wald_retention. Add "profile_retention" to methods when you want the likelihood-ratio version; it is slower because it refits once per testable loading entry.

Examples

if (FALSE) { # \dontrun{
cmp <- suggest_lambda_constraints(
  fit,
  methods = c("varimax_threshold", "wald_retention"),
  threshold = 0.30,
  retention_prob = 0.90
)
cmp$summary
fit_con <- gllvmTMB(
  value ~ 0 + trait + latent(0 + trait | site, d = 2),
  data = df,
  family = binomial(),
  lambda_constraint = list(unit = cmp$recommended$constraint)
)

# Expensive: one likelihood-ratio refit per testable loading.
cmp_profile <- suggest_lambda_constraints(
  fit,
  methods = "profile_retention"
)
} # }