mids: Multiply imputed data set (`mids`)

Description

The mids object is an S3 class that represents a multiply imputed data set. The mids() function is the S3 constructor. The following functions produce a mids object: mids(), mice(), mice.mids(), cbind(), rbind(), ibind(), as.mids() and filter().

Usage

mids(
  data = data.frame(),
  imp = list(),
  m = integer(),
  where = matrix,
  blocks = list(),
  call = match.call(),
  nmis = integer(),
  method = character(),
  predictorMatrix = matrix(),
  visitSequence = character(),
  formulas = list(),
  post = character(),
  blots = list(),
  ignore = logical(),
  seed = integer(),
  iteration = integer(),
  lastSeedValue = tryCatch(get(".Random.seed", envir = globalenv(), mode = "integer",
    inherits = FALSE), error = function(e) NULL),
  chainMean = list(),
  chainVar = list(),
  loggedEvents = data.frame(),
  version = packageVersion("mice"),
  date = Sys.Date()
)
# S3 method for mids
plot(
  x,
  y = NULL,
  theme = mice.theme(),
  layout = c(2, 3),
  type = "l",
  col = 1:10,
  lty = 1,
  ...
)
# S3 method for mids
print(x, ...)
# S3 method for mids
summary(object, ...)

Value

mids() returns a mids object.

plot() returns a xyplot object.

print() returns the input object invisibly.

summary() returns the input object invisibly.

Arguments

data: A data frame or a matrix containing the incomplete data. Missing values are coded as NA.
imp: Calculated field
m: Number of multiple imputations. The default is m=5.
where: A data frame or matrix with logicals of the same dimensions as data indicating where in the data the imputations should be created. The default, where = is.na(data), specifies that the missing data should be imputed. The where argument may be used to overimpute observed data, or to skip imputations for selected missing values. Note: Imputation methods that generate imptutations outside of mice, like mice.impute.panImpute() may depend on a complete predictor space. In that case, a custom where matrix can not be specified.
blocks: List of vectors with variable names per block. List elements may be named to identify blocks. Variables within a block are imputed by a multivariate imputation method (see method argument). By default each variable is placed into its own block, which is effectively fully conditional specification (FCS) by univariate models (variable-by-variable imputation). Only variables whose names appear in blocks are imputed. The relevant columns in the where matrix are set to FALSE of variables that are not block members. A variable may appear in multiple blocks. In that case, it is effectively re-imputed each time that it is visited.
call: Calculated field
nmis: Calculated field
method: Can be either a single string, or a vector of strings with length length(blocks), specifying the imputation method to be used for each column in data. If specified as a single string, the same method will be used for all blocks. The default imputation method (when no argument is specified) depends on the measurement level of the target column, as regulated by the defaultMethod argument. Columns that need not be imputed have the empty method "". See details.
predictorMatrix: A numeric matrix of length(blocks) rows and ncol(data) columns, containing 0/1 data specifying the set of predictors to be used for each target column. Each row corresponds to a variable block, i.e., a set of variables to be imputed. A value of 1 means that the column variable is used as a predictor for the target block (in the rows). By default, the predictorMatrix is a square matrix of ncol(data) rows and columns with all 1's, except for the diagonal. Note: For two-level imputation models (which have "2l" in their names) other codes (e.g, 2 or -2) are also allowed.
visitSequence: A vector of block names of arbitrary length, specifying the sequence of blocks that are imputed during one iteration of the Gibbs sampler. A block is a collection of variables. All variables that are members of the same block are imputed when the block is visited. A variable that is a member of multiple blocks is re-imputed within the same iteration. The default visitSequence = "roman" visits the blocks (left to right) in the order in which they appear in blocks. One may also use one of the following keywords: "arabic" (right to left), "monotone" (ordered low to high proportion of missing data) and "revmonotone" (reverse of monotone). Special case: If you specify both visitSequence = "monotone" and maxit = 1, then the procedure will edit the predictorMatrix to conform to the monotone pattern. Realize that convergence in one iteration is only guaranteed if the missing data pattern is actually monotone. The procedure does not check this.
formulas: A named list of formula's, or expressions that can be converted into formula's by as.formula. List elements correspond to blocks. The block to which the list element applies is identified by its name, so list names must correspond to block names. The formulas argument is an alternative to the predictorMatrix argument that allows for more flexibility in specifying imputation models, e.g., for specifying interaction terms.
post: A vector of strings with length ncol(data) specifying expressions as strings. Each string is parsed and executed within the sampler() function to post-process imputed values during the iterations. The default is a vector of empty strings, indicating no post-processing. Multivariate (block) imputation methods ignore the post parameter.
blots: A named list of alist's that can be used to pass down arguments to lower level imputation function. The entries of element blots[[blockname]] are passed down to the function called for block blockname.
ignore: A logical vector of nrow(data) elements indicating which rows are ignored when creating the imputation model. The default NULL includes all rows that have an observed value of the variable to imputed. Rows with ignore set to TRUE do not influence the parameters of the imputation model, but are still imputed. We may use the ignore argument to split data into a training set (on which the imputation model is built) and a test set (that does not influence the imputation model estimates). Note: Multivariate imputation methods, like mice.impute.jomoImpute() or mice.impute.panImpute(), do not honour the ignore argument.
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.
iteration: Calculated field
lastSeedValue: Calculated field
chainMean: Calculated field
chainVar: Calculated field
loggedEvents: Calculated field
version: Calculated field
date: Calculated field
x: An object of class mids
y: A formula that specifies which variables, stream and iterations are plotted. If omitted, all streams, variables and iterations are plotted.
theme: The trellis theme to applied to the graphs. The default is mice.theme().
layout: A vector of length 2 given the number of columns and rows in the plot. The default is c(2, 3).
type: Parameter type of panel.xyplot.
col: Parameter col of panel.xyplot.
lty: Parameter lty of panel.xyplot.
...: Others arguments
object: Object of class mids

