Nextflow (`nf-core`) on O2

Nextflow is a workflow system for creating scalable, portable, and reproducible workflows. It is based on the dataflow programming model, which greatly simplifies the writing of parallel and distributed pipelines, allowing you to focus on the flow of data and computation. Due to software requirements, HMS IT is unable to provide global support for Nextflow-based workflows. However, general guidance and procedures for setting up a local pipeline are outlined below.

Installing Nextflow (and nf-core)

Users generally have a choice to make here - Nextflow is the generic option that allows for workflow creation and customization from scratch. nf-core is simultaneously a repository of existing pipelines as well as utility with which to execute these pipelines, as a drop-in replacement for (most of) Nextflow itself.

Installing Nextflow does NOT install nf-core, but installing nf-core DOES install nextflow.

Nextflow

To install Nextflow alone, Java is required. It is is sufficient to load one of the existing java modules:

( java/jdk-21.0.2 is the newest available Java module at the time of writing.)

Next, navigate to where you would like the nextflow executable to be generated, then run the following (in an interactive session):

If at this point you would like to relocate the executable to somewhere more convenient, you may do so with mv. Make sure the directory containing the nextflow executable is on your PATH variable, and you are ready to use Nextflow.

nf-core

To install nf-core (and Nextflow together), the easiest method is to create a conda environment. See Conda on O2 for generic instructions to create a conda environment. The command to use is below:

Next, activate the environment:

And nf-core, as well as Nextflow, should be available to use.

Creating/Using Custom Nextflow Pipelines

Unfortunately, HMS IT is unable to support custom workflow creation below a surface level due to high amounts of customization involved. If a user is interested in creating their own Nextflow workflow, please see the Nextflow documentation for guidance on how to set up the structure correctly. HMS IT may be able to make recommendations related to resource requirements and such on O2.

If attempting to use an established Nextflow workflow that is independent of official nf-core repositories, please refer to the instructions provided by the workflow maintainer.

Preparing Pipelines for Execution (using Singularity containers)

If using the singularity profile, it is necessary to move the associated containers to a whitelisted directory, per O2 containerization policy.

Official nf-core Pipelines

Users that are interested in leveraging existing nf-core workflows may do so using the nf-core utility that they had installed via the instructions above. Generally, these workflows are invoked with the singularity profile for reproducibility purposes. However, manual intervention from HMS Research Computing is still currently required to get the containers installed.

