Generate experimental stochastic completion datasets

Run pigauto's full imputation pipeline and return M stochastic completions of the trait matrix instead of a single point estimate. The conformal-width and mc_dropout draws returned here are experimental prediction diagnostics. The mc_dropout route uses independent Gaussian perturbations per latent cell, scaled by selected baseline SD, and adds GNN dropout variation only when the GNN is enabled. Do not use these datasets for downstream inference or Rubin pooling.

Usage

multi_impute(
  traits,
  tree,
  m = 100L,
  draws_method = c("auto", "conformal", "mc_dropout", "posterior"),
  species_col = NULL,
  trait_types = NULL,
  multi_proportion_groups = NULL,
  log_transform = TRUE,
  missing_frac = 0.25,
  covariates = NULL,
  epochs = 2000L,
  verbose = TRUE,
  seed = NULL,
  gnn = FALSE,
  lambda_mode = c("estimate", "fixed_1", "cv", "bayes"),
  posterior_control = list(),
  ...,
  ordinal_levels = NULL
)

# S3 method for class 'pigauto_mi'
print(x, ...)

Arguments

traits

data.frame with species as rownames and trait columns. Same input format as impute(). Supported column types are numeric, integer, factor, ordered factor, and logical.

tree

object of class phylo aligned with traits.

m

integer. Number of stochastic completion datasets to generate (default 100). Observed cells are identical across all M datasets; only originally-missing cells vary.

draws_method

character. How stochastic draws are generated for missing cells. One of:

"auto": (default; previously "conformal") Use "posterior" when the data fit its requirements (every trait continuous, one row per species, no covariates, no multi_proportion_groups); otherwise use "conformal" and print a message saying why and that the draws cannot be pooled. The chosen method is stored in result$draws_method. To get the previous default, set draws_method = "conformal".
"conformal": Use this method when "auto" falls back because the posterior sampler's requirements are not met, or when explicitly requested. Run the model once, then sample each originally-missing cell from a Normal distribution centred on the point estimate with SD = conformal_score / 1.96. Converting a split-conformal residual quantile to a Normal scale is a heuristic; a nominal held-out conformal diagnostic does not establish that these draws are suitable for downstream multiple-imputation inference. For continuous, count, ordinal, and proportion traits, when no finite conformal score is available, pigauto uses the reported pred$se as a scale input for fallback draws. For log-transformed continuous traits, log1p-transformed counts, and logit-transformed proportions, pred$se is reported on the original scale, but the draw is made on the transformed scale. Pigauto does not fully convert pred$se between these scales, so diagnostic draw spread may be too wide or too narrow. Fitted point predictions are unchanged. Binary and categorical traits use Bernoulli / categorical draws from predicted probabilities.
"mc_dropout": Add independent Gaussian perturbations per latent cell, scaled by selected baseline SD. This returns M stochastic draws; when the GNN is enabled, its network runs use dropout in training mode. These prediction-diagnostic draws are not joint phylogenetic BM posterior draws and are unsupported for downstream inference.
"posterior": Continuous traits only, one row per species, no covariates. Fit a Bayesian multivariate phylogenetic mixed model by MCMC and return m completions drawn from the posterior predictive distribution of the missing cells. No GNN is fitted. See "Posterior draws" below. In simulation (continuous traits, 30% missing completely at random, 200 datasets per cell, n = 100 to 1000, lambda 0.3 to 1, trait correlation 0 or 0.5), a Rubin-pooled downstream PGLS slope and phylogenetic correlation had 95% interval coverage of 0.925 to 0.975 in every cell. At lambda = 1 with trait correlation 0.5, slope coverage was 0.955, 0.940 and 0.965 at n = 100, 300 and 1000 (reference frequentist MI: 0.955, 0.920, 0.935). At n = 100 with correlated traits the pooled slope was biased by about -0.02 towards zero, with coverage still 0.96. These results concern only the stated simulation regimes and do not establish inferential performance elsewhere. The registered validation found five tested posterior slope regimes failed and three indeterminate; see the registered inferential results. The previous residual prior (posterior_control = list(residual_prior = "iw")) attenuated the relationship between correlated traits at lambda near 1: coverage 0.96, 0.88 and 0.75 at the same three n.

