Extract the trait loading matrix

Returns the trait loading matrix from a fit returned by gllvmTMB(). This is the canonical snake_case accessor in the extract_*() family; getLoadings() is an accepted compatibility spelling for readers coming from gllvm. Both return the same matrix.

Usage

extract_loadings(fit, level = "unit", rotate = c("none", "varimax", "promax"))

Arguments

fit

A fitted multivariate model returned by gllvmTMB(). Admitted engine = "julia" bridge fits expose raw unit-tier loadings and scores; rotated ordinations remain gated for Julia bridge fits.

level

"unit" (between-unit) or "unit_obs" (within-unit). Deprecated aliases "B" and "W" are still accepted with a warning.

rotate

Optional "varimax" or "promax" rotation after fitting. Default "none" returns the engine's native lower-triangular Lambda. For Julia bridge fits only "none" is currently routed.

Value

An n_traits x d numeric matrix.

See also

extract_ordination() for scores and loadings together; getLoadings() for the gllvm-style spelling.

Examples

set.seed(1)
## Five traits measured three times on each of 60 units. Between units,
## the traits share two latent axes (Lambda) plus a trait-specific
## unique variance (psi = 0.2 for every trait).
Lambda <- matrix(c(0.9, 0.7, 0.5, -0.3, 0.2,
                   0.0, 0.4, -0.5, 0.6, 0.8), nrow = 5, ncol = 2)
sim <- simulate_unit_trait(
  n_units = 60, n_obs_per_unit = 3, n_traits = 5,
  Lambda_B = Lambda, psi_B = rep(0.2, 5), sigma2_eps = 0.3
)
fit <- gllvmTMB(
  value ~ 0 + trait + latent(0 + trait | unit, d = 2, unique = TRUE),
  data  = sim$data,
  trait = "trait",
  unit  = "unit"
)
## extract_loadings() is the snake_case spelling of getLoadings();
## both return the same matrix
L <- extract_loadings(fit, level = "unit")
#> ℹ `Lambda_B` is identified only up to rotation (d_B = 2).
#> • Use `rotate = "varimax"` for a quick rotation after fitting, or
#> • see `suggest_lambda_constraint()` for a default `lambda_constraint` matrix to
#>   pass to a refit.
#> • `extract_Sigma_B()` is rotation-invariant and does not need this.
L
#>                 LV1        LV2
#> trait_1  0.81946050  0.0000000
#> trait_2  0.61255342  0.2941478
#> trait_3  0.47902887 -0.5060310
#> trait_4 -0.07050534  0.6347396
#> trait_5  0.26511195  0.6060781
identical(L, getLoadings(fit, level = "unit"))
#> ℹ `Lambda_B` is identified only up to rotation (d_B = 2).
#> • Use `rotate = "varimax"` for a quick rotation after fitting, or
#> • see `suggest_lambda_constraint()` for a default `lambda_constraint` matrix to
#>   pass to a refit.
#> • `extract_Sigma_B()` is rotation-invariant and does not need this.
#> [1] TRUE
## Rotated after fitting, e.g. with varimax
extract_loadings(fit, level = "unit", rotate = "varimax")
#>                LV1        LV2
#> trait_1 0.80713640 -0.1415851
#> trait_2 0.65416346  0.1838881
#> trait_3 0.38439340 -0.5811865
#> trait_4 0.04022431  0.6373754
#> trait_5 0.36584207  0.5511575