If the pipeline is part of the official nf-core repositories (e.g., it is listed at https://nf-co.re/pipelines/ ), then please contact HMS Research Computing at rchelp@hms.harvard.edu with the pipeline name and version for which you would like the containers to be installed.

Custom or non-`nf-core` pipelines

Users attempting to set up a Nextflow pipeline that is not an official nf-core pipeline will need to download the containers associated with the pipeline using whatever means is suggested by the pipeline maintainers.

You may attempt to use the self-service container installation tool to install your containers to the whitelisted directory as specified here: Self-Install Singularity Containers Note that this does require you to download the containers locally first. If this does not work for whatever reason, or the container installation is incomplete (i.e., you are also dealing with additional symbolic links or something else that the tool cannot presently handle), manual intervention will be required.

At this point, please contact HMS Research Computing at rchelp@hms.harvard.edu for assistance with moving these containers to the whitelisted location, and please indicate the path to which you downloaded these containers, as well as whether the pipeline is going to be for your personal use or if it will be shared with fellow lab members.

After containers are installed

If the requested containers were associated with an official nf-core pipeline, they will be installed to

Note that this is a directory that exists independent of individual user or lab membership - if you are looking to leverage a new nf-core pipeline, please look inside this directory tree to check if the pipeline and version you are intending to use has already installed containers. This will save you the time to contact HMS IT.

For other pipelines, they will be installed to

or

and possibly within some descriptive subdirectory, depending on preference.

For both cases, once the containers are installed, it is required to set the NXF_SINGULARITY_CACHEDIR environment variable prior to executing the workflow:

Obviously, this variable will need to be reset depending on the pipeline being executed.

From there, modification of the pipeline configuration files may be necessary. To start, there should be a nextflow.config file located at $HOME/.nextflow/assets/CATEGORY/PIPELINENAME/nextflow.config. This file will contain parameter settings associated with various steps in the workflow, as well as global maximum resource requirements.

Integrating Pipelines with slurm

Nextflow/nf-core does not provide HPC resource utilization out of the box via standard workflow configurations, but it can be configured manually. If you do not provide a configuration file to interact with the Slurm scheduler on O2, Nextflow/nf-core will only use the local resources of your current job allocation (such as within an interactive srun job).

Boilerplate O2 Configuration File

The following is an example of a configuration file that will allow you to submit individual steps of the pipeline as jobs to O2’s slurm scheduler. Presently, only short, medium, and long partitions are represented. If you would like to leverage a different partition (such as a contributed partition), please make edits to this file accordingly.

Presently there is no boilerplate configuration available for GPU utilization. Please contact rchelp@hms.harvard.edu for inquiries about leveraging GPUs with your Nextflow/nf-core pipeline via slurm.

Paste this configuration into a text file on O2 somewhere (for example at the current working directory), and save it as something like nextflow_slurm.config. You can then invoke your pipeline using nextflow ... -c nextflow_slurm.config -profile cluster,singularity to prioritize this configuration file above (in addition to) the existing workflow configurations.

Configuration File specification

The following is a brief summary of each section of this configuration file and their functions:

• params designates global maximum job allocation parameters, as well as configuration metadata.

  • max_memory is a global limit on how much memory any single job can request of the scheduler.

  • max_cpus is a global limit on how many cores any single job can request of the scheduler.

  • max_time is a global limit on how much wall time (real-life duration) any single job can request of the scheduler. 30.d (30 days) is the hard limit.

If you have access to resources that may allow you more than these values, you can consider modifying them accordingly.

• profiles describes methods by which the pipeline can be invoked. This is specified at execution time via nextflow ... -p profilename1,profilename2,.... At least one profile name must be specified. The profile names in this file are in addition to the default profiles (the singularity profile in this file augments the default singularity profile implemented by Nextflow, etc.).

  • the singularity profile sets parameters to allow usage of Singularity containers on O2 to execute pipeline steps. You shouldn’t need to mess with this profile.

  • the cluster profile sets parameters to allow submission of pipeline steps via O2’s slurm scheduler.

    • the only parameter you may be interested in is the queue parameter, which governs which partition a pipeline step is submitted to.

      • If a pipeline step requires less than 12 hours, it is submitted to short. If less than 5 days, medium. Otherwise, long.

      • If you have access to additional partitions (such as mpi, highmem, contributed partitions, etc.), set queue accordingly.

        • Keep in mind that such special partitions do not have the same time governances (other than the 30 day limit) on them, so if you would like to integrate one or more of these partitions with the existing short / medium / long paradigm, you will likely need to modify one or more of the pipeline-specific configuration files as well. Please contact rchelp@hms.harvard.edu with inquiries about this.

        • If you are planning to use a specialized partition exclusively, then simply overwrite the queue specification with that partition name.

  • the local profile invites the pipeline to be executed within your existing resource allocation (e.g., inside the active interactive session). You need to make sure you have requested the MAXIMUM of cores and memory desired by any one step of the pipeline in order for this profile to execute successfully.

• executor describes how the pipeline processes will be run (such as on local compute resources, on cloud resources, or by interacting with a cluster compute scheduler). The executor will keep track of each of the processes, and if they succeed or fail.

  • When using the slurm executor, Nextflow can submit each process in the workflow as an sbatch job.

    • Additional parameters that govern the Slurm job submission process are queueSize and submitRateLimit. The queueSize is how many tasks can be processed at one time; here we use 1900 tasks. The submitRateLimitis the maximum number of jobs that will be submitted for a specified time interval. In our file, we limit it to 20 jobs submitted per second.

  • When using the local executor, Nextflow will run each process using the resources available on the current compute node.

Modifying the configuration file

As mentioned above, the following variables may be modified depending on your job submission preferences:

• queue - if you would like to submit to a contributed or other specialized access partition, you can replace this entire string with the appropriate partition name (e.g., highmem or gpu_quad). You will still need to make sure you have access to submit to that partition.

• clusterOptions - this is a variable that allows you to set additional sbatch parameters (or even other execution parameters for pipeline steps, but that is outside the scope of this section). More information can be found in the Nextflow documentation for the clusterOptions flag. An example of its use here could be something like:

here, we are now submitting directly to the gpu_quad partition in all cases instead of dealing with the cpu-only partitions, and are excluding the compute nodes with L40S GPU cards (just as an example).

Do note that if you do plan to use gpu-based partitions, you should make sure that your process runtime limits do not exceed that of the partition’s specified limits (5 days in this case). If that is a concern, add the time field to the above block to override the process limits specified by the workflow:

Executing Nextflow Pipelines

Once the NXF_SINGULARITY_CACHEDIR environment variable is set (assuming you are using the singularity profile), you have two options for invoking your pipeline:

1. if the pipeline is an official nf-core pipeline, you can simply paste the command from the website and modify it to use the correct input, output, and profile settings.

2. Otherwise, use nextflow run. A typical nextflow run command may look something like this:

   You may need to refer to execution instructions provided by the pipeline maintainer.

To view a list of all pipelines you have ever downloaded/run, you can invoke the nextflow list command. These pipelines are located at $HOME/.nextflow/assets.

Cleaning Up After Execution

After your pipeline completes, there will be work and .nextflow directories at the location where you executed the workflow (not to be confused with your output directory). You may find it useful to occasionally delete these directories, especially if you find that you are using far more space than anticipated. You can keep track of your utilization with the quota-v2 tool (see Filesystem Quotas | Checking Usage ).

Note that these directories will be present at every location where you have ever executed a pipeline, so you may need to remove multiple directories from different locations if you do not have an established means of organization for juggling multiple workflows.

Also note that resume (checkpointing) functionality will not work if you remove the work OR .nextflow directory for a given workflow execution location - it will think you are starting over from the beginning. You will see the following message:

Troubleshooting Pipelines

Each workflow execution will generate a .nextflow.log file in the directory where the pipeline is invoked. Subsequent executions will result in nextflow renaming previous .nextflow.log files to .nextflow.log.1, .nextflow.log.2, etc., depending on how many executions are performed in the current directory - .nextflow.log is always going to be the log file associated with the most recent run, with files with increasing numbers associating with older and older runs (.2 happened before .1, etc.).

Workflows that are resume-d will generate a NEW .nextflow.log file, so it may be necessary to reconcile the newest log with the most recent previously generated logs to view full workflow output.

Some workflows may also include a debug profile, which you can invoke alongside other profiles, to get more verbose output while the workflow is executing.

There are also some workflows where when it fails for some reason, but you do not see an error explaining the failure unless you visit a log file within a subdirectory of the work folder. In such a case, you can refer to the output from nextflow log runName -f status,name,workdir. In that command, runName is the name that will be automatically assigned when your workflow is executed and the items after -f are columns to display in the output.

In the above output, each process that was run is displayed on its own line. The first column has the status for the process, the second column reports the name of the process, and the final column reports the workdir. The available columns that can be reported with nextflow log can be seen via

Definitions for each of these fields can be found in the Nextflow documentation here.

All but one of our processes had COMPLETED status, meaning everything executed as expected. We would need to troubleshoot steps that report FAILED or ABORTED, of which we have one (the MULTIQC step). To find the associated files for a process, look at the last column; this has location of the associated subdirectory of the work folder. Depending on the workflow, there may or may not be a log file with useful error messages contained within the process directory.