Skip to contents

Extract the trait loading matrix

Source: R/output-methods.R
extract_loadings.Rd

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.81945913  0.0000000
#> trait_2  0.61255871  0.2941395
#> trait_3  0.47902009 -0.5060250
#> trait_4 -0.07049118  0.6347425
#> trait_5  0.26512664  0.6060760
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.80713727 -0.1415722
#> trait_2 0.65416434  0.1838892
#> trait_3 0.38439487 -0.5811731
#> trait_4 0.04022878  0.6373764
#> trait_5 0.36584755  0.5511586