Scope
This article is for descriptive prediction sensitivity
only. Tree uncertainty was not part of the analysis-aware MI
validation campaign. multi_impute_trees() does not produce
datasets supported for downstream inference, and it cannot currently be
combined with multi_impute_analysis().
Use this article only when you have a posterior sample of trees (from BEAST, MrBayes, BirdTree.org, etc.) and want to see how point imputations change across that sample.
Prediction-sensitivity workflow
With share_gnn = TRUE (the default), the GNN is trained
once on a reference tree and the baseline is recomputed for every
posterior tree. The returned datasets can be compared descriptively; do
not pass them to pool_mi().
library(pigauto)
data(avonet300, trees300)
df <- avonet300
rownames(df) <- df$Species_Key
df$Species_Key <- NULL
mi <- multi_impute_trees(df, trees = trees300, m_per_tree = 1L)
# share_gnn = TRUE, reference_tree = MCC via phangorn -- all default
mass_by_tree <- vapply(mi$datasets, function(dat) dat$Mass, numeric(nrow(df)))
apply(mass_by_tree, 1L, stats::sd) # descriptive sensitivity, not an MI SEThe code above is illustrative and left unevaluated because the tree loop is computationally expensive.
Why share_gnn = TRUE preserves tree signal
The calibrated gate r_cal controls how much of each
prediction comes from the baseline vs the GNN. In
high-phylogenetic-signal regimes the gate often closes or nearly closes,
so pred = baseline(tree_t) and the per-tree baseline
carries the tree-uncertainty signal. When the gate is partly open, the
GNN component is shared across trees and the per-tree baseline still
varies with tree_t. See ?multi_impute_trees
under “Share-GNN (tree-sharing) mode” for the fully-open and
partially-open cases.
If you need exact per-tree model independence (e.g. for
methodological comparison), set share_gnn = FALSE:
mi_slow <- multi_impute_trees(df, trees300, m_per_tree = 1L,
share_gnn = FALSE)
# fits T = length(trees300) full pigauto models -- ~10-15x slower.What this does not establish
Variation across these datasets is not a calibrated standard error, confidence interval, or fraction of missing information. It does not validate Rubin pooling, variance components, correlations, BLUPs, conditional modes, or latent loadings. A future tree-aware analysis backend requires a separate known-DGP campaign.