Conformal and MC-dropout draws perturb missing cells around a point prediction rather than drawing them jointly from their conditional distribution given the observed data. In a 16-regime simulation of a downstream phylogenetic regression (PGLS slope, two traits, 120 replicates per regime), conformal draws biased the pooled slope by -0.20 to -0.46, and the pooled 95% intervals covered the truth in 0 to 17% of replicates, in all 16 regimes; MC-dropout draws biased it by -0.03 to -0.38. For continuous traits, the documented route permits eligible "posterior" draws to be fitted with with_imputations() and pooled with pool_mi() under the conditions below. Software eligibility does not show that the resulting estimates and uncertainty are reliable. In the registered validation, five of eight tested posterior-slope regimes failed the prespecified criteria and three were indeterminate; none was supported. These results apply to those tested regimes. Other analyses need evidence for their model, data, and missingness process; see the registered inferential results.

species_col

character or NULL. If set, marks the column in traits containing species identifiers and enables multiple observations per species. See impute() for details.

trait_types

named character vector overriding auto-detected trait types for specific columns. Required for "proportion" and "zi_count". See impute() and preprocess_traits(). Default NULL (auto-detect).

multi_proportion_groups

named list declaring compositional trait groups (rows summing to 1), e.g. list(diet = c("plant", "invert", "vert")). Forwarded to impute() / preprocess_traits(). Default NULL.

log_transform

logical. Log-transform every continuous trait whose observed values are all positive (default TRUE), then back-transform the imputations. Set it to FALSE when traits are already on a log scale (for example log body mass): otherwise they are logged a second time and imputed on a log(log) scale, which can bias analyses done on the log scale. With a mix of raw and already-logged traits, log the raw ones yourself and set FALSE. In a real-data check (PanTHERIA, 4,027 mammal species, four already-logged traits, posterior draws), the default shifted Rubin-pooled regression slopes by up to 3.9 standard errors of the complete-data slope, in a direction that depended on which values were missing; with FALSE the largest shift was 1.8.

missing_frac

numeric. Fraction of observed cells held out for validation/test during training (default 0.25). Passed through to impute().

covariates

data.frame or matrix of fully observed environmental covariates. For "mc_dropout" and "conformal" diagnostic draws, forwarded to impute(): a selected per-column numeric BM baseline may use them even with gnn = FALSE. Joint MVN and threshold-joint baselines omit them and emit a separate baseline warning. One-versus-rest categorical baselines also omit them but do not trigger that warning themselves. In a mixed fit, another selected joint route can still trigger it. With gnn = TRUE, they also enter the GNN and additive linear component. Choosing predict_method = "per_column" within a joint fit does not enable covariate regression. The posterior sampler is a separate model route; see its eligibility requirements below. Default NULL.

epochs

integer. Maximum GNN training epochs (default 2000).

verbose

logical. Print progress (default TRUE).

seed

optional integer. When supplied, makes fitting and imputation draws reproducible; the default NULL uses the current RNG stream.

gnn

logical. Passed through to impute() / fit_pigauto(). When TRUE, the usual GNN correction is trained. When FALSE (default), no GNN is used (baseline-only fit; see fit_pigauto()). With draws_method = "mc_dropout" this uses independent latent-cell Gaussian perturbations scaled by baseline SD, with no GNN dropout; an explanatory message is printed for that call. These are not joint BM posterior draws; draws_method = "conformal" is unaffected. Covariate use is route-dependent as described above; the warning under gnn = FALSE does not rule out covariate-aware per-column BM predictions/draws.

lambda_mode

character. Pagel-lambda mode for the BM baseline, forwarded to impute() / fit_pigauto(). "estimate" (default) fits a per-trait Pagel's lambda on each continuous-family (BM-eligible) latent column. Discrete traits estimate their own lambda by default (discrete_lambda = "estimate", passed through ... to impute()); set discrete_lambda = "fixed_1" to retain lambda = 1 for their baseline. Joint exact prediction can also use a shared lambda_block for its cross-trait conditional. "fixed_1" preserves the pre-lambda Brownian correlation matrix everywhere; "cv" and "bayes" are alternative per-column estimators. See fit_pigauto() for the full contract, including the predict_method = "exact" / joint_refine_iter > 0 interaction with lambda_block.

posterior_control

list of settings for draws_method = "posterior" (ignored otherwise). Elements, with defaults:

