Platform Setup¶

Page Maps¶

graph LR
  family["Reproducible Research"]
  program["Deep Dive Snakemake"]
  section["Guides"]
  page["Platform Setup"]
  capstone["Capstone evidence"]

  family --> program --> section --> page
  page -.applies in.-> capstone

flowchart LR
  orient["Orient on the page map"] --> read["Read the main claim and examples"]
  read --> inspect["Inspect the related code, proof, or capstone surface"]
  inspect --> verify["Run or review the verification path"]
  verify --> apply["Apply the idea back to the module and capstone"]

Read the first diagram as a timing map: this guide is for a named pressure, not for wandering the whole course-book. Read the second diagram as the guide loop: arrive with a concrete question, use only the matching sections, then leave with one smaller and more honest next move.

Deep Dive Snakemake depends on more than a snakemake binary existing somewhere on the machine. The course assumes a small, explicit platform contract.

This page makes that contract clear before you hit avoidable setup failures.

Minimum Tooling¶

You need:

Python 3.11 or newer
Snakemake in the supported >=9.14,<9.24 window if you are using a preinstalled global binary
a writable local filesystem for the capstone working directories
dot from Graphviz if you want DAG or rulegraph rendering

The safest path on a fresh machine is still make bootstrap-confirm, because it creates the supported local toolchain instead of depending on whatever snakemake happens to be installed globally.

Version Contract¶

The course and capstone keep 9.14.x as the clean-room classroom baseline, and the packaging surfaces accept the broader supported window >=9.14,<9.24. That split is intentional:

environment.yaml preserves the pinned 9.14 baseline for a stable teaching and container contract
pyproject.toml and make bootstrap accept newer compatible 9.x releases without pretending the capstone is version-agnostic

That matters because the course relies on modern behavior around profiles, modules, reporting, and current CLI surfaces.

Use one of these two routes:

preferred: make bootstrap-confirm to create a repo-managed local toolchain inside the supported window and run the strongest clean-room proof route
acceptable: use a preinstalled snakemake, but verify snakemake --version falls inside >=9.14,<9.24 before trusting course commands literally

Repository Root¶

The course-level commands use the repository root Makefile:

make PROGRAM=reproducible-research/deep-dive-snakemake program-help
make PROGRAM=reproducible-research/deep-dive-snakemake docs-build

Use these commands when you want docs or program-level verification.

Capstone Setup¶

From programs/reproducible-research/deep-dive-snakemake/capstone/:

make bootstrap
make walkthrough
make wf-dryrun

That sequence creates the supported local toolchain under artifacts/venv/reproducible-research/deep-dive-snakemake/capstone/, prints the resolved versions, and proves the workflow can at least plan correctly before a full execution.

One-Command Truth Path¶

On a fresh machine, the shortest honest setup-and-proof route is:

make bootstrap-confirm

That target creates the supported local toolchain and then runs the clean-room confirmation route without depending on a preinstalled global snakemake.

Verify Your Setup¶

From the capstone directory:

make help
make bootstrap
make verify

If make bootstrap and make verify both succeed, the capstone can execute, publish its bundle, and validate the promoted artifacts using the supported local toolchain.

Common Setup Failures¶

Symptom	Likely cause	Fix
`make bootstrap` fails immediately	Python 3.11+ is missing or unavailable to `python3`	install Python 3.11+ and rerun `make bootstrap`
`snakemake` missing in `make info`	no global Snakemake is installed and `make bootstrap` has not been run yet	run `make bootstrap` or point `SNAKEMAKE` at the intended binary
config validation skips unexpectedly	`jsonschema` or `pyyaml` missing	install the missing Python packages if you want schema validation to execute
`dag` or `rulegraph` fails	Graphviz `dot` missing	install Graphviz and rerun the target
`verify` fails after a successful dry-run	runtime dependencies or filesystem assumptions differ from the planning surface	inspect `profiles/`, `config/`, and the failing rule logs before changing workflow code