Dependencies and Install

Quick Start

1. Install Nextflow (>=24.04.2).

   There are several options for install if you do not already have it on your system:

   • Install into conda environment, which will require a version of Anaconda to be installed on your system.

     mamba create -n nextflow -c bioconda nextflow=24.04.2  

   • If you prefer a to use curl or wget for install see the Nextflow Documentaiton

2. Install Docker or Singularity >=3.8.7 for full pipeline reproducibility. While Docker and Singularity are the most commonly used, Phylophoenix can also be used with Podman and Charliecloud

3. (optional) If you installed nextflow via a conda environment activate the nextflow environment with:

   conda activate nextflow

4. Run PHoeNIx on a test sample loaded with the package with a single command:

   nextflow run cdcgov/phylophoenix -r v1.0.0 -profile <singularity/docker/custom>,test --input $PATH_TO_SAMPLESHEET

Note that this command clones (downloads) the repo to ~/.nextflow/assets/cdcgov/phoenix. See PHoeNIx Wiki for how to clone and have the software downloaded to a different location.

> * The pipeline comes with config profiles called `docker` and `singularity` which instruct the pipeline to use the named tool for software management. For example, `-profile test,docker`.
> * Please check [nf-core/configs](https://github.com/nf-core/configs#documentation) to see if a custom config file to run nf-core pipelines already exists for your Institute. If so, you can simply use `-profile <institute>` in your command. This will enable either `docker` or `singularity` and set the appropriate execution settings for your local compute environment.

5. Start running your own analysis with a samplesheet!

   nextflow run cdcgov/phylophoenix -r v1.0.0 -profile <singularity/docker/custom> --input <path_to_samplesheet.csv> --metadata <metadata.tsv>

All the Details

Install and Set up Dependencies

1. Install Nextflow (>=24.04.2).

There are several options for install if you do not already have it on your system:

• Use curl or wget for install see the Nextflow Documentation

• A good way to install Nextflow is with conda or mamba. Mamba is much faster so we would recommend that. This will require installation of Anaconda first. A short tutorial on Anaconda and its set up can be found here.

  If you need mamba installed and you already have anaconda on your system run:

  conda install -c conda-forge mamba

  To install Nextflow run:

  mamba create -n nextflow -c conda-forge -c bioconda nextflow=24.04.2  

  Then you can activate the environment with:

  conda activate nextflow

  - You will run PhyloPHoeNIx from inside this environment!

2. Configuring Nextflow for command-line interface (CLI) users

Configuration will be needed so that Nextflow knows how to fetch the required software. This is usually done in the form of a config profile. You can chain multiple config profiles in a comma-separated string.

• The pipeline comes with config profiles called docker and singularity which instruct the pipeline to use the named tool for software management. For example, -profile test,docker.
• Please check nf-core/configs to see if a custom config file to run nf-core pipelines already exists for your Institute. If so, you can simply use -profile <institute> in your command. This will enable either docker or singularity and set the appropriate execution settings for your local compute environment.
• If you are using singularity and are persistently observing issues downloading Singularity images directly due to timeout or network issues, you can use the --singularity_pull_docker_container parameter to pull and convert the Docker image instead. Alternatively, you can use the nf-core download command to download images first, before running the pipeline. Setting the NXF_SINGULARITY_CACHEDIR or singularity.cacheDir Nextflow options enables you to store and re-use the images from a central location for future pipeline runs.
  • To add NXF_SINGULARITY_CACHEDIR to your bash profile run the following:
    1. Open your ~/.bash_profile by running nano ~/.bash_profile or some other text editor that isn't nano.
    2. Inside the ~/.bash_profile add the following lines

    export NXF_SINGULARITY_CACHEDIR=/$PATH/Singularity_Containers
    export PATH

    3. Here $PATH is the full path to where you want to store the folder. You can name Singularity_Containers folder whatever you want. You will need to restart your terminal or run source ~/.bash_profile to allow nextflow to see the new path.

3. Installing Container Software

Install Docker or Singularity

Run PhyloPHoeNIx

To run PhyloPHoeNIx there are two options the difference being where you want it installed:

1. Install the latest version via cloning PhyloPHoeNIx github repo into a folder of your choosing:

   cd $PATH_TO_INSTALL
   git clone https://github.com/CDCgov/phylophoenix 

   If you want to run a particular version then you can download that using the -b argument like this:

   git clone -b v1.0.0 https://github.com/CDCgov/phylophoenix 

   Then you can run it (make sure you activate your conda environment first, if that is how nextflow is installed!):

   nextflow run $PATH_TO_INSTALL/phylophoenix/main.nf -profile <singularity/docker/custom> --input <path_to_samplesheet.csv>

2. Alternatively, PhyloPHoeNIx run directly (will download to ~/.nextflow/assests/cdcgov/phylophoenix):

   nextflow run cdcgov/phylophoenix -r v1.0.0 -profile <singularity/docker/custom> --input <path_to_samplesheet.csv>

   Running PhyloPHoeNIx this way means it will just pull the version specified with -r on github to run and it will be installed into ~/.nextflow/assets/cdcgov/phylophoenix.

Testing Install

To test that the pipeline was installed and configured correctly run the following by running either:

nextflow run phylophoenix/main.nf -profile test,<singularity/docker/custom> --input <path_to_samplesheet.csv>

or

nextflow run cdcgov/phylophoenix -r v1.0.0 -profile test,<singularity/docker/custom> --input <path_to_samplesheet.csv>

This command will run the pipeline on preloaded data. If all goes well you should see some output that looks like this: