Skip to contents

Fit a downstream model on every imputed dataset

Source: R/with_imputations.R
with_imputations.Rd

Apply a user-supplied model-fitting function .f to each of the M complete datasets stored in a pigauto_mi object and return the list of fits. For inference, use an object returned by multi_impute_analysis(); conformal-width, Brownian/MC-dropout, and PMM prediction-diagnostic draws are unsupported. The analysis-aware workflow is experimental and is limited to fixed-effect coefficients and their covariance matrices.

Usage

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

Arguments

mi

A pigauto_mi object returned by multi_impute_analysis(). Plain lists of data.frames are also accepted and treated as the datasets slot directly.

.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. When mi comes from multi_impute_trees(), .f may also declare explicit tree, tree_index, or imputation arguments; these are filled with the posterior tree object, its index in mi$trees, and the stochastic-completion index. The dataset also carries matching attributes. This metadata support is for prediction-sensitivity diagnostics only; tree-aware downstream inference is unsupported.

...

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.

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.

See also

multi_impute_analysis(), pool_mi()

Examples

if (FALSE) { # \dontrun{
mi <- multi_impute_analysis(
  data = df, formula = y ~ x + z, missing = "x",
  model = "lm", m = 50L
)

fits <- with_imputations(mi, function(d) stats::lm(y ~ x + z, data = d))

pool_mi(fits)

} # }