View trees in Nextstrain

Overview

Phylogenetic trees generated automatically or on-demand through CZ GEN EPI can be viewed in the Nextstrain platform. Below are details on how to view and explore interactive phylogenetic trees in Nextstrain.

After reading this user guide, you will be able to:

• View automatic and on-demand tree builds in Nextstrain
• Explore interactive trees in Nextstrain
• Add sample IDs to your Nextstrain tree

Viewing phylogenetic trees in Nextstrain

To access your tree builds and view them on Nextstrain:

1. If you are on the Sample page, click on the Phylogenetic Trees tab to see your tree builds (see Get familiar with Phylogenetic Tree page).
   
   Example Sample page showing Phylogenetic Trees tab.
2. Find the tree of interest by Tree Name, Creation Date, and/or Tree Type. Note that SARS-CoV-2 Overview trees can be either automatically generated by CZ GEN EPI on a daily basis ("Automatic Build") or on-demand by the user ("User"). These Overview tree builds can be distinguished under the name of a given tree.
   
   Automatic and on-demand tree builds are labeled under the tree names.
3. To view a tree of interest, click on the tree name or "View in Nextstrain" icon. Note that this icon becomes available after tree builds are completed.
   
   Example Phylogenetic Tree page showing the icon for visualizing trees in Nextstrain.
4. A notice message will be displayed indicating that tree data will be sent to Nextstrain for visualization.
   
   If you agree with the notice message indicating that tree data will be sent to Nextstrain for visualization, click "Confirm" to continue.
5. View the interactive tree in Nextstrain. The default parameters will allow you to focus on emerging lineages for SARS-CoV-2 and clades for Mpox.
   
   Example of SARS-CoV-2 automatic tree opened in Nextstrain with default parameters.  By default, the tree is colored by emerging lineage. The sample legend, number of samples on the tree, and the "Mutations" axis are highlighted. Note that grayed-out samples (branch tips) do not represent emerging lineages. Example Mpox on-demand Overview tree opened in Nextstrain with default parameters. By default, the tree is colored by clade.The sample legend and the "Divergence" axis are highlighted. 
   
   Note that the default titles for SARS-CoV-2 Nextstrain trees will vary depending on the tree build. However, all Mpox tree builds will have the same title. Titles include:

• Automatic SARS-CoV-2 trees (Overview): "Overview tree for samples collected in [Your default location] between YYYY-MM-DD and YYYY-MM-DD"
• On-demand SARS-CoV-2 Overview trees: "Overview tree for samples collected in [Your location of interest]"
• On-demand SARS-CoV-2 Targeted trees: "Targeted tree for samples collected in [Your location of interest]"
• On-demand SARS-CoV-2 Non-contextualized trees: "Non-contextualized tree for samples collected in [Your location of interest]"
• All on-demand Mpox trees: "Genomic epidemiology of Mpox"

Exploring interactive trees

The default tree might make it difficult to distinguish samples. You can explore the tree to learn more about the clades and samples within it. Instructions below use SARS-CoV-2 trees as examples but the same approaches apply to Mpox trees.

1. You can adjust the color scheme of the tree using the "Color by" dropdown menu on the left-hand side of the screen. For example, you can choose to show colors by region. This will allow you to easily distinguish samples from North America, which are dominated by samples from your jurisdiction.
   
   You can edit the tree color scheme by clicking on the "Color By" dropdown menu.
   
   Example automatic tree colored by region.
2. You can zoom in on clades of interest.
   
   To zoom in, click on the branch of interest.
   
   Example after zooming in on the 21M (Omicron) clade on the tree above.
3. You can learn about specific samples by hovering over branch tips of interest.
   
   Example highlighting sample information and how to reset the tree layout.

Enable tree coloring options with additional metadata

You can add coloring options to your trees by downloading a metadata file and adding it to the Nextstrain tree page. The downloaded file allows you to easily spot user-selected samples, and with modifications, you can add coloring of your own metadata. Instructions below use SARS-CoV-2 trees as examples but, unless noted, the same approaches apply to Mpox trees.

To add sample IDs:

1. Download the tab-delimited table with IDs for all samples on the tree of interest from the Phylogenetic Tree page and keep it available (you will upload it on step 3).
   
   To download a tab-delimited file with sample IDs specifying whether samples were selected by the user, click on the download dropdown menu for the tree of interest and select "Private IDs (.tsv)".
   
   This Private IDs table file contains two columns: 

• Sample Identifiers: Sample IDs, including Private and Public IDs.
• Selected: Specifies (yes or no) if samples represent user-selected samples (i.e., samples selected by the user through the sample table and/or by specifying sample IDs).
  
  Example Private IDs table file
  Note that you can make your own metadata file. To do this:

• Start with the Private IDs table file above, or make a tab-delimited file listing samples from the tree of interest in one column and specific metadata in other columns. 
• Make one column per metadata variable and fill in the value for each sample. 
• Not all the samples from the tree of interest need to be listed in your metadata file. You only need to include the ones that have metadata of interest.
  
  Example metadata table file made in Excel

2. Open the tree in Nextstrain by clicking on the "View in Nextstrain" icon .
3. View the interactive tree in Nextstrain. The default parameters will allow you to see emerging lineages.
   
4. Upload the downloaded Private IDs file by simply dragging and dropping it onto the Nextstrain tree page.  After adding the Private IDs file, you will be able to see the new "Selected" variable for coloring your tree. If you prepared your own metadata file, you will be able to see the added metadata variables on the list.
   
   After dragging the table file onto the Nextstrain page, you will see a message on the top right side of the screen. If successful, the message will be highlighted in green. Note the new "Selected" variable under the "Color by" dropdown menu after adding the table file.
   
5. Color your tree by "Selected" using the "Color By" dropdown menu. You will be able to see user-selected samples ("yes") highlighted in yellow.
   
   Tree color scheme after coloring by "Selected". Now the tree reflects user-selected ("yes") vs samples that were added by CZ GEN EPI ("no") and you can easily spot clades of interest that include selected samples.
6. You can zoom in on branches of interest.
   
   Example tree image after zooming in on a clade containing user-selected samples.
7. You can filter the samples shown on the tree to further focus on samples of interest. To do this:
   1. 1. Scroll all the way down the Nextstrain tree page. You can set filters on the "About this Tree" section.
         
         See available filters under the "About this tree" section on the Nextstrain tree page. Click on the downward arrow to see options within a filter of interest.
      2. Click on the filter of interest.
         
         Example list of filter options under "Admin Division".
      3. Scroll back up the Nextstrain tree page to visualize the filtered tree.
         
         Example tree showing samples from the California Admin Division after filtering.
      4. Click on the eye symbol to inactivate the filter and see all the samples again. You can re-activate the filter by clicking on the eye symbol again. If you want to remove the filter, click on the trash can icon.
         
         Select the eye symbol to inactivate a given filter. Select the trash can symbol to remove it.
8. By default, the tree scale reflects divergence based on the number of mutations for SARS-CoV-2 or nucleotide substitutions per site for Mpox. However, for SARS-CoV-2 tree builds, you can change the tree scale to reflect time by changing the "Branch Length" setting. This would help you evaluate the time difference between samples of interest. This option is not available for Mpox trees.
   
   You can change the SARS-CoV-2 tree scale to evaluate how far apart samples have been collected. To change the scale, click on "Time" under the "Branch Length" menu on the left-hand side of the page.
   
   By changing the SARS-CoV-2 tree scale, you can look at the time difference between samples of interest. Samples that are genetically identical could be sampled at different times.