Tutorial: Nextstrain Phylogenies for seasonal H1N1, H3N2 and B/Victoria Viruses

Part 1: Building the conda environment and running the tutorial dataset

Elgin Akin

2026-08-09

A couple of notes

Note

This tutorial runs on macOS (Apple Silicon or Intel) and on Windows through WSL2. On Windows, every command runs in the Ubuntu terminal of WSL2.

Important

Docker is no longer supported. Older versions of these slides used Docker Desktop and nextstrain shell. The pipeline now runs from one conda environment, pekosz-nextstrain. Use conda activate pekosz-nextstrain in place of nextstrain shell, and auspice view in place of nextstrain view.

  • A little terminal navigation knowledge is expected. This tutorial will be easier if you know how to do the following in a command-line interface:
    • make a directory
    • move in/out of directories
    • check your current location
  • Some knowledge of git/GitHub is expected but not necessary.

What you will accomplish

By the end of this tutorial, you will:

  • clone a GitHub repository and build the pekosz-nextstrain conda environment;
  • run the Pekosz Lab influenza Nextstrain workflow on a small teaching dataset;
  • build eight segment phylogenies and one concatenated whole-genome phylogeny for each subtype;
  • create 27 Nextstrain builds across H1N1, H3N2, and B/Victoria, plus the surveillance report; and
  • open the results in a browser and in Auspice.

The tutorial uses 20 samples per subtype (generated by Dr. Heba Mostafa’s Lab at the Johns Hopkins Hospital) and the same Snakemake workflow used for a normal production build.

The (simplified) path from setup to results

flowchart LR
    A[Install Miniforge] --> B[Clone the repository]
    B --> C[bash scripts/build_env.sh]
    C --> D[conda activate pekosz-nextstrain]
    D --> E[Add vaccine.fasta]
    E --> F[Dry run]
    F --> G[Run Snakemake]
    G --> H[Report + Auspice]

  • This pipeline requires only 3 input files to run:
    • vaccine.fasta – vaccine strains from GISAID, supplied by you (see Tutorial 3)
    • JHH_sequences.fasta – segment sequences from the Johns Hopkins Hospital
    • JHH_metadata.txt – one row per specimen with its sequencing run and date

Note

For this tutorial, the two JHH files are supplied in the tutorial folder. You supply vaccine.fasta.

Warning

You must run every command from the repository’s top-level nextstrain/ directory.

Before you begin: what you need

  • macOS, or Windows with WSL2;
  • a terminal (Terminal on macOS; the Ubuntu terminal on WSL2);
  • git (preinstalled on macOS; sudo apt install git on WSL);
  • an internet connection (the build downloads current Nextclade datasets);
  • conda, via Miniforge (next slide); and
  • optionally, Positron with the Snakemake Language and SQLite Viewer extensions.

Setup takes about 20 minutes, mostly waiting. Docker is not needed.

Install Miniforge (conda)

Miniforge provides conda, configured for the conda-forge channel (no Anaconda licence needed).

macOS (and the Ubuntu terminal on WSL2):

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

Windows: first install WSL2 from an administrator PowerShell with wsl --install, restart, and open Ubuntu from the Start menu.

  1. Accept the licence and the default location.
  2. Answer yes when asked to initialise conda.
  3. Close the terminal and open a new one: your prompt now starts with (base).

An existing Anaconda or Miniconda installation also works (conda 23.10 or newer).

Clone the repository

  1. Open a terminal (in Positron: Terminal > New Terminal).
  2. Navigate to where you keep code:
cd ~
  1. Clone the repository and enter it:
git clone https://github.com/Pekosz-Lab/nextstrain.git
cd nextstrain
  1. In Positron, select File > Open Folder and open the top-level nextstrain folder.
  • All commands that follow assume this is your current directory.

Note

On WSL, clone into your Linux home (cd ~), not under /mnt/c/...: builds on the Windows drive are many times slower. Keep your clone outside OneDrive or Dropbox if you can.

Build the environment with one script

bash scripts/build_env.sh

This one command:

  1. creates (or updates) the pekosz-nextstrain conda environment from workflow/envs/environment.yml;
  2. turns on the data-protection git hooks and creates the empty source_prep/runs/ and source_prep/output/ folders (used in Part 2); and
  3. checks every tool (Snakemake, augur, Nextclade, MAFFT, IQ-TREE, seqkit, BLAST, csvtk) and runs small test builds.

Wait for All N checks passed.

Situation Command
Rebuild from scratch bash scripts/build_env.sh --recreate
Apple Silicon solve fails bash scripts/build_env.sh --intel
Re-run the checks only bash scripts/build_env.sh --check

Activate the environment

Activate it in every new terminal:

conda activate pekosz-nextstrain

Your prompt now shows (pekosz-nextstrain). Confirm the setup:

git config --get core.hooksPath     # must print .githooks
snakemake --version                 # prints a 9.x version
ls Snakefile config/tutorial.yaml tutorial/JHH_sequences.fasta

Warning

Never pip install or conda install into pekosz-nextstrain by hand. Your environment would silently differ from everyone else’s.

Vaccine GISAID sequences must come from the user

vaccine.fasta is not distributed with the tutorial because GISAID data cannot be openly shared.

