TITLE: Auger/Auspice/UShER: SARS-CoV-2  Cluster Detection Workflow for the Terra Platform
AUTHORS: Anusha Ginni, Jill Hagey

[DESCRIPTION]
<div class = "text-blocks"><div class = "text-block">The Titan_Augur workflows was written to process concatenated assembly fasta data for SARS-CoV-2 Phylogenetics analysis and cluster detection.</div><br/><div class = "text-block">Augur has two workflows, Augur_Prep and Augur_Run which you need to run one after the other. The output of these workflows is the required inputs for Auspice/Nextstrain to understand the genetic relatedness and draw phylogenetics inferences. </div><br/><div class = "text-block">The inputs for the Augur_Prep job include metadata on the sample (you can upload as a tsv), the assembly fasta and pango lineage for each sample. If you ran Titan on Terra you will already have generate the the assembly fasta and pango lineage for samples, but if you used another pipeline you will need to upload them.</div><br/><div class = "text-block">Upon initiating a Augur_Prep job, input data will be processed and the output will be a sample metadata and assemblies in the correct format to perform Augur_run analysis. The Augur_run workflow then takes the metadata and the concatenated fasta assemblies to generate the outputs that can be used for phylogenetics inferences on Auspice or Nextstrain visualization interface tools. </div><br/><div class = "text-block">This protocol also shows steps on how to visualize using the Auspice as well as UCSC UShER tools.</div><br/><div class = "text-block">Here are some helpful viedos:</div><div class = "text-block"><ul style = "list-style-type:disc;"></ul></div><br/><div class = "text-block"><a href="https://www.youtube.com/watch?v=r92L-B6wWOU" style = "text-decoration:underline;color:blue;cursor:pointer;"><span style = ":;">https://www.youtube.com/watch?v=r92L-B6wWOU</span></a></div><br/><div class = "text-block"><a href="https://www.youtube.com/watch?v=4nPS5Vab2dE" style = "text-decoration:underline;color:blue;cursor:pointer;"><span style = ":;">https://www.youtube.com/watch?v=4nPS5Vab2dE</span></a></div><br/><div class = "text-block"><a href="https://www.youtube.com/watch?v=uDXBcHR8GSQ&t=2186s" style = "text-decoration:underline;color:blue;cursor:pointer;"><span style = ":;">https://www.youtube.com/watch?v=uDXBcHR8GSQ&t=2186s</span></a></div></div>

