TractoFlow

This page provides information on running the TractoFlow pipeline via XNAT. TractoFlow is a robust diffusion MRI processing pipeline developed by the SCIL (Sherbrooke Connectivity Imaging Lab). It performs a fully automated dMRI processing from raw data to tractography.

What is TractoFlow?

TractoFlow processes diffusion MRI data to correct for artifacts and reconstruct white matter pathways. Its main steps include:

  • Denoising: MP-PCA denoising on DWI data.

  • Preprocessing: Eddy current correction, Topup (if reverse phase encoding is available), and motion correction.

  • T1w Image Processing: Brain extraction and registration to DWI space.

  • DTI Metrics: Computation of Fractional Anisotropy (FA), Mean Diffusivity (MD), Axial Diffusivity (AD), and Radial Diffusivity (RD).

  • fODF computation: Fiber Orientation Distribution Function using Constrained Spherical Deconvolution (CSD).

  • Tractography: Probabilistic or deterministic tracking (Particle Filtering Tracking).

For detailed information, visit the official Tractoflow documentation.

What You Need Before Running

  1. BIDS Conversion: You must run dcm2bids first. The pipeline expects data in the Resources/rawdata folder.

    • Required: A valid T1w anatomical image.

    • Required: A valid DWI acquisition (dwi.nii.gz, .bval, .bvec).

    • Optional but Recommended: A reverse phase encoding b0 image (fmap) for distortion correction.

  2. FreeSurfer: While TractoFlow can perform its own brain extraction, running FreeSurfer beforehand and having the outputs available in Resources/freesurfer is highly recommended. The XNAT pipeline script explicitly checks for existing FreeSurfer outputs to improve T1w processing and registration.

How to Launch the Pipeline

Note

For step-by-step instructions on running any pipeline, see Running Pipelines on XNAT. To enable pipelines for your project, see Enabling Pipelines for Your Project. For running pipelines across multiple subjects in parallel, see Running Pipelines Across Multiple Subjects.

  1. Navigate to your session on XNAT.

  2. Click “Run Preprocessing Pipeline”.

  3. Select “TractoFlow” from the pipeline dropdown.

  4. Configure the parameters:

    • Session Label: Typically auto-filled.

    • Project ID: Typically auto-filled.

    • FMRIPrep Flags: (Optional) Although labeled generic flags, this field is intended for passing specific Tractoflow Nextflow arguments if supported by the wrapper. Note: In standard configuration, the pipeline runs with optimal defaults.

Warning

The pipeline requires significant computational resources. Please allow 12-24 hours for completion.

Output Structure

TractoFlow generates a comprehensive set of derivatives. The XNAT pipeline transfers these back to a tractoflow folder in the session Resources.

<Resources>/
  tractoflow/
    DTI_Metrics/
        sub-01_ses-01__fa.nii.gz       (Fractional Anisotropy)
        sub-01_ses-01__md.nii.gz       (Mean Diffusivity)
        sub-01_ses-01__ad.nii.gz
        sub-01_ses-01__rd.nii.gz
    FODF_Metrics/
        ... (fODF data for tracking)
    Tractography/
        sub-01_ses-01__pft_tracking_prob_sc_t1_seeding_mask.trk
    Readme.md
    report.html (Quality Control Report)

Key Output Files:

  • DTI_Metrics/*_fa.nii.gz: Use this for voxel-based analysis of white matter integrity.

  • Tractography/*.trk: The whole-brain tractogram. This can be visualized in software like MI-Brain, Dipy, or Mrtrix.

  • report.html: A visual report of the processing steps. Check this to verify brain extraction and registration quality.

Component Versions

Component

Version

Filename / Command

Java

1.8.0_31

module load jdk/1.8.0_31

Nextflow

21.10.6

/scratch/mri/singularityimages/nextflow

Tractoflow

2.4.4

/scratch/mri/singularityimages/tractoflow/main.nf

Container

1.6.0

scilus_1.6.0.sif

Pipeline Command

The pipeline is executed on the cluster using the following command structure:

/scratch/mri/singularityimages/nextflow run /scratch/mri/singularityimages/tractoflow/main.nf \
    --input <input_directory> \
    --output_dir <output_directory> \
    -with-singularity /scratch/mri/singularityimages/scilus_1.6.0.sif \
    -profile use_gpu,fully_reproducible \
    -resume

Note

The pipeline is configured to use the GPU profile and ensures full reproducibility.

Troubleshooting

  • Missing T1w or DWI: The pipeline will fail immediately if these are not found in the BIDS structure.

  • Registration Failures: If the tracking results look wrong (e.g., streamlines exiting the brain), check the report.html for registration errors between T1w and DWI.

  • Job Errors: If the job fails, download the slurm-*.out and slurm-*.err logs from the tractoflow/logs directory (or temp_files if the transfer failed) and contact support.

References