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

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)
#> 
#>  iter imp variable
#>   1   1  bmi  hyp  chl
#>   1   2  bmi  hyp  chl

# Run for additional iteration
mids <- future_mids(mids, maxit = 1L)
#> Warning: Sampling did not converge in 2 iterations
#> R-hat: NA

if (FALSE) {
# Run until convergence
mids <- future_mids(mids, maxit = 100L)
mids
}

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