Generates Multivariate Imputations by Chained Equations (MICE)

```
mice(data, m = 5, method = vector("character", length = ncol(data)),
predictorMatrix = (1 - diag(1, ncol(data))),
visitSequence = (1:ncol(data))[apply(is.na(data), 2, any)],
form = vector("character", length = ncol(data)),
post = vector("character", length = ncol(data)), defaultMethod = c("pmm",
"logreg", "polyreg", "polr"), maxit = 5, diagnostics = TRUE,
printFlag = TRUE, seed = NA, imputationMethod = NULL,
defaultImputationMethod = NULL, data.init = NULL, ...)
```

data

A data frame or a matrix containing the incomplete data. Missing
values are coded as `NA`

.

m

Number of multiple imputations. The default is `m=5`

.

method

Can be either a single string, or a vector of strings with
length `ncol(data)`

, specifying the elementary imputation method to be
used for each column in data. If specified as a single string, the same
method will be used for all columns. The default imputation method (when no
argument is specified) depends on the measurement level of the target column
and are specified by the `defaultMethod`

argument. Columns that need
not be imputed have the empty method `''`

. See details for more
information.

predictorMatrix

A square matrix of size `ncol(data)`

containing
0/1 data specifying the set of predictors to be used for each target column.
Rows correspond to target variables (i.e. variables to be imputed), in the
sequence as they appear in data. A value of '1' means that the column
variable is used as a predictor for the target variable (in the rows). The
diagonal of `predictorMatrix`

must be zero. The default for
`predictorMatrix`

is that all other columns are used as predictors
(sometimes called massive imputation). Note: For two-level imputation codes
'2' and '-2' are also allowed.

visitSequence

A vector of integers of arbitrary length, specifying the
column indices of the visiting sequence. The visiting sequence is the column
order that is used to impute the data during one pass through the data. A
column may be visited more than once. All incomplete columns that are used as
predictors should be visited, or else the function will stop with an error.
The default sequence `1:ncol(data)`

implies that columns are imputed
from left to right. It is possible to specify one of the keywords
`'roman'`

(left to right), `'arabic'`

(right to left),
`'monotone'`

(sorted in increasing amount of missingness) and
`'revmonotone'`

(reverse of monotone). The keyword should be supplied as
a string and may be abbreviated.

form

A vector of strings with length `ncol(data)`

, specifying
formulae. Each string is parsed and executed within the `sampler()`

function to create terms for the predictor. The default is to do nothing,
indicated by a vector of empty strings `''`

. The main value
lies in the easy specification of interaction terms. The user must
ensure that the set of variables in the formula match those in `predictors`

.

post

A vector of strings with length `ncol(data)`

, specifying
expressions. Each string is parsed and executed within the `sampler()`

function to postprocess imputed values. The default is to do nothing,
indicated by a vector of empty strings `''`

.

defaultMethod

A vector of three strings containing the default
imputation methods for numerical columns, factor columns with 2 levels, and
columns with (unordered or ordered) factors with more than two levels,
respectively. If nothing is specified, the following defaults will be used:
`pmm`

, predictive mean matching (numeric data) `logreg`

, logistic
regression imputation (binary data, factor with 2 levels) `polyreg`

,
polytomous regression imputation for unordered categorical data (factor >= 2
levels) `polr`

, proportional odds model for (ordered, >= 2 levels)

maxit

A scalar giving the number of iterations. The default is 5.

diagnostics

A Boolean flag. If `TRUE`

, diagnostic information
will be appended to the value of the function. If `FALSE`

, only the
imputed data are saved. The default is `TRUE`

.

printFlag

If `TRUE`

, `mice`

will print history on console.
Use `print=FALSE`

for silent computation.

seed

An integer that is used as argument by the `set.seed()`

for
offsetting the random number generator. Default is to leave the random number
generator alone.

imputationMethod

Same as `method`

argument. Included for
backwards compatibility.

defaultImputationMethod

Same as `defaultMethod`

argument.
Included for backwards compatibility.

data.init

A data frame of the same size and type as `data`

,
without missing data, used to initialize imputations before the start of the
iterative process. The default `NULL`

implies that starting imputation
are created by a simple random draw from the data. Note that specification of
`data.init`

will start the `m`

Gibbs sampling streams from the same
imputations.

...

Named arguments that are passed down to the elementary imputation functions.

Returns an S3 object of class `mids`

(multiply imputed data set)

Generates multiple imputations for incomplete multivariate data by Gibbs sampling. Missing data can occur anywhere in the data. The algorithm imputes an incomplete column (the target column) by generating 'plausible' synthetic values given other columns in the data. Each incomplete column must act as a target column, and has its own specific set of predictors. The default set of predictors for a given target consists of all other columns in the data. For predictors that are incomplete themselves, the most recently generated imputations are used to complete the predictors prior to imputation of the target column.

A separate univariate imputation model can be specified for each column. The default imputation method depends on the measurement level of the target column. In addition to these, several other methods are provided. You can also write their own imputation functions, and call these from within the algorithm.

The data may contain categorical variables that are used in a regressions on
other variables. The algorithm creates dummy variables for the categories of
these variables, and imputes these from the corresponding categorical
variable. The extended model containing the dummy variables is called the
padded model. Its structure is stored in the list component `pad`

