future_mids: Parallelize ”mice::mice.mids()” Using '{future}'

In jesse-smith/futuremice: A Future for MICE

Parallelize 'mice::mice.mids()' Using {future}

Description

future_mids() is analogous to mice::mice.mids(), but parallelizes chains using the {furrr} package and stops early if convergence is detected using the R-hat statistic (see the future_mice() documentation for details).

Usage

future_mids(
  obj,
  newdata = NULL,
  maxit = 100L,
  minit = min(5L, maxit),
  quiet = FALSE,
  chunk_size = 1L,
  rhat_max = 1.05,
  progressor = NULL,
  update_call = TRUE,
  ...
)

Arguments

obj	A mids object, as created by mice::mice(), future_mice(), or future_mids() (this function)
newdata	An optional data.frame for which multiple imputations are generated according to the model in obj.
maxit	The number of additional Gibbs sampling iterations.
minit	The minimum number of iterations to run. This is also the number of iterations used to assess convergence. Convergence is defined as all(tail(rhat, minit) < rhat_max).
quiet	Should convergence messages and warning be suppressed?
chunk_size	The average number of chains per future. Differs from the usual {future} parameter in that multiple chains ("chunks") will be evaluated in a single call to mice::mice() if there is an integer i such that ⁠1 < i <= chunk_size⁠ and m %% i == 0.
rhat_max	The R-hat threshold used to assess convergence. Convergence is defined as all(tail(rhat, minit) < rhat_max).
progressor	An optional progressor function to signal progress updates. If supplied, you are responsible for ensuring that the number of steps in the progressor is consistent with the number of iterations performed in future_mice().
update_call	Should mids$call be set to new future_mids() call or left unchanged?
...	Named arguments that are passed down to the univariate imputation functions.

Value

Returns an S3 object of class mids (multiply imputed data set)

Examples

# Run in parallel (just two cores to avoid hogging resources)
# Picking a number of workers that divides `m` evenly can help performance
future::plan("multisession", workers = pmin(2L, future::availableCores()))

# Run `mice::mice()`
# `m` and `maxit` are small here to keep runtime short
mids <- mice::mice(mice::nhanes, m = 2L, maxit = 1L)

# Run for additional iteration
mids <- future_mids(mids, maxit = 1L)

## Not run: 
# Run until convergence
mids <- future_mids(mids, maxit = 100L)
mids

## End(Not run)

# Reset future plan
future::plan("sequential")

jesse-smith/futuremice documentation built on Nov. 24, 2023, 7:19 a.m.