Phylogenetic-signal diagnostic for a modelled missing predictor

For a gllvmTMB() fit with a phylogenetic missing-predictor covariate model (mi(x) with impute = list(x = x ~ ... + phylo(1 | species, tree = tree))), phylo_signal_mi() reports an effective phylogenetic-signal statistic for the covariate model and flags the weak-signal case. Phylogenetic imputation helps when the signal in x is strong and degrades toward the independent (no-borrowing) model when it is weak; forcing a phylogenetic prior on a phylogenetically-unstructured trait adds noise rather than information (Penone et al. 2014 Methods Ecol. Evol. 5:961-970; Molina-Venegas 2024 Methods Ecol. Evol.; Goolsby, Bruggeman & Ane 2017 Methods Ecol. Evol. 8:22-27, Rphylopars).

Usage

phylo_signal_mi(object, variable = NULL, threshold = 0.1, warn = FALSE)

Arguments

object

A gllvmTMB fit with a phylogenetic missing-predictor model.

variable

Optional missing-predictor name; defaults to the only modelled missing predictor.

threshold

Effective-lambda threshold below which the signal is flagged as weak (default 0.1).

warn

Logical; when TRUE, warn against over-interpreting conditional modes when phylogenetic signal is weak. Default FALSE (the function returns the statistic silently).

Value

A list with variable, lambda (effective Pagel lambda), sd_x, sigma_x, weak (logical), and threshold.

Details

The statistic is an effective Pagel's lambda for the covariate, lambda = sd_x^2 / (sd_x^2 + sigma_x^2), the fraction of species-level variance in x explained by the phylogenetic field (sd_x) relative to the i.i.d. residual (sigma_x) – the Pagel partition of the covariate model. lambda near 1 = strong signal (informative borrowing); lambda near 0 = weak signal (the covariate model is approximately equivalent to an independent model). This is a verification / interpretation aid, not part of the fit; it does not change estimates.

See also

imputed() for conditional modes; gllvmTMB() for the impute = phylo covariate model.