Phylogenetic-signal proportions per trait (PGLLVM Eq. 23-25)

For a phylogenetic species-level GLLVM, decomposes each trait's between-species latent variance into three additive components that sum to one: $$H_t^2 \;=\; \frac{[\boldsymbol\Sigma_\text{phy}]_{tt}}{V_{\eta,t}}, \qquad C^2_{\text{non},t} \;=\; \frac{[\boldsymbol\Sigma_\text{non,shared}]_{tt}}{V_{\eta,t}}, \qquad \Psi_t \;=\; \frac{[\mathbf S_\text{non}]_{tt}}{V_{\eta,t}},$$ where $V_{\eta,t} = [\boldsymbol\Sigma_\text{phy}]_{tt} + [\boldsymbol\Sigma_\text{non,shared}]_{tt} + [\mathbf S_\text{non}]_{tt}$ is the total between-species latent variance for trait $t$ (Nakagawa et al. in prep, PGLLVM paper Eq. 19, 22-25).

Usage

extract_phylo_signal(
  fit,
  ci = FALSE,
  conf_level = 0.95,
  method = c("profile", "wald", "bootstrap"),
  nsim = 500L,
  seed = NULL
)

Arguments

fit: A gllvmTMB_multi fit with a phylo_latent() term.
ci: Logical. When TRUE, adds confidence-interval columns to the output for the H^2 column. Default FALSE for backward compatibility.
conf_level: Confidence level when ci = TRUE. Default 0.95.
method: One of "profile" (default), "wald", "bootstrap". Only used when ci = TRUE. For 2-component decompositions (phylo_unique vs species-level unique only) profile uses a linear contrast; for 3-component decompositions (PGLLVM with phylo_latent + species-level latent + unique) the profile path is not yet implemented and falls back to the point estimate.
nsim: Number of bootstrap replicates when method = "bootstrap". Default 500.
seed: Optional RNG seed for the bootstrap.

Value

A data frame with columns trait, H2, C2_non, Psi, V_eta (the denominator), one row per trait. The three proportions sum to 1.0 by construction. When ci = TRUE, three additional columns are added: H2_lower, H2_upper, H2_method.

Details

Interpretation:

$H_t^2$: phylogenetic signal — proportion of between- species latent variance attributable to phylogenetically structured variation ("evolutionary conservatism"). When the model includes both phylo_latent() and phylo_unique(), $\boldsymbol\Sigma_\text{phy}$ is the sum $\boldsymbol\Lambda_\text{phy} \boldsymbol\Lambda_\text{phy}^{\!\top} + \mathbf S_\text{phy}$ and $H_t^2$ reflects the total phylogenetic variance.
$C^2_{\text{non},t}$: non-phylogenetic communality — proportion of variance attributable to shared non-phylogenetic axes ("coordinated tip-level lability" across traits).
$\Psi_t$: uniqueness — proportion of variance not captured by any shared axis ("relative modularity").

Requires phylo_latent() (and optionally phylo_unique()) plus species-level latent() AND unique() in the fit. If unique() at the species tier is missing, $\Psi_t = 0$ for all traits and a cli::cli_inform() advisory fires.

Examples

if (FALSE) { # \dontrun{
fit <- gllvmTMB(
  value ~ 0 + trait + phylo_latent(species, d = 2) +
                      latent(0 + trait | species, d = 2) +
                      unique(0 + trait | species),
  data = df, phylo_tree = tree, unit = "species"
)
extract_phylo_signal(fit)
} # }