Running PhyloPHoeNIx on Different Systems

How do I Adjust CPUs/Memory Usage?

Notes on config files

PhyloPhoenix is written in Nextflow, which has a native hierarchy for the order in which it pulls info from config files. Nextflow uses config files to determine how many CPUs/Memory to give to jobs which are all found in the conf folder. However, the pipeline also follows nf-core standards, so settings for memory, CPUs and other resource constrains are found in conf/base.config which isn’t part of Nextflow’s hierarchy. PhyloPHoeNIx is structured so that each process is "labeled" as high, medium, or low based on its resource requirements, and the corresponding CPU and memory allocations are determined by these labels in the base.config file. The test profile has it own config that can be edited to speed up the test sample as its just limited to 2 CPUs.

Options for edit resource requirement - Pick one option

1. The simplest approach if you have computer with a known RAM cutoff then use the master resource parameters when running phoenix

2. Edit the CPUs/Memory in the base.config for a label well cause all process with that label to use those resources.
3. Create a new config file with your desired differences to the base.config and pass it with -c. Then those SHOULD be the settings used.

If you used git clone for your install then edit the base.config file and save it in the same place and you are good to go. However, if you used nextflow run or are running on nextflow tower the best way to change the number of CPUs/Memory for each process is to create a new config file with labels like the base.config and pass it to nextflow with the -c command on CLI.

Configuration for Running PhyloPHoeNIx on a High Performance Computing (HPC) Cluster

To run PhyloPHoeNIx on an HPC and submit jobs to a cluster you will need to make config file for your executor. We provide a template in the conf folder to edit. How to pass this to PhyloPHoeNIx depends on the type of install you are using. For full details on configs see nextflow documentation.

If you used git clone to install

After editing the template in the conf folder you save it in the same place and then run PhyloPHoeNIx with:

nextflow run $PATH_TO_INSTALL/phoenix/main.nf -profile singularity,custom_HPC --input samplesheet.csv

If you used nextflow pull or nextflow run to install

After editing the template in the conf folder, then you save it to a new location passing it the PhyloPHoeNIx with the -c parameter. Now you can run PhyloPHoeNIx with:

nextflow run cdcgov/phylophoenix -r v1.0.0 -profile singularity -c mycustom_config.config --input samplesheet.csv

Running PhyloPHoeNIx >=v1.1.0 on Terra

For states that are using Terra.bio to run bioinformatic workflows like SARS-CoV-2 genomic characterization we have provided PhyloPHoeNIx as a workflow that can be imported into your workspace.

1. Upload your samples just as you would for other analysis. Your metadata.tsv file should contain at minimum the headers entity:sample_id, Read_1, and Read_2 in a tab delaminated file. Once files are uploaded proceed to importing the workflow into your workspace.

1. Under the workflows tab click the + blue circle in the "Find a workflow" box to add a new workflow.

2. In the pop-up window click dockstore, which will take you to the dockstore website where we will search for the PhyloPHoeNIx workflow.

3. Search "phylophoenix" in the search bar of the dockstore webpage.

4. The PHoeNIx workflow should then appear in the search output. Make sure it says "WDL" under the format column as there is also a nextflow version of the pipeline that will not work on Terra. Click the workflow hyperlink.

Now you will should be in a dockstore page for the PhyloPHoeNIx workflow. Click on the latest version of the pipeline on the right hand side of the page in the "recent versions" menu. The greyed out "Terra" button should now turn blue if it was not already. Click it.

Note: If you run the "main" branch this will run the latest version of the pipeline, but if you want to run a specific version then you can pick that branch right now the only stable release of PhyloPHX is v1.1.0

5. Select the Destination Workspace you want to import the workflow into from the drop down menu. Then click the blue "import" button.

6. Importing the workflow should immediately take you to its workflow space in your chosen workspace. Click the "Outputs" table and then click the "Use defaults" hyperlink to auto fill the output names. If you forget to do this you won't have output saved!

7. Click the "Select Data" blue button and select the samples you want to analyze from the pop up window. Then click save to close the pop up window.
8. Click the "Inputs tab" and fill in the following REQUIRED field:

• current_full_results - this.samples.full_results
  If you want fill in the following OPTIONAL field:
• by_st / combine_complex / no_all / use_secondary_mlst - true or false
• output_folder_name - Any string with quotes around it for example: "phylophx"

9. There are optional fields for CPU, disk_size and memory that you can adjust if there are errors regarding lack of resources. You will need at least >50GB of memory. DO NOT add anything for the docker option.
10. Click the blue "Save" button on the right hand side of the page and this will cause the greyed out "RUN ANAYLISIS" to turn blue. Click "RUN ANAYLISIS" and this will launch the pipeline.