Why Report the Workflow That Was Run?
A MICE methods description has two related jobs. It should explain the statistical reasoning behind the imputation and analysis, and it should record the concrete steps that were actually executed. Those are not interchangeable. “We used predictive mean matching because the variable was skewed” is a rationale; it does not say which variables were imputed, what predictors were used, or how many imputations were generated. Conversely, a copied function call may expose settings without explaining why they suit the analysis.
A useful report lets a reader trace the path from the prepared incomplete data, through the chained conditional models, to the analysis of the completed datasets. It need not reproduce every line of code. It should, however, make material decisions visible, avoid claiming that an intended setting was executed when it was not, and explain the statistical basis for the choices that matter.
The statistical rationale should be consistent with the assumptions and goals of the analysis. For example, an analyst may justify an imputation model by explaining which observed variables were included to make a missing-at-random assumption plausible, or why a conditional model was appropriate for a variable’s measurement scale. Such reasoning does not prove the assumption or guarantee model adequacy. It explains the choices and their intended role. A workflow report should not turn a rationale into an unsupported claim that the assumptions were satisfied.
What the Account Needs to Make Clear
A compact methods account usually follows the order of the computation. First identify the software used to carry out the imputation and the relevant interface or procedure. Then describe material data preparation, including how special missing-value codes, categories, transformations and derived variables were handled. Next state the run settings and model specification that determine the chained equations. Finally, describe how each completed dataset was analyzed and how estimates were combined.
For the imputation run, report the number of imputations \(m\), the number of iterations per chain, the random seed when set, the method assigned to each incomplete variable, and the predictor choices. State additional settings when they affect the run, such as a nondefault visit order, restrictions on which cells were imputed, or constraints on generated values. If defaults were used, say so only when you have verified which defaults applied. A seed helps document a random-number initialization; by itself it does not guarantee identical results across software environments or establish that the rest of the workflow can be reproduced.
Be precise about the input to the run. Report whether variables were recoded or transformed, whether derived variables were recalculated in the completed datasets, and how the analysis variables were represented. State which variables were imputed and which were not, with a reason where that choice affects interpretation. For example, a variable can be fully observed but still serve as a predictor. A variable excluded from imputation is not necessarily excluded from the analysis.
A reproducible implementation description and a statistical rationale can be organized in separate sentences or columns. The table below illustrates the distinction.
| What to report | Implementation detail | Statistical rationale |
|---|---|---|
| Imputation method | Predictive mean matching was assigned to systolic blood pressure. | It was selected for a continuous variable whose imputed values should remain plausible relative to observed values. |
| Predictors | Age, sex, severity and treatment were included in the blood-pressure model. | The variables were chosen because they were relevant to blood pressure, missingness, or the planned analysis. |
| Derived variable | BMI was recalculated from height and weight in each completed dataset. | This preserves the deterministic relationship between the recorded components and BMI. |
| Run length | Thirty imputations were generated using 25 iterations per chain. | The number of imputations and iterations were selected for the analysis plan, not as evidence that the models were adequate. |
The explanation must match the implemented specification. If the method was changed after a failed run, or a planned predictor was removed, report the final run rather than silently describing the original plan. When an implementation choice has a statistical consequence, report both what happened and why it was done. A model formula is often clearer than a broad statement such as “all relevant covariates were included.”
Worked Examples: Turning a Run into a Report
Worked Example: Reporting the Imputation Specification
Suppose a hypothetical clinical analysis has incomplete systolic blood pressure, adherence status and ordinal severity. Age, sex and treatment group are observed. The analyst runs MICE in R with the mice function, requesting \(m=30\) completed datasets and 25 iterations per chain, and sets the seed to 18427. Predictive mean matching is assigned to blood pressure, logistic regression to binary adherence, and an ordinal logistic model to severity. Each imputation model includes age, sex, treatment group and the other analysis variables. No special visit order is specified.
A report can state: “We used the R mice function to generate 30 imputations, with 25 iterations per chain and random-number seed 18427. Systolic blood pressure was imputed by predictive mean matching, adherence status by logistic regression, and ordinal severity by an ordinal logistic model. The imputation models included age, sex, treatment group and the other analysis variables; the default visit order was used.”
The report then gives the rationale separately: “These conditional models were selected to reflect the continuous, binary and ordinal measurement scales, respectively. The predictor set was chosen to include variables relevant to the planned analysis and to the missingness process.” This explanation records the intended reasoning without claiming that a particular missingness assumption has been verified.
This account is more informative than “MICE was used,” because it identifies settings that define the run. It is also more faithful than listing settings from a planned configuration if the analyst later changed them. In a real report, the analyst should check the executed run object or saved configuration before writing these sentences.
Worked Example: Describing Data Preparation Precisely
Consider a hypothetical dataset with 120 adults. Height is recorded in metres and weight in kilograms, and BMI is a planned analysis variable. Four height entries use the special code 999 to represent missingness. Before imputation, the analyst recodes those four entries as missing, converts sex to a two-level categorical variable, and specifies BMI to be recalculated from height and weight in each completed dataset.
For one hypothetical adult with weight 72 kg and height 1.70 m, the derived value is calculated as:
A methods description could say: “Before imputation, the code 999 in height was recoded as missing, and sex was represented as a two-level categorical variable. BMI was recalculated from imputed height and weight in each completed dataset using weight in kilograms divided by squared height in metres.” This states what the code did and makes the transformation interpretable.
The rationale is that BMI is deterministically defined by height and weight; recalculating it preserves that definition within each completed dataset. The account should not instead imply that BMI was independently imputed if it was calculated from the imputed components. The four recoded entries are included here to make the hypothetical preparation step explicit, not as a claim about any real dataset.
Worked Example: Reporting the Analysis Sequence
In a hypothetical teaching example, five completed datasets are used to fit the same logistic regression for a binary outcome, with treatment group as the predictor. Suppose the estimated treatment coefficients, on the log-odds scale, are 0.10, 0.12, 0.08, 0.11 and 0.09. The corresponding within-imputation variances are each 0.010. This small example is for showing how to describe the sequence and pooling arithmetic; five imputations are not a general recommendation.
First, average the five coefficient estimates:
The deviations from 0.10 are 0, 0.02, -0.02, 0.01 and -0.01. Their squared values sum to 0.001, so the between-imputation variance is:
The mean within-imputation variance is \(\bar{U}=0.010\). Applying Rubin’s total-variance formula gives:
The methods description should say that the same logistic regression was fitted to each of the five completed datasets and that estimates and variances were combined using Rubin’s rules. It should not report only an estimate from one completed dataset. The pooled coefficient here is 0.10 log-odds units for the treatment contrast; the calculation illustrates the sequence, not a claim about a real treatment effect.
A Short Justification for Reporting the Sequence
The reason to document the sequence rather than just name the method is that the result depends on linked implementation decisions. Let \(D\) denote the prepared incomplete data, \(C\) the run configuration, and \(A\) the analysis procedure. The reported estimate can be viewed schematically as a function of all three:
Changing \(D\), such as by treating a special code as a valid measurement rather than missing, changes the input. Changing \(C\), such as the imputation methods or predictor set, changes the chained conditional models. Changing \(A\), such as fitting a different model in each completed dataset, changes what is pooled. Therefore, naming MICE alone cannot identify the implemented analysis. A concise account of the sequence exposes the decisions that connect the incomplete data to the final estimate.
This is a reporting justification, not a guarantee of exact computational replication. Random-number generation, software behavior and other environment details can affect whether an identical numerical result is obtained. The methods account should accurately describe the run and support interpretation; reproducibility also depends on retaining suitable code and records.
Common Reporting Failures and Practical Checks
- Reporting intention instead of execution. “We planned 30 imputations” is not a description of a run that stopped after 18. Report the completed run and disclose material departures from the plan.
- Giving a seed as if it were a full specification. A seed does not identify the prepared data, model methods, predictors or analysis procedure. Report those as well.
- Using vague predictor language. “Relevant covariates were included” does not identify the models. Name the predictors or provide a readable model specification.
- Conflating rationale with evidence. Saying that variables were included to make a missing-at-random assumption more plausible does not establish that the assumption holds. Describe the rationale without overstating what the data can show.
- Leaving derived variables ambiguous. State whether a derived variable was imputed directly or recalculated from its components in each completed dataset.
- Describing only the imputation stage. State what analysis was fitted to each completed dataset and how its estimates were combined. Otherwise, the transition from imputations to reported results is unclear.
Before finalizing the methods account, compare it with the executed configuration and saved run record. Check that the number of completed imputations, iteration count, seed, variable-specific methods and predictor choices match the actual run. Then confirm that data transformations and the final analysis sequence are described in the same order in which they occurred. These checks help detect a mismatch between the report and the computation; they do not replace assessment of model assumptions or diagnostics.
There are limits to what a methods paragraph can accomplish. A long list of settings without a rationale is hard to interpret, while a rationale without settings is hard to reproduce. A report also cannot by itself establish that the imputation models were well specified or that the missingness assumptions were correct. Keep the account selective but complete: include decisions that affect the data, imputation or analysis, and keep detailed technical records available where the prose would otherwise become unwieldy.
Check Your Understanding
Answer each question, then compare your response with the solutions below.
- A report says, “MICE was run with a fixed seed.” Name three other implementation details that would help identify the run.
- A continuous variable was imputed by predictive mean matching because the analyst wanted plausible values. Which part is the implementation detail and which is the rationale?
- Height and weight were imputed, and BMI was recalculated in each completed dataset. What must the methods description clarify about BMI?
- Five completed datasets each produce a treatment coefficient on the log-odds scale. What analysis steps should be reported after the imputation step?
- Why does describing variables as “relevant predictors” leave an important reporting gap?
Solutions. (1) Report, for example, the number of imputations, iterations per chain, methods assigned to incomplete variables, predictor choices, and any material nondefault settings. (2) Predictive mean matching is the implementation detail; the desire to generate plausible values is the rationale. (3) Clarify that BMI was calculated from height and weight within each completed dataset, rather than independently imputed, and state the formula and units if needed. (4) State that the same specified analysis was fitted to each completed dataset and that the resulting estimates and variances were combined using the stated pooling procedure. (5) It does not identify which variables entered which conditional models, so readers cannot understand the implemented predictor specification.