Communality of each trait (manuscript Eq. 32)

$$c_t^2 \;=\; \frac{(\boldsymbol\Lambda \boldsymbol\Lambda^{\!\top})_{tt}}{(\boldsymbol\Lambda \boldsymbol\Lambda^{\!\top})_{tt} + S_{tt}}.$$

Usage

extract_communality(
  fit,
  level = c("unit", "unit_obs", "B", "W"),
  link_residual = c("auto", "none"),
  ci = FALSE,
  conf_level = 0.95,
  method = c("profile", "wald", "bootstrap"),
  nsim = 500L,
  seed = NULL
)

Arguments

fit

A gllvmTMB_multi object.

level

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

link_residual

For binomial fits: "auto" (default) adds the link-specific implicit residual to the denominator; "none" returns communalities on the latent+unique-implied scale only.

ci

Logical. When TRUE, returns a tidy data frame with confidence-interval columns; when FALSE (the default), returns a plain named numeric vector for backward compatibility.

conf_level

Confidence level when ci = TRUE. Default 0.95.

method

One of "profile" (default), "wald", "bootstrap". Only used when ci = TRUE. Prefer profile or Wald-style intervals where available; bootstrap is a slower option for deliberate sampling checks.

nsim

Number of bootstrap replicates when method = "bootstrap". Default 500.

seed

Optional RNG seed for the bootstrap.

Value

When ci = FALSE: a numeric vector indexed by trait. When ci = TRUE: a data frame with columns trait, tier, c2, lower, upper, method.

Details

The proportion of trait \(t\)'s variance that is shared with the other traits via the latent factors. Bounded between 0 and 1. Calls extract_Sigma() internally for the chosen level, so the diagonal uses the full \(\boldsymbol\Sigma = \boldsymbol\Lambda \boldsymbol\Lambda^{\!\top} + \mathbf S\) decomposition when both latent() and unique() are in the formula.

Caveat: communality with latent-only fits

If the fit has latent() but no unique() at the requested level (for Gaussian / lognormal / Gamma responses), then \(\mathbf S = \mathbf 0\) and c_t^2 = 1 for every trait — this is mathematically correct given the model spec but tells you nothing about trait integration. The extract_Sigma() advisory message will fire to flag this. To get meaningful communalities, refit with + unique(0 + trait | <group>).

For binomial fits the link-specific implicit residual (\(\pi^2/3\) for logit, 1 for probit, \(\pi^2/6\) for cloglog) is added to the denominator by default; pass link_residual = "none" to suppress.

See also

extract_Sigma(); extract_ICC_site(); extract_correlations(); extract_repeatability(); confint.gllvmTMB_multi().

Examples

if (FALSE) { # \dontrun{
  sim <- simulate_site_trait(
    n_sites = 20, n_species = 6, n_traits = 4,
    mean_species_per_site = 4, seed = 1
  )
  fit <- gllvmTMB(
    value ~ 0 + trait +
            latent(0 + trait | site, d = 2) +
            unique(0 + trait | site),
    data = sim$data
  )
  ## Per-trait between-unit communality.
  extract_communality(fit, level = "unit")
  ## With profile-likelihood CIs.
  extract_communality(fit, level = "unit", ci = TRUE)
} # }