nextstrain.org/flu

This is the Nextstrain build for seasonal influenza viruses, available online at nextstrain.org/flu.

The build encompasses fetching data, preparing it for analysis, doing quality control, performing analyses, and saving the results in a format suitable for visualization (with auspice). This involves running components of Nextstrain such as fauna and augur.

All influenza virus specific steps and functionality for the Nextstrain pipeline should be housed in this repository.

This build is more complicated than other standard nextstrain build because all four currently circulating seasonal influenza lineages (A/H3N2, A/H1N1pdm, B/Vic and B/Yam) are analyzed using the same Snakefile with appropriate wildcards. In addition, we run analyses of both the HA and NA segments of the influenza virus genome and analyze datasets that span different time intervals (eg 2, 3, 6 years). Furthermore, the Nextstrain analysis of influenza virus evolution also uses antigenic and serological data from different WHO collaborating centers.

The different builds for the general public and the different WHO collaborating centers are configured via separate config files. The Nextstrain build configs (upload, nextstrain-public, private.nextflu.org) are used for our semi-automated builds through our GitHub Action workflows.

Example build

You can run an example build using the example data provided in this repository.

First follow the standard installation instructions for Nextstrain's suite of software tools.

Then run the example build via:

nextstrain build .  --configfile profiles/example/builds.yaml

When the build has finished running, view the output Auspice trees via:

nextstrain view auspice/

Quickstart with GISAID data

Navigate to GISAID. Select the "EpiFlu" link in the top navigation bar and then select "Search" from the EpiFlu navigation bar. From the search interface, select A/H3N2 human samples collected in your time period of interest. Under the "Required Segments" section at the bottom of the page, select "HA". Check "exclude" TPE submissions to exclude restricted data, as shown in the example below.

Then select the "Search" button. Select the checkbox in the top-left corner of the search results (the same row with the column headings), to select all matching records as shown below.

Select the "Download" button. From the "Download" window that appears, select "Isolates as XLS (virus metadata only)" and then select the "Download" button.

Create a new directory for these data in the seasonal-flu working directory.

mkdir -p ingest/data/

Save the XLS file you downloaded as ingest/data/<YYYY-MM-DD-N>-metadata.xls.

• <YYYY-MM-DD> is the date the files were downloaded from GISAID.
• <N> is the number of the download to support multiple downloads in the same day since GISAID limits the number of records per download.
• For example, if you had to split the data between two downloads on 2025-04-11, then save the files as
  • 2025-04-11-01-metadata.xls
  • 2025-04-11-02-metadata.xls

Return to the GISAID "Download" window, and select "Sequences (DNA) as FASTA". In the "DNA" section, select the checkbox for "HA". In the "FASTA Header" section, enter

DNA Accession no. | Submitting lab  | Originating lab

Uncheck both boxes related to spaces in the FASTA header. Your settings should look like those shown in the screenshot below.

Select the "Download" button. Save the FASTA file you downloaded ingest/data/<YYYY-MM-DD-N>-sequences.fasta.

Run the Nextstrain ingest workflow for these data to produce the clean input for the phylogenetic workflow with the following command.

nextstrain build ingest --configfile build-configs/gisaid/config.yaml

Explore the configuration file for this workflow by opening ingest/build-configs/gisaid/config.yaml in your favorite text editor. This configuration file determines the outputs of the workflow, including the lineages and segments. If you would like to create builds for other lineages and/or segments, make sure to download the data from GISAID then edit the config file to rerun ingest and create outputs for your data of interest.

Run the workflow to create an annotated phylogenetic tree of recent A/H3N2 HA data with the results from the ingest workflow with the following command.

nextstrain build . --configfile profiles/gisaid/builds.yaml

When the workflow finishes running, visualize the resulting tree with the following command.

nextstrain view auspice

Explore the configuration file for this workflow by opening profiles/gisaid/builds.yaml in your favorite text editor. This configuration file determines how the workflow runs, including how samples get selected for the tree. Try changing the number of maximum sequences retained from subsampling from 100 to 500 and the geographic grouping from region to country. Rerun your analysis by adding the --forceall flag to the end of the nextstrain build command you ran above. How did those changes to the configuration file change the tree?

To skip subsampling and use all records that you downloaded from GISAID, set filters string in the build configuration file to an empty string as shown in the following subsection of the YAML file.

      subsamples:
        global:
            filters: ""

Configuration

Explore the other configuration files in profiles/, to see other examples of how you can build your own Nextstrain workflows for influenza.

Important

The workflow is optimized for HA and NA segments and requires additional files if you are building other segments!

• The following files are required for different lineage and segment builds:
  • reference: "config/{lineage}/{segment}/reference.fasta"
  • annotation: "config/{lineage}/{segment}/genemap.gff"
  • tree_exclude_sites: "config/{lineage}/{segment}/exclude-sites.txt"
• The workflow assigns clade annotations to non-HA segments from HA, so the clades configuration should always point to the HA clade definition TSV.
• The workflow only has subclade annotations for HA and NA segments, so remove the subclades configuration for other segments builds.

Inputs

The configuration can include a top-level inputs list that defines the separate inputs' name, lineage, metadata, id field, and sequences. Optionally, the config can have a top-level additional-inputs list that is used to define additional data that are combined with the default inputs:

inputs:
    - name: default
      lineage: h3n2
      metadata: ingest/results/h3n2/metadata.tsv
      id_field: strain
      sequences: ingest/results/h3n2/{segment}.fasta

additional_inputs:
    - name: private
      lineage: <lineage>
      metadata: <path-or-url>
      id_field: <metadata-id-field-name>
      sequences: <path-or-url>

The id_field key for each input is passed through to augur merge --metadata-id-columns. The merged metadata's id field is always named strain for downstream scripts.

The sequences key can include the {segment} template to match to multiple segment filepaths. Sequences can also be a defined a dict with keys for specific segments if they have different filepaths.

inputs:
    - name: default
      lineage: h3n2
      metadata: ingest/results/h3n2/metadata.tsv
      id_field: strain
      sequences:
        ha: ingest/results/h3n2/ha.fasta
        na: ingest/new-results/h3n2/na.fasta

History

• Prior to March 31, 2023, we selected strains for each build using a custom Python script called select_strains.py. With the merge of the refactored workflow, we have since used a configuration file to define the augur filter query logic we want for strain selection per build.