Part 1

Author
Affiliation

Elgin Akin

Johns Hopkins University

Navigate back to the blog post

Warning

Important note about GISAID data

GISAID data cannot be openly redistributed. For that reason, vaccines.fasta is not included in this tutorial.

You must obtain an authorized vaccine FASTA using your own GISAID account and place it at exactly:

tutorial/vaccines.fasta

Do not commit or publicly share this file. The FASTA headers must use the format expected by fludb/scripts/upload_vaccine.py. See Tutorial: Add Vaccine Strains from GISAID in the main project README for the download and header-formatting instructions.

What you need

Before beginning, you need:

  • This repository on your computer
    • git clone https://github.com/Pekosz-Lab/nextstrain.git
    • navigate to your directory cd nextstrain
  • an authorized vaccines.fasta from GISAID
  • Docker Desktop
  • the Nextstrain command-line
  • optionally, an IDE such as Positron
  • A terminal (will be native on all machines)

The build downloads current Nextclade datasets, so it also requires an internet connection.

1. Install Docker Desktop

Docker provides the reproducible environment containing the software needed by the workflow.

  1. Open the official Docker Desktop installation guide.
  2. Select the instructions for macOS, Windows, or Linux.
  3. Install and start Docker Desktop.
  4. Wait until Docker reports that its engine is running.

Open a terminal and verify Docker:

docker run --rm hello-world

If this command cannot connect to Docker, open Docker Desktop and wait for it to finish starting before trying again.

3. Install the Nextstrain CLI and Docker runtime

Follow the official Nextstrain installation guide. Install the Nextstrain command-line interface and select Docker as the runtime.

After installation, open a new terminal and verify the setup:

nextstrain check-setup

The Docker runtime should be reported as supported. Make sure Docker Desktop is running whenever you use Nextstrain.

4. Open the repository

If you have not already downloaded the repository, clone it and enter its top-level directory:

git clone https://github.com/Pekosz-Lab/nextstrain.git
cd nextstrain

If you already have the repository, use cd to enter it. All remaining commands must be run from the repository’s top-level directory—the directory containing Snakefile, config/, and tutorial/.

You can confirm your location with:

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

5. Supply the GISAID vaccine file

After downloading and formatting your authorized vaccine sequences, save the file as:

tutorial/vaccines.fasta

The pipeline will run as intended and produce all builds with an empty vaccines.fasta if you are not able to provide it. Just create a file called vaccines.fasta and move it to

tutorial/vaccines.fasta

Confirm that all three tutorial inputs are present:

ls -lh \
  tutorial/JHH_sequences.fasta \
  tutorial/JHH_metadata.txt \
  tutorial/vaccines.fasta

6. Start the Nextstrain shell

From the repository’s top-level directory, run:

nextstrain shell .

You should see a message similar to:

Entering the Nextstrain runtime (docker)

Your terminal is now inside the Nextstrain Docker environment. The repository is available as the current working directory, and commands such as snakemake, augur, auspice, and nextclade should be available.

To confirm Snakemake is available:

snakemake --version

8. Run the tutorial

Still inside the Nextstrain shell, run:

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

What the command means:

  • snakemake starts the workflow.
  • --cores 8 permits up to eight CPU cores to be used. If your computer has fewer resources, use --cores 4 or --cores 2.
  • --configfile config/tutorial.yaml selects the small tutorial inputs instead of the normal files in source/.

The first run can take longer because Nextstrain may need to download datasets and Docker may need to prepare its runtime. Keep Docker Desktop running and do not close the terminal while the workflow is active.

Successful completion ends without a red error message and creates output under:

auspice/
├── h1n1/
├── h3n2/
└── vic/

Each directory contains JSON files for eight segment builds, a genome build, and their associated tip-frequency data.

9. View the JSON output

  • navigate to auspice.us
  • click and drag a set of JSON files (2 per segment build)

Rerunning and troubleshooting

A previous production build exists

Tutorial and production runs share data/, results/, logs/, auspice/, and fludb.db. Do not mix the two runs. Use a fresh checkout or clean workspace for the tutorial.

If you intentionally want to archive and remove an existing build first, read the snapshot-and-clean section of the main README before running:

snakemake --cores 8 snapshot_clean

This command archives and then removes existing build outputs, so do not run it until you understand what will be cleaned.

Docker is unavailable

Start Docker Desktop, wait for the engine to become ready, and run:

nextstrain check-setup

Then re-enter the runtime with nextstrain shell ..

The workflow was interrupted

After correcting the cause of the interruption, rerun with:

snakemake --cores 8 --configfile config/tutorial.yaml --rerun-incomplete

Snakemake will reuse completed files and continue the remaining work.

The vaccine file is rejected

Check that the file is named exactly tutorial/vaccines.fasta and that its headers match the required seven-field GISAID format described in the vaccine tutorial.

Never post GISAID sequence data in a public issue, repository, or support message.

Beyond this tutorial: