Confidence intervals on individual entries of the loading matrix

Return per-entry CIs on the reduced-rank loading matrix Lambda_<level> of a confirmatory gllvmTMB() fit. Method v1 is the delta-method Wald CI: a numerical Jacobian J = d vec(Lambda) / d theta_rr is combined with the TMB sdreport() covariance to give cov(vec(Lambda)) = J %*% cov.fixed %*% t(J), from which symmetric Wald intervals are read.

Usage

loading_ci(
  fit,
  level = c("unit", "unit_obs"),
  method = c("wald", "wald_asym", "profile"),
  conf_level = 0.95,
  sigma_d2 = 1
)

Arguments

fit

A multivariate gllvmTMB() fit object.

level

Which loading matrix to summarise: "unit" (default) or "unit_obs". Legacy aliases "B" / "W" are accepted with a one-shot deprecation warning.

method

CI method:

"wald" (default): Symmetric Wald via delta method.
"wald_asym": Asymmetric Wald via the Fisher-z transformation on the standardised loading \(\rho = \Lambda / \sqrt{\Lambda^2 + \sigma_d^2}\). Same cost as "wald" (no refit) but captures the bounded-support asymmetry that symmetric Wald on \(\Lambda\) ignores. CIs are wider toward large \(|\Lambda|\) and narrower toward 0 — the qualitatively correct shape, leaving higher-order log-likelihood-curvature corrections to the profile path.
"profile": Profile-likelihood inversion through loading_profile(). This refits across a grid for each free loading entry and can be used when Wald inference is blocked by a non-positive-definite Hessian.

conf_level

Confidence level. Defaults to 0.95.

sigma_d2

link-implicit residual variance on the link scale. Only used when method = "wald_asym". Defaults to 1 (binomial probit and ordinal_probit; the cleanest non-Gaussian case). For logit use \(\pi^2/3\); for cloglog use \(\pi^2/6\). Set to the fitted unique variance for Gaussian. A future version will auto-detect per-trait from the family.

Value

A data frame (one row per Lambda entry) with columns trait, axis, estimate, se, lower, upper, method, and pinned (logical: TRUE for entries fixed by lambda_constraint, whose SE is exactly 0 by construction).

Details

Per-entry CIs are only well-defined for confirmatory fits — i.e. fits supplied with a lambda_constraint that fixes enough entries to pin the rotation. Exploratory fits leave Lambda identified only up to a d x d orthogonal rotation, so the SE on any single Lambda[i, k] depends on the rotation convention and is not a biological quantity. This function therefore errors on exploratory fits and points the user at confirmatory_lambda() / suggest_lambda_constraint(), or at extract_communality() / extract_Sigma() for rotation-invariant summaries.

Examples

if (FALSE) { # \dontrun{
# Build a confirmatory fit
M <- confirmatory_lambda(
  species  = species_names,
  group    = species_group,
  d        = 2L,
  loads_on = list(A = 1L, B = 2L)
)
fit <- gllvmTMB(
  value ~ 0 + trait + latent(0 + trait | site, d = 2L),
  data              = df_long,
  family            = binomial(link = "probit"),
  lambda_constraint = list(unit = M)
)
loading_ci(fit, level = "unit")
} # }