Rotate the loadings of a fitted multivariate model

Applies a varimax or promax rotation to the loading matrix \(\Lambda\) from a fit returned by gllvmTMB(). Use level = "unit" for the between-unit reduced-rank component and level = "unit_obs" for the within-unit component. The latent scores are rotated by the complementary transform so the linear predictor, fitted log-likelihood, and implied covariance are unchanged.

Usage

rotate_loadings(
  fit,
  level = "unit",
  method = c("varimax", "promax", "none"),
  order_axes = TRUE,
  sign_anchor = c("auto", "none"),
  anchor_traits = NULL
)

Arguments

fit: A fitted multivariate model returned by gllvmTMB().
level: "unit" (between-unit) or "unit_obs" (within-unit). Deprecated aliases "B" and "W" are still accepted with a warning.
method: One of "varimax", "promax", or "none".
order_axes: Logical. When TRUE (default for rotated output), reorder rotated axes by decreasing shared variance colSums(Lambda^2). Ignored when method = "none".
sign_anchor: One of "auto" or "none". "auto" (default for rotated output) flips each rotated axis so its anchor trait has a positive loading. Ignored when method = "none".
anchor_traits: Optional character vector of trait names used for sign anchoring. Supply one trait per axis after ordering. Axes without a supplied anchor use the trait with the largest absolute loading.

Value

A list with rotated Lambda (n_traits × d), rotated scores (with rows = units or within-unit observations, columns = factors), and the rotation matrix T such that \(\Lambda_{\text{rotated}} = \Lambda T\). The list also includes axis_variance, axis_order, axis_sign, and anchor_traits metadata after any ordering and sign anchoring.

Details

Rotation is for interpretation of the loading columns, especially figures. It does not make the axes uniquely "right"; it chooses a readable orientation among mathematically equivalent orientations. For quantitative interpretation, start from the model-implied Sigma, correlations, communality, and uniqueness, then use rotated axes for labels and plots.

A defensible plotting workflow is: fit the model, check convergence, reconstruct covariance summaries, then rotate loadings for visual interpretation. Rotate level = "unit" and level = "unit_obs" separately because they represent different covariance structures. method = "varimax" is the usual first choice for a simple loading pattern; use method = "promax" only when correlated latent axes are intended.

The rotation is applied to \(\Lambda\) on the left and to the latent scores on the right using the inverse transform, so \(\Lambda_{\text{rot}} \mathbf{z}_{\text{rot}} = \Lambda \mathbf{z}\) is unchanged. For varimax, T is orthogonal so the rotation preserves the implied covariance \(\Lambda \Lambda^\top\); for promax, T is oblique and the columns of \(\Lambda_{\text{rot}}\) are no longer orthogonal.

Examples

if (FALSE) { # \dontrun{
set.seed(1)
sim <- simulate_site_trait(
  n_sites = 60, n_species = 12, n_traits = 4,
  Lambda_B = matrix(c(1.0, 0.7, -0.3, 0.5,
                      0.3, -0.5, 0.8, 0.2),
                    nrow = 4, ncol = 2),
  psi_B = c(0.3, 0.3, 0.3, 0.3),
  seed = 1
)
fit <- gllvmTMB(value ~ 0 + trait +
                        latent(0 + trait | site, d = 2),
                data  = sim$data,
                trait = "trait",
                unit  = "site")
raw <- extract_ordination(fit, "unit")
rot <- rotate_loadings(fit, level = "unit", method = "varimax")
# raw$loadings - lower-triangular (hard to read)
# rot$Lambda  - varimax-rotated (typically simpler structure)
} # }