Skip to main content
v2026.11,986 entries · CC-BY 4.0

mice Package in R: Multiple Imputation Step by Step

Impute missing data in R with mice(), fit models with with(), and pool with pool(): arguments, defaults, output and troubleshooting from the official docs.

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.

  1. 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).
  2. Impute. Run imp = mice(nhanes, maxit = 2, m = 2, seed = 1). The result, imp, is a mids object (multiply imputed data set) holding the original data, the imputations and the settings used. In a real analysis, leave m and maxit at least at their defaults (5 and 5) rather than copying the deliberately small values of the documentation example; the choice of m is discussed in how many imputations you need.
  3. Fit your analysis model to every completed dataset. Run fit = with(imp, lm(chl ~ age + bmi)). The with() call refits the same model on each of the m completed datasets and returns the m fits together.
  4. 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 class mipo.

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.

mice() main arguments and documented defaults
ArgumentDefaultWhat it controls
m5Number of imputed datasets to create
maxit5Number of iterations of the chained-equations cycle
seedNAPassed to set.seed(); the default leaves the random number generator alone, so runs differ
methodNULLImputation method per column; an empty string means the column is not imputed
predictorMatrixevery variable predicts every other0/1 matrix; a 1 means the column is a predictor for the target variable of that row
defaultMethodpmm (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

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about mice Package in R: Multiple Imputation Step by Step

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →