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 = NULL,
  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_{tk} = \Lambda_{tk} / \sqrt{\Sigma_{total,tt}}\). Used by "varimax_threshold" and "wald_retention". Comrey-Lee 1992 convention: 0.30 = "fair" salience (default). Must be a finite scalar in [0, 1). 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(|rho| > threshold) < retention_prob.
"profile_retention": pin entry if a profile LRT fails to reject H0: Lambda = 0 at significance level 1 - retention_prob.

Must be a finite scalar in (0, 1). 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

Deprecated compatibility argument; ignored by the standardised-loading conventions. Their denominators now come from the model-implied total variance returned by extract_Sigma().

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

set.seed(1)
# Simulate six traits measured twice on each of 100 units. Traits 1, 3
# and 5 share one latent axis; traits 2, 4 and 6 share a second one.
Lambda <- cbind(c(1.0, 0.0, 0.9, 0.0, 0.8, 0.0),
                c(0.0, 0.7, 0.0, 0.7, 0.0, 0.6))
sim <- simulate_unit_trait(n_units = 100, n_obs_per_unit = 2,
                           n_traits = 6, Lambda_B = Lambda,
                           psi_B = 0.3, sigma2_eps = 0.3)
form <- value ~ 0 + trait +
  latent(0 + trait | unit, d = 2, unique = TRUE)

# Exploratory fit: all loadings are estimated, apart from the single
# zero the model always uses to fix the orientation of the two axes.
fit <- gllvmTMB(form, data = sim$data, trait = "trait", unit = "unit")

# Two quick suggestions, neither of which refits the model: a hard
# cut-off on the rotated, standardised loadings, and a version that
# also accounts for their uncertainty.
cmp <- suggest_lambda_constraints(
  fit,
  methods = c("varimax_threshold", "wald_retention"),
  threshold = 0.30,
  retention_prob = 0.90
)
cmp$summary[, c("method", "cost", "n_pins", "n_free")]
#>              method                       cost n_pins n_free
#> 1 varimax_threshold                   no refit      6      6
#> 2    wald_retention no refit; needs PD Hessian      6      6

# The recommended matrix: 0 = pinned to zero, NA = estimated.
cmp$recommended_method
#> [1] "wald_retention"
cmp$recommended$constraint
#>         f1 f2
#> trait_1 NA  0
#> trait_2  0 NA
#> trait_3 NA  0
#> trait_4  0 NA
#> trait_5 NA  0
#> trait_6  0 NA

# Refit with those zeros pinned. The pins were chosen from these same
# data, so read the AIC comparison as a sanity check, not as
# independent evidence that the pattern is right.
fit_con <- gllvmTMB(form, data = sim$data, trait = "trait", unit = "unit",
                    lambda_constraint = list(
                      unit = cmp$recommended$constraint))
round(extract_loadings(fit_con, level = "unit"), 2)
#>          LV1  LV2
#> trait_1 0.89 0.00
#> trait_2 0.00 0.76
#> trait_3 1.02 0.00
#> trait_4 0.00 0.65
#> trait_5 0.71 0.00
#> trait_6 0.00 0.68
AIC(fit, fit_con)
#>         df      AIC
#> fit     24 3104.606
#> fit_con 19 3101.987

# A likelihood-ratio version, methods = "profile_retention", is also
# available. It is expensive: one refit per testable loading.