Putting it all together

CBIO7501 · Lesson 12

Aziz Khan

Today you will

  • reproduce a classmate’s project from a clean clone, with only its README
  • report what worked, what did not, and the one fix that helps most
  • release your ltee-project with a DOI
  • take a checklist into your next project

Take control of each part

Diagram: data and code go into a workflow that runs in a software environment and produces results such as reports and figures.

Figure: NBIS, Tools for Reproducible Research, CC BY 4.0

Data, code, environment, workflow, results: you now have a tool for each.

The five pillars, revisited

Pillar Your LTEE project
Literate programming reports/ltee-report.qmd, notebooks/
Version control and sharing Git, GitHub, pull requests, releases
Environment control pixi.toml + pixi.lock, containers/Dockerfile
Persistent data sharing figshare + NCBI, checksums in metadata/
Documentation README, CITATION.cff, decisions log

Glue: Snakemake/Nextflow and the Reproduce GitHub Action.

The real test

Can someone else get your results, from your repository alone, without asking you?

Today that someone is your neighbor.

Swap and reproduce: the rules

60 minutes.

  1. Clone your partner’s capstone into a new folder
  2. Use only the repository: no questions, no looking over shoulders
  3. Fill in the reproduce report as an issue on their repository
  4. 15 minutes: read both reports together; agree on one fix each

What usually goes wrong

  • A file that only exists on the author’s laptop (git status shows ??)
  • pixi.toml changed, pixi.lock not committed
  • Data downloaded by hand, not by a script
  • An absolute path, or a command missing from the README
  • Results that differ, and nobody wrote down what to expect

Most of these turn the Reproduce check red before anyone else tries.

Release: a version with a DOI

git tag v1.0.0 ──► GitHub release ──► Zenodo archives it ──► DOI
                                         (title, authors, license from CITATION.cff)
  • Practise on sandbox.zenodo.org first
  • New release, new version DOI; the concept DOI always points to the latest
  • ltee-project: public, real Zenodo DOI, hand it in
  • Capstone: a GitHub release is enough; private (shared with the instructor) is fine; sandbox DOI optional

Habits to keep

Projects

  • one folder per project, from raw data to results
  • one Git repository per project
  • data and results stay out of Git
  • commit often

Data

  • raw data read-only
  • no hand-edited copies: script every change
  • backups in more than one place
  • deposit raw data early

Code

  • nothing by hand that code can do
  • scripts, reports and workflows connect raw data to results
  • settings in a config file, not in the code

What is reasonable for your next project?

Level Practices
Minimal: reproducible code and environment, from day one template, Git + GitHub, raw data read-only and scripted, pixi.toml/pixi.lock committed
Good: structured and documented Quarto report or notebooks under Git, Pixi tasks or Snakemake, CI reproduce check, README + CITATION.cff
Great: the full environment, connected in a workflow containers built from the lock file, Snakemake or Nextflow (nf-core on clusters), releases with DOIs

Every tool has alternatives

Job This course Alternatives
version control Git Jujutsu (Git-compatible), Mercurial, Subversion
environments Pixi Conda / Mamba, pip and uv (Python only), apt / brew (system)
workflows Snakemake, Nextflow Make, CWL and WDL, Galaxy (web interface)
literate programming Quarto, Jupyter R Markdown, Marimo (reactive Python notebooks)
containers Docker, Apptainer Podman, virtual machines (VirtualBox)

The ideas transfer: a record of changes, a pinned environment, an automated pipeline, a document computed from data.

Quiz

  1. Your partner’s clone fails, yours works. Most likely cause? (a) their laptop (b) something on your laptop is not committed (c) GitHub
  2. What does a Zenodo release give you that a GitHub repository does not? (a) a website (b) a permanent archive with a DOI (c) CI

Recap

  • Reproducibility is tested by someone else, from a clean clone
  • CI catches most failures before your colleague does
  • Release + Zenodo = a citable, permanent version
  • Start your next project with the checklist, not at the end

Now: tutorial 12, the LTEE project hand-in and the capstone rubric.

Sources

Text and slides CC BY 4.0 unless marked otherwise. Full list: Sources and credits.