Reproducibility is a Habit, Not a Checkbox

The Silent Rot of Computational Projects

Every computational researcher has experienced the cold dread of revisiting an analysis written two years prior. A reviewer requests a minor revision: adjust the FDR threshold from $0.05$ to $0.01$ and regenerate Figure 4B.

You open the terminal. You navigate to the repository. You run the script:

$ python3 generate_figure_4b.py
Traceback (most recent call last):
  File "generate_figure_4b.py", line 14, in <module>
    import scanpy as sc
ModuleNotFoundError: No module named 'scanpy'

You install scanpy. You re-run. Now an internal API changed: sc.tl.louvain() was replaced by sc.tl.leiden(). You fix the import. The code runs—and the resulting cluster assignments do not match Figure 4B in the submitted PDF. Different cell populations are labeled. The seed was omitted, the package versions were unpinned, and the raw intermediate matrix was manually overwritten in Excel during a late-night debugging session.

The project has decayed. Not because the biological idea was flawed, but because computational hygiene was treated as an afterthought.

       Fragile Analysis (Checkbox Mentality)           Reproducible Analysis (Habit)
  ┌─────────────────────────────────────────┐     ┌─────────────────────────────────────────┐
  │ • Manual file downloads                 │     │ • Deterministic Makefile / Nextflow     │
  │ • Unpinned 'pip install foo'            │     │ • Explicit lockfile (conda-lock / uv)   │
  │ • Hardcoded absolute paths              │     │ • Relative paths & config-driven params │
  │ • No random seeds set                   │     │ • Fixed RNG seeds across all steps      │
  │ • Excel formatting side-effects         │     │ • Immutable raw data, automated QC      │
  │ Result: Cannot rerun after 6 months     │     │ Result: Fully rerun on clean VM         │
  └─────────────────────────────────────────┘     └─────────────────────────────────────────┘

The Four Pillars of Computational Durability

Over years of debugging broken pipelines, four non-negotiable principles have emerged:

1. Immutable Raw Data

Raw sequencer outputs (.fastq.gz), microarray CEL files, and clinical spreadsheets must be marked read-only immediately upon receipt. No human hand or automated script should ever write to the data/raw/ directory. All subsequent steps must read from raw/ and write downstream derivatives to timestamped data/processed/ folders.

2. Lockfiles, Not Loose Requirements

Writing requirements.txt with pandas>=1.3 is an invitation for future failures. A patch release can alter default parameters or change tie-breaking behavior in sorting algorithms. Use lockfiles (conda-lock, uv.lock, or Docker containers) that record exact SHA-256 checksums of every shared library.

3. Workflow Engines over Bash Scripts

A single sequential bash script (run_all.sh) fails silently when an intermediate step crashes midway. Using modern workflow managers (Nextflow, Snakemake) guarantees checkpointing, resume capabilities, and explicit dependency graphing.

4. Zero Manual GUI Edits

The moment a scientist drags a .csv into Microsoft Excel, dates turn into gene symbols (the infamous SEPT2 $\to$ 2-Sep conversion), and trailing zeros are silently truncated. If an edit cannot be audited in a git diff, it should not happen.

Conclusion

Reproducibility is not something you paste onto a project in the final week before manuscript submission. It is the discipline with which you name files on day one, the habit of recording seeds, and the respect you extend to your future self and the wider scientific community.