n_chains: 4L. Number of MCMC chains. Chain 1 starts at the per-trait REML Pagel's lambda clamped to [0.02, 0.98] (up to 2,000 tips; above that, or if the REML fit fails, at lambda = 0.9), and the other chains start from values dispersed around it. mi$posterior$start holds the REML lambda and chain 1's lambda before clamping.
n_iter: 5000L. Sweeps per chain after burn-in.
burnin: 1000L. Burn-in sweeps per chain (also used to tune the Metropolis step sizes).
thin: Default: n_iter integer-divided by ceiling(keep_draws / n_chains), so that the chains together keep keep_draws sweeps.
keep_draws: 1000L. Target number of kept posterior predictive draws across chains, used for the per-cell intervals. Must be at least m. The default thin keeps at least this many whenever n_iter is at least ceiling(keep_draws / n_chains). If a user-set n_iter or thin keeps fewer (but at least m), a warning is raised and the intervals use the sweeps that were kept; keeping fewer than m is an error.
param_uncertainty: "full" (default), "none" or "both". "none" is an improper plug-in mode for validation only: the covariance matrices are fixed at their posterior means from a full run, and only the missing cells (and the trait means) are drawn. Its result carries mi_workflow = "pigauto_posterior_plugin_diagnostic", and with_imputations() and pool_mi() refuse it. "both" is also for validation only: it runs the sampler once and returns the proper results exactly as "full" does, plus the plug-in draws from the same run in mi$posterior_improper.
seed: Integer or NULL. Defaults to seed.
auto_extend: TRUE. If the chains fail the convergence rule (any split R-hat at least 1.05 or any bulk ESS at most 400), every chain continues from where it stopped for another n_iter sweeps and the diagnostics are recomputed on all sweeps after burn-in; this repeats until the rule is met or max_extend extensions have been made. Burn-in is not repeated and the Metropolis step sizes stay as tuned in burn-in, so an extended chain is the same chain as one run longer from the start. After k extensions the kept draws are every thin * (k + 1)-th sweep, spread over the whole run, so their number does not change. A fit that meets the rule first time is not affected. FALSE never extends.
max_extend: 3L. Maximum number of extensions, a whole number from 0 to 10. The default allows at most 4 times n_iter sweeps per chain after burn-in.
residual_prior: "sep" (default) or "iw". The default separation strategy uses half-Cauchy priors for residual standard deviations, scaled by the trait's observed latent-trait standard deviation, and an LKJ(1) prior for the full residual-correlation matrix. Before applying the numerical cutoff, the LKJ(1) prior does not give each pairwise correlation a uniform distribution when there are more than two traits. The cutoff also narrows the prior support; see the posterior-draw details. "iw" selects the legacy inverse-Wishart prior used before pigauto 0.11.0.9002; it is retained for reproducing earlier results.

...

additional arguments forwarded to fit_pigauto() via impute(). See fit_pigauto() for the full list, including the optional safety_floor control described below.

ordinal_levels

named list giving the scientific order of ordinal levels, e.g. list(status = c("LC", "NT", "VU", "EN", "CR")). Each named column is coerced to an ordered factor with exactly those levels before type detection, and the completed datasets return it as an ordered factor. Observed values absent from the declared levels are an error. See impute() / read_traits(). Default NULL.

x

A stochastic-completion or posterior MI object.

Value

An object of class "pigauto_mi" with components:

