Total trait covariance Omega summed across requested tiers

Sum of $\boldsymbol\Sigma_\text{tier}$ matrices across the user- selected tiers. The canonical PGLLVM use case is the species-level three-piece decomposition: $$\boldsymbol\Omega \;=\; \boldsymbol\Sigma_\text{phy} \;+\; \boldsymbol\Sigma_\text{non,shared} \;+\; \boldsymbol\Psi_\text{non}.$$ Here tiers = c("phy", "B") returns $\boldsymbol\Sigma_\text{phy} + \boldsymbol\Sigma_\text{B}$ where $\boldsymbol\Sigma_B = \boldsymbol\Lambda_B \boldsymbol\Lambda_B^{\!\top} + \boldsymbol\Psi_B$ aggregates the non-phylogenetic shared and unique components.

Usage

extract_Omega(fit, tiers = NULL, link_residual = c("auto", "none"))

Arguments

fit: A fit returned by gllvmTMB().
tiers: Character vector. Subset of c("B", "W", "phy"). Default NULL auto-detects: includes "phy" if phylo_latent() is in the formula, "B" if any latent()/indep() at unit, "W" if any latent()/indep() at unit_obs.
link_residual: For non-Gaussian fits: "auto" (default) adds a per-trait link-specific implicit residual to the diagonal of the summed Omega (once, not per tier — see "Family-aware link residuals" in extract_Sigma()); mixed-family fits get the residual implied by each trait's family/link. "none" returns the summed fitted covariance without link-residual additions. Gaussian / lognormal-only fits are unaffected.

Value

A list with Omega (T × T summed covariance), R_Omega (correlation), tiers_used (which tiers were actually summed), note (notes from each underlying extract_Sigma() call), and (when link_residual = "auto") residual_split — the per-trait $\sigma^2_d / \sigma^2_e / \sigma^2_\text{total}$ data frame from extract_residual_split().

Details

For two-level behavioural-syndrome fits, tiers = c("B", "W") returns the phenotypic trait covariance $\boldsymbol\Sigma_P = \boldsymbol\Sigma_B + \boldsymbol\Sigma_W$ .

Examples

if (FALSE) { # \dontrun{
# PGLLVM three-piece total
set.seed(1)
tree <- ape::rcoal(20)
tree$tip.label <- paste0("sp", seq_len(20))
sim <- simulate_site_trait(
  n_sites = 25, n_species = 20, n_traits = 3,
  mean_species_per_site = 20, sigma2_eps = 0.4,
  Lambda_B = matrix(0.6, 3, 1), psi_B = rep(0.2, 3),
  Cphy = ape::vcv(tree, corr = TRUE), sigma2_phy = rep(0.4, 3),
  seed = 1
)
dat <- sim$data
levels(dat$species) <- tree$tip.label
fit <- gllvmTMB(
  value ~ 0 + trait + phylo_latent(species, d = 1, tree = tree) +
                      latent(0 + trait | site, d = 1) +
                      unique(0 + trait | site),
  data    = dat,
  cluster = "species"
)
om <- extract_Omega(fit, tiers = c("phy", "B"))
round(om$R_Omega, 2)

# Phenotypic covariance from a two-level behavioural-syndromes fit
set.seed(1)
sim <- simulate_site_trait(
  n_sites = 40, n_species = 6, n_traits = 4, mean_species_per_site = 4,
  Lambda_B = matrix(c(1, .5, -.4, .3, 0, .8, .4, -.2), 4, 2),
  psi_B = c(.2, .15, .1, .25),
  Lambda_W = matrix(c(.4, .2, -.1, .3), 4, 1),
  psi_W = c(.1, .08, .05, .12),
  beta = matrix(0, 4, 2), seed = 1
)
dat <- sim$data
fit <- gllvmTMB(
  value ~ 0 + trait +
          latent(0 + trait | site, d = 2) + unique(0 + trait | site) +
          latent(0 + trait | site_species, d = 1) +
          unique(0 + trait | site_species),
  data = dat
)
om2 <- extract_Omega(fit, tiers = c("B", "W"))
} # }