Why Software Versions Belong in a MICE Report
A MICE analysis is carried out by more than its statistical specification. The R interpreter evaluates the code, packages supply functions and algorithms, and the operating system and external tools can affect installation or execution. A report that names the imputation method but leaves these dependencies unspecified may be difficult to reproduce, even when the code and input data are available.
Software reporting is not the same as reporting the implemented MICE workflow. The workflow describes what the analysis did; the software record describes the computational environment in which it was done, and how that environment can be reconstructed. The aim is not to list every technical detail indiscriminately. It is to identify versions and dependencies that matter for installing, running, and interpreting the analysis.
The exact record depends on how the analysis is run. A project that uses only R packages installed from binaries has different system requirements from one that compiles packages from source or calls an external executable. The record should report what was actually used, not a generic list of tools that might have been used.
What to Record
A useful software record has four related layers. Together they identify the environment without implying that a version list alone guarantees identical results.
| Layer | What to report | Why it matters |
|---|---|---|
| Operating environment | Operating system and version, architecture, and relevant system libraries or runtime details | Installation and some numerical or system-level behavior can depend on the platform. |
| R | R version and, when relevant, build or platform details | R versions can differ in behavior, compatibility, and available package binaries. |
| R packages | Versions of packages directly used, with a lockfile for the project dependency set | Package functions, defaults, and dependency requirements can change between releases. |
| External tools | Tool name and version, plus relevant system libraries, services, or configuration | R package records do not automatically describe software invoked outside R. |
For a MICE project, report the version of mice and the versions of packages that provide other analysis functions used in the project. Include packages used for data preparation, model fitting, and output generation when their behavior is material to the reported results. This is not a requirement to print a sprawling inventory of every package installed on a computer. A project lockfile is generally a better way to retain the project dependency set, including indirect dependencies.
A package dependency can be direct or transitive. A direct dependency is explicitly used or declared by the project. A transitive dependency is required by another package in that dependency chain. Both can affect whether a project installs or runs. A lockfile records package information for a project environment according to the package manager's format; it is not a complete record of all software on the host computer.
Lockfiles: Useful, but Not the Whole Environment
A dependency lockfile records package versions and related source or repository information so that the project's R package library can be restored more consistently. In R, a project using renv can retain an renv.lock file alongside the project. The lockfile is useful only when it is saved, kept synchronized with the project, and used during restoration. Merely stating that a lockfile exists does not tell a reader which one was used.
A lockfile does not, by itself, ensure that a restoration will succeed on every computer. A required package version may no longer be available from its recorded source, a system library may be missing, or a package may require compilation tools. Nor does the lockfile necessarily capture every relevant detail of an external program, operating system, or hardware configuration. State the R version and platform separately, and name additional requirements when they apply.
A session report, such as the output of sessionInfo(), is a useful supplement: it can report the R session's platform and information about attached packages and loaded namespaces. It is not a substitute for a project lockfile. It may not represent every package installed in the project library, and it does not fully specify system-level dependencies or external tools. Use the lockfile for the project dependency set and a session report as a snapshot of the session that actually ran.
A Short Justification for the Record
Think of an analysis environment as a collection of components. Let \(E\) denote the environment description, with components for platform, R, packages, and external requirements. For two runs to use the same recorded software environment, their reported components must agree:
If even one component that affects execution is unreported, the reader cannot check whether it agrees between the original run and a reproduction attempt. Recording the components therefore makes comparison possible. This is a justification for a complete record, not a theorem that matching records force identical output: random-number handling, hardware, numerical libraries, input data, and execution details can also matter. Software documentation narrows uncertainty; it does not replace the rest of reproducibility practice.
Worked Example: Writing a Concise Software Record
Suppose a hypothetical MICE project ran on Ubuntu 22.04, 64-bit x86_64, with R 4.4.2. Its project library used mice 3.17.0 and dplyr 1.1.4. The project retained an renv.lock file, and no executable outside R was called. Draft a concise record and check its contents.
Record: “The analysis was run with R 4.4.2 on 64-bit x86_64 Ubuntu 22.04. The project used mice 3.17.0 and dplyr 1.1.4; the project dependency versions are recorded in the accompanying renv.lock file. No external executable was required.”
The record names the operating system and architecture, the R version, two material package versions, and the lockfile. The package versions are consistent with the statement about the project environment only if they are also the versions recorded for that project's library; the record should be checked against the lockfile rather than copied from memory. If the project used other analysis packages, they should be identified or recoverable from that same lockfile.
Worked Example: Diagnosing an Incomplete Version Statement
A hypothetical report says, “We used R and the latest version of mice.” The analysis files contain an renv.lock recording R 4.3.3 and mice 3.16.0, but the report does not identify an operating system. What should be corrected?
“Latest” is not a stable version identifier: it can refer to different releases at different dates or from different repositories. Replace it with the version used in the analysis, here mice 3.16.0, and report R 4.3.3. The lockfile supports those statements, provided it is the lockfile for the run being reported.
The operating system is still missing. It cannot be inferred from the two package versions, so the analyst must verify it from the run environment or its records. A corrected statement might read: “The analysis used R 4.3.3 and mice 3.16.0 on [verified operating system and version]; package dependencies are recorded in the accompanying renv.lock file.” The bracketed information must be replaced with an observed value, not guessed.
Worked Example: Recording an External Tool and a System Requirement
In a hypothetical project, R and its packages performed the MICE analysis, but a separate command-line program called toolX converted an input file before the R code read it. The conversion also required a system library called libY. The project used R 4.4.2 and mice 3.17.0. What should the software record include?
It should name the relevant versions and requirements, for example: “R 4.4.2 and mice 3.17.0 were used on [operating system and version]. Input conversion used toolX [verified version] and required libY [verified version or documented system package]. R package dependencies are recorded in renv.lock.”
The actual versions of toolX and libY must be obtained from the environment or installation records; they cannot be derived from the R package versions. If the tool version cannot be recovered, report that limitation plainly rather than supplying a plausible-looking value. A package lockfile alone does not document this external dependency.
Building and Checking the Record
A reliable record can be assembled as a short sequence of checks. Keep the evidence with the project so that the report and the saved environment description can be compared later.
Record the operating system and version, architecture, and R version from the environment that executed the analysis.
Confirm the versions of mice and other material packages against the project library and lockfile. Avoid labels such as “current” or “latest.”
Keep the lockfile with the project and use the package manager's restoration procedure when rebuilding the R library. Record which file is the project lockfile.
Determine whether execution depended on external programs, system libraries, compilers, or services. Report versions or requirements that affect installation or execution.
Check that the written R and package versions agree with the lockfile and session record, and that the platform and external requirements are not omitted.
This procedure assumes that the record refers to the environment used for the reported run, that the lockfile is retained and readable, and that the stated package versions can be verified. It does not assume that the same version is available from every repository or that a restored library will be bit-for-bit identical across operating systems.
Alternatives, Diagnostics, and Limitations
Different documentation tools serve different purposes. A lockfile is usually the central record for restoring project package versions. A session report is useful evidence about the R session that ran. A container image can also describe and distribute a larger environment, including system components, but it needs its own image identifier or digest and still may rely on host hardware or services. These approaches complement one another; none should be described as covering more than it actually captures.
| Approach | Strength | Limitation |
|---|---|---|
| Package-version list | Easy to read in a report | Can omit transitive dependencies and platform details. |
| R session report | Snapshots useful details from the running R session | Does not fully specify the project library or non-R requirements. |
| Project lockfile | Records the project package dependency set for restoration | Does not guarantee availability or capture all operating-system and external-tool details. |
| Container or managed environment | Can capture more of the operating environment | Requires an exact image or environment reference and still has host-level limitations. |
Warning signs include an uncommitted or missing lockfile, a report with “latest” instead of a version, a mismatch between the report and lockfile, or a lockfile that does not include packages actually required by the project. Restoration errors can point to unavailable package sources, incompatible R versions, missing system libraries, or compilation requirements. If restoration is tested, record the environment in which that test succeeded; success on one platform does not prove success on all platforms.
A common mistake is to write, “The lockfile guarantees exact reproducibility.” The reasoning is that the lockfile records package versions, so every relevant computational condition must therefore match. The conclusion is too strong: the lockfile principally records R package dependencies, while operating systems, external tools, system libraries, and numerical environments may remain different. A better statement is that the lockfile supports restoration of the project's package environment, alongside a separate record of the R version, platform, and other requirements.
Check Your Understanding
Answer each question, then compare your response with the solutions below.
- Why is “the latest version of mice” not a sufficient version statement?
- What does a project lockfile contribute, and name one category of information it may not fully capture.
- A report includes R 4.4.2 and a lockfile but omits the operating system. Is the software record complete? Explain.
- A program outside R converts a file used by the analysis. What information about it may belong in the record?
- A session report and lockfile list different versions of a package. What should the analyst do before finalizing the report?
Solutions. (1) “Latest” changes over time and may differ by repository; state the exact version used. (2) It records the project's R package dependency information to support restoration; it may not fully capture the operating system, system libraries, or external tools. (3) No. The operating system and relevant platform details should be verified and reported separately because they cannot be inferred from R's version or the lockfile alone. (4) Record the external program's name and verified version, and relevant system libraries or configuration required to run it. (5) Investigate which environment and file correspond to the actual run, resolve the discrepancy using saved evidence, and report only the verified versions. Do not silently choose one source or guess.