datasets: A list of length m. Each element is a data.frame with the same shape and column types as the input traits; observed cells are preserved. Missing cells are filled with stochastic draws where available. A cell marked for imputation can remain NA if no prediction is available. These datasets are for prediction diagnostics, not downstream inference, except with draws_method = "posterior" (unless posterior_control$param_uncertainty = "none"), whose datasets are posterior imputations: fit the analysis to them with with_imputations() and pool the fits with pool_mi() (see posterior below and "Posterior draws").
m: Number of stochastic completion datasets.
pooled_point: A single data.frame of observed values and point completions for reporting; missing cells can remain NA when no prediction is available. It is the point completion returned by the selected route, not generally an average of the m decoded datasets. Use datasets for an eligible downstream multiple-imputation analysis. For the posterior route, missing-cell values decode the mean latent value over retained posterior predictive draws, not necessarily the m returned datasets.
se: Matrix of per-cell uncertainty summaries. For the conformal and MC-dropout routes, these come from the prediction step; for posterior draws, they are original-scale posterior predictive standard deviations calculated from all retained draws. Their meaning depends on the method and trait type, and they need not describe the spread among the returned datasets. They are descriptive, not Rubin's-rules pooled standard errors, and must not be used for downstream pooling.
draws_method: The method actually used, including the selected method when draws_method = "auto".
Diagnostic prediction outputs: The conformal_lower, conformal_upper, probabilities, and evaluation components are returned for the conformal and MC-dropout routes, not the posterior route.
conformal_lower, conformal_upper: For diagnostic routes, lower and upper prediction-bound matrices when conformal scores are available. A bound matrix may contain NA for traits without scores; both components are NULL when no score object is available. See predict.pigauto_fit() for scale and trait-specific interpretation.
probabilities: For diagnostic routes, a named list of class probabilities and, for a multi_proportion trait when only one prediction run is returned, component proportions. See predict.pigauto_fit() for the per-type shapes.
evaluation: For diagnostic routes, validation- and test-set evaluation metrics from the underlying imputation fit. This is NULL when there are no test cells or when evaluation fails.
Prediction row order: On diagnostic routes, se, the bound matrices, and probability rows follow the fitted model's internal row order. data$input_row_order[k] gives the original input row placed at internal row k; NA marks a tree tip without an input row; use order(data$input_row_order, na.last = NA) to restore input-row order. datasets and pooled_point use original input row order. Posterior- route se uses original input row order.
mi_workflow: Method-dependent provenance. Prediction-diagnostic conformal and MC-dropout draws use "pigauto_diagnostic_mi". Eligible posterior draws with parameter uncertainty use "pigauto_posterior_mi_v1" and can enter with_imputations() and pool_mi() under the documented posterior-route conditions. Posterior draws with param_uncertainty = "none" use "pigauto_posterior_plugin_diagnostic": covariance matrices are fixed while trait means and missing cells are drawn, and these draws remain ineligible for downstream pooling.
imputed_mask: Logical matrix aligned to the input rows and trait columns; TRUE marks an originally missing target in a row included in the fit, not necessarily a successful fill. A marked cell can remain NA if no prediction was available. When species_col is supplied, its column is excluded.
fit: The underlying pigauto_fit object, retained for diagnostics and calls to predict() on the fitted data. New-species prediction is not implemented.
data: The pigauto_data object.
tree: The input phylogeny.
species_col: Passed-through species-column name or NULL.
posterior: draws_method = "posterior" only. A list with cell_interval (data.frame: row (row of traits), trait, lower, upper, median; 95% posterior predictive interval on the original scale), diagnostics (data.frame: parameter, rhat, ess_bulk, with attributes "converged", "n_extensions" (the number of automatic extensions made) and "sweeps_per_chain" (the sweeps after burn-in per chain that the diagnostics use)), params (list: Sigma_P and Sigma_E as K x K x draws arrays, lambda and mu as draws x K matrices, on the latent scale), converged, control, hyper (priors), start (REML lambda and chain-1 start lambda, before clamping to [0.02, 0.98]), draw_index (kept sweeps used for the m datasets), wall_s and sweeps (all sweeps, burn-in included, summed over chains). For this method fit is NULL, se holds the posterior predictive SD of each imputed cell, the class is c("pigauto_posterior_mi", "pigauto_mi", "list") and mi_workflow is "pigauto_posterior_mi_v1" ("pigauto_posterior_plugin_diagnostic" with posterior_control$param_uncertainty = "none", which with_imputations() and pool_mi() refuse).
posterior_improper: Only with posterior_control$param_uncertainty = "both" (validation only). A list with datasets (m data.frames drawn with the covariance matrices fixed at their posterior means, with the same missing-cell limits described above, from the same chain run as datasets), cell_interval (same columns as posterior$cell_interval), and the fixed Sigma_P and Sigma_E. Not for downstream inference: it ignores parameter uncertainty.

The print method returns x invisibly.

Details

For continuous traits, draws_method = "posterior" instead returns posterior predictive draws that the documented software route permits analysts to fit and pool under the conditions below.

Validation boundary: the registered validation found five of eight tested posterior-slope regimes failed and three were indeterminate; none met the support criteria. These results are limited to the tested regimes and do not establish performance for a new analysis. See the registered inferential results before using with_imputations() and pool_mi(). The separate analysis-aware backend, multi_impute_analysis(), covers its own documented narrow regime.

