Running the pipeline

Parameters and profiles

A pipeline like nf-mouse is highly flexible and configurable. To simplify usage for anyone who wants to run it without diving into every parameter, we created a set of profiles that regroup multiple variables.

That said, here are some important parameters you might find useful.

Parameters

1. --use_preqc

   By selecting this parameter and combined with the profile run_preqc, you will use the output of a combination of checks and validations steps to insure your images and bvecs are oriented correctly.

2. --use_fodf_for_tracking

   By selecting this parameter, tracking will be carried out using the FODF reconstruction.

3. --run_step

   Each preprocessing step of nf-mouse can be skipped. You can deactivate a specific step by adding --run_STEP false. Here are the following steps that can be disabled: denoising, eddy, n4, resampling,

For the full parameter list, consult the page parameters

Profiles

Processing profiles:

1. pre_qc:

   By selecting this profile, you will run a set of checks and validations steps to insure your images and bvecs are oriented correctly.

   Caution

   If you want to use the output of the pre QC data you must add —use_preqc. See parameters section.

Configuration profiles:

1. docker (Recommended):

   Each process will be run using Docker containers.

2. apptainer (Recommended):

   Each process will be run using Apptainer images.

3. arm:

   Made to be use on computers with an ARM architecture (e.g., Mac M1,2,3,4). This is still experimental, depending on which profile you select, some containers might not be built for the ARM architecture. Feel free to open an issue if needed.

4. slurm:

   If selected, the SLURM job scheduler will be used to dispatch jobs.

   Note

   Please note that, by using this profile, you might have to adapt the config files to your specific computer nodes architecture.

Using either -profile docker or -profile apptainer is highly recommended, as it controls the version of the software used and ensure reproducibility. While it is technically possible to run the pipeline without Docker or Apptainer, the amount of dependencies to install is simply not worth it.

Multiple profiles

For example, to perform the pre_qc and use apptainer, users should select -profile pre_qc,apptainer.

Typical command-line

The typical command for running the pipeline is as follows:

Command

nextflow run scilus/nf-mouse -r main \
     --input <input_directory> \
     --outdir <output_directory> \
     -profile docker \ # or apptainer
     -with-report <report_name>.html \
     -resume

This will launch the pipeline using the main branch (latest non-released version) with the docker configuration profile. There are only 3 parameters that need to be supplied at runtime:

1. --input: for the path to your BIDS directory

   For more details on how to organize your input folder, please refer to the inputs section.

2. --outdir: path to the output directory

   We do not specify a default for the output directory location to ensure that users have total control on where the output files will be stored, as it can quickly grow into a large number of files. The recommended naming would be something along the line of nf-mouse-v{version} where {version} could be 0.1.0 for example.

3. -r: Release nf-mouse

   You need to select the nf-mouserelease you want to use. Release available.

4. -profile: profile to be run and container system to use

   nf-mouse processing steps was designed in profiles, giving users total control on which type of processing they want to make. One caveat is that users need to explicit tell which profile to run. This is done via the -profile parameter. To view the available processing profiles, please see this section

   Note

   The -profile command line parameter is a core nextflow parameter, hence the preceding single dash. This means you can also specify nextflow specific profile side-by-side nf-mouse processing profiles (e.g., the docker/apptainer selection).

5. -resume: Enables nextflow caching capabilities.

   This is a core nextflow arguments. It enables the resumability of your pipeline. In the event where the pipeline fails for a variety of reasons, the following run will start back where it left off. For more details, see the core nextflow arguments section.

6. -with-report: Enables nextflow caching capabilities.

   This is a core nextflow arguments. It enables the html report of your pipeline. For more details, see the core nextflow arguments section.

Note

More parameters can be tuned to your own usage, for a concise list of the most common parameters, you can run nextflow run scilus/nf-mouse -r main --help. Otherwise, for the complete list of parameters, please refer to the parameters section of the documentation.

Running the pipeline in offline mode

If the computer nodes you are planning to use do not have access to the internet, there is a few steps to go through to make sure the containers and templates are available during pipeline execution. Please head over to running with no internet access section.

Now it’s time to look at your output directory. See output section.

Build your own command line

Here is a smart tool to help you build

Select nf-mouse release

main (latest development) v0.1.0

Input and output directories

Input directory:

Output directory:

Pipeline options

Use pre-QC

Use fODF for tracking

Skip processing steps

• Denoising
• Eddy current
• N4 correction
• Resampling
• Tracking

Select execution profiles

Container engine (choose one):

Docker

Apptainer

Additional profiles:

run_preqc

slurm

gpu

The executable command:

Copy

nextflow run scilus/nf-mouse -r main \ --input INPUT \ --outdir ./results \ -profile docker,pre_qc \ -resume

Advanced usage

The execution method for nf-mouse varies, often depending on the informatics structure where you intend to run nf-mouse.

Here are three extra sections that could help you:

• Advanced users
• No Internet
• FAQ

Outputs

You are now ready to explore the output BIDS structure.