Structure

Objects of class "mids" are lists with the following elements:

data:: Original (incomplete) data set.
imp:: A list of ncol(data) components with the generated multiple imputations. Each list component is a data.frame (nmis[j] by m) of imputed values for variable j. A NULL component is used for variables for which not imputations are generated.
m:: Number of imputations.
where:: The where argument of the mice() function.
blocks:: The blocks argument of the mice() function.
call:: Call that created the object.
nmis:: An Named vector with counts of missing values per variable
method:: A vector of strings of length(blocks specifying the imputation method per block.
predictorMatrix:: A numerical matrix of containing integers specifying the predictor set.
visitSequence:: A vector of variable and block names that specifies how variables and blocks are visited in one iteration throuh the data.
formulas:: A named list of formula's, or expressions that can be converted into formula's by as.formula. List elements correspond to blocks. The block to which the list element applies is identified by its name, so list names must correspond to block names.
post:: A vector of strings of length length(blocks) with commands for post-processing.
blots:: "Block dots". The blots argument to the mice() function.
ignore:: A logical vector of length nrow(data) indicating the rows in data used to build the imputation model. (new in mice 3.12.0)
seed:: The seed value of the solution.
iteration:: Last Gibbs sampling iteration number.
lastSeedValue:: Random number generator state.
chainMean:: An array of dimensions ncol by maxit by m elements containing the mean of the generated multiple imputations. The array can be used for monitoring convergence. Note that observed data are not present in this mean.
chainVar:: An array with similar structure as chainMean, containing the variance of the imputed values.
loggedEvents:: A data.frame with five columns containing warnings, corrective actions, and other inside info.
version:: Version number of mice package that created the object.
date:: Date at which the object was created.

LoggedEvents

The loggedEvents entry is a matrix with five columns containing a record of automatic removal actions. It is NULL is no action was made. At initialization the program removes constant variables, and removes variables to cause collinearity. During iteration, the program does the following actions:

One or more variables that are linearly dependent are removed (for categorical data, a 'variable' corresponds to a dummy variable)
Proportional odds regression imputation that does not converge and is replaced by polyreg.

Explanation of elements in loggedEvents:

it: iteration number at which the record was added,
im: imputation number,
dep: name of the dependent variable,
meth: imputation method used,
out: a (possibly long) character vector with the names of the altered or removed predictors.

Methods

The mids class of objects has methods for the following generic functions: print, summary, plot.

Plot

The plot() metho plots the trace lines of the MICE algorithm. The plot method for a mids object plots the mean imputed value per imputation and the mean standard deviation of the imputed values against the iteration number for each of the $m$ replications. By default, the function creates a plot for each incomplete variable. On convergence, the streams should intermingle and be free of any trend.

Author

Stef van Buuren, Karin Groothuis-Oudshoorn

Details

The S3 class mids has the following methods: bwplot(), complete(), densityplot(), plot(), print(), stripplot(), summary(), with() and xyplot().

References

van Buuren S and Groothuis-Oudshoorn K (2011). mice: Multivariate Imputation by Chained Equations in R. Journal of Statistical Software, 45(3), 1-67. tools:::Rd_expr_doi("10.18637/jss.v045.i03")

Examples

Run this code

data <- data.frame(a = c(1, NA, 3), b = c(NA, 2, 3))
q <- list(
  a = structure(
    list(`1` = 3, `2` = 3, `3` = 3, `4` = 3, `5` = 3),
         row.names = "2", class = "data.frame"),
  b = structure(
    list(`1` = 3, `2` = 3, `3` = 2, `4` = 2, `5` = 3),
         row.names = "1", class = "data.frame"))

imp <- mids(
  data = data,
  imp = q,
  m = 5,
  where = is.na(data),
  blocks = list(a = "a", b = "b"),
  nmis = colSums(is.na(data)),
  method = c(a = "mean", b = "norm"),
  predictorMatrix = matrix(1, nrow = 2, ncol = 2, dimnames = list(c("a", "b"), c("a", "b"))),
  visitSequence = c("a", "b"),
  formulas = list(a = a ~ b, b = b ~ a),
  post = NULL,
  blots = NULL,
  ignore = logical(nrow(data)),
  seed = 123,
  iteration = 1,
  chainMean = list(a = c(1, 2, 3), b = c(3, 2, 1)),
  chainVar = list(a = c(1.1, 1.2, 1.3), b = c(0.9, 1.0, 1.1)),
  loggedEvents = NULL)

print(imp)
imp <- mice(nhanes, print = FALSE)
plot(imp, bmi + chl ~ .it | .ms, layout = c(2, 1))

Run the code above in your browser using DataLab