Step 2 Running the Pipeline

Step 2: Running the Pipeline

What is this?

One Snakemake command that builds all 27 trees and the reports from the files in source/.

Why does it matter?

Snakemake runs every step in the right order and only reruns what changed, so a run is repeatable and resumable.

What do I do?

Archive the previous run, dry-run, run, then check the result.

Snakemake is the workflow tool that runs the pipeline. It is made of rules: each says which files it needs, which it makes, and the command in between. Snakemake works out the order (the DAG, the graph of steps) from those files.

flowchart LR
    CMD["snakemake --profile profiles/default --cores 8"] --> ON["Run start:<br/>provenance + data scan<br/>.run/run_logs/"]
    ON --> ING["Ingest<br/>source/ → fludb.db → data/"]
    ING --> RES["Per build:<br/>Nextclade, filter, align, tree<br/>results/{subtype}/{segment}/"]
    RES --> AUS["auspice/{subtype}/*.json"]
    AUS --> REP["Surveillance report<br/>reports/"]
    REP --> END["Run end:<br/>run report<br/>.run/reports/"]

Loading

What happens after you press Enter: inputs flow left to right, and every run is bracketed by a provenance record at the start and a run report at the end.

Before you run

1. conda activate pekosz-nextstrain, and be in the nextstrain folder.
2. source/ holds the three inputs (Step 1).
3. The previous run is archived (below), so old data/, results/ and fludb.db are gone.

The commands

snakemake -n --cores 8                                   # dry run: lists what would run; nothing executes
snakemake --profile profiles/default --cores 8           # full production run (use this day to day)

Always dry-run first after changing anything, and read what it plans to rerun. If it wants to rerun everything after a one-line change, ask why.

The default profile (profiles/default/config.yaml) prints each shell command, prints a failed job's log to the console, reruns jobs interrupted by a crash, and lets unaffected builds finish if one fails. Plain snakemake --cores 8 also works without those conveniences.

Since commit 9478cb9, the ingest rules automate what used to be manual: segment typing with flusort, loading genomes and vaccine strains into fludb, and writing every build's inputs to data/ with fludb/scripts/download.py.

Run a subset

Goal	Command
One build	snakemake --cores 8 auspice/h3n2/ha.json
A few builds	snakemake --cores 8 auspice/h3n2/ha.json auspice/h3n2/na.json
One subtype's genome build	snakemake --cores 8 auspice/vic/genome.json
Everything except the report	snakemake --cores 8 --config surveillance_report=false
The tutorial data	snakemake --profile profiles/default --cores 8 --configfile config/tutorial.yaml

Config options

Set with --config key=value or a file with --configfile:

Key	Default	Effect
source_dir	source	Folder holding the inputs
jhh_sequences, jhh_metadata, vaccine_sequences	source/JHH_sequences.fasta, source/JHH_metadata.txt, source/vaccine.fasta	Individual input paths
surveillance_report	true	false skips the report
snapshot_clean	false	true archives and cleans after a successful full build
sync_subclade_colors	true	false skips syncing subclade colors from nextstrain/seasonal-flu before export (Subclade colors)

Ready-made config files: config/tutorial.yaml (reads all inputs from tutorial/), config/snapshot_clean.yaml (sets snapshot_clean: true). Report settings are in config/report.yaml (Step 4).

Runtime and compute

• Production: the run of 2026-10-06 (20261006T191100) executed 330 jobs in 11 min 20 s on 10 cores. Expect 10 to 20 minutes on a recent 8-core laptop; more with more data.
• Tutorial: a few minutes.
• Cores: thread counts are declared with threads: and capped at --cores. Pass a larger --cores on a server to give the genome alignment (up to 80 threads) and tree (up to 64) more threads; --cores 4 or --cores 2 works on small computers, just slower.
• Network: each run downloads the current Nextclade HA/NA datasets.
• Memory and per-step times for your machine are in the run report (Step 4).

Archive and clean before new data

Warning

Before starting a new build with updated data, you must run this. It archives your current results and cleans the workspace.

The rules live in workflow/snakemake_rules/snapshot.smk and run scripts/snapshot_clean.sh, which:

1. Copies auspice/, .run/, reports/, source/, nextclade/, results/ and config/ (those that exist) into a timestamped folder and compresses it to snapshots/{YYYYMMDDTHHMMSS}.tar.gz.
2. Deletes data/, results/, reports/, auspice/, .run/logs/, .run/benchmarks/, fludb.db and the flusort_* files in source/ and tutorial/. .run/run_logs/ and .run/reports/ are kept, so run history persists.

Option	Command	When
Right now	snakemake --cores 8 snapshot_clean	Before loading new data. Runs every time you call it (no completion marker), so you can make several snapshots
After a successful full build	snakemake --cores 8 --configfile config/snapshot_clean.yaml	Every completed build saves a snapshot and cleans up automatically, after all trees and the report are finished

snapshots/
├── 20251111T163000.tar.gz
└── snapshot_clean.done     # marker used only by the automatic option; does not block manual runs

Build or rebuild reports before cleaning: reports/ is archived and then removed.

Tutorial vs. production

Both use the same data/, results/, .run/, auspice/, reports/ and fludb.db. Never mix them: archive and clean, or use a separate clone, when switching. Omitting --configfile config/tutorial.yaml restores the normal source/ inputs.

Troubleshooting / FAQ

• The run was interrupted. Fix the cause and rerun the same command; the profile's rerun-incomplete reuses finished files and continues.
• One build failed, others finished. That is keep-going at work. The failed job's log is printed and kept in .run/logs/{rule}/. Rerun after fixing; only the failed part runs.
• Missing input files mentioning source/ or tutorial/vaccine.fasta: an input is missing or misnamed (Step 1).
• command not found: snakemake: conda activate pekosz-nextstrain.
• A warning about GISAID data or hooks at the start of the run: read it; see Data Protection.
• Old results show up in a new run: you skipped snapshot_clean.

Next step → Step 3: Filtering & Quality Control