Build on-demand trees

Overview

You, or someone from your group, can build phylogenetic trees in CZ GEN EPI with specific samples of interest. You can also specify the type of tree build (Overview, Targeted or Non-contextualized) based on your epidemiological questions. Given that you are deciding when to build trees and selecting tree types, these are known as ‘on-demand’ phylogenetic trees, which are different from the automatic builds. Below are details about how to build on-demand phylogenetic trees. 

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

• Generate on-demand phylogenetic trees
• Further customize on-demand Overview and Non-contextualized trees 

Generating phylogenetic trees on-demand

See steps below to build an on-demand Overview, Targeted, or Non-contextualized phylogenetic tree with customized samples of interest.

1. (Optional) When selecting samples of interest to force include in your tree build, the first option is to select samples from the table on your Sample page. Alternatively, you can add samples by their GISAID ID (see step 4 below). To include samples from the table on your Sample page, select samples of interest by adding a checkmark. Remember that you can filter samples on the table to search and select samples of interest.
   
   Select samples for on-demand phylogenetic tree building and click on the tree icon representing the ‘Run Phylogenetic Analysis’ menu on the right-hand side of the Sample page.
   
   Select ‘Nextstrain Phylogenetic Tree’ from the dropdown menu.
2. Click on ‘Nextstrain Phylogenetic Tree’ from the ‘Run Phylogenetic Analysis’ dropdown menu on the right-hand side of the page. A dialog box will appear where you will provide a name for the tree build and specify the desired tree type. The tree type will depend on the questions you are trying to answer (see information about the different types of on-demand trees here).
   
   Dialog box for specifying tree name, type, and, if applicable, customization parameters.
3. When you click on the different types of trees you will see information summarizing the main purpose of each tree type. Select the most suitable tree for your analysis. Note that you can customize Overview and Non-contextualized trees by specifying lineage(s) and/or collection date range of interest (see below for details).
   
   When selecting a tree type within the dialog box, you will see a summary describing its main purpose.
4. (Optional) You can also use the ‘Force-include samples by ID (optional)’ box to add samples from CZ GEN EPI and/or GISAID to your tree. Note that samples selected on the Sample page (step 1) and/or added through the dialog box will be force-included on your tree without undergoing quality control. See details about sample selection here.
   
   Scroll down within the ‘Create New Phylogenetic Tree’ dialog box to find the field where you can add samples for your tree build under ‘Force-Include Samples by ID (optional)’. In this example, three samples were selected from the Sample page table and two other samples were added by specifying their IDs within the dialog box.
   
   Note the following when adding samples through the ‘Create New Phylogenetic Tree’ dialog box:

• To add samples from GISAID use their GISAID ID (e.g. USA/CA-CZB-0000/2021 or hCoV-19/USA/CA-CZB-0000/2021).
• To add samples from CZ GEN EPI use their Public IDs or Private IDs.
• Multiple sample IDs must be separated by tabs, commas, or enter one ID per row.
• In the case of targeted trees, samples specified here also serve as the focal samples that CZ GEN EPI uses to add all contextual samples.
• To learn how selected samples relate to other samples on the tree see section below.
• Adding more than 2000 samples will increase the tree building run time.
  
  Samples selected through steps 1 and 4 are referred to as ‘user-selected samples’. 

5. After making all of your tree selections (samples, tree name, and type), click on ‘Create tree’ at the bottom of the Create New Phylogenetic Tree’ dialog box.
   
   To begin your tree build, click on ‘Create Tree’ at the bottom of the dialog box after specifying your selections including samples, tree name, and tree type.
6. Tree builds may take up to 12 hours. Go to the Phylogenetic Tree page to check the tree status. Once the build is complete, you will be able to view the tree in Nextstrain, download it, edit its name, and/or delete it (learn about functionalities within the Phylogenetic Tree page here).
   
   Click on the Phylogenetic Tree page to see tree build status. Once the tree build is completed, you will be able to click on icons to view the tree in Nextstrain and download the tree. You can also edit the tree name or delete it by clicking on the ‘More Actions’ dropdown menu.
7. View your tree in Nextstrain.

Customizing Overview and Non-contextualized tree builds

All on-demand tree builds can be customized by specifying which samples you would like to see on the tree, namely user-selected samples. However, you can further customize Overview and Non-contextualized trees by filtering samples based on lineage(s) and/or a sample collection date range of interest. Note that sample selections will impact which samples are chosen for the tree. 

To further customize Overview and Non-contextualized trees:

1. After selecting the desired tree type within the ‘Create New Phylogenetic Tree’ dialog box, specify options for lineage and dates in the provided fields.
   
   Customization options for Overview and Non-contextualized trees.
   
   Note the following: 

• The lineage and date range selections will limit which samples from your jurisdiction will be included on the tree.
• For Non-Contextualized trees, if no samples of the selected lineage and/or date range exist in either CZ GEN EPI or GISAID, the tree build will fail. 
• User-selected samples already selected through the Sample page or those added within the ‘Create New Phylogenetic Tree’ dialog box by IDs will still be force-included on your tree regardless of lineage and/or date range parameters selected during customization. In other words, sample customization parameters added here will not overwrite user-selected samples. See the diagram below to better understand the distribution of user-selected samples and those selected by setting lineage and date range filters:
  
  Diagram summarizing sample composition for on-demand Overview and Non-contextualized trees.

2. Click on the downward arrow under ‘Lineage’ to see the list of lineages. To make selections, simply click on lineage(s) of interest. By default, ‘All’ lineages are selected.
   
   Click on the downward arrow under ‘Lineage’ to see the list of lineages. The total number of selected lineages will show within the lineage box. To deselect a given lineage, click on it and the check mark will be removed.
3. Click on the downward arrow under ‘Collection Date’ to specify a date range of interest. By default, ‘All time’ is selected. You can choose from preset date ranges or specify dates following the YYYY-MM-DD format.
   
   Click on the downward arrow under ‘Collection Date’ to see date options. Selected dates will show on the Collection Date field.
   
   When specifying date ranges, you can set a time interval. If you leave the beginning date blank, you are effectively selecting all the days prior to a given date. If you leave the end date blank, you are selecting days from a specified date until the present day. When done specifying the date range of interest, click on ‘Apply’. Selected dates will then show on the Collection Date field. 
4. After making your lineage and date range selections, continue to build your tree (steps 5 through 7 from the previous section).