Cheap diagonal cross-check for the paired phylogenetic decomposition (large T)

Refits the user's data with phylo_indep + indep – a stacked multivariate generalisation of T univariate phylogenetic GLMMs in the spirit of Williams et al. (2025) Eq. 3 – using the same engine, family, link, and grouping as the supplied two-U fit. Compares the per-trait diagonals of the joint two-U fit's implied $\boldsymbol\Sigma_{\mathrm{phy}}$ (and $\boldsymbol\Sigma_{\mathrm{non}}$) against the marginal-only baseline. Tests only the diagonals (cheap); does not test the off-diagonal cross-trait covariances.

Usage

compare_indep_vs_two_U(
  fit_two_U,
  threshold = 0.1,
  phylo_vcv = NULL,
  phylo_tree = NULL
)

Arguments

fit_two_U: A gllvmTMB_multi joint two-U fit, e.g. produced by gllvmTMB(value ~ 0 + trait + phylo_latent(species, d = K_phy) + phylo_unique(species) + unique(0 + trait | species), ...). The cross-check refits the same data and family with phylo_dep + dep and compares.
threshold: Numeric (default 0.10): relative-disagreement threshold (Frobenius RMSE / Frobenius magnitude of the unstructured estimate) above which a component is flagged.
phylo_vcv, phylo_tree: Optional. The phylogenetic correlation matrix or ape::phylo tree, only needed if fit_two_U was produced by an older package version that did not store the phylogeny on the fit. Default is to recover them from the fit (fit_two_U$phylo_vcv / fit_two_U$phylo_tree).

Value

A list with components:

joint: Joint two-U fit's implied diag(Sigma_phy) and diag(Sigma_non) (named numeric vectors of length T).
indep: The marginal-only baseline's diag(Sigma_phy) and diag(Sigma_non) (same shape; may contain NULL if alt fit failed).
agreement: Data frame with rows for Sigma_phy_diag and Sigma_non_diag, columns rmse, indep_mag, rel_disagreement, and flag.
flag, threshold, alt_fit: As in compare_dep_vs_two_U().

Details

Use this diagnostic when T is large (T $\geq$ 30) and the unstructured fit needed by compare_dep_vs_two_U() is intractable. Otherwise prefer compare_dep_vs_two_U() (gold standard).

Cross-check intent: the per-trait diagonals are the simplest summary the joint two-U fit and the marginal baseline both target. If the diagonals already disagree beyond the threshold, no inspection of the cross-trait off-diagonals is warranted.

References

Williams, M. J., McGillycuddy, M., Drobniak, S. M., Bolker, B. M., Warton, D. I., & Nakagawa, S. (2025). Fast phylogenetic generalised linear mixed-effects modelling using the glmmTMB R package. bioRxiv 2025.12.20.695312. doi:10.1101/2025.12.20.695312

Examples

if (FALSE) { # \dontrun{
diag <- compare_indep_vs_two_U(fit)
diag$flag
diag$agreement
} # }