Skip to contents

Per-trait proportion-of-variance decomposition across all model components

Source: R/extract-omega.R
extract_proportions.Rd

For each trait, returns the proportion of total latent variance attributable to each component present in the model: shared (rr) and unique (diag) at each tier (B, W, phy), plus optionally the binomial link's implicit residual.

Usage

extract_proportions(
  fit,
  link_residual = c("auto", "none"),
  format = c("long", "wide")
)

Arguments

fit

A gllvmTMB_multi fit.

For non-Gaussian fits: "auto" (default) adds the link's implicit residual as its own per-trait component (e.g. \(\pi^2/3\) for binomial logit, \(\log(1 + 1/\hat\mu_t)\) for Poisson log; see "Family-aware link residuals" in extract_Sigma() for the full per-family table). Mixed-family fits get the residual implied by each trait's family/link. "none" omits the link-implicit component.

format

"long" (default) returns a tibble-like data frame with one row per (trait, component); "wide" returns one row per trait with one column per component.

Value

Long format: data frame with columns trait, component (e.g. "shared_unit", "unique_unit", "shared_phy", "link_residual"), variance (the absolute variance), proportion (the share of the total). Wide format: data frame with one column per component plus a total_variance column; the per-trait proportions sum to 1.

OLRE interpretation: for fits with a genuine observation-level unique() term (see extract_residual_split()), the unique_W component in this output corresponds to \(\sigma^2_e\) (the estimated OLRE variance) and the link_residual component corresponds to \(\sigma^2_d\) (the distribution-specific latent residual).

Details

This is the most general proportion-decomposition function in the package. extract_phylo_signal() is the focused PGLLVM \(H^2 / C^2_\text{non} / \Psi\) convenience wrapper for the species-level case; extract_communality() gives the rr-only "shared" proportion at one tier; extract_ICC_site() gives the between-vs-within proportion. extract_proportions() returns all of these in one tidy frame.

See also

extract_phylo_signal() — the PGLLVM-specific shortcut; extract_communality(); extract_ICC_site(); extract_residual_split() — explicit \(\sigma^2_d / \sigma^2_e\) decomposition for OLRE fits.

Examples

if (FALSE) { # \dontrun{
extract_proportions(fit)                           # long format
extract_proportions(fit, format = "wide")          # one row per trait
} # }