register_vimpute_method: Register an imputation method for 'vimpute()'

In VIM: Visualization and Imputation of Missing Values

Register an imputation method for vimpute()

Description

vimpute() resolves its method argument through a package-level method registry. The built-in methods ("ranger", "xgboost", "regularized", "robust", "gam", "robgam", "restricted") are pre-registered; this function adds (or, with overwrite = TRUE, replaces) a user-defined method backed by any pair of mlr3 learners – e.g. regr.rpart/classif.rpart from mlr3 itself, or learners from mlr3extralearners such as lightgbm – without modifying VIM. After registration the new name can be used anywhere the built-in method names work: as a global method, in a per-variable method list, and in method-keyed learner_params.

Usage

register_vimpute_method(
  name,
  learner,
  packages = character(),
  setup = NULL,
  defaults = NULL,
  search_space = NULL,
  supports_formula = FALSE,
  fallback = "robust",
  validate = NULL,
  overwrite = FALSE
)

Arguments

name	Single character string: the method name to be used in vimpute(method = ). Must not collide with a registered method unless overwrite = TRUE. Built-in methods cannot be replaced or removed.
learner	Named list with elements regr and/or classif, each a character vector of mlr3 learner ids (candidates in preference order; the first is the default, multiple candidates are compared by cross-validation like the built-in "regularized" method). Methods registered with only a regr (or only a classif) learner fall back to fallback for target variables of the other type, with a warning.
packages	Character vector of packages that must be installed when the method is used (checked with requireNamespace() at vimpute() call time, not at registration).
setup	NULL or a function with no arguments, called once per vimpute() call before the method's learners are constructed. Use it to register custom mlr3 learners or load learner collections (e.g. function() library(mlr3extralearners)).
defaults	NULL, a named list of learner parameter values, or a function ⁠function(task_type, nthread)⁠ returning such a list (task_type is "regr" or "classif", nthread the thread count vimpute chose for the data size). User-supplied learner_params override these defaults.
search_space	NULL or a function ⁠function(learner_id, task)⁠ returning ⁠list(space = paradox::ps(...), n_evals = <integer>)⁠, consulted when tune = TRUE. Without it, tuning is skipped for the method with a warning (as for unknown learners).
supports_formula	Logical: can the method be used with the formula argument of vimpute()? Formula-based imputation requires a learner that models from a design matrix; the built-ins with formula support are "robust", "regularized", "gam", "robgam", and "restricted".
fallback	Single method name used when validate rejects a variable or a target type has no learner. Defaults to "robust".
validate	NULL or a function ⁠function(y_obs, data, variable)⁠ called during pre-checking for every variable the method is assigned to (y_obs: the observed values of the target; data: the full dataset; variable: the target's name). Return NULL to accept, a character string (the warning message) to reject towards fallback, or list(reason = , fallback = ) to reject towards a specific method. Fallbacks are validated in turn until a method accepts.
overwrite	Logical: replace an existing registration of the same name? Built-in methods can never be replaced.

Details

Uncertainty handling for registered methods: PMM (uncert = "pmm", the default, and pmm = TRUE) and uncert = "midastouch" work with any method because they only use the method's predictions. uncert = "normalerror"/"resid" and boot = TRUE derive residuals from training predictions when the model object does not expose them.

Value

Invisibly, the registered method name.

See Also

vimpute_methods(), unregister_vimpute_method(), vimpute()

Other vimpute method registry: unregister_vimpute_method(), vimpute_methods()

Examples

# a CART method backed by mlr3's rpart learners -- one call, no VIM patching
register_vimpute_method("cart",
  learner  = list(regr = "regr.rpart", classif = "classif.rpart"),
  packages = "rpart")
"cart" %in% vimpute_methods()

data(sleep)
res <- vimpute(sleep[, c("Sleep", "Dream", "Span")], method = "cart",
               sequential = FALSE)

unregister_vimpute_method("cart")

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