VIM (version 7.3.0)

imputeCellM: Cellwise M-estimation imputation

Description

Impute missing values using a cell-weighted M-estimation approach. Each cell in the predictor matrix receives its own weight reflecting potential cellwise contamination, so that contaminated predictor cells are downweighted without discarding entire observations.

Usage

imputeCellM(
  formula,
  data,
  method = "tukey",
  alpha = NULL,
  maxit_irwls = 50,
  eps_irwls = 1e-06,
  uncert = "pmm",
  value_back = "all",
  maxit = 10,
  eps = 0.005,
  trace = FALSE
)

Value

If value_back = "ymiss", a named vector of imputed values (for rows that were originally missing) is returned. Otherwise, a list with components:

data_imputed

the imputed data.frame (same structure as input)

cellweights

n x p matrix of final cell weights (1 = clean, 0 = fully downweighted). Categorical columns always have weight 1.

converged

logical; always TRUE for single-formula imputation, convergence of the sweeps for the data.frame interface

iterations

integer; always 1L for single-formula imputation, the number of sweeps for the data.frame interface

Arguments

formula

a model formula (e.g., y ~ x1 + x2) describing a single response to impute, or a data.frame/matrix with missing values; in the latter case all variables with missing values are imputed by chained equations and data must not be supplied.

data

data.frame containing the data (formula interface only).

method

weight function: "tukey" (default) or "huber". Tukey bisquare is recommended because the consistency proof requires redescending weights.

alpha

tuning constant. NULL (default) uses 4.685 for Tukey and 1.345 for Huber.

maxit_irwls

maximum IRWLS iterations (default: 50).

eps_irwls

convergence tolerance for IRWLS (default: 1e-6).

uncert

imputation uncertainty method: "pmm" (default), "normalerror", "resid", or "none" (deterministic predictions; categorical variables are imputed by the most probable category).

value_back

"all" (default) returns the complete dataset, or "ymiss" returns only the imputed values (formula interface only; ignored with a data.frame first argument).

maxit

maximum number of chained-equation sweeps (data.frame interface only; default: 10).

eps

convergence tolerance for the chained sweeps (data.frame interface only; default: 5e-3). Convergence is declared when the relative change in imputed values falls below this threshold.

trace

logical; if TRUE, print progress of the chained sweeps (data.frame interface only).

Author

Matthias Templ

Details

The function has two interfaces: with a model formula, a single response variable is imputed from the specified predictors; with a data.frame (or matrix) as first argument, all variables with missing values are imputed by chained equations, i.e. each such variable is regressed on all remaining variables and the sweeps are iterated until the imputed values stabilise.

The formula interface is a lightweight single-response alternative to imputeCellIRMI. It fits one cell-weighted IRWLS regression using cellIRWLS() and imputes the missing values in the response variable. This is appropriate when only one variable needs imputation and a specific model formula is desired.

The data.frame interface runs the same per-variable machinery as a chained-equations algorithm: missing values are initialised (median/mode), then each variable with missing values in turn is used as response in a formula containing all remaining variables. Sweeps use deterministic predictions and are iterated until the relative change of the imputed values falls below eps (or maxit is reached); the requested uncert step is applied once after convergence.

For categorical response variables, a weighted multinomial model via multinom is fitted instead. Categorical predictors are not subject to the cellwise contamination model (their cell weights are always 1).

References

M. Templ, A. Kowarik, P. Filzmoser (2011) Iterative stepwise regression imputation using standard and robust methods. Computational Statistics & Data Analysis, Vol. 55, pp. 2793-2806.

See Also

imputeCellIRMI, imputeRobust

Other imputation methods: hotdeck(), impPCA(), imputeCellEM(), imputeCellIRMI(), imputeCellMCD(), imputeCellwise(), imputeRobust(), imputeRobustChain(), irmi(), kNN(), matchImpute(), medianSamp(), rangerImpute(), regressionImp(), sampleCat(), vimmi, vimpute(), xgboostImpute()

Examples

# \donttest{
data(sleep, package = "VIM")
# Impute Dream using BodyWgt and BrainWgt as predictors
result <- imputeCellM(Dream ~ BodyWgt + BrainWgt, data = sleep)
head(result)

# Return only imputed values
impvals <- imputeCellM(Dream ~ BodyWgt + BrainWgt, data = sleep,
                       value_back = "ymiss")

# Huber weights (less aggressive downweighting)
result2 <- imputeCellM(Dream ~ BodyWgt + BrainWgt, data = sleep,
                       method = "huber")

# Chained-equations interface: impute all variables with missings
result3 <- imputeCellM(sleep)
head(result3$data_imputed)
# }