Reproducible computational research

Keeping track of your code, software, and progress with git and pixi

Previously

In Capstone Project 2, you fit a molecular clock to a tree of 24 SARS-CoV-2 genomes

I estimated that tree with a program called IQ-TREE, on my computer

Could you redo the whole analysis, from the genomes to the clock? Could I redo it a year from now?

Will it run next year?

A true story from October 2026:

  1. A command that set up a marimo notebook worked fine in September
  2. In October, the same command failed with a long error message
  3. Nothing about the notebook had changed

What changed? Python 3.15 was released. The command asked for “the newest Python,” and one of marimo’s dependencies didn’t work with 3.15 yet

Software changes under your feet, even when your code doesn’t

A reproducibility problem

In a survey of 1,576 researchers:1

  • More than 70% had tried and failed to reproduce another scientist’s experiments
  • More than 50% had failed to reproduce their own

Computational work should be the easy case: a computer does the same thing every time, if we give it the same data, code, software, and steps

What we need to record

Ingredient Example How we’ll record it
Data The 24 aligned genomes Record how we got it (and a copy if it’s not huge)
Code clock.py git
Software Python 3.14, NumPy, IQ-TREE, … pixi
Steps The exact IQ-TREE command pixi tasks
Randomness IQ-TREE’s random search A seed

See Sandve et al. (2013) and Wilson et al. (2017) for more good habits

Version control with git

Without version control

clock.py
clock_v2.py
clock_v2_fixed.py
clock_FINAL.py
clock_FINAL_omicron_removed_USE_THIS_ONE.py
  • Which version made Figure 2?
  • What changed between them?
  • What if I delete the wrong one?

Git keeps a history of snapshots

A commit is a snapshot of your files, with a message, an author, and a date

$ git log --oneline
36c37de Leave Omicron out of the clock
2fc175a Add the molecular clock script and task
99de975 Estimate the ML tree with IQ-TREE
f9d8d06 Add task to download the SARS-CoV-2 alignment, and the data
3d7a7c5 Add IQ-TREE from bioconda
f2f0520 Create a pixi environment with Python 3.14
12f7a96 Add project title and author to README
539e886 Initial commit

One file name, and every version of it, forever

Making a commit

Your files
working folder
git add
⟶
Staged
changes
git commit
⟶
Your history
.git folder
git push
⟶
GitHub
backup & sharing
  • Stage (git add) chooses which changes go in the next snapshot
  • Commit (git commit -m "message") saves the snapshot
  • Push (git push) backs it up on GitHub, where others can see it

Everyday git

Command What it does
git status What has changed since my last commit?
git diff <file> Exactly what changed, line by line
git add <file> Stage a file’s changes for the next commit
git commit -m "..." Save a snapshot of the staged changes
git push Send my commits to GitHub
git log --oneline List my commits
git restore <file> Undo changes since my last commit

What to commit

Commit it Don’t commit it
Code and scripts Installed software (.pixi/)
The instructions for the software (pixi.toml, pixi.lock) Files that change every run (logs with dates)
Small data, and where it came from Big data (record how to get it instead)
Key results (the tree, the figure) Temporary files

A .gitignore file lists what git should ignore

Reproducible environments with pixi

“It works on my computer”

Our analysis needs Python, NumPy, SciPy, matplotlib, and IQ-TREE

Each of those needs other packages, which need other packages, …

Each one has a version, and a different version can change your results, or break your code

A project environment

pixi.toml
what we asked for
pixi solves
⟶
pixi.lock
exactly what we got
pixi install
⟶
.pixi/
the installed software
  • Commit pixi.toml and pixi.lock: small text files
  • Don’t commit .pixi/: big, and pixi can rebuild it, exactly, from the lock file

Building an environment

Terminal
pixi init
pixi add "python=3.14.*" numpy scipy matplotlib marimo
pixi workspace channel add bioconda
pixi add iqtree
  • Packages come from channels: conda-forge (general scientific software) and bioconda (bioinformatics)
  • They include programs that aren’t Python, like IQ-TREE (molab can only install Python packages)
  • "python=3.14.*" pins the version we care about

Recording the steps: tasks

A task saves a command in pixi.toml, so anyone can rerun it

pixi.toml (simplified)
[tasks]
get-data = "curl -L -o data/sars-cov-2.fasta https://..."
tree = "iqtree3 -s data/sars-cov-2.fasta -m HKY -seed 1 ..."
clock = { cmd = "python scripts/clock.py", depends-on = ["tree"] }
Terminal
pixi run clock

One command runs the whole analysis, from the alignment to the figure

The exercise

Codespaces

A codespace is a Linux computer in the cloud, which you use in your web browser, with git and pixi already installed

Codespaces are temporary: GitHub deletes a codespace after 30 days without use, even if your work isn’t pushed. Commit and push often!

The real test

At the end of the exercise, you will:

  1. Delete your codespace
  2. Make a brand new one from your GitHub repository
  3. Run pixi run clock
  4. Run git status
nothing to commit, working tree clean

The new computer reproduced your tree and figure, exactly

The plan

  1. Your project repository: Make your copy, and your first commit
  2. A reproducible environment: Python, packages, and IQ-TREE with pixi
  3. Estimating the tree: IQ-TREE as a pixi task; what to commit
  4. Fitting the clock: Change the analysis; go back in time with git; why the seed matters
  5. Prove it’s reproducible: Delete, rebuild, rerun

Each part ends with a push, so you can stop after any part

Exercise

  1. Open the reproducibility exercise
  2. Follow the steps to copy the project template and open your codespace

References

Baker, Monya. 2016. “1,500 Scientists Lift the Lid on Reproducibility.” Nature 533 (7604): 452–54. https://doi.org/10.1038/533452a.
Sandve, Geir Kjetil, Anton Nekrutenko, James Taylor, and Eivind Hovig. 2013. “Ten Simple Rules for Reproducible Computational Research.” PLoS Computational Biology 9 (10): e1003285. https://doi.org/10.1371/journal.pcbi.1003285.
Wilson, Greg, Jennifer Bryan, Karen Cranston, Justin Kitzes, Lex Nederbragt, and Tracy K. Teal. 2017. “Good Enough Practices in Scientific Computing.” PLoS Computational Biology 13 (6): e1005510. https://doi.org/10.1371/journal.pcbi.1005510.

Acknowledgements

I drafted and iterated on these slides in collaboration with Anthropic’s Claude (Opus 5.5 model).