Basic usage

Don’t hesitate to provide feedback!

This page describes the basic usage for sf-pediatric. If something is not clear for you, do not hesitate to open an issue on sf-pediatric GitHub page.

Checklist

Before running the pipeline, make sure you have completed the following:

1. Prerequisites installed?

   Verify that nextflow and either docker or apptainer are installed and working. See the installation guide for detailed instructions.

2. BIDS data validated?

   Your data must be organized in BIDS format with the participants.tsv file containing the age column. See the inputs guide for details.

3. FreeSurfer license available?

   Caution

   If you plan to use the segmentation profile, you must have a valid FreeSurfer license. Get one here (free for academic use). You’ll specify the path with --fs_license /path/to/license.txt

4. Know which analysis you want to run?

   Decide which profiles you need based on your research goals. See the Understanding the profiles guide.

5. Will you have access to the internet during processing?

   Internet access is not required to run the pipeline. However, by default, the pipeline will download some dependencies during execution. If you plan on running it on a machine without internet access (e.g., an HPC cluster), head over to the running with no internet access section.

A simple example

If you’re new to the pipeline, start with this basic command for diffusion MRI preprocessing and tractography:

Assumptions

By default, the pipeline assumes two important things:

1. B-values ≤ 1200 s/mm² for DTI fitting.

2. B-values ≥ 700 s/mm² for fODF fitting.

If your acquisition protocol does not fit those assumptions, you can change the pipeline behavior. For more information, see this section.

Command

nextflow run scilus/sf-pediatric -r 0.2.2 \
   --input /absolute/path/to/your/BIDS_directory \
   --outdir /absolute/path/to/results \
   -profile docker,tracking \
   -resume

What does this do?

This command will:

• Download and run the pipeline version 0.2.2
• Process all subjects in your BIDS directory using the tracking profile
• Save the results to your specified output directory
• Use Docker containers

Need help choosing profiles?

If you’re unsure which profiles to use, check out the understanding the profiles guide for detailed explanations and common recipes.

Required parameters

Every pipeline run needs at least these three parameters:

1. --input - Path to your BIDS directory

   Your data must follow BIDS format with a participants.tsv file containing an age column.

2. --outdir - Where to save results

   Results can be large (several GB per subject), so choose a location with sufficient space. We recommend naming the output directory with the version number (e.g., --outdir /path/to/results/sf-pediatric-v0.2.2)

3. -profile - Which profiles to run

   # Always include a container system (docker/apptainer) + processing profiles
   -profile docker,tracking
   -profile apptainer,tracking,segmentation,connectomics

   See the profiles guide for detailed information on choosing profiles.

Important optional parameters

Shell selection for DTI and fODF models

Check your b-values!

As mentioned above, the pipeline assumes by default:

1. B-values ≤ 1200 s/mm² for DTI fitting.

2. B-values ≥ 700 s/mm² for fODF fitting.

Does your data have different b-values? (e.g., HCP protocol with b-values of 1500 and 3000 s/mm²)

If your data does not match the above-mentioned assumptions, you MUST specify which shells to use, or the pipeline will likely fail. Follow the instructions below.

How to specify shells:

# For HCP-like protocol (b-values: 1500 and 3000)
nextflow run scilus/sf-pediatric -r 0.2.2 \
   --input /path/to/BIDS \
   --outdir /path/to/results \
   --dti_shells "0 1500" \
   --fodf_shells "0 1500 3000" \
   -profile docker,tracking \
   -resume

For more details, see --dti_shells and --fodf_shells parameters.

Selecting specific subjects to process

Sometimes, you might want to process only a subset of subjects from your complete BIDS dataset. This is entirely possible using the --participant_label parameter.

# Process only sub-01 and sub-02
nextflow run scilus/sf-pediatric -r 0.2.2 \
   --input /path/to/BIDS \
   --outdir /path/to/results \
   --participant_label "sub-01,sub-02" \
   -profile docker,tracking \
   -resume

Selecting a large number of subjects

For multiple subjects or complex configurations, using an external params.yml file containing all CLI parameters is recommended (see the advanced usage section for more information).

All modifiable parameters

While we only overviewed the most common parameters here, sf-pediatric can be customized even further through various additional parameters that can all be supplied through the command line (as shown above) or through an external params.yml file (see advanced usage). The complete list of modifiable parameters can be found in the parameters section.

Understanding pipeline outputs

Something went wrong?

If for some reason, the pipeline’s execution stopped early, or do not start, head over to the troubleshooting page!

The pipeline will create the following structure in your current working directory (assuming your --outdir is located in this directory):

• Directorywork/ # Temporary files (can be deleted after successful run)

  • …
• Directorysf-pediatric-v0.2.2/ # Your results (specified by —outdir)

  • dataset_description.json
  • participants.tsv
  • Directorymultiqc/ # Quality control reports

    • …
  • Directorysub-01/

    • Directoryses-01/

      • Directoryanat/ # Anatomical images (T1w/T2w processing)

        • …
      • Directorydwi/ # Diffusion images and tractography

        • …
      • Directoryfigures/ # QC visualizations

        • …
      • Directorymultiqc/ # Subject-specific QC

        • …
      • Directoryxfm/ # Image transformations

        • …
• .nextflow.log # Log file (check this if errors occur)
• Directory.nextflow/ # Nextflow cache (enables -resume)

  • …

For a detailed description of each output file, see the outputs guide.