vimpute_spec: Per-variable imputation specification for 'vimpute()'

In VIM: Visualization and Imputation of Missing Values

Per-variable imputation specification for vimpute()

Description

Bundles everything vimpute() can configure for a single variable – method, learner parameters, formula or predictors, tune, PMM settings, makeNA values and a donorcond donor condition – into one object, instead of coordinating up to nine parallel per-variable arguments. Pass a named list of specs as vimpute(spec = ); the reserved name ".default" supplies the spec for variables not listed (its method, learner parameters and tune/PMM knobs; formula/predictors/makeNA/ donorcond are variable-specific and not allowed in ".default").

Usage

vimpute_spec(
  method,
  ...,
  formula = NULL,
  predictors = NULL,
  tune = FALSE,
  pmm = FALSE,
  pmm_k = NULL,
  pmm_k_method = NULL,
  makeNA = NULL,
  donorcond = NULL,
  uncert = NULL
)

vs_ranger(...)

vs_xgboost(...)

vs_regularized(...)

vs_robust(...)

vs_gam(...)

vs_robgam(...)

## S3 method for class 'vimpute_spec'
print(x, ...)

Arguments

method	Single string: a registered imputation method (see vimpute_methods()).
...	Named learner parameters for the method's learners (e.g. num.trees = 500 for "ranger"), validated eagerly.
formula	One-sided (~ x1 + s(x2)) or two-sided formula for the variable's model; only for methods with formula support. A one-sided formula is completed with the variable as its left-hand side.
predictors	Character vector of predictor columns (the predictors equivalent, works for every method). A spec takes either formula or predictors, not both.
tune	Logical: tune this variable's learner (see vimpute_tune_control()).
pmm	Logical: predictive mean matching for this (numeric) variable.
pmm_k	NULL or a positive integer: PMM donor count.
pmm_k_method	NULL, "mean", "median", "random", or a function: PMM aggregation when pmm_k > 1.
makeNA	NULL or a vector of values to be treated as missing for this variable (as in vimpute(makeNA = )).
donorcond	NULL or a donor condition string such as ">= 0" (as in vimpute(donorcond = )).
uncert	Not a spec knob – set uncert on the vimpute() call; supplying it here errors (it guards against silently treating it as a learner parameter).
x	A vimpute_spec object

Details

Learner parameters in ... are validated eagerly against the method's learner parameter sets, so a typo fails at the constructor call, not in iteration 7 of the imputation. vs_ranger(), vs_xgboost(), vs_regularized(), vs_robust(), vs_gam() and vs_robgam() are shorthands for the built-in methods; methods added via register_vimpute_method() use vimpute_spec("<name>", ...).

A variable with a spec uses that spec's settings exactly (no field-level merging with ".default"). uncert remains a call-level argument of vimpute() and is not a spec knob.

Value

An object of class vimpute_spec.

See Also

vimpute(), register_vimpute_method()

Examples

## Not run: 
data(sleep)
res <- vimpute(sleep,
  spec = list(
    Sleep    = vs_ranger(num.trees = 300, tune = TRUE),
    NonD     = vs_robust(donorcond = ">= 0"),
    .default = vs_ranger()
  ),
  seed = 1)

# the same, as formula grammar:
res2 <- vimpute(sleep,
  Sleep ~ . | ranger(num.trees = 300, tune = TRUE),
  NonD  ~ . | robust(donorcond = ">= 0"),
  .default = vs_ranger(),
  seed = 1)

## End(Not run)

VIM documentation built on Sept. 2, 2026, 5:07 p.m.