.

Built-in elementary imputation methods are:

- pmm
Predictive mean matching (any)

- norm
Bayesian linear regression (numeric)

- norm.nob
Linear regression ignoring model error (numeric)

- norm.boot
Linear regression using bootstrap (numeric)

- norm.predict
Linear regression, predicted values (numeric)

- mean
Unconditional mean imputation (numeric)

- 2l.norm
Two-level normal imputation (numeric)

- 2l.pan
Two-level normal imputation using pan (numeric)

- 2lonly.mean
Imputation at level-2 of the class mean (numeric)

- 2lonly.norm
Imputation at level-2 by Bayesian linear regression (numeric)

- 2lonly.pmm
Imputation at level-2 by Predictive mean matching (any)

- quadratic
Imputation of quadratic terms (numeric)

- logreg
Logistic regression (factor, 2 levels)

- logreg.boot
Logistic regression with bootstrap

- polyreg
Polytomous logistic regression (factor, >= 2 levels)

- polr
Proportional odds model (ordered, >=2 levels)

- lda
Linear discriminant analysis (factor, >= 2 categories)

- cart
Classification and regression trees (any)

- rf
Random forest imputations (any)

- ri
Random indicator method for nonignorable data (numeric)

- sample
Random sample from the observed values (any)

- fastpmm
Experimental: Fast predictive mean matching using C++ (any)

These corresponding functions are coded in the `mice`

library under
names `mice.impute.method`

, where `method`

is a string with the
name of the elementary imputation method name, for example `norm`

. The
`method`

argument specifies the methods to be used. For the `j`

'th
column, `mice()`

calls the first occurence of
`paste('mice.impute.',method[j],sep='')`

in the search path. The
mechanism allows uses to write customized imputation function,
`mice.impute.myfunc`

. To call it for all columns specify
`method='myfunc'`

. To call it only for, say, column 2 specify
`method=c('norm','myfunc','logreg',…{})`

.

*Passive imputation:* `mice()`

supports a special built-in method,
called passive imputation. This method can be used to ensure that a data
transform always depends on the most recently generated imputations. In some
cases, an imputation model may need transformed data in addition to the
original data (e.g. log, quadratic, recodes, interaction, sum scores, and so
on).

Passive imputation maintains consistency among different transformations of
the same data. Passive imputation is invoked if `~`

is specified as the
first character of the string that specifies the elementary method.
`mice()`

interprets the entire string, including the `~`

character,
as the formula argument in a call to ```
model.frame(formula,
data[!r[,j],])
```

. This provides a simple mechanism for specifying determinstic
dependencies among the columns. For example, suppose that the missing entries
in variables `data$height`

and `data$weight`

are imputed. The body
mass index (BMI) can be calculated within `mice`

by specifying the
string `'~I(weight/height^2)'`

as the elementary imputation method for
the target column `data$bmi`

. Note that the `~`

mechanism works
only on those entries which have missing values in the target column. You
should make sure that the combined observed and imputed parts of the target
column make sense. An easy way to create consistency is by coding all entries
in the target as `NA`

, but for large data sets, this could be
inefficient. Note that you may also need to adapt the default
`predictorMatrix`

to evade linear dependencies among the predictors that
could cause errors like `Error in solve.default()`

or ```
Error:
system is exactly singular
```

. Though not strictly needed, it is often useful
to specify `visitSequence`

such that the column that is imputed by the
`~`

mechanism is visited each time after one of its predictors was
visited. In that way, deterministic relation between columns will always be
synchronized.

Van Buuren, S., Groothuis-Oudshoorn, K. (2011). `mice`

:
Multivariate Imputation by Chained Equations in `R`

. *Journal of
Statistical Software*, **45**(3), 1-67.
http://www.jstatsoft.org/v45/i03/

van Buuren, S. (2012). *Flexible Imputation of Missing Data.* Boca
Raton, FL: Chapman & Hall/CRC Press.

Van Buuren, S., Brand, J.P.L., Groothuis-Oudshoorn C.G.M., Rubin, D.B. (2006)
Fully conditional specification in multivariate imputation. *Journal of
Statistical Computation and Simulation*, **76**, 12, 1049--1064.

Van Buuren, S. (2007) Multiple imputation of discrete and continuous data by
fully conditional specification. *Statistical Methods in Medical
Research*, **16**, 3, 219--242.

Van Buuren, S., Boshuizen, H.C., Knook, D.L. (1999) Multiple imputation of
missing blood pressure covariates in survival analysis. *Statistics in
Medicine*, **18**, 681--694.

Brand, J.P.L. (1999) *Development, implementation and evaluation of
multiple imputation strategies for the statistical analysis of incomplete
data sets.* Dissertation. Rotterdam: Erasmus University.

```
# NOT RUN {
# do default multiple imputation on a numeric matrix
imp <- mice(nhanes)
imp
# list the actual imputations for BMI
imp$imputations$bmi
# first completed data matrix
complete(imp)
# imputation on mixed data with a different method per column
mice(nhanes2, meth=c('sample','pmm','logreg','norm'))
# }
```

Run the code above in your browser using DataLab