Capturing and Inspecting MICE Run Objects

Why Capture the Run Object?

A completed MICE run is more than a set of filled-in data tables. The fitted object contains the incomplete input and information about the imputation process, including imputed values and several settings. If you retain only a few completed data sets copied from the console, you lose much of the context needed to inspect or reproduce the run. Console output is also transient: it can be truncated, reformatted, or separated from the data that produced it.

This tutorial focuses on capturing an object in memory together with the settings and input identifiers needed to interpret it. It does not treat the fitted object as proof that the analysis is statistically appropriate. Its contents must still be interpreted in light of the imputation models, assumptions, and diagnostics.

Definition: A MICE run record is a deliberately assembled object containing the fitted MICE object and a compact record of the inputs and run settings used to create it. The fitted object may retain many settings, but a separate record makes important choices explicit and easier to review.

In R, the fitted object returned by the mice package is commonly a mids object. Its named components can be inspected with ordinary R operations such as names(fit) and str(fit, max.level = 1). The exact set and details of components can vary by package version, so inspect the object actually returned by the installed version rather than assuming every field is present.

What to Capture Alongside the Fitted Object

The object itself typically contains the incomplete data, imputation results, and a number of run details. A separate record should preserve the choices that matter for identifying and interpreting this run, including the input identifiers and a human-readable settings list. Do not assume that a single field inside the object is a complete record of the analysis plan.

A useful record can include the input row identifiers in their original order, a description or version of the input data, the number of imputations $m$, the iteration limit, the seed supplied to the run, the chosen methods, the predictor specification, and software versions. Some of these may also be stored in the fitted object. Recording them explicitly provides a convenient cross-check. Retain only identifiers that are needed for review, and protect them as carefully as the underlying data when they can identify individuals.

Key distinction: The fitted object records the result and some of the run configuration; the accompanying record states which input and intended settings the analyst associates with that result. Neither one alone establishes that the run used the intended data or that the imputation models were suitable.

Worked Example: Assembling an In-Memory Run Record

Suppose a hypothetical analysis uses 100 records with an identifier, a fully observed predictor x, a binary group variable, age, and a continuous score. Age is missing for rows 3, 19, and 41; score is missing for rows 7, 19, 52, and 88. The identifier is retained separately and is not used as an imputation predictor. The analysis plan specifies five imputations, 10 iterations, and seed 2718.

After preparing the data frame called dat without the identifier column, the following is an illustrative R pattern:

id_used <- input$id
cfg <- list(m = 5, maxit = 10, seed = 2718,
  methods = c(age = "pmm", score = "pmm"),
  predictorMatrix = pred, input_version = "analysis extract 2026-10-25")
fit <- mice::mice(dat, m = cfg$m, maxit = cfg$maxit,
  seed = cfg$seed, method = meth, predictorMatrix = cfg$predictorMatrix)
run_record <- list(fit = fit, settings = cfg, input_id = id_used)

Here, meth and pred are the method vector and predictor matrix already specified for the run; their values should agree with the explicit record in cfg. The row order of id_used must match the rows of dat. An immediate check is length(id_used) == nrow(dat), which should evaluate to TRUE. This record remains in memory; creating a durable file is a separate task.

The example names software version and input version in the settings record because the returned object is not a substitute for identifying the environment and input. It also keeps the identifier out of the imputation predictors. If the dimensions or row order differ, the association between imputed rows and identifiers is no longer trustworthy.

Inspecting the Stored Components

Inspection should answer targeted questions, not just display a large object. Start with the object class and names, then check the input dimensions and missingness counts, the settings, and the stored imputations. In a mids object, commonly useful components include data, imp, m, nmis, method, predictorMatrix, where, iteration, chainMean, and loggedEvents. Use names and structure inspection to confirm which are available.

The data component is the incomplete input used by the run. The imp component stores imputed values by variable. For a variable with missing values, its imputation table generally has one row per imputed case and one column per imputation. Thus, if $r_j$ cases are missing on variable $j$, the corresponding imputation table has $r_j$ rows and $m$ columns. A logical where matrix can indicate which cells were to be imputed; nmis gives missing-value counts by variable. These components should agree with the input pattern.

The method component identifies the method used for each variable, and the predictorMatrix records predictor choices in the conventional setup. Iteration summaries such as chainMean and chainVar provide stored information about chains, but their presence does not establish convergence. If a component is absent, empty, or has unexpected dimensions, consult the installed package's object structure and run configuration before drawing conclusions.

Worked Example: Checking Imputation Table Dimensions

Use the hypothetical 100-row data set above. There are three missing age values and four missing score values, so $n_{\mathrm{mis,age}}=3$, $n_{\mathrm{mis,score}}=4$, and $m=5$. The expected stored tables have dimensions $3 \times 5$ for age and $4 \times 5$ for score.

In R, inspect fit$nmis, dim(fit$imp$age), and dim(fit$imp$score). The expected results are, respectively, counts of 3 and 4 for age and score, dimensions 3 5 for age, and dimensions 4 5 for score. The dimension check follows directly from the storage layout: each missing case contributes one row of imputed values, and each imputation contributes one column.

A compact consistency check is stopifnot(fit$m == cfg$m, nrow(fit$data) == length(id_used), fit$nmis["age"] == 3, fit$nmis["score"] == 4, nrow(fit$imp$age) == 3, ncol(fit$imp$age) == 5, nrow(fit$imp$score) == 4, ncol(fit$imp$score) == 5). If any condition fails, stop and investigate rather than treating the object as the planned run. For example, a four-column score table would not match five requested imputations, and an age count of zero would contradict the stated input pattern.

