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

# \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_
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.04433    0.1463 126724244.    0.3030  0.7619  -0.2424    0.3310
#>            x  -0.1269    0.1451      335.3   -0.8744  0.3825  -0.4124    0.1586
#>            z  0.06293    0.1541    862651.    0.4083  0.6830  -0.2391    0.3650
#>         fmi        riv
#>  0.00008885 0.00008884
#>     0.06020    0.05776
#>    0.001079   0.001078
# }