With the default draws_method = "auto", eligible continuous-trait data use posterior draws; other inputs use conformal prediction-diagnostic draws. Check result$draws_method before downstream fitting.

The conformal and MC-dropout draws do not condition on a declared substantive analysis model. Consequently, stochastic variation alone does not make them proper or congenial multiple imputations. The analysis-aware backend requires the analysis model before generating draws and dispatches only across its documented supported model classes.

draws_method = "conformal": Run the model once. For a continuous latent column standardized to mean zero and unit variance, missing values are sampled as $z_{ij}^{(k)} \sim \mathrm{N}(\hat z_{ij},\; (q_{ij}/1.96)^2)$. Here $q_{ij}$ is the available split-conformal score: the global trait score or, with Mondrian calibration, the near/far score for cell $i$. Other trait types use their type-specific latent representation and decoding described below. Dividing the score by 1.96 is a pragmatic Normal-scale construction, not an inference consequence of a nominal held-out conformal diagnostic. For discrete traits (binary, categorical) it uses Bernoulli / categorical draws from the estimated probability vector. For zi_count the gate is Bernoulli from P(nonzero) and the conditional magnitude is drawn on the log1p-z latent using the conformal score (or the magnitude latent SE when scores are unavailable) — not the reported SE of expected count. For multi_proportion groups it draws the K CLR latent columns with their BM latent SEs, projects back to sum-zero CLR space, and decodes to the simplex.

draws_method = "mc_dropout": Add independent Gaussian perturbations per latent cell, scaled by selected baseline SD. This returns M stochastic draws; when the GNN is enabled, its network runs use dropout in training mode. These are prediction-diagnostic draws, not joint phylogenetic BM posterior draws or validated downstream-inference imputations. A baseline perturbation can contribute variation when the GNN weight is zero, but this does not guarantee non-zero variation.

draws_method = "posterior": see the "Posterior draws" section.

Nakagawa & Freckleton (2008, 2011) provide ecological missing-data context. Their full-text passages were not verified for a blanket recommendation about this workflow; they do not establish validity of pigauto draws.

When to use this

With draws_method = "conformal" or "mc_dropout", this function is useful for comparing stochastic prediction behavior from one tree; those draws are not for downstream inference. With draws_method = "posterior" (continuous traits), it returns posterior predictive draws that the documented software route permits analysts to fit and pool under the conditions in "Posterior draws". This software eligibility does not establish model compatibility or inferential performance across regimes; the registered validation had five tested slope regimes fail and three remain indeterminate. with_imputations() fits eligible analyses and pool_mi() pools those fits. multi_impute_analysis() is the separate analysis-aware backend for its own documented regime.

multi_impute_trees() provides an experimental posterior-tree sensitivity check. Its outputs are diagnostic and are not accepted by with_imputations() or pool_mi(), so tree-aware downstream inference is not currently supported.

Posterior draws

With draws_method = "posterior", the latent (z-scored, optionally log-transformed) traits follow the multivariate phylogenetic mixed model $$\begin{aligned} \mathrm{vec}(Y) &\sim \mathrm{N}(\mathrm{vec}(1_n\mu^\top),\\ &\quad \Sigma_P \otimes R + \Sigma_E \otimes I_n), \end{aligned}$$ where $Y$ is the $n$-species by $K$-trait matrix, $\mu$ is the vector of $K$ trait means, and $\mathrm{vec}$ stacks matrix columns. Here $1_n$ is an $n$-vector of ones, $R$ is the phylogenetic correlation matrix of the tree, and $I_n$ is the $n \times n$ identity matrix. The model uses full $K \times K$ phylogenetic ($\Sigma_P$) and residual ($\Sigma_E$) covariance matrices, with a flat prior on $\mu$. The implied Pagel's lambda of trait $k$ is $\Sigma_P[k,k] / (\Sigma_P[k,k] + \Sigma_E[k,k])$.

The phylogenetic covariance uses a parameter-expanded inverse-Wishart prior on its standardized covariance matrix and Normal priors on the expansion parameters. The default residual covariance prior uses a separation strategy: residual standard deviations have half-Cauchy priors scaled by the observed latent-trait standard deviations, and the full residual-correlation matrix has an LKJ(1) prior. Before applying the numerical cutoff, the LKJ(1) prior does not give each pairwise correlation a uniform distribution when there are more than two traits. For numerical stability, the sampler gives zero prior density if the smallest eigenvalue of the residual covariance matrix, standardized by observed latent-trait standard deviations, is below 0.000001. In plain language, on this standardized scale, variance along every unit-length direction must be at least 0.000001. This cutoff narrows the prior support. The legacy posterior_control$residual_prior = "iw" option instead uses an inverse-Wishart prior on the residual covariance. Prior settings are returned in mi$posterior$hyper.

The sampler draws the phylogenetic effects, the trait means and the missing cells as one block using the implementation's sparse phylogenetic node-precision Cholesky factor, and updates the covariance matrices by parameter-expanded Gibbs steps plus Metropolis moves with the phylogenetic effects integrated out. Mixing is monitored with rank-normalised split R-hat and bulk effective sample size (Vehtari et al. 2021); mi$posterior$diagnostics reports them. Vehtari et al. recommend R-hat below 1.01. Pigauto's R-hat cutoff of 1.05 is less strict than the paper's recommendation; its bulk-ESS cutoff is 400. When any R-hat is at least 1.05 or any ESS is at most 400, the chains are extended automatically (posterior_control$auto_extend and max_extend), and a warning is raised if the rule still fails after the last extension. These diagnostics cover the monitored elements of Sigma_P, Sigma_E and lambda; they do not establish adequate precision for every posterior quantile or validate the sampler.

Before fitting a downstream model, check attr(mi$posterior$diagnostics, "converged"). If it is not TRUE, inspect the per-parameter diagnostics and sampling controls, then refit and check again. Do not interpret or pool the draws while the flag is false or unavailable. Passing this package-specific convergence rule does not establish calibrated downstream inference.

Evidence scope. The earlier Rubin-study campaign used pigauto b565cad and subsequent separation-prior refits, 200 datasets per cell, n = 100, 300 or 1000, lambda = 0.3, 0.7 or 1, trait correlation 0 or 0.5, and 30% MCAR missingness. Its downstream targets were PGLS slopes and phylogenetic correlations; the coverage claims above belong to that study and distinguish the legacy IW from the separation prior. The separate posterior acceptance sweep used 40 regimes and its own gate rules. The later registered validation froze a different source and used the default separation prior. Its eight posterior slope regimes used Brownian GLS, n = 300 or 1000, lambda = 0.5 or 1, trait correlation 0.7, 30% missingness under MCAR or phylogenetic MAR, and 500 replicates per regime. Five failed and three were indeterminate; empirical 95% coverage ranged from 86.2% to 95.2%. No inferential scenario met all prespecified support criteria. These campaigns should be compared within their stated models, priors, missingness and acceptance rules. Bayesian properness under the stated model does not by itself establish that an applied analysis is calibrated.

The m datasets are posterior predictive draws spaced evenly across the kept sweeps of all chains. Per-cell 95% intervals in mi$posterior$cell_interval come from all kept sweeps (keep_draws of them by default), never from the m datasets.

These draws come from a linear-Gaussian model of the imputed traits on the scale where they were imputed (the log scale for traits log-transformed by log_transform). The documented software route permits downstream fitting only under the stated eligibility conditions: analyses must be linear in the imputed traits on that scale and use variables among the imputed traits. This fitting eligibility does not establish model compatibility or inferential performance across analyses or tested regimes. In the registered validation, five posterior slope regimes failed and three were indeterminate; see the registered inferential results. Each imputed trait must also have at least two observed values among the rows being fitted; otherwise posterior mode stops and names the affected traits. This minimum is a software requirement, not evidence that two observations are enough for reliable estimation. Not covered: covariates from outside the imputed traits, because the imputation model does not contain them; nonlinear terms (such as squares) or interactions among imputed traits; and analysing a log-transformed trait on its raw scale. The GNN is not used, and gnn, epochs, missing_frac, lambda_mode and other fitting arguments are ignored (a message lists any that were supplied). Non-continuous traits, multiple observations per species (or any species_col), covariates, and input with no missing cells in the rows of traits (tree tips absent from traits do not count) are errors.

Optional safety floor

When fit_pigauto() is called with safety_floor = TRUE (opt-in; the default is FALSE), the 3-way blend r_BM * BM + r_GNN * GNN + r_MEAN * MEAN propagates through prediction-diagnostic draws through predict.pigauto_fit(). The posterior sampler uses its own model and does not use this blend. For draws_method = "mc_dropout" the mean term contributes no between-draw variance (it is a deterministic scalar per column); between-draw variance comes from the independent baseline perturbations and, when enabled, GNN-dropout terms only. For draws_method = "conformal" the blend centre is the 3-way prediction and conformal scores remain calibrated on the blended residuals.

Printing

Prints diagnostic or posterior/convergence summaries. Cell counts refer to targeted cells; a targeted cell can remain missing if a prediction is unavailable. Displaying an object does not authorize downstream pooling. The ... argument is currently unused.

References

Rubin DB (1987). Multiple Imputation for Nonresponse in Surveys. Wiley.

Nakagawa S, Freckleton RP (2008). "Missing inaction: the dangers of ignoring missing data." Trends in Ecology & Evolution 23(11): 592-596.

Gelman A (2006). "Prior distributions for variance parameters in hierarchical models." Bayesian Analysis 1(3): 515-534.

Hadfield JD (2010). "MCMC methods for multi-response generalized linear mixed models: the MCMCglmm R package." Journal of Statistical Software 33(2): 1-22.

Hadfield JD, Nakagawa S (2010). "General quantitative genetic methods for comparative biology: phylogenies, taxonomies and multi-trait models for continuous and categorical characters." Journal of Evolutionary Biology 23(3): 494-508.

Vehtari A, Gelman A, Simpson D, Carpenter B, Buerkner P-C (2021). "Rank-normalization, folding, and localization: an improved R-hat for assessing convergence of MCMC." Bayesian Analysis 16(2): 667-718.

Nakagawa S, Freckleton RP (2011). "Model averaging, missing data and multiple imputation: a case study for behavioural ecology." Behavioral Ecology and Sociobiology 65(1): 103-116.

The references provide methodological context for priors, phylogenetic models and MCMC diagnostics. They do not establish pigauto's exact prior specification, sampler correctness or package-specific diagnostic thresholds. The "Posterior draws" section describes the implementation and retained campaign evidence separately.

Examples

# \donttest{
library(pigauto)
data(avonet300, tree300)
tree <- ape::keep.tip(tree300, tree300$tip.label[seq_len(30L)])
df <- avonet300[match(tree$tip.label, avonet300$Species_Key),
                c("Mass", "Wing.Length"), drop = FALSE]
rownames(df) <- tree$tip.label
df$Mass[seq_len(3L)] <- NA_real_
mi <- multi_impute(df, tree, m = 2L, draws_method = "conformal",
                   epochs = 5L, verbose = FALSE)
#> Warning: Small validation set for 2 trait(s): Mass (n=4), Wing.Length (n=3). Calibrated gate and conformal scores will be noisy for these trait(s). 95% split-conformal coverage is NOT achievable for 2 trait(s) with fewer than 19 validation cells (Mass (n=4), Wing.Length (n=3)): the achievable ceiling is n_val / (n_val + 1), which only reaches 0.95 at n_val >= 19. See `?fit_pigauto` under 'Calibration at small n' for smoothing options.
print(mi)
#> pigauto experimental stochastic completion diagnostics
#>   M        : 2 completion draws (conformal-width sampling)
#>   Species  : 30
#>   Traits   : 2 -- Mass, Wing.Length
#>   Cells    : 3 targeted / 60 total (5.0%)
#> 
#>   Access diagnostic draws:  mi$datasets[[i]]
#>   Downstream inference:     unsupported for these draws
#>   Analysis-aware MI:        multi_impute_analysis(...)
lapply(mi$datasets, head)
#> [[1]]
#>                               Mass Wing.Length
#> Nothoprocta_pentlandii    67.71273       148.2
#> Eudromia_formosa         138.21793       223.9
#> Rhea_americana          3648.45309       604.5
#> Ptilopachus_petrosus     193.00000       117.2
#> Bambusicola_fytchii      313.70000       142.8
#> Francolinus_psilolaemus  478.30000       167.3
#> 
#> [[2]]
#>                              Mass Wing.Length
#> Nothoprocta_pentlandii   143.8096       148.2
#> Eudromia_formosa         234.9331       223.9
#> Rhea_americana          2562.2431       604.5
#> Ptilopachus_petrosus     193.0000       117.2
#> Bambusicola_fytchii      313.7000       142.8
#> Francolinus_psilolaemus  478.3000       167.3
#> 
# }