Get started

The ggmice package

The ggmice package provides visualizations for the evaluation of incomplete data, mice imputation model arguments, and multiply imputed data sets (mice::mids objects). The functions in ggmice adhere to the ‘grammar of graphics’ philosophy, popularized by the ggplot2 package. With that, ggmice enhances imputation workflows and provides plotting objects that are easily extended and manipulated by each individual ‘imputer’.

This vignette gives an overview of the different plotting function in ggmice. The core function, ggmice(), is a ggplot2::ggplot() wrapper function which handles missing and imputed values. In this vignette, you’ll learn how to create and interpret ggmice visualizations.

Experienced mice users may already be familiar with the lattice style plotting functions in mice. These ‘old friends’ such as mice::bwplot() can be re-created with the ggmice() function, see the Old friends vignette for advice.


You can install the latest ggmice release from CRAN with:


The development version of the ggmice package can be installed from GitHub with:

# install.packages("devtools")

After installing ggmice, you can load the package into your R workspace. It is highly recommended to load the mice and ggplot2 packages as well. This vignette assumes that all three packages are loaded:


We will use the mice::boys data for illustrations. This is an incomplete dataset (n = 748) with cross-sectional data on 9 growth-related variables (e.g., age in years and height in cm).

We load the incomplete data with:

dat <- boys

For the purpose of this vignette, we impute all incomplete variables m = 3 times with predictive mean matching as imputation method. Imputations are generated with:

imp <- mice(dat, m = 3, method = "pmm")

We now have the necessary packages, an incomplete dataset (dat), and a mice::mids object (imp) loaded in our workspace.

The ggmice() function

The core function in the ggmice package is ggmice(). This function mimics how the ggplot2 function ggplot() works: both take a data argument and a mapping argument, and will return an object of class ggplot.

Using ggmice() looks equivalent to a ggplot() call:

ggplot(dat, aes(x = age))
ggmice(dat, aes(x = age))

The main difference between the two functions is that ggmice() is actually a wrapper around ggplot(), including some pre-processing steps for incomplete and imputed data. Because of the internal processing in ggmice(), the mapping argument is required for each ggmice() call. This is in contrast to the aesthetic mapping in ggplot(), which may also be provided in subsequent plotting layers. After creating a ggplot object, any desired plotting layers may be added (e.g., with the family of ggplot2::geom_* functions), or adjusted (e.g., with the ggplot2::labs() function). This makes ggmice() a versatile plotting function for incomplete and/or imputed data.

The object supplied to the data argument in ggmice() should be an incomplete dataset of class data.frame, or an imputation object of class mice::mids. Depending on which one of these is provided, the resulting visualization will either differentiate between observed and missing data, or between observed and imputed data. By convention, observed data is plotted in blue and missing or imputed data is plotted in red.

The mapping argument in ggmice() cannot be empty. An x or y mapping (or both) has to be supplied for ggmice() to function. This aesthetic mapping can be provided with the ggplot2 function aes() (or equivalents). Other mapping may be provided too, except for colour, which is already used to display observed versus missing or imputed data.

Incomplete data

If the object supplied to the data argument in ggmice() is a data.frame, the visualization will contain observed data in blue and missing data in red. Since missing data points are by definition unobserved, the values themselves cannot be plotted. What we can plot are sets of variable pairs. Any missing values in one variable can be displayed on the axis of the other. This provides a visual cue that the missing data is distinct from the observed values, but still displays the observed value of the other variable.

For example, the variable age is completely observed, while there are some missing entries for the height variable hgt. We can create a scatter plot of these two variables with:

ggmice(dat, aes(age, hgt)) +

The age of cases with missing hgt are plotted on the horizontal axis. This is in contrast to a regular ggplot() call with the same arguments, which would leave out all cases with missing hgt. So, with ggmice() we loose less information, and may even gain valuable insight into the missingness in the data.

Another example of ggmice() in action on incomplete data is when one of the variables is categorical. The incomplete continuous variable hgt is plotted against the incomplete categorical variable reg with:

ggmice(dat, aes(reg, hgt)) +

Again, missing values are plotted on the axes. Cases with observed hgt and missing reg are plotted on the vertical axis. Cases with observed reg and missing hgt are plotted on the horizontal axis. There are no cases were neither is observed, but otherwise these would be plotted on the intersection of the two axes.

The ‘grammar of graphics’ makes it easy to adjust the plots programmatically. For example, we could be interested in the differences in growth data between the city and other regions. Add facets based on a clustering variable with:

ggmice(dat, aes(wgt, hgt)) +
  geom_point() +
  facet_wrap(~ reg == "city", labeller = label_both)

Or, alternatively, we could convert the plotted values of the variable hgt from centimeters to inches and the variable wgt from kilograms to pounds with:

ggmice(dat, aes(wgt * 2.20, hgt / 2.54)) +
  geom_point() +
  labs(x = "Weight (lbs)", y = "Height (in)")
#> Warning: Mapping variable 'wgt * 2.2' recognized internally as wgt.
#> Please verify whether this matches the requested mapping variable.
#> Warning: Mapping variable 'hgt/2.54' recognized internally as hgt.
#> Please verify whether this matches the requested mapping variable.

A final example of ggmice() applied to incomplete data is faceting based on a missingness indicator. Doing so may help explore the missingness mechanisms in the incomplete data. The distribution of the continuous variable age and categorical variable reg are visualized faceted by the missingness indicator for hgt with:

# continuous variable
ggmice(dat, aes(age)) +
  geom_density() +
  facet_wrap(~ factor( == 0, labels = c("observed height", "missing height")))

# categorical variable
ggmice(dat, aes(reg)) +
  geom_bar(fill = "white") +
  facet_wrap(~ factor( == 0, labels = c("observed height", "missing height")))

Imputed data

If the data argument in ggmice() is provided a mice::mids object, the resulting plot will contain observed data in blue and imputed data in red. There are many possible visualizations for imputed data, four of which are explicitly defined in the mice package. Each of these can be re-created with the ggmice() function (see the Old friends vignette). But ggmice() can do even more.

For example, we could create the same scatter plots as the ones above, but now on the imputed data:

ggmice(imp, aes(age, hgt)) +

ggmice(imp, aes(reg, hgt)) +

ggmice(imp, aes(wgt, hgt)) +
  geom_point() +
  facet_wrap(~ reg == "city", labeller = label_both)