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 (Nakagawa et al. in prep, Eq. 19): $$\boldsymbol\Omega \;=\; \boldsymbol\Sigma_\text{phy} \;+\; \boldsymbol\Sigma_\text{non,shared} \;+\; \mathbf S_\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} + \mathbf S_B$ aggregates the non-phylogenetic shared and unique components.

Usage

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

Arguments

fit: A gllvmTMB_multi fit.
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()/unique() at unit, "W" if any latent()/unique() 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 latent+unique-implied scale. 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$ (Nakagawa et al. in prep, Eq. 28).

Examples

if (FALSE) { # \dontrun{
# PGLLVM three-piece total
om <- extract_Omega(fit, tiers = c("phy", "B"))
round(om$R_Omega, 2)

# Phenotypic covariance from a two-level behavioural-syndromes fit
om2 <- extract_Omega(fit, tiers = c("B", "W"))
} # }