register_vimpute_method: 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
)

Value

Invisibly, the registered method name.

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.

Examples

Run this code

# 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()
# \donttest{
data(sleep)
res <- vimpute(sleep[, c("Sleep", "Dream", "Span")], method = "cart",
               sequential = FALSE)
# }
unregister_vimpute_method("cart")