Impute a Data Frame by Sweeping `missRanger` Over `mtry`

Runs [missRanger::missRanger()] once for every candidate `mtry`, then keeps, **for each column independently**, the imputation from whichever `mtry` minimised that column's out-of-bag prediction error. The `ranger`-based counterpart to [missforest_sweep_mtry()], with the same return shape so the two engines can be compared on one data set.

Usage

missranger_sweep_mtry(
  data,
  exclude = NULL,
  mtry_values = NULL,
  num.trees = 500,
  pmm.k = 0,
  maxiter = 10,
  seed = NULL,
  num.threads = 1,
  max_pct_missing = NULL,
  parallel = TRUE,
  checkpoint_dir = NULL,
  shard = NULL,
  checkpoint_mismatch = c("recompute", "overwrite", "error")
)

Arguments

data: A data frame or tibble to impute. After `exclude` is applied, any remaining column that is entirely `NA` is refused with an error.
exclude: Character vector of columns to hold out of the imputation entirely – typically subject identifiers and time columns. They are removed before fitting and re-attached, unchanged, to the result. Default `NULL`. A name that is not a column of `data` is an error, so a misspelt identifier cannot stay in the predictor set unnoticed.
mtry_values: Integer vector of `mtry` values to sweep. Defaults to `1:missranger_max_mtry(data)`. Note this is **not** `1:(p - 1)`, the `missForest` bound – see [missranger_max_mtry()] for why, and expect a shorter sweep than [missforest_sweep_mtry()] performs on the same data.
num.trees, pmm.k, maxiter, num.threads: Passed to [missranger_oob_by_mtry()].
seed: Integer seed passed to every fit in the sweep, or `NULL` (default) for an unseeded sweep. See Reproducibility.
max_pct_missing: Optional proportion in `(0, 1]`. Columns missing a greater share than this are held out of the imputation and carried through unimputed, and are reported in `excluded_high_missing`. `NULL` (the default) imputes every column regardless of how sparse it is. Imputing a column observed in a handful of rows manufactures values rather than recovering them, and nothing downstream can tell the difference; a threshold states that judgement as a rule that carries to the next data set, instead of naming the offending column inline. Note a threshold below `1` subsumes the all-`NA` refusal, since an all-`NA` column exceeds every threshold.
parallel: Whether to evaluate the sweep with [furrr::future_map()]. Default `TRUE`. When `FALSE`, runs sequentially via [purrr::map()].
checkpoint_dir: Optional directory path where per-task checkpoints are stored.
shard: Optional shard specification (e.g. `c(1, 2)`) for distributed computation.
checkpoint_mismatch: Action on mismatch: `"recompute"`, `"overwrite"`, or `"error"`.

Value

A list of four elements, matching [missforest_sweep_mtry()]:

`imp_data`: A tibble of the imputed data, with `exclude` columns re-attached and the original column order restored. Character and logical columns retain their original classes. Integer columns with imputed values are returned as numeric/double because random forest predictions are continuous.
`oob_error`: A tibble of every imputed column's OOB error at every swept `mtry`.
`best`: The winning row per imputed column. A column whose error is missing at every `mtry` cannot be ranked: it keeps its first row, with a missing `error`, and a warning names it. When no column has missing values nothing is scored, and `oob_error` and `best` are empty tables.
`excluded_high_missing`: Columns held out by `max_pct_missing`, carried through unimputed. `character(0)` when none were.

Details

**`best$error` is a selection criterion, not an error estimate.** `best$error` is the minimum of OOB prediction errors computed over the swept `mtry` grid on the same observed cells, with predictors that were themselves iteratively imputed. It is optimistically biased and should be used strictly for model selection, not reported as an unbiased estimate of imputation accuracy.

Reproducibility

The same `seed` is passed to every fit in the sweep. That is deliberate: holding the seed fixed across `mtry` values is a common-random-numbers comparison, so differences in OOB error reflect `mtry` rather than sampling noise between runs. Because `missRanger` seeds itself, a seeded sweep is reproducible independently of the `future` plan and the number of workers – the property a mixed Windows/Linux/arm64 fleet needs – without depending on L'Ecuyer stream management. `furrr`'s own parallel-safe seeding is still enabled, which covers the unseeded case. A seeded sequential sweep (`parallel = FALSE`) restores the caller's random number state when each fit finishes, so it does not disturb later draws in the calling code. When `seed` is an integer, caller's `.Random.seed` is restored on exit for both sequential and parallel modes.

Parallel plan

This function never calls [future::plan()] – the appropriate backend differs by machine, and choosing one here would override the caller's. Set a plan before calling. Note that `num.threads` defaults to `1` so that `ranger`'s own threading does not nest inside the sweep; see [missranger_oob_by_mtry()]'s Threading section.

Examples

# \donttest{
if (requireNamespace("missRanger", quietly = TRUE)) {
  df <- data.frame(
    id = 1:12,
    a = c(1, 2, NA, 4, 5, 6, NA, 8, 9, 10, 11, NA),
    b = c(2, 4, 6, NA, 10, 12, 14, NA, 18, 20, NA, 24),
    c = c(5, 4, 3, NA, 1, 2, 3, 4, 5, NA, 3, 2)
  )
  res <- missranger_sweep_mtry(
    df, exclude = "id", num.trees = 50, seed = 42, parallel = FALSE
  )
  res$best
}
#> # A tibble: 3 × 4
#>   column error_type error  mtry
#>   <chr>  <chr>      <dbl> <int>
#> 1 c      1-R2        1        1
#> 2 a      1-R2        1.47     1
#> 3 b      1-R2        1.13     1
# }