Extract latent random-effect scores

Returns unit-tier (or within-unit) latent random-effect scores as an n \times K matrix. For a fitted object this is the posterior mode of the z_B / z_W innovation block in native rotate = "none" orientation. For output from simulate_site_trait(), returns the generating draws stored in truth$z_B / truth$z_W.

Usage

extract_latent_scores(x, level = c("unit", "unit_obs"))

Arguments

x

A fitted gllvmTMB_multi / gllvmTMB_va / gllvmTMB_julia object, or a gllvmTMB_site_trait_sim object from simulate_site_trait().

level

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

Value

An n \times K numeric matrix with unit row names and "LV1", "LV2", … column names; NULL when no reduced-rank term exists at the requested level.

Details

Point estimates match extract_ordination() with component = "innovation", getLV() at rotate = "none", and ordination_uncertainty() $scores when that function succeeds. Score uncertainty (se, cov) remains ordination_uncertainty() / getLV() with se = TRUE.

See also

extract_ordination(), ordination_uncertainty(), getLV(), simulate_site_trait()

Examples

if (FALSE) { # \dontrun{
sim <- simulate_site_trait(
  n_sites = 20, n_species = 6, n_traits = 4,
  mean_species_per_site = 4,
  Lambda_B = matrix(c(0.9, 0.6, -0.4, 0.5), nrow = 4, ncol = 1),
  seed = 1
)
u_true <- extract_latent_scores(sim, level = "unit")
fit <- gllvmTMB(
  value ~ 0 + trait + latent(0 + trait | site, d = 1),
  data = sim$data
)
z_hat <- extract_latent_scores(fit, level = "unit")
} # }