vimpute_spec: 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 vimpute_spec
print(x, ...)

Value

An object of class vimpute_spec.

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.

Examples

Run this code

if (FALSE) {
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)
}