Deriving a Basic Structural Check

The dimension check is not an arbitrary convention. Let $W$ be the logical imputation-target matrix, with one row per input record and one column per variable. Define $r_j$ as the number of TRUE entries in column $j$. Under the usual mids representation in which only targeted cells are listed in imp, the table for variable $j$ contains $r_j$ rows and $m$ imputation columns. Therefore:

\operatorname{dim}(\text{imp}_j) = (r_j,m), \qquad r_j = \sum_{i=1}^{n} I(W_{ij}=\mathrm{TRUE}).

For ordinary missing-at-random-cell imputation with no extra cells deliberately targeted, $r_j$ is the number of missing observations in variable $j$, so it should equal the corresponding count in nmis. If the analyst deliberately targets observed cells too, the number of TRUE entries in where can exceed the number of missing values. In that case, the table row count is checked against the target pattern, not blindly against the missing count. This qualification matters because an intentional overimputation target is not automatically an error.

The check is structural, not inferential. Matching dimensions show that the object layout is compatible with the target pattern; they do not show that imputed values are plausible, that chains mixed adequately, or that the missingness assumptions are defensible.

Worked Example: Separating Structural Checks From Model Review

Suppose the age imputation table for the hypothetical data set has three rows and five columns, as expected. Inspecting its dimensions confirms that 15 age values are stored. The number 15 is $3 \times 5$: three targeted cases, each represented in five completed data sets. It does not mean that there are 15 distinct people with missing age.

Next inspect the actual values, for example with head(fit$imp$age), and confirm that the table's case labels correspond to the intended missing rows where the object representation provides those labels. Compare the age values across imputations for each case. A stored value outside a possible age range, such as a negative age, would require investigation of the model, constraints, or data handling. A plausible range alone does not validate the distribution or the imputation model.

Finally inspect the methods and predictor specification alongside the run plan. If age was supposed to use predictive mean matching but fit$method["age"] is empty or names a different method, the object and plan disagree. If loggedEvents contains warnings or other records, review each entry in context; an empty event list is not proof that every modeling assumption holds.

Diagnostics, Alternatives, and Limits

A systematic inspection is more reliable than treating printed console output as a record. A short sequence is:

Identify the object.
Check its class, names, row count, and number of imputations. Confirm that these match the intended run.

Check input alignment.
Compare the number and order of retained identifiers with the rows in the incomplete data. Verify the recorded input version or description.

Reconcile targets and results.
Compare missingness counts and the imputation target pattern with the row counts and columns of the stored imputation tables.

Review choices and warnings.
Compare methods and predictors with the run plan, and inspect recorded events and chain summaries rather than relying on a short printout.

The main alternative is to retain only the completed data sets or a console transcript. Completed data sets can be useful for downstream work, but by themselves they may not retain the incomplete input, target pattern, methods, predictor choices, or chain-level summaries. A transcript may show selected settings but does not provide a structured object for programmatic checks. A run record combines a structured fitted object with an explicit settings and identifier record, while avoiding the assumption that either alternative is sufficient by itself.

Object inspection has important limits. It can identify mismatched dimensions, unexpected methods, missing components, and recorded warnings. It cannot establish that the imputation model is congenial to the analysis, verify the missing-data assumptions, guarantee adequate mixing, or rule out data leakage. Those require substantive review and appropriate statistical diagnostics. The object may also contain sensitive input data and imputed values, so access and handling must follow the same protections as the source data.

Common Mistakes

Using the console display as the record. Printed output is selective and transient. Inspect and retain the structured object together with explicit run settings.
Assuming the object contains every needed choice. Some fields can be version-dependent or incomplete as a record of intent. Keep key settings and input identifiers alongside it.
Misreading imputation-table dimensions. Three rows and five columns represent three imputed cases across five imputations, not five additional cases or 15 people.
Treating structural agreement as statistical validation. Correct dimensions do not establish convergence, plausible distributions, or valid assumptions.
Including identifiers as predictors merely because they are available. Keep identifiers for alignment and review unless a substantive modeling rationale supports their use.

Key takeaway: Capture the fitted MICE object with a compact record of run settings and row identifiers, then check the stored input, target pattern, imputation tables, methods, and events. These checks establish traceable structure, not statistical validity.

Check Your Understanding

Answer each question, then compare with the solutions.

A run uses $m=4$, with two missing values in a variable and no other cells targeted. What dimensions should its imputation table have?
Why keep the input identifiers outside the predictor data frame?
The intended run has five imputations, but a stored imputation table has four columns. What should you conclude and do?
Does a matching imputation-table dimension establish convergence? Explain.
Name two kinds of information that should accompany a fitted object even if the object also stores some run settings.

Solutions. (1) It should have two rows and four columns: one row per targeted case and one column per imputation. (2) Identifiers support row alignment and review; using them as predictors without a substantive rationale can introduce meaningless or problematic model information. (3) The object does not match the intended setting or the assumed representation; stop and investigate the stored object, configuration, and package behavior before using it. (4) No. Dimensions check structural consistency only; convergence requires appropriate chain diagnostics and substantive assessment. (5) Examples include the input identifiers and version or description, and explicit settings such as $m$, iteration limit, seed, methods, predictors, or software version.