Tutorial 1 Your First Build

Tutorial 1: Your First Build

Follow along! In about 30 minutes you will run the real pipeline on a small practice dataset and look at your own trees and surveillance report. Nothing here can break anything, and nothing leaves your computer.

What you'll use: 20 H1N1, 20 H3N2 and 20 B/Victoria samples generated by Dr. Heba Mostafa's Lab at the Johns Hopkins Hospital, stored in tutorial/. The tutorial makes all 24 segment builds, 3 whole-genome builds and the surveillance report, using exactly the same workflow as a production run.

📽️ Supplemental slides: https://elginakin.github.io/posts/content/pekosz_nextstrain/

Important

This tutorial uses the pekosz-nextstrain conda environment. Earlier versions of the tutorial offered the Nextstrain Docker runtime (nextstrain shell). It is no longer supported: viewing trees locally was unreliable (especially on WSL), and Docker may not support the report steps. If any older material tells you to install Docker, follow Getting Started instead.

flowchart LR
    A["Setup done<br/>(Getting Started)"] --> B["Add vaccine.fasta<br/>(or an empty file)"]
    B --> C["Dry run"]
    C --> D["Run"]
    D --> E["Open the report<br/>and the trees"]

Loading

Five moves: your setup, one input file, a rehearsal, the run, and the results.

Before you start

• You finished Getting Started and saw All N checks passed.
• Your terminal is in the top-level nextstrain folder. Check:

ls Snakefile config/tutorial.yaml tutorial/JHH_sequences.fasta

• conda activate pekosz-nextstrain (your prompt shows (pekosz-nextstrain)).
• No production build is sitting in the workspace (see FAQ below).

1. Supply the GISAID vaccine file

GISAID data cannot be openly redistributed, so vaccine.fasta is not included. If you have your own GISAID account, download and format the vaccine strains (Tutorial 3) and save them at exactly:

tutorial/vaccine.fasta

No GISAID account yet? The pipeline runs fine with an empty file (your trees just won't show vaccine strains):

touch tutorial/vaccine.fasta

Do not commit or share this file (git ignores it, and the data guard blocks it anyway). Confirm all three inputs:

ls -lh tutorial/JHH_sequences.fasta tutorial/JHH_metadata.txt tutorial/vaccine.fasta

2. Rehearse with a dry run

A dry run checks the workflow and input paths without building anything:

snakemake --dry-run --cores 8 --configfile config/tutorial.yaml

You'll see a list of jobs and a summary count. A message mentioning tutorial/vaccine.fasta means the vaccine file is missing or misnamed.

3. Run it

snakemake --profile profiles/default --cores 8 --configfile config/tutorial.yaml

• --profile profiles/default prints each command and the log of any failed job.
• --cores 8 allows up to eight CPU cores. Use --cores 4 or --cores 2 on smaller computers.
• --configfile config/tutorial.yaml reads the small tutorial inputs instead of source/.

It takes a few minutes. At the start you'll see a data-protection line (data_guard: OK ...). Success ends without a red error message and creates:

auspice/
├── h1n1/     8 segment builds + genome build (+ tip-frequency files)
├── h3n2/
└── vic/
reports/
├── surveillance_report.html   interactive report – open in any browser
├── surveillance_report.pptx   slide deck
├── figures/  tables/          PNG figures and TSV tables
└── report.tsv  report.xlsx

4. Look at what you made 🎉

• The report: open reports/surveillance_report.html in a browser (macOS: open reports/surveillance_report.html; WSL: explorer.exe reports/surveillance_report.html). How to read it: Step 4.
• Explore live: marimo run scripts/report.py opens the report as an app where you can pick any sequencing run.
• The trees: go to https://auspice.us and drag in a build's two JSON files (e.g. auspice/h3n2/ha.json and ha_tip-frequencies.json), or run auspice view --datasetDir auspice/h3n2 and open http://localhost:4000. Try coloring by clade, then by sequencing_run.
• How the run went: .run/reports/index.md and the run's report.md.

You've just run the whole pipeline. 🚀

5. Clean up

Before running anything else (another tutorial run or production), archive and clean:

snakemake --cores 8 snapshot_clean

For the maintainer: regenerating the tutorial dataset

python scripts/generate_tutorial_dataset.py
cp source/vaccine.fasta tutorial/vaccine.fasta

The generator picks 20 distinct samples per subtype from fludb and mixes segment profiles (12 complete genomes, 2 HA-only, 2 NA-only, 3 without HA/NA, 1 NS-only) to exercise the diagnostics. Confirm the chosen samples are released on GISAID before committing; the data guard's JHH check needs ALLOW_JHH_DATA=1 (Data Protection).

The current tutorial samples (sequencing runs IV23Run6 to IV26Run7) were confirmed released on GISAID by the maintainer in October 2026.

Troubleshooting / FAQ

• A previous production build exists. Tutorial and production runs share data/, results/, .run/, auspice/, reports/ and fludb.db. Do not mix them: use a fresh clone, or archive first with snapshot_clean (Step 2; it deletes outputs, so read it first).
• command not found: snakemake (or augur, nextclade...): run conda activate pekosz-nextstrain. Re-check any time with bash scripts/build_env.sh --check.
• The environment is broken or out of date: bash scripts/build_env.sh --recreate.
• The run was interrupted: fix the cause and rerun the same command; it continues where it stopped.
• The vaccine file is rejected: check it is named exactly tutorial/vaccine.fasta and its headers match the 7-field format.
• Never post GISAID sequence data in a public issue, repository or support message.

Next step → Pipeline Overview