Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
The mice package for R performs multiple imputation by chained equations (MICE): it fills each missing value several times, lets you run your usual analysis on every completed dataset, and pools the results into one set of estimates with pool(). The core workflow is three calls, mice() to impute, with() to fit a model on each completed dataset, and pool() to combine the fits, and this guide walks through each one with the arguments, defaults and output as the package documentation describes them.
What the mice package is used for in research
Missing values are routine in survey, cohort and trial data, and deleting incomplete rows discards information and can bias estimates when the missingness is related to the data. Multiple imputation replaces each missing value with several plausible draws, so the uncertainty about the filled-in values flows through to the final standard errors. The mice package implements the chained-equations form of this approach. The package site states that the algorithm “can impute mixes of continuous, binary, unordered categorical and ordered categorical data”, and the CRAN description adds that each variable gets its own imputation model, with support for two-level continuous data, passive imputation and diagnostic plots.
The reference paper for the package is van Buuren and Groothuis-Oudshoorn (2011), “mice: Multivariate Imputation by Chained Equations in R”, Journal of Statistical Software 45(3), 1-67, doi 10.18637/jss.v045.i03. It records that mice began as an S-PLUS library in 2000 and became an R package in 2001. Cite it when you report an analysis that used the package.
Before imputing, decide whether imputation is appropriate for your data. Whether values are missing completely at random, at random or not at random determines what multiple imputation can and cannot fix; see diagnosing MCAR, MAR and MNAR missingness. For the software-agnostic protocol, including what to report, see multiple imputation: a practical protocol.
Install or access mice
mice is distributed through CRAN, the Comprehensive R Archive Network. Install it from within R with:
install.packages("mice")library(mice)
The CRAN page for mice lists version 3.19.0 (published 2025-12-10), a dependency of R 2.10.0 or later, the licence as GPL-2 or GPL-3, and Stef van Buuren as maintainer. The development version lives in the amices GitHub organisation and can be installed with devtools::install_github(repo = "amices/mice"); the development version is numbered ahead of CRAN, so report the version you actually ran (packageVersion("mice")) in your methods section. Official documentation, including the function reference and vignettes, is at amices.org/mice.
Step-by-step: impute, analyse and pool with mice
The package documentation demonstrates the whole workflow on nhanes, a small example dataset that ships with mice and contains missing values in several variables. The steps below follow that example.
- Look at the missing-data pattern. Run
md.pattern(nhanes)before imputing so you know which variables are incomplete and how the gaps overlap (how to read the result is covered in the next section). - Impute. Run
imp = mice(nhanes, maxit = 2, m = 2, seed = 1). The result,imp, is amidsobject (multiply imputed data set) holding the original data, the imputations and the settings used. In a real analysis, leavemandmaxitat least at their defaults (5 and 5) rather than copying the deliberately small values of the documentation example; the choice ofmis discussed in how many imputations you need. - Fit your analysis model to every completed dataset. Run
fit = with(imp, lm(chl ~ age + bmi)). Thewith()call refits the same model on each of the m completed datasets and returns the m fits together. - Pool the results. Run
summary(pool(fit)).pool()combines the estimates from the m complete-data analyses using Rubin’s rules (Rubin 1987), with the Barnard-Rubin (1999) degrees of freedom, and returns an object of classmipo.
The same pattern works with any model that with() can fit and that has an estimate and a standard error per term, so replace lm with the model your study calls for. For the logic of pooling, see Rubin’s rules for pooling imputed estimates.
Key arguments of mice() and their defaults
The data table below lists the main mice() arguments with the defaults stated on the package’s reference page. Three deserve attention in every project. m is the number of imputed datasets. maxit is the number of iterations of the chained-equations cycle. seed is passed to set.seed(); because its default (NA) leaves the random number generator alone, two runs without a seed give different imputations, so set a seed and record it for reproducibility.
The predictorMatrix argument is a matrix of 0s and 1s in which a 1 means the column variable is used as a predictor for the row’s target variable; by default every variable predicts every other. The method argument names an imputation method per column, and an empty string "" means that column is not imputed. When you do not give a method, mice chooses by variable type: predictive mean matching (pmm) for numeric variables, logistic regression (logreg) for two-level factors, polytomous regression (polyreg) for unordered factors with more than two levels, and proportional odds (polr) for ordered factors with more than two levels.
Output and how to read it
Reading md.pattern() output
md.pattern(x, plot = TRUE, rotate.names = FALSE) returns a matrix in which each row is a missing-data pattern. A 1 means the variable is observed in that pattern and a 0 means it is missing. The last column gives the number of cases showing the pattern, the last row gives the number of missing values per variable, and the bottom-right corner gives the total number of missing values. For nhanes the documentation example shows 13 complete cases, 8, 9 and 10 missing values for hyp, bmi and chl respectively, and 27 missing values in total. A pattern table like this tells you which variables carry most of the gaps and whether the gaps cluster in the same rows.
Reading summary(pool(fit))
The pooled summary has one row per model term and the columns term, estimate, std.error, statistic, df and p.value. The estimate is the pooled coefficient, the std.error reflects both within-imputation and between-imputation variability, and df is the Barnard-Rubin degrees of freedom. Report these pooled values, not the estimates from any single completed dataset.
Extracting completed datasets with complete()
complete(data, action = 1L, include = FALSE, ...) turns the mids object back into ordinary data. The action argument controls the shape of the result:
| action | What you get |
|---|---|
| A number n (default 1) | The nth completed dataset |
| 0 | The original data with the missing values (NA) left in place |
| “all” | A list of all m completed datasets |
| “long” | The completed datasets stacked, with .imp and .id columns identifying the imputation and the row |
| “stacked”, “broad”, “repeated” | Other layouts for the same completed data, as listed on the reference page |
Setting include = TRUE together with action = "all" adds the original data to the list; with m = 5 the documentation example complete(imp, "all", include = TRUE) therefore returns a list of length 6.
Checking that the imputations look plausible
Diagnostic plots compare observed and imputed values. densityplot(imp, ~ hc | .imp) draws one panel per imputation, with observed values in blue and imputed values in red; large, unexplained differences between the two are a prompt to re-examine the imputation model. If the density plot fails because a group is empty, the reference page suggests bwplot or stripplot instead.
Troubleshooting common mice problems
The results change every time I run mice()
That is expected without a seed. The default seed = NA leaves the random number generator untouched, so pass seed = 1 (or any fixed integer) to mice() and state it in your methods.
A variable is being imputed that I want left alone
Set its entry in method to the empty string "". A column with no imputation method is not imputed.
A variable should not be used to predict others
Edit predictorMatrix: a 0 means the column is not a predictor for that row’s target. By default every variable predicts every other, which is not always sensible for identifiers or derived variables.
The imputed variable has the wrong imputation method
Check the variable’s type in R. mice picks its default method from the column type (numeric, two-level factor, unordered factor, ordered factor), so a categorical variable stored as numbers is treated as numeric and imputed with predictive mean matching.
densityplot() stops with an error about an empty group
Use bwplot() or stripplot() for the same observed-versus-imputed comparison, as the densityplot reference page advises.
Is the missingness mechanism a problem for my analysis?
Imputation under the usual assumptions presumes the data are missing at random given the variables in the model. If you suspect not, see diagnosing MCAR, MAR and MNAR missingness.
Free alternatives to mice in R and beyond
Several other R packages on CRAN handle missing data. They differ in method rather than in being drop-in replacements, and the descriptions below come from each package’s CRAN page.
| Package | What its CRAN page says it does |
|---|---|
| mice | Multiple imputation by chained equations; each variable gets its own imputation model |
| Amelia | Multiple imputation using a bootstrapping-based algorithm, for cross-sectional, time-series and time-series-cross-sectional data; works from the R command line or a graphical user interface |
| missForest | Single nonparametric imputation of mixed-type data using a random forest, with an out-of-bag imputation error estimate |
| norm | Analysis of multivariate normal datasets with missing values, including EM, data augmentation and multiple imputation |
If your team works in Stata rather than R, the equivalent workflow is covered in multiple imputation in Stata with mi impute and mi estimate.
Frequently asked questions
What does the mice package do in R?
It creates multiple imputations for missing data using chained equations: each incomplete variable is imputed from a model using the other variables, and the cycle is repeated for maxit iterations to produce m completed datasets.
How do I install mice?
Run install.packages("mice") in R and load it with library(mice). The CRAN release is the standard route; the development version is installed with devtools::install_github(repo = "amices/mice").
What do m and maxit mean in mice()?
m is the number of imputed datasets to create (default 5) and maxit is the number of iterations of the chained-equations cycle (default 5).
How do I combine results after imputation?
Fit the model on every completed dataset with with(imp, ...), then pass the result to pool(). It applies Rubin’s rules and returns pooled estimates, standard errors and degrees of freedom.
How do I get the imputed data out of the mids object?
Use complete(imp) for the first completed dataset, or complete(imp, "long") for all of them stacked with .imp and .id columns.
How do I make mice results reproducible?
Pass a seed to mice(). It is passed to set.seed(); with the default NA the random number generator is left alone and each run differs.
Sources
- mice package website (amices), https://amices.org/mice/, read 2026-11-14.
- CRAN, package mice, https://cran.r-project.org/web/packages/mice/index.html, read 2026-11-14.
- mice() function reference, https://amices.org/mice/reference/mice.html, read 2026-11-14.
- pool() reference, https://amices.org/mice/reference/pool.html, read 2026-11-14.
- complete() reference, https://amices.org/mice/reference/complete.mids.html, read 2026-11-14.
- md.pattern() reference, https://amices.org/mice/reference/md.pattern.html, read 2026-11-14.
- densityplot() reference, https://amices.org/mice/reference/densityplot.mids.html, read 2026-11-14.
- van Buuren S, Groothuis-Oudshoorn K (2011), mice: Multivariate Imputation by Chained Equations in R, Journal of Statistical Software 45(3), https://www.jstatsoft.org/article/view/v045i03, read 2026-11-14.
- CRAN package pages for Amelia, missForest and norm, https://cran.r-project.org/web/packages/, read 2026-11-14.
Data: mice() main arguments and documented defaults
Compiled from the official mice() function reference page of the amices mice package: for each main argument, the default value and what the argument controls. Read 2026-11-14; defaults are those stated in the usage and argument sections of the reference.
Period covered: 2026.
| Argument | Default | What it controls |
|---|---|---|
| m | 5 | Number of imputed datasets to create |
| maxit | 5 | Number of iterations of the chained-equations cycle |
| seed | NA | Passed to set.seed(); the default leaves the random number generator alone, so runs differ |
| method | NULL | Imputation method per column; an empty string means the column is not imputed |
| predictorMatrix | every variable predicts every other | 0/1 matrix; a 1 means the column is a predictor for the target variable of that row |
| defaultMethod | pmm (numeric), logreg (2-level factor), polyreg (unordered factor, more than 2 levels), polr (ordered factor, more than 2 levels) | Method used per variable type when method is not given |
Sources
- mice() function reference (amices) (accessed 2026-11-14)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







