A version number is part of the method
Research software is not a passive container. An update can alter defaults, numerical libraries, rounding, missing-value treatment, pseudo-random behaviour or an export format. An analysis run today may therefore differ from one opened in a later release even when the visible commands appear unchanged. A version statement does not prove reproducibility, but it gives an investigation a fixed starting point. Without it, a reviewer cannot readily separate a methodological disagreement from a technical change.
The task is not to inventory every application installed on a computer. Record the components that could affect input, transformation or output. A straightforward qualitative coding task may need far less detail than a model built from dozens of Python packages and native libraries. Let the complexity and the consequence of divergence determine the depth of the record.
What a defensible environment record contains
Start with the product, edition, full version string and build number. Name the operating system and processor architecture. Add modules, plug-ins, language packs, macros and external runtimes. Locale settings such as decimal separator, character encoding and time zone matter when they shape imports or dates. Identify the input dataset by a stable version or checksum; this need not expose confidential data.
- Identity: product, edition, version, build and trusted source.
- Platform: operating system, architecture and relevant hardware.
- Dependencies: packages, extensions, drivers and their versions.
- Configuration: non-default options, locale, filters and weighting.
- Execution: date, input revision, command or click sequence, and outputs.
Keep this record beside the analysis, not in a personal notebook that will be lost at submission. A plain-text file is easy to compare over time and remains readable without specialist software.
Graphical software needs an action trail
For Excel, SPSS, MAXQDA and similar interfaces, record the route from import to export. A screenshot can support an important setting, but it is not a complete method: it may crop a menu, hide earlier actions and cannot easily be searched. Export syntax, logs or histories where the application supports them. Otherwise, number the essential actions and state the dialogue, option and selected value.
Pay particular attention to quiet state: active filters, hidden rows, weighting, exclusion rules, recoding, pivot refreshes and the selected worksheet. Preserve an untouched input separately from the working copy. If a value was corrected manually, log the old value, new value, reason and authorised person. These details make the boundary between automated transformation and human intervention visible.
Freeze code environments thoughtfully
For R, Python and other scripted workflows, generated package lists are more reliable than a selection typed from memory. A lockfile, requirements.txt, renv record or container manifest can pin dependencies at different levels of precision. Store it with the analysis code, an interpreter version and one unambiguous start command. Mention system libraries or drivers that the package manager does not capture.
A frozen specification is a historical record, not an instruction to run vulnerable software forever. Keep the original environment description, then test upgrades in a separate branch or folder. Explain material differences in a changelog. For long-term use, open formats, documented installation steps and an archived release are usually more robust than a link to the moving head of a development branch.
Turn documentation into a re-run test
Ask a colleague, or your future self, to start in a clean folder and follow the record. They should be able to locate the input, reconstruct the environment, identify the entry point and produce the stated outputs. Capture every missing instruction. Compare more than the final estimate: check row counts, exclusions, warnings, intermediate objects and file hashes. For stochastic work, state the acceptable tolerance and document the random seed.
If the historical version can no longer be installed, the record remains useful. It explains how the original result arose and supports a reasoned comparison with a reconstructed or upgraded run. Mark what was emulated, substituted or recalculated. A faithfully reproduced value and a newly interpreted value are different kinds of evidence.
Common mistakes and a sensible privacy boundary
“Analysed in R” is too vague. At the other extreme, publishing an unchecked system dump can disclose user names, private paths, server addresses or credentials. Inspect generated manifests before release and redact secrets without removing methodologically relevant version information. Proprietary software may be described precisely, but licence files and restricted installers must not be distributed.