Skip to contents

Extract latent random-effect scores

Source: R/extract-latent-scores.R
extract_latent_scores.Rd

Returns unit-tier (or within-unit) latent random-effect scores as an n-by-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 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-by-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

## Simulate 4 traits recorded on a few species at each of 30 sites. The
## between-site trait variation comes from one latent axis (one loading
## per trait in Lambda_B) plus some trait-specific variation (psi_B).
## beta = 0 turns off the simulator's environmental effects, which this
## model does not include.
set.seed(1)
sim <- simulate_site_trait(
  n_sites = 30, n_species = 6, n_traits = 4,
  mean_species_per_site = 4,
  beta = matrix(0, 4, 2),
  Lambda_B = matrix(c(0.9, 0.6, -0.4, 0.5), nrow = 4, ncol = 1),
  psi_B = rep(0.2, 4)
)
## The true site scores the simulation drew: one row per site, one
## column per latent axis
u_true <- extract_latent_scores(sim, level = "unit")
head(u_true)
#>          LV1
#> 1 -0.7432732
#> 2  0.1887923
#> 3 -1.8049586
#> 4  1.4655549
#> 5  0.1532533
#> 6  2.1726117
## Fit one latent axis between sites; unique = TRUE also fits the
## trait-specific variances, as in the simulated data
fit <- gllvmTMB(
  value ~ 0 + trait + latent(0 + trait | site, d = 1, unique = TRUE),
  data  = sim$data,
  trait = "trait",
  unit  = "site"
)
## The estimated site scores (posterior modes), in the same layout
z_hat <- extract_latent_scores(fit, level = "unit")
head(z_hat)
#>          LV1
#> 1 -0.2901416
#> 2  0.6723780
#> 3 -2.0563490
#> 4  0.7106401
#> 5 -0.6305943
#> 6  2.1509266
## The sign of a latent axis is arbitrary, so compare up to sign: the
## estimated scores are strongly correlated with the true ones
abs(cor(z_hat[, "LV1"], u_true[, "LV1"]))
#> [1] 0.8674705
## This model has no latent term within sites, so there are no
## within-site scores to return
extract_latent_scores(fit, level = "unit_obs")
#> NULL