How do I overlay metadata on my Nextstrain tree?

You can add metadata of interest to your Nextstrain tree and enable tree coloring based on the added metadata. See guide regarding how to view trees in Nextstrain for more details. Here we summarize how to add metadata to your Nextstrain tree.

To overlay metadata of interest on your Nextstrain tree:

1. Create a tab-delimited file with sample IDs and metadata of interest for each sample. There are two options to create your file:
   
   Option 1: You can download a tab-delimited table with IDs for all samples on the tree of interest from the Phylogenetic Tree page and add columns for other metadata variables locally on your computer.
   
   You can download a tab-delimited file with sample IDs specifying whether samples were selected by the user from the Phylogenetic Tree page. To do this, click on the download dropdown menu for the tree of interest and select "Private IDs (.tsv)".
   
   The downloadable 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 from the sample table and/or by specifying sample IDs).
  
  Example Private IDs table file
  
  Option 2: You can make your own tab-delimited file listing a subset of samples from the tree of interest in one column and specific metadata in other columns.
  
  Example metadata table file made in Excel

2. When creating your metadata file with either approach mentioned in step 1, make one column per metadata variable and fill in the value for each sample. Samples that have blank values for a given metadata variable will not be colored in the tree when choosing to color by that variable (see step 6 below).
3. Save your metadata file as a tab-delimited file (.tsv) and keep it available (you will need it in step 6 below).
4. Open the tree of interest in Nextstrain by clicking on the "View in Nextstrain" icon  within the Phylogenetic Tree page.
5. View the interactive tree in Nextstrain. The default parameters will allow you to see the tree colored by emerging lineages.
   
   Example default tree colored by emerging lineages.
6. Upload the created metadata file by simply dragging and dropping it onto the Nextstrain tree page.  After adding the metadata file, you will be able to see the new metadata variables for coloring your tree (based on the metadata column headers found in your metadata file).
   
   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. In this example, we added metadata regarding user selected samples. Note the new ‘Selected’ variable under the "Color by" dropdown menu after adding the table file.
7. Color your tree by the metadata variable of interest using the "Color By" dropdown menu.
   
   Example tree color scheme after coloring by user selected samples ("Selected"). Now the tree reflects user-selected ("yes") vs samples that were added by CZ GEN EPI ("no"). Clades of interest that include user selected samples can be easily spotted.
8. Explore your tree with the added metadata (see Viewing trees in Nextstrain for details on how to zoom in on branches of interest, filter samples, and change the tree scale).