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.
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
)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.frame containing the data (formula interface only).
weight function: "tukey" (default) or "huber".
Tukey bisquare is recommended because the consistency proof requires
redescending weights.
tuning constant. NULL (default) uses 4.685 for Tukey
and 1.345 for Huber.
maximum IRWLS iterations (default: 50).
convergence tolerance for IRWLS (default: 1e-6).
imputation uncertainty method: "pmm" (default),
"normalerror", "resid", or "none" (deterministic
predictions; categorical variables are imputed by the most probable
category).
"all" (default) returns the complete dataset,
or "ymiss" returns only the imputed values (formula interface
only; ignored with a data.frame first argument).
maximum number of chained-equation sweeps (data.frame interface only; default: 10).
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.
logical; if TRUE, print progress of the chained
sweeps (data.frame interface only).
If value_back = "ymiss", a named vector of imputed values
(for rows that were originally missing) is returned. Otherwise, a list
with components:
the imputed data.frame (same structure as input)
n x p matrix of final cell weights (1 = clean, 0 = fully downweighted). Categorical columns always have weight 1.
logical; always TRUE for single-formula
imputation, convergence of the sweeps for the data.frame interface
integer; always 1L for single-formula
imputation, the number of sweeps for the data.frame interface
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).
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.
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.
Other imputation methods:
hotdeck(),
impPCA(),
imputeCellEM(),
imputeCellIRMI(),
imputeCellMCD(),
imputeCellwise(),
imputeRobust(),
imputeRobustChain(),
irmi(),
kNN(),
matchImpute(),
medianSamp(),
rangerImpute(),
regressionImp(),
sampleCat(),
vimmi,
vimpute(),
xgboostImpute()
# \donttest{
data(sleep, package = "VIM")
# Impute Dream using BodyWgt and BrainWgt as predictors
result <- imputeCellM(Dream ~ BodyWgt + BrainWgt, data = sleep)
head(result)
#> $data_imputed
#> BodyWgt BrainWgt NonD Dream Sleep Span Gest Pred Exp Danger
#> 1 6654.000 5712.00 NA 0.3 3.3 38.6 645.0 3 5 3
#> 2 1.000 6.60 6.3 2.0 8.3 4.5 42.0 3 1 3
#> 3 3.385 44.50 NA 0.6 12.5 14.0 60.0 1 1 1
#> 4 0.920 5.70 NA 2.4 16.5 NA 25.0 5 2 3
#> 5 2547.000 4603.00 2.1 1.8 3.9 69.0 624.0 3 5 4
#> 6 10.550 179.50 9.1 0.7 9.8 27.0 180.0 4 4 4
#> 7 0.023 0.30 15.8 3.9 19.7 19.0 35.0 1 1 1
#> 8 160.000 169.00 5.2 1.0 6.2 30.4 392.0 4 5 4
#> 9 3.300 25.60 10.9 3.6 14.5 28.0 63.0 1 2 1
#> 10 52.160 440.00 8.3 1.4 9.7 50.0 230.0 1 1 1
#> 11 0.425 6.40 11.0 1.5 12.5 7.0 112.0 5 4 4
#> 12 465.000 423.00 3.2 0.7 3.9 30.0 281.0 5 5 5
#> 13 0.550 2.40 7.6 2.7 10.3 NA NA 2 1 2
#> 14 187.100 419.00 NA 1.0 3.1 40.0 365.0 5 5 5
#> 15 0.075 1.20 6.3 2.1 8.4 3.5 42.0 1 1 1
#> 16 3.000 25.00 8.6 0.0 8.6 50.0 28.0 2 2 2
#> 17 0.785 3.50 6.6 4.1 10.7 6.0 42.0 2 2 2
#> 18 0.200 5.00 9.5 1.2 10.7 10.4 120.0 2 2 2
#> 19 1.410 17.50 4.8 1.3 6.1 34.0 NA 1 2 1
#> 20 60.000 81.00 12.0 6.1 18.1 7.0 NA 1 1 1
#> 21 529.000 680.00 NA 0.3 NA 28.0 400.0 5 5 5
#> 22 27.660 115.00 3.3 0.5 3.8 20.0 148.0 5 5 5
#> 23 0.120 1.00 11.0 3.4 14.4 3.9 16.0 3 1 2
#> 24 207.000 406.00 NA 0.6 12.0 39.3 252.0 1 4 1
#> 25 85.000 325.00 4.7 1.5 6.2 41.0 310.0 1 3 1
#> 26 36.330 119.50 NA 2.3 13.0 16.2 63.0 1 1 1
#> 27 0.101 4.00 10.4 3.4 13.8 9.0 28.0 5 1 3
#> 28 1.040 5.50 7.4 0.8 8.2 7.6 68.0 5 3 4
#> 29 521.000 655.00 2.1 0.8 2.9 46.0 336.0 5 5 5
#> 30 100.000 157.00 NA 6.6 10.8 22.4 100.0 1 1 1
#> 31 35.000 56.00 NA 3.1 NA 16.3 33.0 3 5 4
#> 32 0.005 0.14 7.7 1.4 9.1 2.6 21.5 5 2 4
#> 33 0.010 0.25 17.9 2.0 19.9 24.0 50.0 1 1 1
#> 34 62.000 1320.00 6.1 1.9 8.0 100.0 267.0 1 1 1
#> 35 0.122 3.00 8.2 2.4 10.6 NA 30.0 2 1 1
#> 36 1.350 8.10 8.4 2.8 11.2 NA 45.0 3 1 3
#> 37 0.023 0.40 11.9 1.3 13.2 3.2 19.0 4 1 3
#> 38 0.048 0.33 10.8 2.0 12.8 2.0 30.0 4 1 3
#> 39 1.700 6.30 13.8 5.6 19.4 5.0 12.0 2 1 1
#> 40 3.500 10.80 14.3 3.1 17.4 6.5 120.0 2 1 1
#> 41 250.000 490.00 NA 1.0 NA 23.6 440.0 5 5 5
#> 42 0.480 15.50 15.2 1.8 17.0 12.0 140.0 2 2 2
#> 43 10.000 115.00 10.0 0.9 10.9 20.2 170.0 4 4 4
#> 44 1.620 11.40 11.9 1.8 13.7 13.0 17.0 2 1 2
#> 45 192.000 180.00 6.5 1.9 8.4 27.0 115.0 4 4 4
#> 46 2.500 12.10 7.5 0.9 8.4 18.0 31.0 5 5 5
#> 47 4.288 39.20 NA 0.0 12.5 13.7 63.0 2 2 2
#> 48 0.280 1.90 10.6 2.6 13.2 4.7 21.0 3 1 3
#> 49 4.235 50.40 7.4 2.4 9.8 9.8 52.0 1 1 1
#> 50 6.800 179.00 8.4 1.2 9.6 29.0 164.0 2 3 2
#> 51 0.750 12.30 5.7 0.9 6.6 7.0 225.0 2 2 2
#> 52 3.600 21.00 4.9 0.5 5.4 6.0 225.0 3 2 3
#> 53 14.830 98.20 NA 2.4 2.6 17.0 150.0 5 5 5
#> 54 55.500 175.00 3.2 0.6 3.8 20.0 151.0 5 5 5
#> 55 1.400 12.50 NA 1.2 11.0 12.7 90.0 2 2 2
#> 56 0.060 1.00 8.1 2.2 10.3 3.5 NA 3 1 2
#> 57 0.900 2.60 11.0 2.3 13.3 4.5 60.0 2 1 2
#> 58 2.000 12.30 4.9 0.5 5.4 7.5 200.0 3 1 3
#> 59 0.104 2.50 13.2 2.6 15.8 2.3 46.0 3 2 2
#> 60 4.190 58.00 9.7 0.6 10.3 24.0 210.0 4 3 4
#> 61 3.500 3.90 12.8 6.6 19.4 3.0 14.0 2 1 1
#> 62 4.050 17.00 NA 3.9 NA 13.0 38.0 3 1 1
#>
#> $cellweights
#> BodyWgt BrainWgt NonD Dream Sleep Span Gest
#> 1 0.0000000 0.00000000 1.0000000 0.8881658 0.7394051 0.7670234 0.00000000
#> 2 0.9784487 0.98357650 0.9743955 0.9979540 0.9748224 0.9500989 0.98305620
#> 3 0.9999929 0.89494659 1.0000000 0.9276624 0.9770968 0.9994558 0.99551793
#> 4 0.9769603 0.98069750 1.0000000 0.9816610 0.8094280 1.0000000 0.96408357
#> 5 0.0000000 0.00000000 0.7748058 1.0000000 0.7786571 0.1201433 0.00000000
#> 6 0.8053841 0.00000000 0.9965536 0.9390341 0.9976854 0.9373180 0.87722439
#> 7 0.9569604 0.95866283 0.6886076 0.7870421 0.5859836 0.9931702 0.97608097
#> 8 0.0000000 0.00000000 0.9400789 0.9675147 0.9034416 0.8974778 0.15299042
#> 9 0.9999929 0.98988813 0.9605229 0.8410590 0.9121111 0.9265493 0.99682054
#> 10 0.0000000 0.00000000 0.9999847 0.9918284 0.9969190 0.5271762 0.73667167
#> 11 0.9666704 0.98295654 0.9574003 0.9953993 0.9770968 0.9707063 0.98650992
#> 12 0.0000000 0.00000000 0.8439718 0.9390341 0.7786571 0.9026327 0.55712836
#> 13 0.9694436 0.96819332 0.9965536 0.9589759 0.9998767 1.0000000 1.00000000
#> 14 0.0000000 0.00000000 1.0000000 0.9675147 0.7257992 0.7405626 0.24172193
#> 15 0.9582840 0.96289564 0.9743955 0.9953993 0.9770968 0.9403906 0.98305620
#> 16 0.9995368 0.99128605 0.9996168 0.8410590 0.9813276 0.5271762 0.96793178
#> 17 0.9743380 0.97269947 0.9813083 0.7475953 0.9996574 0.9630988 0.98305620
#> 18 0.9613839 0.97830012 0.9919066 0.9816610 0.9996574 0.9900886 0.97921490
#> 19 0.9853071 0.99999091 0.9242121 0.9872466 0.8989664 0.8457806 1.00000000
#> 20 0.0000000 0.49638392 0.9199724 0.2775871 0.7049369 0.9707063 1.00000000
#> 21 0.0000000 0.00000000 1.0000000 0.8881658 1.0000000 0.9265493 0.12932533
#> 22 0.0000000 0.09324040 0.8497278 0.9153804 0.7722855 0.9892294 0.94169794
#> 23 0.9594133 0.96197417 0.9574003 0.8732772 0.9163039 0.9443729 0.95127517
#> 24 0.0000000 0.00000000 1.0000000 0.9276624 0.9868741 0.7539263 0.66259035
#> 25 0.0000000 0.00000000 0.9199724 0.9953993 0.9034416 0.7210294 0.44671949
#> 26 0.0000000 0.05756327 1.0000000 0.9872466 0.9646743 0.9994558 0.99682054
#> 27 0.9589384 0.97463633 0.9743955 0.8732772 0.9394302 0.9833329 0.96793178
#> 28 0.9791746 0.98002663 0.9944733 0.9494774 0.9724425 0.9748587 0.99849658
#> 29 0.0000000 0.00000000 0.7748058 0.9494774 0.7119497 0.6166376 0.34753039
#> 30 0.0000000 0.00000000 1.0000000 0.1684585 0.9993286 0.9761737 0.99452604
#> 31 0.0000000 0.79359117 1.0000000 0.9153804 1.0000000 0.9993524 0.97387180
#> 32 0.9564976 0.95788717 0.9974108 0.9918284 0.9900350 0.9309535 0.95932669
#> 33 0.9566264 0.95842119 0.5189245 0.9979540 0.5703955 0.9646886 0.98957398
#> 34 0.0000000 0.00000000 0.9691967 0.9994883 0.9673681 0.0000000 0.60893560
#> 35 0.9594632 0.97069290 0.9998620 0.9816610 0.9998767 1.0000000 0.97037907
#> 36 0.9843842 0.98786390 0.9999847 0.9494774 0.9969190 1.0000000 0.98568294
#> 37 0.9569604 0.95914407 0.9242121 0.9872466 0.9589759 0.9373180 0.95575383
#> 38 0.9575993 0.95880749 0.9635302 0.9979540 0.9699576 0.9242992 0.97037907
#> 39 0.9893751 0.98264231 0.8261523 0.3975297 0.6091179 0.9546421 0.94498163
#> 40 0.9999020 0.99396020 0.7946875 0.9153804 0.7527567 0.9670094 0.97921490
#> 41 0.0000000 0.00000000 1.0000000 0.9675147 1.0000000 0.9677659 0.03612961
#> 42 0.9679051 0.99955477 0.7329603 1.0000000 0.7786571 0.9956821 0.95428406
#> 43 0.8326353 0.09324040 0.9833748 0.9589759 0.9988903 0.9883349 0.89971873
#> 44 0.9883180 0.99503028 0.9242121 1.0000000 0.9429400 0.9980174 0.95279115
#> 45 0.0000000 0.00000000 0.9791227 0.9994883 0.9770968 0.9373180 0.98395605
#> 46 0.9971990 0.99614738 0.9955744 0.9589759 0.9770968 0.9962208 0.97156712
#> 47 0.9964729 0.93117339 1.0000000 0.8410590 0.9770968 0.9991186 0.99682054
#> 48 0.9633068 0.96603421 0.9691967 0.9675147 0.9589759 0.9519412 0.95862375
#> 49 0.9968570 0.84660061 0.9944733 0.9816610 0.9976854 0.9874050 0.99095931
#> 50 0.9533511 0.00000000 0.9999847 0.9816610 0.9960436 0.9149821 0.91221199
#> 51 0.9736355 0.99644054 0.9574003 0.9589759 0.9204012 0.9707063 0.75259930
#> 52 0.9997382 0.99795638 0.9283434 0.9153804 0.8650941 0.9630988 0.75259930
#> 53 0.5467838 0.27416541 1.0000000 0.9816610 0.6907420 0.9983769 0.93832365
#> 54 0.0000000 0.00000000 0.8439718 0.9276624 0.7722855 0.9892294 0.93660268
#> 55 0.9851552 0.99672213 1.0000000 0.9816610 0.9983425 0.9974108 0.99849658
#> 56 0.9579043 0.96197417 0.9996168 0.9918284 0.9998767 0.9403906 1.00000000
#> 57 0.9765806 0.96903761 0.9574003 0.9872466 0.9559723 0.9500989 0.99551793
#> 58 0.9928956 0.99644054 0.9283434 0.9153804 0.8650941 0.9741882 0.82629693
#> 59 0.9590135 0.96861685 0.8609570 0.9675147 0.8492604 0.9276624 0.98650992
#> 60 0.9971657 0.77313005 0.9888553 0.9276624 0.9998767 0.9646886 0.79806958
#> 61 0.9999020 0.97425455 0.8822536 0.1684585 0.6091179 0.9352289 0.94817420
#> 62 0.9980243 0.99999091 1.0000000 0.7870421 1.0000000 0.9980174 0.97921490
#> Pred Exp Danger
#> 1 1.0000000 0.6617148 0.9589759
#> 2 1.0000000 0.9589759 0.9589759
#> 3 0.8410590 0.9589759 0.9589759
#> 4 0.8410590 1.0000000 0.9589759
#> 5 1.0000000 0.6617148 0.8410590
#> 6 0.9589759 0.8410590 0.8410590
#> 7 0.8410590 0.9589759 0.9589759
#> 8 0.9589759 0.6617148 0.8410590
#> 9 0.8410590 1.0000000 0.9589759
#> 10 0.8410590 0.9589759 0.9589759
#> 11 0.8410590 0.8410590 0.8410590
#> 12 0.8410590 0.6617148 0.6617148
#> 13 0.9589759 0.9589759 1.0000000
#> 14 0.8410590 0.6617148 0.6617148
#> 15 0.8410590 0.9589759 0.9589759
#> 16 0.9589759 1.0000000 1.0000000
#> 17 0.9589759 1.0000000 1.0000000
#> 18 0.9589759 1.0000000 1.0000000
#> 19 0.8410590 1.0000000 0.9589759
#> 20 0.8410590 0.9589759 0.9589759
#> 21 0.8410590 0.6617148 0.6617148
#> 22 0.8410590 0.6617148 0.6617148
#> 23 1.0000000 0.9589759 1.0000000
#> 24 0.8410590 0.8410590 0.9589759
#> 25 0.8410590 0.9589759 0.9589759
#> 26 0.8410590 0.9589759 0.9589759
#> 27 0.8410590 0.9589759 0.9589759
#> 28 0.8410590 0.9589759 0.8410590
#> 29 0.8410590 0.6617148 0.6617148
#> 30 0.8410590 0.9589759 0.9589759
#> 31 1.0000000 0.6617148 0.8410590
#> 32 0.8410590 1.0000000 0.8410590
#> 33 0.8410590 0.9589759 0.9589759
#> 34 0.8410590 0.9589759 0.9589759
#> 35 0.9589759 0.9589759 0.9589759
#> 36 1.0000000 0.9589759 0.9589759
#> 37 0.9589759 0.9589759 0.9589759
#> 38 0.9589759 0.9589759 0.9589759
#> 39 0.9589759 0.9589759 0.9589759
#> 40 0.9589759 0.9589759 0.9589759
#> 41 0.8410590 0.6617148 0.6617148
#> 42 0.9589759 1.0000000 1.0000000
#> 43 0.9589759 0.8410590 0.8410590
#> 44 0.9589759 0.9589759 1.0000000
#> 45 0.9589759 0.8410590 0.8410590
#> 46 0.8410590 0.6617148 0.6617148
#> 47 0.9589759 1.0000000 1.0000000
#> 48 1.0000000 0.9589759 0.9589759
#> 49 0.8410590 0.9589759 0.9589759
#> 50 0.9589759 0.9589759 1.0000000
#> 51 0.9589759 1.0000000 1.0000000
#> 52 1.0000000 1.0000000 0.9589759
#> 53 0.8410590 0.6617148 0.6617148
#> 54 0.8410590 0.6617148 0.6617148
#> 55 0.9589759 1.0000000 1.0000000
#> 56 1.0000000 0.9589759 1.0000000
#> 57 0.9589759 0.9589759 1.0000000
#> 58 1.0000000 0.9589759 0.9589759
#> 59 1.0000000 1.0000000 1.0000000
#> 60 0.9589759 0.9589759 0.8410590
#> 61 0.9589759 0.9589759 0.9589759
#> 62 1.0000000 0.9589759 0.9589759
#>
#> $converged
#> [1] TRUE
#>
#> $iterations
#> [1] 1
#>
# 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)
#> BodyWgt BrainWgt NonD Dream Sleep Span Gest Pred Exp Danger
#> 1 6654.000 5712.0 8.4 2.0 3.3 38.6 645 3 5 3
#> 2 1.000 6.6 6.3 2.0 8.3 4.5 42 3 1 3
#> 3 3.385 44.5 10.8 1.5 12.5 14.0 60 1 1 1
#> 4 0.920 5.7 14.3 2.4 16.5 3.5 25 5 2 3
#> 5 2547.000 4603.0 2.1 1.8 3.9 69.0 624 3 5 4
#> 6 10.550 179.5 9.1 0.7 9.8 27.0 180 4 4 4
# }