Fit a downstream model on every imputed dataset

Apply a user-supplied model-fitting function .f to each of the M complete datasets stored in an analysis-aware MI object and return the list of fits. This is the documented software fitting entry for multi_impute_analysis() and for multi_impute() with draws_method = "posterior". Prediction-diagnostic ("conformal", "mc_dropout") and posterior-tree sensitivity completions stop with an actionable error before any model is fitted. The workflow is experimental and limited to fixed-effect coefficients and their covariance matrices. Passing software eligibility checks means the package permits fitting; it does not establish inferential performance across tested regimes or compatibility with every downstream model.

Usage

with_imputations(
  mi,
  .f,
  ...,
  .progress = interactive(),
  .on_error = c("continue", "stop")
)

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

Arguments

mi: A pigauto_analysis_mi object returned by multi_impute_analysis(), or a pigauto_posterior_mi object returned by multi_impute() with draws_method = "posterior" (and param_uncertainty = "full", the default, or "both"). Legacy pigauto_mi objects, diagnostic completions, tree-sensitivity completions, plug-in posterior draws, and bare dataset lists are not supported fitting inputs.
.f: A function of the form function(dataset, ...) that fits a model to one complete data.frame and returns a model object. pool_mi() supplies automatic fixed-effect adapters for its documented model classes. Other classes require coef() and vcov() methods that return compatible fixed-effect quantities, or explicit extractor functions supplied to pool_mi(); extractability does not imply that an unlisted analysis model has passed the analysis-aware validation gate.
...: Additional arguments passed to .f for every imputation.
.progress: Logical. Show a text progress indicator (default TRUE in interactive sessions).
.on_error: One of "continue" (default) or "stop". When "continue", errors from .f are captured per imputation and the loop proceeds; a warning at the end summarises failures. When "stop", the first error aborts the entire run.
x: A list of downstream imputation fits.

Value

A list of length M with class "pigauto_mi_fits". Each element is either a model fit or, if .f errored on that imputation and .on_error = "continue", an object of class "pigauto_mi_error" containing the captured condition. pool_mi() filters error elements automatically.

The print method returns x invisibly.

Posterior draws and congeniality

The draws_method = "posterior" completions come from a linear-Gaussian phylogenetic mixed model of the imputed traits only, on the scale where they were imputed (the log scale for traits log-transformed by log_transform). The documented software route permits fitting analyses that are linear in the imputed traits on that scale and whose variables are among the imputed traits. This eligibility does not establish that an analysis model is compatible with the imputation model or that inference is calibrated. In the registered validation, five tested posterior slope regimes failed and three were indeterminate; see the registered inferential results. The route has not established support outside its measured regimes. Not covered: covariates from outside the imputed traits, nonlinear terms (such as squares) or interactions among imputed traits, and analysing a log-transformed trait on its raw scale. The formula passed to .f is not checked; this is the analyst's responsibility. Plug-in draws from posterior_control$param_uncertainty = "none" (validation only) are refused.

Printing

Prints successful and failed fit counts and the first successful fit class. Failed elements remain in the list until pooling removes them. The ... argument is currently unused.

Examples

# \donttest{
dat <- data.frame(y = stats::rnorm(30L), x = stats::rnorm(30L),
                  z = stats::rnorm(30L))
dat$x[seq(3L, 30L, by = 5L)] <- NA_real_
# Workflow example only: m = 2L is not an analysis recommendation.
# Choose enough imputations to make Monte Carlo error small relative to
# the standard errors you report.
mi <- multi_impute_analysis(
  data = dat, formula = y ~ x + z, missing = "x",
  model = "lm", m = 2L
)
fits <- with_imputations(mi, function(d) stats::lm(y ~ x + z, data = d))
pool_mi(fits)
#> Pooled estimates from 2 multiply-imputed fits (Rubin's rules)
#> Confidence level: 95%
#> 
#>         term estimate std.error      df statistic p.value conf.low conf.high
#>  (Intercept)   0.1046    0.1413  15437.    0.7405  0.4590  -0.1723    0.3816
#>            x -0.03633    0.1622   65.63   -0.2240  0.8234  -0.3601    0.2875
#>            z  0.07160    0.1435 167141.    0.4991  0.6177  -0.2096    0.3528
#>       fmi      riv
#>  0.008177 0.008114
#>    0.1490   0.1408
#>  0.002458 0.002452
# }