E-Science: Build a Reproducible Research Workflow - Yenra

Keep the inputs and the recipe together

A chart on its own hides a surprising amount: which measurements were excluded, which units were converted, whether missing values became zeros, and which software produced the output. Organize a project so those decisions are explicit. This does not require a large computing cluster. A small folder with well-described data and a short script can be a better starting point than a complicated service whose settings are lost.

On a small screen, scroll the table sideways to read all columns.

Separate raw inputs from derived files. When you correct a unit or flag a dubious observation, express that change in code or a documented processing step; preserve the supplied record. Use a version-control system for suitable text files and code, and record the input data version alongside the code revision. Large or restricted datasets may live elsewhere, but their stable identifiers and access instructions still belong in the project record.

Version control helps explain changes; it does not replace tested backups or provide permission to publish data. The authors of Ten Simple Rules for Reproducible Computational Research emphasize preserving the route to each result, avoiding undocumented manual manipulation, and recording software context.

For data, explain each field, its units, codes, and missing-value rules. For code, state how to install dependencies, invoke the analysis, and recognize success. Cornell provides separate guidance for research-data READMEs and research-code READMEs; the distinction helps prevent a detailed dataset description from standing in for missing run instructions.

Try a small, complete analysis

Download the reproducible temperature project (ZIP). It contains fictional observations from the data-logger guide, a plain Python script, documentation, and an expected result. It uses the Python standard library only and makes no network requests. Read the script before running it; it writes only its result file inside the extracted project.

The project contains:

• README.md: purpose, data dictionary, assumptions, commands, and limitations.
• data/raw/temperature-example.csv: six scheduled rows, including one explicitly missing measurement.
• analysis.py: input checks and the calculation, using decimal arithmetic.
• expected/summary.json: the values a successful run should reproduce.
• environment.txt: the Python version used for verification and dependency requirements.
• SHA256SUMS.txt: file fingerprints for the distributed inputs, code, and documentation.

Extract the ZIP into its own folder. With Python 3 available, run python analysis.py from that folder; on Windows, py -3 analysis.py is an alternative when the Python launcher is installed. The script prints its result and writes results/summary.json. It checks that the calculated result matches the included expected result before reporting success.

The script rejects duplicate or out-of-order timestamps, a broken one-minute schedule, inconsistent status/value combinations, and invalid numeric values. It does not fill the missing reading. These checks make the declared assumptions executable. They do not establish that a real sensor was positioned correctly, that the clock was accurate, or that the readings represent every moment of the window.

To explore a changed dataset, copy the project first. A changed valid temperature should make the supplied expected-result comparison fail. Investigate the difference and calculate the new expectation independently before revising it. Changing a test just to make it pass would remove the protection it was meant to provide. For a larger project, keep additional small test cases whose correct answers you can calculate separately.

Publish a version someone can actually use

Freeze the files used for a reported result. Record a release identifier, code revision, input versions, dependencies, and relevant operating environment. If a workflow uses containers, keep the build instructions and an immutable image identifier where possible; a moving tag such as “latest” does not identify one environment. If randomness matters, record seeds and relevant hardware or numerical-library settings, while recognizing that a seed alone may not guarantee identical computation.

The 2025 community paper Applying the FAIR Principles to computational workflows treats workflows themselves as research objects worth describing and sharing. For a release, choose an appropriate repository, add a clear license for the material you may license, and connect the deposited version to its paper or report. Include enough metadata to find and interpret it even when the data require controlled access.

FAIR means findable, accessible, interoperable, and reusable. The FAIR principles address identifiers, metadata, access protocols, provenance, and reuse conditions. Accessible does not necessarily mean downloadable by everyone: the GO FAIR explanation of openness explicitly accommodates controlled access. A FAIR dataset is not automatically accurate, unbiased, or sufficient to reproduce a scientific claim.

Use automation to expose decisions

AI-assisted tools can help draft a data dictionary, suggest input checks, or explain an unfamiliar function. Verify generated code against small examples with independently known answers, including missing values and unit conversions. Check proposed software calls in the actual library documentation. Keep the reviewed code that was run, not only a chat transcript, and follow the project's data-access rules when choosing what a tool may receive.

Here, computational reproducibility means obtaining the stated result from the stated inputs and method. An independent experiment collecting new observations is a different test. A wrong formula can run identically every time; a biased sample can produce a perfectly reproducible mean. The final research record needs both an executable analysis and a reason to believe the experiment answered the intended question.