R/vimpute.R
vimpute.RdImpute missing values with prefered model, sequentially, with hyperparametertuning and with PMM (if wanted)
vimpute(
data,
considered_variables = names(data),
method = setNames(as.list(rep("ranger", length(considered_variables))),
considered_variables),
pmm = FALSE,
pmm_k = NULL,
pmm_k_method = "mean",
learner_params = NULL,
formula = FALSE,
makeNA = NULL,
donorcond = NULL,
sequential = TRUE,
nseq = 10,
eps = 0.005,
imp_var = TRUE,
pred_history = FALSE,
tune = FALSE,
verbose = FALSE,
boot = FALSE,
robustboot = "stratified",
uncert = "none",
m = 1L
)Dataset with missing values. Provide as a data.table.
A character vector of variable names to be either imputed or used as predictors, excluding irrelevant columns from the imputation process.
Specifies the imputation method for each variable. Can be provided either:
as a single global method (e.g. "ranger"), applied to all variables, or
as a named list (e.g. as.list(var1 = "xgboost", var2="robust")), assigning a method to each variable individually. Supported methods:
ranger (Random Forest)
xgboost (Gradient Boosting)
regularized (glmnet regression/classification)
robust (robustbase::lmrob / glmrob)
gam (Generalized Additive Model via mgcv::gam)
robgam (Robust GAM with outlier downweighting, simple or iterative reweighting)
Predictive Mean Matching (PMM) settings. Can be provided:
as a single TRUE/FALSE (global), or
as a named list, assigning PMM per (numeric) variable.
Number of nearest neighbors used in PMM. Accepted forms:
single global integer (applies to all variables), or
named list assigning values per variable, or
NULL (default), meaning:
k = 1 automatically for variables using PMM,
k = NULL for variables without PMM
Aggregation method used when pmm_k > 1 in PMM.
Default is "mean".
Accepted forms:
single global string ("mean", "median", "random"), or
single global function (called with the k nearest observed values), or
named list assigning methods per variable, or
NULL values inside such lists, which fall back to "mean"
Semantics:
"mean": mean of the k nearest neighbors
"median": median of the k nearest neighbors
"random": random draw of one among the k nearest neighbors
function: custom aggregator returning one numeric value
Hyperparameters for the chosen methods. Can be provided in three ways:
Per variable (e.g. list(mpg = list(num.trees = 500)))
Per method (e.g. list(ranger = list(num.trees = 600)))
Global, applied to all variables using the same method
Optional modeling formula to restrict or transform predictor variables. Only supported for regularized (glmnet), robust (lmrob/glmrob), gam (mgcv::gam), and robgam (robust GAM) methods Provide as a named list, e.g.:
list(mpg = mpg ~ hp + drat)
list(hp = log(hp) ~ wt + cyl) For X: follows the rules of model.matrix For Y: transformations supported are log(), exp(), sqrt(), I(1/..). Only applicable for numeric variables.
Optional named list that defines additional values to be treated as imputable missing
values per variable, similar to kNN(). For variables listed in makeNA,
only the specified values are imputed; existing NA values are left untouched.
Variables not listed in makeNA continue to impute regular NA values.
Optional named list of donor conditions per variable, similar to kNN().
Rows whose observed target values do not satisfy the condition are excluded from the
donor pool for model fitting for that variable.
If TRUE, all variables with missing data are imputed sequentially across iterations.
Maximum number of iterations (if sequential is TRUE).
Convergence threshold: the imputation process stops early if predictions change less than this amount across iterations.
If TRUE, additional columns indicating imputed values (VAR_imp) are added.
If TRUE, all predicted values across all iterations are stored.
Hyperparameter tuning flag. Can be:
TRUE/FALSE globally
or a list specifying tuning per variable, e.g. list(var1 = TRUE) Tuning is performed halfway through nseq iterations.
If TRUE additional debugging output is provided
If TRUE, bootstrap resampling is applied before model fitting to account
for model uncertainty. The bootstrap strategy is controlled by robustboot.
Most effective with method = "robust". Default: FALSE
Bootstrap strategy when boot = TRUE. Options:
"standard" (classical bootstrap),
"stratified" (good/bad residual split, default),
"residual" (inverse residual weighting).
Imputation uncertainty method applied to predictions:
"none" (point prediction, default),
"normalerror" (add N(0, sigma_hat)),
"resid" (add sampled residual),
"pmm" (predictive mean matching),
"midastouch" (covariate-distance-weighted PMM, Siddique & Belin 2008).
If pmm = TRUE is set, it takes precedence over uncert.
Number of multiple imputations. Default: 1 (single imputation).
When m > 1, returns a vimmi object storing the original
data and imputed values efficiently. Use complete.vimmi to
extract completed datasets.
Either:
the imputed dataset (default, when m = 1), or
a list containing the imputed dataset and prediction history (when pred_history = TRUE or tune = TRUE), or
a vimmi object (when m > 1).
Other imputation methods:
hotdeck(),
impPCA(),
imputeCellEM(),
imputeCellIRMI(),
imputeCellM(),
imputeCellMCD(),
imputeCellwise(),
imputeRobust(),
imputeRobustChain(),
irmi(),
kNN(),
matchImpute(),
medianSamp(),
rangerImpute(),
regressionImp(),
sampleCat(),
vimmi,
xgboostImpute()
if (FALSE) { # \dontrun{
# Single imputation (default)
x <- vimpute(data = sleep, sequential = FALSE)
# Sequential imputation with 3 iterations
y <- vimpute(data = sleep, sequential = TRUE, nseq = 3)
# Impute only selected variables
z <- vimpute(data = sleep, considered_variables =
c("Sleep", "Dream", "Span", "BodyWgt"), sequential = FALSE)
# Multiple imputation (m = 5) with bootstrap and residual uncertainty
# Returns a vimmi object
result <- vimpute(data = sleep, method = "ranger", sequential = FALSE,
imp_var = FALSE, m = 5, boot = TRUE, uncert = "resid")
print(result)
# Extract completed datasets
d1 <- complete(result, 1) # first imputed dataset
all_d <- complete(result, "all") # list of 5 datasets
long_d <- complete(result, "long") # long format with .imp column
# Fit a model on each imputed dataset
fits <- with(result, lm(Sleep ~ Dream + Span))
# Multiple imputation with robust method and residual uncertainty
result2 <- vimpute(data = sleep, method = "robust", m = 5,
boot = TRUE, robustboot = "stratified",
uncert = "normalerror")
} # }