Decomposes each trait's variance on the linear-predictor scale into
contributions from the active random-effect components of the model and
the Gaussian or lognormal observation residual. Column names follow the
fitted report blocks: rr_B, diag_B, rr_W, diag_W, diag_species,
diag_cluster2, phylo_rr, phylo_diag, propto, one kernel_<name>
column per term of a fit with several named kernel_*() terms, one
re_int_<group> column per (1 | group) random intercept, and residual.
Arguments
- fit
A fitted multivariate model returned by
gllvmTMB().
Value
An n_traits × n_components matrix of variance shares; each row
sums to 1 over the included components (a row whose total is not positive
is NA). Columns are only the components active in the fit. When a
component was left out, the "omitted_components" attribute names it.
Details
A (1 | group) intercept is a single draw per group level added to every
trait, so its column carries the same variance in every row. A tree =
input is rescaled to unit root-to-tip height, so phylogenetic columns are
variances per species. A vcv =, A =, pedigree or kernel K = matrix
is used as supplied: when its diagonal is not 1, the column holds the
loading variance rather than the per-level variance, and the shares
change with the matrix's scale (rescale it to a unit diagonal first, for
example with ape::vcv(tree, corr = TRUE)).
residual is the observation variance \(\sigma^2_\varepsilon\) of
Gaussian and lognormal traits (on the log scale for lognormal). When a
diagonal term has one row per observation (an indep() term at the
observation level, or the default latent() Psi when each unit has one
observation per trait), the package does not estimate
\(\sigma_\varepsilon\): it fixes it at 1/1000 of the standard deviation
of all responses pooled on the raw scale. That fixed value is still part
of the fitted variance, so it is counted. It is negligible when the traits
share a scale, but not when trait scales differ widely or when lognormal
responses are large. Non-Gaussian link-implicit residual shares are
handled by extract_proportions(), not by VP().
Some active components are not partitioned: random-slope terms (their
variance, intercept included, changes with the covariate value),
response-column slopes and coefficients (likewise), the known sampling
variance of meta_V() (it differs by observation), spatial fields (their
variance is on the SPDE parameter scale) and temporal states
(extract_temporal() reports their per-trait variances). VP() leaves
each of them out, names them in a warning of class
gllvmTMB_vp_component_omitted, and records them in the
"omitted_components" attribute of the result. The shares are then
proportions of the included components only.
VP() serves the same purpose as gllvm::VP() / gllvm::plotVP(), but
partitions random-effect and residual variance. Fixed effects, including
the predictor part of latent(..., lv = ~ x), are not partitioned.
Structured trait-intercept rho fits are excluded; use extract_Sigma() and
its source_strength metadata.
See also
extract_proportions() for the canonical per-trait
variance-share decomposition (shared_unit, unique_unit_obs, phy
tiers, link-residual, etc.).