Key Points

Why Reproducibility Matters

Computational reproducibility means someone can take your code, data, and documentation and get the same results
There are three levels: numerical reproducibility (same numbers), logical reproducibility (same conclusions), and process reproducibility (same workflow)
Reproducibility benefits you first: it’s easier to debug, extend, and share reproducible work

The reproducibility crisis is real, with major consequences for science and careers
Common obstacles include environment differences, manual steps, implicit dependencies, and poor documentation
A reproducibility checklist helps you identify and close gaps systematically
Reproducibility is a practical investment in your research quality and impact

A standard project structure (data/src/results) makes research clear and reproducible
Raw data is sacred: keep it original, unchanged, and read-only
Processed data should be generated by scripts, not manually edited
Results are artifacts that should be regeneratable from code
Always use relative paths in code so it’s portable
Separating concerns (data, code, results) prevents confusion and accidents

A comprehensive README is essential for reproducibility
Document data provenance with source URLs, checksums, and download instructions
Processing logs explain how raw data becomes processed data
Jupyter notebooks should be exploratory; final analysis belongs in clean scripts
A clear project structure section helps newcomers navigate your repository

Your computational environment includes language versions, package versions, system libraries, and OS configuration
“It works on my machine” happens when environments differ; reproducibility requires capturing your environment
conda is the recommended tool for research; it manages Python packages, R packages, and system dependencies
Always export your environment with conda env export and include it in your repository
Pin exact versions before publishing for maximum reproducibility

pip and requirements.txt are alternatives for pure Python projects
Docker provides maximum reproducibility but adds complexity; useful for complex environments
On HPC clusters, document module dependencies separately from conda
Apptainer (formerly Singularity) is the Docker equivalent for HPC clusters where Docker is unavailable – on Sagehen: module load apptainer
Include environment files, setup scripts, and module lists in your repository

Make automates multi-step workflows and only re-runs necessary steps
Makefiles explicitly document data dependencies and analysis steps
A Makefile target depends on prerequisites; if anything changes, the target is re-run
Recipe lines must use TABs, not spaces
.PHONY targets like all, clean, and help make your Makefile self-documenting

Variables, .PHONY targets, and special variables ($@, $<, $^) make Makefiles clean and maintainable
Pattern rules let you define one rule for many similar transformations
Make can orchestrate HPC job submissions for parallel processing
Debug with make -n (dry run) and make -d (debug output)
A good Makefile with help and clean targets makes your workflow self-documenting
For complex pipelines with hundreds of jobs, consider Snakemake or Nextflow

Git is valuable for research beyond just code; track analysis decisions, methods, and evolution
Use meaningful commit messages documenting why you made changes
Avoid tracking: large raw data files, credentials, or binary intermediate results
Your git log is a lab notebook showing the progression of your research
.gitignore keeps large/sensitive/irrelevant files out of version control

Branches let you explore different analysis approaches without breaking working code
Tag versions for submissions, revisions, and publications
Collaborate using shared repositories, feature branches, and pull requests
Git history demonstrates reproducibility: others can see exactly what changed and when
Don’t track large data, binary files, or sensitive information in Git

SLURM job dependencies enable reproducible, sequential workflows on HPC
Use --dependency=afterok:JOBID to make one job wait for another to complete successfully
Job arrays parallelize independent tasks across compute nodes
Robust scripts include input verification, error handling, and output verification
Debug failed jobs by checking logs, using sacct, and running interactively with salloc

Integrate Make with SLURM for automated, reproducible job submission
Track job IDs in files so downstream jobs can declare dependencies
Use --dependency=afterok:JID so SLURM enforces ordering between steps
Capture environment state, input checksums, and compute metadata for reproducibility
Make HPC workflows trackable with clear logging and a make status target
Idempotent reruns require both Make’s modification-time tracking and idempotent scripts
A complete HPC pipeline includes scripts, src, data, results, and logs directories
Verify reproducibility by re-running and diffing outputs; non-zero diff means hidden non-determinism

Comprehensive README is the foundation of research documentation
Include overview, quick start, methods, results, and license in your README
A reproducibility checklist ensures nothing is missed before publication
The complete package includes README, LICENSE, CITATION.cff, environment.yml, and Makefile
Checklist before publication ensures your research is discoverable, citable, and reproducible