Communality of each trait

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

Usage

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

Arguments

fit: A fit returned by gllvmTMB(). A bootstrap_Sigma() result is also accepted when it contains communality summaries; in that case the function reuses the stored point estimates and percentile bounds rather than refitting.
level: "unit" (between-unit), "unit_obs" (within-unit), or "phy" (phylogenetic tier). 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 fitted model covariance scale without link-residual additions.
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 "wald" (default), "bootstrap", or "profile". Only used when ci = TRUE. The nonlinear penalty-profile prototype is currently withheld from the public release; requesting "profile" stops with an explanation. Bootstrap is a slower simulation-and-refit option and is not automatically coverage-calibrated.
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. For a bootstrap_Sigma input, the interval columns are copied from the bootstrap object.

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} + \boldsymbol\Psi$ decomposition. Ordinary latent() includes $\boldsymbol\Psi$ by default.

Caveat: communality with no-Psi fits

If the fit uses latent(..., unique = FALSE) at the requested level, then $\boldsymbol\Psi = \mathbf 0$ and c_t^2 = 1 for every trait. This is mathematically correct for the no-residual subset but tells you nothing about trait integration. The extract_Sigma() advisory message will fire to flag this. To get meaningful communalities, use ordinary latent() with the default unique = TRUE.

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.

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),
    data  = sim$data,
    trait = "trait",
    unit  = "site"
  )
  ## Per-trait between-unit communality.
  extract_communality(fit, level = "unit")
  ## With delta-method Wald CIs.
  extract_communality(fit, level = "unit", ci = TRUE, method = "wald")
  boot <- bootstrap_Sigma(fit, n_boot = 50, level = "unit",
                          what = "communality", progress = FALSE)
  extract_communality(boot, level = "unit", ci = TRUE)
} # }