Using your own authorized GISAID access:

  1. Download and format the vaccine sequences.
  2. Save the file as tutorial/vaccine.fasta.
  3. Do not commit or publicly share it (git ignores it, and the data guard blocks it).

Header requirements are documented in Tutorial 3: Updating Vaccine Strains and in Part 2 of these slides.

No vaccine data? Use an empty placeholder

The workflow can run without vaccine references, but the expected file must still exist:

touch tutorial/vaccine.fasta

An empty file produces the tutorial builds without vaccine strains.

Confirm all three inputs:

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

Check the workflow before running it

Perform a dry run with the environment active:

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

A dry run:

  • checks the workflow graph;
  • confirms that required input paths resolve;
  • lists the jobs and a summary count; and
  • does not create the builds.

A message mentioning tutorial/vaccine.fasta means the vaccine file is missing or misnamed.

Execute the tutorial

snakemake --profile profiles/default --cores 8 --configfile config/tutorial.yaml
  • snakemake starts the workflow.
  • --profile profiles/default prints each command and the log of any failed job, reruns interrupted jobs, and lets other builds finish if one fails.
  • --cores 8 allows up to eight CPU cores. Use --cores 4 or --cores 2 on smaller computers.
  • --configfile config/tutorial.yaml selects tutorial inputs instead of source/ inputs.

At the start you’ll see a data-protection line: data_guard: OK ...

Note

The tutorial produces all 24 segment builds, three whole-genome builds and the surveillance report in a few minutes. It uses the same workflow as a production run, but reads its starting files from tutorial/.

What Snakemake does for you (briefly)

flowchart LR
    A[data guard + provenance] --> B[ingest: flusort + fludb]
    B --> C[Nextclade clades]
    C --> D[filter]
    D --> E[align]
    E --> F[build, refine, annotate trees]
    F --> G[Auspice JSON]
    G --> H[surveillance + run reports]

The Snakemake rules for the segment and genome Nextstrain builds are as follows:

  • Main file: Snakefile
  • “Parts of a whole” files in workflow/snakemake_rules/:
    • ingest.smk – segment typing, fludb, build inputs
    • segments.smk and genomes.smk – the 24 segment and 3 genome builds
    • reports.smk – the surveillance report
    • snapshot.smk – archive and clean

To learn more about Snakemake in general, refer to https://snakemake.github.io/

What Snakemake does for you (source)

simplified rulegraph

Successful output: trees and a report

When the workflow finishes without a red error message, inspect:

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

Each tree has a matching tip-frequency JSON (sidecar file). How the run went is summarized in .run/reports/index.md.

Look at what you made

  • The report: open reports/surveillance_report.html (WSL: explorer.exe reports/surveillance_report.html).
  • Explore live: marimo run scripts/report.py opens the report as an app where you can pick any sequencing run.
  • The trees, locally:
auspice view --datasetDir auspice/h3n2     # then open http://localhost:4000
  • The trees, in the browser: open auspice.us and drag in one build JSON and its matching tip-frequency JSON:
auspice/h1n1/ha.json
auspice/h1n1/ha_tip-frequencies.json

Try coloring by clade, then by sequencing_run.

Interrupted runs can continue

After correcting the cause of an interruption, rerun the same command:

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

The profile’s rerun-incomplete reuses completed outputs and continues unfinished work.

Common checks:

  • Does your prompt show (pekosz-nextstrain)? If not, conda activate pekosz-nextstrain.
  • Does tutorial/vaccine.fasta exist?
  • Are you in the repository root?
  • Environment broken or out of date? bash scripts/build_env.sh --recreate

Ready for a new run? Keep tutorial and production runs separate!

Both modes use the same downstream locations:

data/  results/  .run/  auspice/  reports/  fludb.db

Use a fresh clone or a clean workspace when switching modes.

To archive and clean an existing build:

snakemake --cores 8 snapshot_clean

This saves snapshots/{timestamp}.tar.gz, then removes the build outputs. Read Step 2 before using it.

The complete command sequence

# Once per computer
git clone https://github.com/Pekosz-Lab/nextstrain.git && cd nextstrain
bash scripts/build_env.sh

# Every new terminal
conda activate pekosz-nextstrain

# The tutorial
touch tutorial/vaccine.fasta        # only if you have no GISAID file
snakemake --dry-run --cores 8 --configfile config/tutorial.yaml
snakemake --profile profiles/default --cores 8 --configfile config/tutorial.yaml

# Before the next run
snakemake --cores 8 snapshot_clean

Then open reports/surveillance_report.html and load a matching pair of JSON files from auspice/<subtype>/ at auspice.us.

You are ready to build

The tutorial is reproducible when four conditions are true:

  1. bash scripts/build_env.sh reported All N checks passed.
  2. The three tutorial input files exist.
  3. Commands run with pekosz-nextstrain active, from the repository root.
  4. config/tutorial.yaml is selected.

Start with a dry run, then let Snakemake build all 27 influenza views and the report.

Additional Resources

  1. The Pekosz Lab Nextstrain wiki is the full documentation; these slides follow Getting Started and Tutorial 1
  2. A written tutorial can be found HERE
  3. Part 2 (new sequencing runs and production builds): Part 2 slides

Back to the post