[STEPS]
?. [Setup Terra and Google Cloud Accounts]
The Terra platform registration requires a Google account. If you have a Google account you can sign in using the Terra login page: https://app.terra.bio/  If you do not have Google email you can set up a Google account with a non-Google email. The steps to do this are described in the following link:https://support.terra.bio/hc/en-us/articles/360029186611The Terra platform uses the Google Cloud to run workflows and store data. The following documentation will describe how to set up a Google Cloud account:https://support.terra.bio/hc/en-us/articles/360046295092To link your Terra platform account with your Google Cloud account follow the instructions provided in the following link:https://support.terra.bio/hc/en-us/articles/360026182251-How-to-set-up-billing-in-TerraScroll down to Section 3 titled "Create a Terra Billing Project" and follow the instructions. It is important to note that the name you give to your Terra Billing Project must be unique across all Google Billing Projects. If the name provided is not unique, it won't immediately throw an error, but instead will not complete the process of associating the Google Billing account with the Terra Billing Project. If this occurs cancel the process and set up a new Terra Billing Project.For detailed step by step instructions, refer to Terra registration check out our protocol on registration and billing.
?. [Import Augur workflows from Dockstore]
Importing the Titan_Augur Workflows from Dockstore to the Terra User WorkspaceNote: Augur workflow includes 2 pipelines: 1-Augur_Prep, 2-Augur_Run.The Augur_Prep workflow prepares the metadata that is required to run the Augur_Run workflow, so it is required to import both the pipelines into your workspace. The Augur workflows is hosted on the Dockstore repository and has to be imported into the user's Terra Workspace. Begin by clicking on the three parallel lines in the top left-hand corner, followed by clicking the 'Library' tab and finally click the 'Workflows' button.On the right side of the page Under 'Find Additional Workflows' select the 'Dockstore' from the dialogue box .On the left side of the Dockstore page search for 'theiagen/public_health_viral_genomics/Titan_Augur_Run' in the search bar.Click the 'theiagen/public_health_viral_genomics/Titan_Augur_Run' link. This will take you to a page where you can import the workflow into your Terra workspace. On the right-hand side of the page under the 'Launch with' window click the 'Terra' button. It should bring you back to the Terra platform within the 'Import Workflow' page. If you already have a workspace select it from the dropdown menu Under 'Destination Workspace' and click 'Import'. If not you will need to create a workspace first (see note below) After clicking the 'Import' button you should be automatically directed to the Augur workflow panel in your specified workspace. Now that you have imported the Augur_Run workflow, follow the same steps to import the theiagen/public_health_viral_genomics/Titan_Augur_Prep workflow as well.Quick video showing how to import Augur workflows (Both Augur_Prep & Augur_Run).
If you need to create a new workspace click the 'create a new workspace' button. A pop-up window titled 'Create a New Workspace' should appear. Name your new workspace and associate it with a billing account using the 'Billing project' drop-down menu (this is the Terra Billing Account you created in the previous step should be available). Finally, click the 'Create Workspace' button.After clicking the 'Create Workspace' button you should be automatically directed to the Augur workflow panel in the new workspace page that was just created.
?. [Analysis Inputs/Data uploading]
The Augur workflows require the assembled fasta sequence (consensus sequence), pango linages and metadata for each sample. If we look at the inputs of the workflow we will see the information we need. The assembly file is generated from your genomic characterization workflow. If you have run Titan workflows on Terra then you will already have generated the assembly fasta files and all you need at this point is to select the samples from your analysis sample sets within your workspace. We will do this in step 4, but will still need to upload your metadata for each sample if that is not already associated with them. Construct a file with the following columns that are required metadata for each sample of interest:Collection_date	iso_country	iso_state	iso_continent	iso_countyHere is an example for TABLE file that you will upload to your workspace:To associate your metadata with the assembly fasta and pango lineages already in Terra, being by going to the DATA page and click the blue "+" sign next to the TABLES tab on the left of the web page. A pop-up window will appear to import a table file (see example file above) and either drag and drop the file or browse to find it. Once uploaded return to your samples and notice you will now how additional columns assocaited with each sample. Terra will know to associate the columns with the correct row by your "entity:" column so use the same sample_ids as you did when you originally uploaded the data.If you did not perform any genomic characterization of SARS-CoV-2 sequences before on Terra, you will need to upload your assemblies, and its associated metadata file to run the Augur workflows (see sub-steps below). You have 3 options for uploading your assemblies and metadata. These are the same as what you saw in the Titan protocols.     1. Upload on Terra (can only do single files).    2. Upload to Google bucket and link to Terra (can do single files or bulk files/folders).    3. Upload via 'https://app.terra.bio/#upload' -- This is the easiest optionHere we will show you how to select/upload metadata information to associate with your samples. Note: All the variable names and metadata information in the instructions are dummy and are just for demo purpose only.  Please make sure you are using the right variables/names that pertain to your samples.
Before you start: If your dataset is around
If you have already performed some genome characterization and all the metadata is associated with your samples, follow step 4 to select the Augur_Prep & Augur_Run required inputs from the TABLE (detailed instructions in step 4).
?. [Analysis Inputs/ data uploading]
?. [Analysis Inputs/Data uploading]
The first option is to upload a single sample at a time:Inside your new workspace page, click on the 'Data' panel in the newly created workspace and then click on the 'Files' tab.Once in the 'Files' tab you can either just drag and drop your files into this space or move the mouse over the blue plus sign icon in the bottom right-hand corner and click 'upload'. Upload the sequence files you'll need for this analysis. Each fastq sequence file has to be uploaded individually using this method. Once the files are uploaded you will need to bring a table in to associate your files with their corresponding link to their google bucket location.Finally, the completed Terra sample file will need to be uploaded to the workspace. On the right-hand side of the workspace 'Data' panel there is a 'Tables' tab. Click the blue plus sign icon on the right edge of the 'Tables' tab. A popup window should appear titled 'Import Table Data'. Select your completed tab-separated sample file for upload and then click the 'Upload' button.If the upload is successful then the sample file should be located under the 'Tables' tab as 'sample (#)' where # is the number of samples in your file.  The whole process is shown in the video below:You will notice in the video that you need to upload a file with sample metadata and the path to the fasta/fastq files. Once you have uploaded the files into the workspace, you can either copy, paste and save the paths to the metadata/Table file and upload or edit the paths once you have uploaded the metadata (this way is shown in the video)
The Terra sample table file has to follow a specific template. We've provided the template file here   as a downloadable tab-separated (or .tsv) file. This example file has the minimum amount of columns to be able to create a collection using this method.The tab-separated table has two columns since we have ONT data in this example:entity:sample_id and fastas. If you had Illumina PE data you would need three columns entity:sample_id, Forward_Read, and Reverse_Read.Either by editing the text file or using spreadsheet software like Excel, fill in each column with the required information. The first column 'entity:Test_augur_sample_id' is the sample name that is provided by the user. The second column, fasta are the file paths where it is stored within the Google Cloud. While you had to upload your samples individually you can have all your samples in one datatable.To identify the Google Cloud location right-click on each fastq file that was uploaded in the previous step and copy the link address. The file path should look like something similar to the following: gs://fc-b1e3191a-3d9f-43fe-9743-255551ce2f38/SRR11953697.fastq.gz  Once the table is filled in with the required information be sure to save it as a tab-separated (or tsv) file. The spreadsheet software should have an option to save as a 'tsv' file.Important note on column names: DO NOT USE SPACES! As we did before in creating our workspace and collection names use "_" instead of spaces! The first column MUST have the name "entity:sample_id", you can add other things between "entity:" and "sample_id" if you want. Example: "entity:Illumina_sample_id". You can call the other columns whatever you like, but obviously clarity is key.When completed the table should look similar to the following:Once the table is filled in with the required information be sure to save it as a tab-separated (or tsv) file. The spreadsheet software should have an option to save as a 'tsv' file.Note: When uploading additional sample table files to the same workspace the entity types must be unique and end in "_id" (e.g. sample1_id, sample2_id etc.)
?. [Running the Augur Workflows]
Running Titan_Augur workflows is a two step process. Run Augur_Prep workflowRun Augur_Run workflow
?. [View and Download the Augur workflow output reports]
First, verify the sample set has successfully completed by looking at the 'Workflow Status' section in the top left of the 'Job History' panel. The job has completed when the sample set have a status of 'succeeded' with a green checkmark. Since augur_run analyze with set of samples together, the job status would appear this way, it completed analysis successfully (hence the green checkmark).Once confirming the job completed, go to the 'DATA' panel and under the 'TABLES' tab click on the sample table that you created and uploaded in step 4. It will be named 'sample (#)' which has the set of samples/entities in your fileNow the Terra sample table will have the additional attributes that were added by the workflow when you specified the output names (set to default in this example). You can reduce the number of fields you want to visualize by clicking the "gear" icon in top row on the right. Select only the fields you want to see then click "Done".The three files that are used for visualization are:auspice_input_json - this output is generated from the NextClade analysis that is part of the Augur workflow. This file includes the samples for clade typing and the single sample placed on the tree. Downloading this file won't be saved to your local folders but will be opened in a browser. Make sure you right click on the page and "save as" it to your local directorycombined_assemblies - Is the concatenation of all of the assemblies that were included in this phylogenetic analysis. For this examples it includes all of 20 samples combined into one single filtered fasta file combined_assemblies.metadata_merged - Every metadata file from each sample that is generated by the augur_prep step is merged into one single metadata file.The auspice and combined assemblies determined by the pipeline can be viewed in the Terra sample report by scrolling to the right (or just only selecting those columns using the "gear" icon). You can download or copy this report by using either the 'Download All Rows' or 'Copy Page To Clipboard' buttons at the top of the table. To download a particular output file, click on the link under the column name a popup window titled 'File Details' should appear.Click the 'Download For Let's go ahead and download these 3 files to do some phylogenetic visualization in the next step. Video showing how to download and save the output files.
If you want to check what steps have finished on a job (can be helpful for troubleshooting), then click the job description under the submission column. This will take you to a page with more details on the job run. Next click on the "Workflow Dashboard" icon on the far right under the links column. On the next page you will be able to tell what steps in the pipeline have successfully finished. Here all 3 tasks that were call finished successfully (hence the green checkmark).
?. [Auspice Visualization]
At the end of the Augur analysis, you would have a complete metrics of the genome assemblies, which can be used to analyze the relatedness of the samples via phylogenetic inference using Auspice.You should have downloaded auspice_input_json and metadata merged files from step 5. We will now use them to generate a phylogenetic visualization using auspice.us. Go ahead and launch auspice.us, it will land you directly on to the home page below.You can directly drag and drop the auspice_input_json file, for it to build the phylogenetic tree, and the output would look something like this: Hover over the tree and geographical map to see the divergence of the strains, toggle between the options and parameters based on your needs.And if you wish to add metadata to observe any local outbreaks and quickly identify clusters within the samples that you analyzed, drag and drop the metadata_merged file on the built tree.Note: Once you drop the metadata file, all the attributes will show up in the "Color By" section (like in the picture above) where you can visualize your samples by whatever attribute that you have in your metadata file.Visualization gives few default errors and it would not be a problem, but most importantly it gives the option to color code your samples by metadata variables. Since the metadata in this example is random dummy data so results are not accurate, but if you upload your metadata, it would allow you to 'Color By' the metadata variables.This video shows how to drop and visualize on auspice.
Auspice will take a json file and build a tree that is visualized with NextStrain. The CDC has genomic toolkit modules that will probably be helpful in understanding the output we generate.Module 3.2: Getting started with NextstrainModule 3.4: Walking through Nextstrain trees
?. [NextClade Visualization]
You might want to look at a comparison to Auspice by visualizing through UCSC UShER too.Start by navigating to the UCSC UShER tool home page. Upload your concatenated fasta file (combined_assembly from step 5) by clicking "Choose File" and selecting the combined_assembly file then click "Upload". You can open the combined_assembly file, copy and paste the sequence names/IDs, but uploading this way is easier. UShER is quick and it will build phylogenetic placement against genome in GISAID or GenBank in few minutes. After uploading your assembly file pick which phylogenetic tree version you want to use from the drop down menu. These are updated over time as new genomes are added so its a good idea to take note of the version you choose to use. UShER outputs the subtress results of 50 most closely related samples to your input samples.You can pick the Phylogenetic tree version if you want to see the from where/how your samples are diverged, UShER would reproduce the results adding your samples to the existing tree nodes. We recommend using the top, most up to date tree. Once UShER finishes, it will have constructed a 50 node tree based on the closest neighbor. The subtrees that are generated by the tool depends on divergence of the strains, if the strains are more divergent, it would show more subtrees, and if you wish to add more samples, UShER would add them to the existing tree based on sample divergence and mutation.  You can visualize and explore this using the Nextstrain platform option.The results from UShER would be similar to that of the Auspice tool, however UShER conveniently gives extra information like QC and other metrics which you see in table format on the UShER page.If you wish to see the subtrees, select the options that is available below the table, it will launch the phylogenetic tree being rendered on Nextstrain platform. If you wish to display the metadata, you can drop the metadata on to the  Nextstrain just like we did on Auspice (in step 6).For this demo UShER took the concatenated assembly fastas of 20 samples and constructed a phylogenetic tree against all GISAID trees that are being maintained by the UShER and it gave 16 subtrees (See "Subtree Number" column). If you hover over the "?" of the column variables/sample rows, a gray dialogue box would appear (like in the picture) showing the info on that attribute. Colors are represented to show the variations of each attribute between samples.The lower the score the lighter the color, which means you samples are of high quality when it is green. When the score is high the output would appear in Red. In general the higher the score/red in color in the metrics, suggests that the sample sequence has many errors and sample placements might not be reliable.As an example:  In the image above the Parsimony score, which explains the number of mutations on the branch, for  Sample_10 is highlighted in red, this says the sample has relatively more mutations added to its branch than the others.Refer to CDC's Genomic Toolkit Module 3.3 for more information on this.If you want to see the subtrees click the subtree section of the row you are interested in and the link associated to that sample will redirect to the subtree visual rendered on the Nextstrain platform. Nextstrain distinguishes the public samples in Black and your input samples in Red. Subtrees basically shows how your sample is diverged and placed from the public samples. Here is an example subtree:You can also see the subtress by scrolling down the page and selecting from the individual subtree.Alongside, you will find an extra information such as the path of the mutation from root of the tree to your sample, most closely related sample in the global tree and its pango lineage that has been assigned to the sample in tree.
If you are not familiar with UShER see the CDC's Genomic Toolkit Module 3.3 for more details. Additionally, there is a preprint for UShER as well as a demo released by the authors.
?. [How to debug a failed run]
1. Failure due to the unavailability of the compute environment. Augur_run workflow script requests 78 CPUs in order to generate the auspice and nextstrain build. If the analysis fails due to lack of resources, requesting for more CPUs to Terra would the solution. For more details on how to fix this see step 2 of our Terra Troubleshooting protocol. 2. Failure for not specifying the input attributes correctly. There are two flavors of this error for Augur_Run:Singular instead of plural notationUsing sample instead of Sample_SetFirst, the singular instead of plural problem:Augur_run workflow looks for concatenated set of fasta files, you need to set the root entity to "name_sample_set" (with name being specific to your dataset) and the input attribute notation of "this.name_samples.assembly_fasta and metadata as "this.name_samples.metadata" rather than using "this.assembly_fasta" and "this.metadata" as we did with the Augur_prep protocol. In other words, you select the name_sample_set (singular) in root entity, however for the input use name_samples (plural) notation, since it is looking for all the files as concatenated set.You will see this error if you didn't use the plural:Second, we will look at the problem of using sample instead of sample set as your root entity type:If you actually go into the draft_augur_tree.log file in the GCP you will find this error. The solution here is to make sure your root entity type is set to the sample_set and not sample. 3. Error due to spacing in collection nameIn this example of a failed run we have an error caused by adding spaces into your collection name. If there is a failure for some other reason you can follow similar steps to understand why your job failed. Here we will be using Illumina paired-end data, but the process of debugging an error is the same if you have ONT data. If a run fails you will see this indicated in the job history screen in the "status" column. To understand why it failed click on the "workflow dashboard" icon in the "links" column. This will take you to a new screen and you can click the arrows next to the "message" to expand the message and see what it says. Here we see there are two errors that direct us to a log file to check. To find out more click on the "execution directory" icon under the links header. This will take you to the google bucket with all the output from the run.Follow the file path in the google bucket to the log files that were referenced in the error messages (in red/orange text in the above photo).  Click on the "Authenticated URL" link that will take you to a text file. In the text file we can see that there was an error that cause by there being a space between "Bad" and "Sample" in our file path that was created when we made "Bad Sample" rather than "Bad_Sample" as our collection name. Video of the whole process.  These error message can sometimes be hard to understand. Contact TOAST@cdc.gov if you need help debugging job failures.
?. [Running the Augur Workflows]
Running Augur_Run workflowAs we did before select the version of the workflow you would like to run (pick the latest stable version, here v1.4.4). The main and dev versions of the pipeline are under development and actively changing so its recommended  NOT to use these versions.Ensure that "Run workflow(s) with inputs defined by data table" is selected and click the "Use call caching" box. In contrast to the Augur_prep workflow, select "augur_prep_sample_set" in the the root entity section, because it will expect to have set of files in order to generate the output for the auspice visualizations. Since our root entity is a sample set when you click "SELECT DATA" click on the set of samples that you just ran Augur_Prep on. And in INPUTS section, assembly_fastas attribute is set to "this.augur_prep_samples.assembly_fastas", Remember it will look for set of samples not just sample, so name the attribute to root entity and set it to plural. The rest of the inputs are:Build_name in string format: Here we named it "B.1.147_samples_set", but you can call it whatever you like. sample_Metadata.tsvs (Generated by the Augur_Prep in the previous step) as "this.augur_prep_samples.augur_metadata. Again note the plural form!And it should look like this.Once your input form is complete, move on to the OUTPUTS form and select "Use Defaults'. Terra will then populate the OUTPUTS form with all of the default outputs options generated by the workflow. If you forget to do this you won't have easily accessible results! Save these changes by clicking the 'Save' buttonOnce your INPUTS and OUTPUTS forms are complete, click the 'Save' button on the top right-hand side of the page. The yellow caution icons should disappear and the Run Analysis option should be made availableYou are now ready to run the Augur_Run workflow! Click on the 'Run Analysis' button to the right of the 'Outputs' tab. A popup window should appear titled 'Confirm launch'. If the 'Run Analysis' button is greyed out, you need to save your recent changes by clicking the 'Save' button.Clicking the 'Launch' button should bring you to the 'Job History' panel where each sample will be queued for the Titan_Augur_Run analysis. The status will change from Queued -> Submitted -> RunningVideo showing how to submit the Augur_Run workflow.
If you don't use the plural form then you will get an error see section 8.2 for details.
?. [Running the Augur Workflows]
Running Augur_Prep workflowNavigate to the Augur Prep workflow page:From 'DASHBOARD' menu -> select 'WORKFLOWS' -> select 'Titan_Augur_Prep' workflow tileThis will bring up the Titan_Augur_Prep workflow page:   Select the version of the workflow you would like to run. If no preference pick the latest stable version (in this example v1.4.4). The main and dev versions of the pipeline are under development and actively changing so its recommended  NOT to use these versions.Ensure that "Run workflow(s) with inputs defined by data table" is selected, in the Output tab select 'use_defaults, click the "Use call caching" box and then select the root entity type for the sample data you wish to analyze. Don't use the "set" version!   Click "SELECT DATA" and choose the samples you wish to analyze. Note that where are only 25 samples shown by default so make sure when you click the check box to select all (as shown in video) that you actually get all the samples you intend to! For the inputs to the workflow the top six rows in the input represent variables that have to be provided by the user. Complete the INPUTS section with the appropriate attributes. In our example, for the 'assembly_fastas' variable, for the 'Attribute' text box we set that to 'this.assembly_fasta' to indicate the 'fasta_files' we wish to analyze. The rest of the inputs are as follows:'collection date' should be 'this.collection_date"'iso_continent' should be 'this.iso_continent''iso_country' should be 'this.iso_country''iso_state' should be 'this.iso_state''pango_lineage' should be 'this.pango_lineage' --> like assembly fastas this obtained from the previous analysis (Titan or uploaded from your own).Once you input all the data, it would look similar to the below picture.NOTE: If you named your columns something other than fastas then just type "this." followed by whatever the column name is. We would advise naming your fastas column "fastas" for clarity.Video showing on how to submit the Augur_Prep Run:Once the Augur_Prep workflow runs successfully, you should able to see the sample_metadata.tsv file associated to the sample table data under the TABLE section. This sample_metadata.tsv is selected as one of the inputs to run the Augur_Run workflow, that is why this step is necessary to check it was generated first.The video below shows this step:
Call caching allows Terra to identify and skip jobs that have been run previously; this option is by default enabled to avoid unnecessary compute costs. More information on Terra call caching, including examples of when you may want to disable this feature, is available through the Terra Support Documentation.
?. [Analysis Inputs/Data uploading]
You will likely have many samples to upload and you can do this by going directly to your Google bucket.First, go to “DASHBOARD” tab in your workspace and click “Google Bucket” at the bottom right corner of the same page.This will direct you to your “Google Cloud Platform” page for data uploading. Click “UPLOAD FILES” in the middle of this page to upload single or multiple fastq files. Or you can click “UPLOAD FOLDER” to upload a folder with multiple fastq files stored inside.Go back to your Terra account and click “DATA” tab. The successfully uploaded fastq files will show up. If the upload is successful then the files should be located under the 'Files' tab, either inside the folder (as you named) or filesNow that the samples are uploaded you will need to return and follow the steps in 3.0 to get your metadata associated with each sample and that should look like below.Here is a short video demonstration:
?. [Analysis Inputs/Data uploading]
Alternatively, you can upload your files via 'https://app.terra.bio/#upload'. There is no button on Terra to take you to this page, you will need to type this into the search bar. Navigate to 'https://app.terra.bio/#upload'Select the Terra Workspace to which you would like to upload your fastq files. This will be the same workspace created in the previous step.Click the '+ Create a new collection' link and enter a name for your new collection of fastq files. DO NOT INCLUDE SPACES IN THE COLLECTION NAME, use underscores instead. Spaces will cause an error later in the pipeline.Click the 'Create Collection' button and you will be routed to the data uploader page where you can drag and drop fastq files directly into your browser window to initiate upload.Drag and drop the fastq files that you would like to upload in to the upload space.Once your files have been successfully uploaded, select "NEXT>" to proceed to the metadata upload page.Here is a video of the process: