imputeCellM: Cellwise M-estimation imputation

In VIM: Visualization and Imputation of Missing Values

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
)

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).

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).

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

Note

Model uncertainty via bootstrap (Rubin's combining rules for multiple imputation) is not yet implemented. The current version provides single imputation with stochastic uncertainty (PMM or residual draw). For valid multiple imputation, call the function repeatedly with different seeds and combine using Rubin's rules.

Author(s)

Matthias Templ

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

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)

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