Welcome to the TractoFlow user documentation!

TractoFlow pipeline is developed by the Sherbrooke Connectivity Imaging Lab (SCIL) in order to process diffusion MRI dataset from the raw data to the tractography. The pipeline is based on Nextflow and Singularity. The goal with this pipeline is to be fast and reproducible.

Before install

To run the pipeline you must install Nextflow. To use our Singularity container, you must install the Singularity package.

Nextflow

Local Computer

  1. Before installing check your current version java -version. If return something as java version "1.X" and X is 8 or later, you can skip this step else install java.
  2. Install Nextflow:
$> curl -s https://get.nextflow.io | bash && chmod +x nextflow && \
echo 'export PATH=$PATH:'$(pwd) >> ~/.bashrc && source ~/.bashrc

High Performance computer (HPC)

  1. Try module load java/1.8.0_121 or check with your administrator or on the HPC website.
  2. Use wget to install the last Nextlow edge-all release , change the name, add execution rights and add the nextflow path in the bashrc.
# Example with 19.01.0 version

$> wget https://github.com/nextflow-io/nextflow/releases/download/v19.01.0/nextflow-19.01.0-all && \
mv nextflow-19.01.0-all nextflow && \
chmod +x nextflow && echo 'export PATH=$PATH:'$(pwd) >> ~/.bashrc && source ~/.bashrc

Singularity

Our Singularity container currently works on Linux. We highly recommend to use Singularity on a Linux local computer or on a HPC.

If you want to use Docker on Windows or MacOS, please see the Docker section.

Local Computer

Install singularity-container. Our current singularity container works only on Linux. A macOS version will be released soon.

If you are Debian/Ubuntu, you can get neurodebian:

$> sudo wget -O- http://neuro.debian.net/lists/xenial.us-ca.full | sudo tee /etc/apt/sources.list.d/neurodebian.sources.list && \
sudo apt-key adv --recv-keys --keyserver hkp://pool.sks-keyservers.net:80 0xA5D32F012649A5A9 && \
sudo apt-get update && sudo apt-get install -y singularity-container

High Performance computer (HPC)

Please try module load singularity/2.6 or check with an administrator or on the HPC website.

Docker

MacOS

To install Docker on your MacOS computer, please check the following link:

https://hub.docker.com/editions/community/docker-ce-desktop-mac

Windows

To install Docker on your Windows computer, please check the following link:

https://hub.docker.com/editions/community/docker-ce-desktop-windows

Install

TractoFlow pipeline

Release

Download the last release of TractoFlow pipeline:

$> wget https://github.com/scilus/tractoflow/archive/2.0.1.zip && unzip 2.0.1.zip

For developers

Clone TractoFlow pipeline repository:

# Clone with HTTPS
$> git clone https://github.com/scilus/tractoflow.git

# Clone with SSH
$> git clone git@github.com:scilus/tractoflow.git

Singularity for TractoFlow

Release

Download the last release of the Singularity container for TractoFlow:

$> wget http://scil.usherbrooke.ca/containers_list/tractoflow_2.0.0_8b39aee_2019-04-26.img

For developers

Clone the singularity repository for TractoFlow pipeline:

# Clone with HTTPS
$> git clone https://github.com/scilus/singularity-tractoflow.git

# Clone with SSH
$> git clone git@github.com:scilus/singularity-tractoflow.git

Then, you can build the singularity image:

$> singularity build singularity_name.img singularity_tractoflow.def

Docker for TractoFlow

Release

Download the last release of the Docker container for TractoFlow:

$> wget http://scil.dinf.usherbrooke.ca/containers_list/docker_tractoflow_2.0.0_a0cacfb_2019-04-25.tar.gz

Install the Docker container:

$> docker image load -i "docker_tractoflow_2.0.0_a0cacfb_2019-04-25.tar.gz"

Processing steps

TractoFlow pipeline consist of 23 different steps : 14 steps for the diffusion weighted image (DWI) processing and 8 steps for the T1 weighted image processing.

_images/tractoflow_graph.png

Input

  • Diffusion weighted image (DWI)
  • b-values
  • b-vectors
  • T1 weighted image
  • Reverse phase encoding B0 (Optional)

DWI processes

  • Brain extraction (FSL)
  • Denoising (Mrtrix3)
  • Topup (FSL)
  • Eddy (FSL)
  • N4 bias correction (ANTs)
  • Resample (Dipy)
  • DTI metrics (Dipy)
  • fODF metrics (Dipy)

T1 processes

  • Brain extraction (ANTs)
  • Denoising (Dipy)
  • N4 bias correction (ANTs)
  • Resample (Dipy)
  • Registration (ANTs)
  • Tissue segmentation (FSL)

Tractography

The particle filter tractography is performed. Two types of seeding is available: WM-GM interface or WM mask.

Input structure

Root parameter

The input root parameter is called using --root and require the following file structure:

[root]
├── S1
│   ├── dwi.nii.gz
│   ├── bval
│   ├── bvec
│   ├── rev_b0.nii.gz  (optional)
│   └── t1.nii.gz
└── S2
    ├── dwi.nii.gz
    ├── bval
    ├── bvec
    ├── rev_b0.nii.gz  (optional)
    └── t1.nii.gz

The root folder must contains subjects folders (e.g. S1, S2,…). Each subject folder contains the required images:

  • dwi.nii.gz are the diffusion weighted images.
  • bval is the b-value file in the FSL format.
  • bvec is the b-vector file in the FSL format.
  • rev_b0.nii.gz (optional) is the reversed phase encoded b0 image also called blip-up/blip-down. Used to correct distortion due to diffusion acquisition (Documentation).
  • t1.nii.gz is the T1 weighted image.

BIDS parameter

Work in progress.

Options

To display the options of Tractoflow, please use nextflow run tractoflow/main.nf --help.

Options list

--b0_thr_extract_b0 MAX_VALUE (default: 10)
All b-values below a maximum value are considered b=0 images.
--dwi_shell_tolerance TOLERANCE (default: 20)
All b-values to +-tolerance are considered as the same b-value.
--bet_prelim_f THRESHOLD (default: 0.16)
Fractional Intensity threshold (-f for the bet FSL command) for preliminary DWI brain extraction. See FSL bet documentation for more info.
--dilate_b0_mask_prelim_brain_extraction FACTOR (default: 5)
Dilation factor to keep the whole brain and be more robust to the geometric distortions. This is only applied to the preliminary BET. Not the final extraction.
--run_dwi_denoising BOOL (default: true)
Run dwi denoising (dwidenoise from Mrtrix3). See Mrtrix3 dwidenoise documentation for more info.
--extent SIZE (default: 7)
Denoising block size. Recommended block size should follow the following rule of thumb: extent^3 >= # directions. See Mrtrix3 dwidenoise documentation for more info.
--run_topup BOOL (default: true)
Run Topup. If TractoFlow find any reversed phase encoded b=0 images. Topup will be automatically ignored. See FSL Topup documentation for more info.
--encoding_direction DIRECTION (default: y)
Encoding direction of the DWI [x, y, z]. See FSL Topup documentation for more info.
--dwell_time VALUE (default: 0.062)
Dwell-time value.
--run_eddy BOOL (default: true)
Run Eddy.
--eddy_cmd COMMAND (default: eddy_openmp)
Eddy command to use [eddy_openmp, eddy_cuda].
--bet_topup_before_eddy_f THRESHOLD (default: 0.16)
Fractional Intensity threshold (-f for the bet FSL command) for intermediate BET operation on topup corrected images.
--use_slice_drop_correction BOOL (default: true)
If set, will use the slice drop correction option (–repol) from Eddy.
--bet_dwi_final_f THRESHOLD (default: 0.16)
Fractional Intensity threshold (-f for the bet FSL command) for the final DWI BET.
--run_resample_dwi BOOL (default: true)
Run resample DWI. Resampling is done at the resolution given by –dwi_resolution option.
--dwi_resolution RESOLUTION (default: 1)
DWI resolution (in mm).
--dwi_interpolation METHOD (default: lin)
Interpolation method [nn, lin, quad, cubic].
--number_of_tissues NUMBER (default: 3)
Number of tissue classes (-n for the fast FSL command).
--fa THRESHOLD (default: 0.7)
Initial FA threshold to compute the fiber response function (FRF).
--min_fa MIN_THRESHOLD (default: 0.5)
Minimum FA threshold to compute the FRF.
--roi_radius RADIUS (default: 20)
Region of interest radius to compute the FRF. This ROI starts from the center of the 3D volume (sizeX/2, sizeY/2, sizeZ/2).
--set_frf BOOL (default: false)
Set manually the FRF.
--manual_frf FRF (default: “15,4,4”)
FRF set manually. The FRF must be at 10^-4 scaling in mm^2/s. This corresponds to an elongated symmetric diffusion tensor with eigenvalues (15, 4, 4) x 10^-4 mm^2/s along the principal axis and radial axes respectively.
--mean_frf BOOL (default: true)
Mean the frf of all subjects. USE ONLY IF ALL OF SUBJECTS COME FROM THE SAME SCANNER AND HAVE THE SAME ACQUISITION.
--sh_order ORDER (default: 8)

Spherical harmonics order.

Suggested rule of thumb :
–sh_order=8 for 45+ directions
–sh_order=6 for 20+ directions
–sh_order=4 otherwise
--basis BASIS (default: descoteaux07)
fODF spherical harmonics (SH) basis type [descoteaux07, tournier07].
--fodf_metrics_a_factor FACTOR (default: 2.0)
Multiplicative factor for AFD max in ventricles. As recommended in [Dell’Acqua et al HBM 2013].
--relative_threshold THRESHOLD (default: 0.1)
Relative threshold on fODF amplitude in ]0,1].
--max_fa_in_ventricle THRESHOLD (default: 0.1)
Maximal threshold of FA to be considered as ventricule voxel. Used to compute the ventricules mask and find the maximum fODF amplitude in the ventricules.
--min_md_in_ventricle THRESHOLD (default: 0.003)
Minimal threshold of MD in mm^2/s to be considered as ventricule voxel. Used to compute the ventricules mask and find the maximum fODF amplitude in the ventricules.
--wm_seeding BOOL (default: true)
If ‘–wm_seeding true’, use the WM-GM interface and the WM mask as seeding mask, else use the WM-GM interface as seeding mask.
--algo ALGO (default: prob)

Tracking algorithm [prob, det].

prob: streamline probabilistic.
det: streamline deterministic.
--seeding TYPE (default: npv)

Seeding type [npv, nt].

npv: number of seeds per voxel of the seeding mask
nt: total number of seeds randomly placed in the seeding mask
--nbr_seeds NUMBER (default: 10)
Number of seeds related to the seeding type param.
--random SEED (default: 0)
Random seed. Fixed for reproducible seeds
--step SIZE (default: 0.1)
Step size in mm.
--theta ANGLE (default: 20)
Maximum angle between 2 steps in degrees.
--min_len LENGTH (default: 20)
Minimum length in mm.
--max_len LENGTH (default: 200)
Maximum length in mm.
--compress_streamlines BOOL (default: true)
Compress streamlines.
--compress_value THRESHOLD (default: 0.2)
Compression error threshold in mm. See [Presseau et al Neuroimage 2015] and [Rheault et al Front Neuroinform 2017]
--template_t1 PATH (default: /human-data/mni_152_sym_09c/t1)
Path to the template T1 directory for antsBrainExtraction. The folder must contain t1_template.nii.gz and t1_brain_probability_map.nii.gz. The default path is the human_data folder in the Singularity/Docker container.
--processes_brain_extraction_t1 NUMBER (default: 4)
Number of processes for T1 brain extraction task.
--processes_denoise_dwi NUMBER (default: 4)
Number of processes for DWI denoising task.
--processes_denoise_t1 NUMBER (default: 4)
Number of processes for T1 denoising task.
--processes_eddy NUMBER (default: 1)
Number of processes for eddy task.
--processes_fodf NUMBER (default: 4)
Number of processes for fODF task.
--processes_registration NUMBER (default: 4)
Number of processes for registration task.
--output_dir PATH (default: ./results)
Directory where to write the final results.
--processes NUMBER (default: Maximum number of threads)
The number of parallel processes to launch. Only affects the local scheduler.

How to launch TractoFlow

Local computer

To run the pipeline, use the following command:

# With Singularity
$> nextflow run tractoflow/main.nf --root input_folder --dti_shells "DTI_SHELLS" --fodf_shells "FODF_SHELLS" -with-singularity singularity_name.img

# With Docker
$> nextflow run tractoflow/main.nf --root input_folder --dti_shells "DTI_SHELLS" --fodf_shells "FODF_SHELLS" -with-docker tractoflow:docker

Where DTI_SHELLS are the shells used to compute the DTI metrics (typically b-value < 1200 e.g. “0 1000”) and FODF_SHELLS are the shells used to compute the fODF metrics (typically b > 700 e.g. “0 1000 2000”).

Mounted partition

If your data is not on the same storage disk than your OS (e.g. a mounting disk, a USB stick, an external disk, …), you must bind your disk to the singularity container. Create a file (e.g. singularity.conf) and write the following line:

singularity.runOptions="--bind PATH_TO_DATA"

Where PATH_TO_DATA is the path to your storage disk.

Then run the following command:

# With Singularity
$> nextflow -c singularity.conf run tractoflow/main.nf --root input_folder --dti_shells "DTI_SHELLS" --fodf_shells "FODF_SHELLS" -with-singularity singularity_name.img

# With Docker
$> nextflow -c singularity.conf run tractoflow/main.nf --root input_folder --dti_shells "DTI_SHELLS" --fodf_shells "FODF_SHELLS" -with-docker tractoflow:docker

High Performance Computer (HPC)

The following example is based on the SLURM executor:

If you want to use only one node, please use the same commands presented for the local computer. The follwing lines must be saved in .sh file (e.g. cmd.sh) to be executed with sbatch.

#!/bin/sh

#SBATCH --nodes=1
#SBATCH --cpus-per-task=32
#SBATCH --mem=0
#SBATCH --time=48:00:00

nextflow -c singularity.conf run tractoflow/main.nf --root input_folder --dti_shells "DTI_SHELLS" --fodf_shells "FODF_SHELLS" -with-singularity singularity_name.img -resume

To launch on multiple nodes, you must to use the MPI option that use Ignite executor. The following example use 2 nodes with 32 threads on each nodes. The follwing lines must be saved in .sh file (e.g. cmd.sh) to be executed with sbatch.

#!/bin/sh

#SBATCH --nodes=2
#SBATCH --cpus-per-task=32
#SBATCH --mem=0
#SBATCH --time=48:00:00

export NXF_CLUSTER_SEED=$(shuf -i 0-16777216 -n 1)

srun nextflow -c singularity.conf run tractoflow/main.nf --root input_folder --dti_shells "DTI_SHELLS" --fodf_shells "FODF_SHELLS" -with-singularity singularity_name.img -with-mpi -resume

As a local computer, you must bind your storage disk to the singularity (Please see Mounted partition subsection above).

To launch the pipeline on the HPC:

$> sbatch cmd.sh

Results

The pipeline creates 2 folders: results and work. The files in results are symlinks in works. We highly recommend to not remove work folder.

To transfert or copy-paste the results folder, please use one of the following commands:

# On local computer
$> cp -rL results NEW_PATH/results

# On HPC
$> rsync -rL login@adress:/HPC_PATH/results NEW_PATH/results

Changelog

2.0.1

Date: 8 May 2019

Modify normalization mask and change some default option values

2.0.0

Date: 27 Mar 2019

First release for public access

Github repositories

TractoFlow pipeline repository: TractoFlow

TractoFlow Singularity repository: Singularity-TractoFlow

License

END USER LICENSE AGREEMENT

NOTICE TO USER: PLEASE READ THIS CONTRACT CAREFULLY. BY USING ALL OR ANY PORTION
OF THE APPLICATION YOU ACCEPT ALL THE TERMS AND CONDITIONS OF THIS AGREEMENT.

1. Definitions

When used in this Agreement, the following terms shall have the respective
meanings indicated, such meanings to be applicable to both the singular and
plural forms of the terms defined:

"Licensor" means Sherbrooke Connectivity Imaging Laboratory (SCIL).

"Application" means all of the contents of the files with which this Agreement
is provided, including but not limited to (i) software; (ii)
image files ("Databases").

"Use" or "Using" means to access, install, download, copy or otherwise benefit
from using the functionality of the Application.

“Licensee” means You in an academic or research context.

"Computer" means an electronic device that accepts information in digital or
similar form and manipulates it for a specific result based on a sequence of
instructions.

"Modifications" means (a) any file in the Application that results from an addition to,
deletion from, or modification of the contents; (b) any new file in the Application.

"Contribute" or "Contributor" or "Contributing" means legal entity that contributes to the
modifications of the Application.

2. Software License

As long as you comply with the terms of this End User License Agreement (the
"Agreement"), SCIL grants to you a world-wide, royalty-free and non-exclusive
license to Use the Application. Some third party materials included in the
Application may be subject to other terms and conditions, which are typically
listed in "Third party license" part.

2.1 General Use

You may install and Use the Application on your computer. You may contribute to the
Application. Contributor must respect all terms and conditions of this Agreement.

2.2 Limitations

Using or contributing the Application, (i) you might not use the application for
commercial purposes ("Commercial Use"); (ii) you must contact the SCIL for a
patent based on or using the Application.

2.3 Commercial Use

You may not use the application for commercial purposes. For commercial use,
please contact Imeka Solutions Inc. (https://www.imeka.ca/).

2.4 Third party license

Accepting this Agreement, you accept the license of the third party tools used:

FSL (https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Licence)

MRtrix3 (https://github.com/MRtrix3/mrtrix3/blob/master/LICENCE.txt)

ANTs (https://github.com/ANTsX/ANTs/blob/master/ANTSCopyright.txt)

Dipy (https://github.com/nipy/dipy/blob/master/LICENSE)

Nextflow (https://github.com/nextflow-io/nextflow/blob/master/COPYING)

Singularity (https://github.com/sylabs/singularity/blob/master/LICENSE.md)

3. Transfer

You may transfer all your rights to Use the Application
to another person or legal entity provided that: (a) you also transfer this
Agreement and the Application; (c) the receiving party accepts the terms and
conditions of this Agreement.

4. NO WARRANTY

The Software is being delivered to you "AS IS" and SCIL makes no
warranty as to its use or performance. SCIL AND ITS SUPPLIERS DO
NOT AND CANNOT WARRANT THE PERFORMANCE OR RESULTS YOU MAY OBTAIN BY USING THE
SOFTWARE. EXCEPT FOR ANY WARRANTY, CONDITION, REPRESENTATION OR TERM TO THE
EXTENT TO WHICH THE SAME CANNOT OR MAY NOT BE EXCLUDED OR LIMITED BY LAW
APPLICABLE TO YOU IN YOUR JURISDICTION, SCIL AND ITS SUPPLIERS
MAKE NO WARRANTIES, CONDITIONS, REPRESENTATIONS, OR TERMS (EXPRESS OR IMPLIED
WHETHER BY STATUTE, COMMON LAW, CUSTOM, USAGE OR OTHERWISE) AS TO ANY MATTER
INCLUDING WITHOUT LIMITATION NONINFRINGEMENT OF THIRD PARTY RIGHTS,
MERCHANTABILITY, INTEGRATION, SATISFACTORY QUALITY, OR FITNESS FOR ANY
PARTICULAR PURPOSE. FURTHERMORE, THIS SOFTWARE MAY NOT BE USED FOR MEDICAL
DIAGNOSTIC AS IT IS NOT SANCTIONNED BY AUTHORITIES SUCH AS HEALTH CANADA AND THE
FOOD AND DRUG ADMINISTRATION.

5. LIMITATION OF LIABILITY

IN NO EVENT WILL SCIL OR ITS SUPPLIERS BE LIABLE TO YOU FOR ANY
DAMAGES, CLAIMS OR COSTS WHATSOEVER OR ANY CONSEQUENTIAL, INDIRECT, INCIDENTAL
DAMAGES, OR ANY LOST PROFITS OR LOST SAVINGS, EVEN IF A SCIL
REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSS, DAMAGES, CLAIMS
OR COSTS OR FOR ANY CLAIM BY ANY THIRD PARTY. THE FOREGOING LIMITATIONS AND
EXCLUSIONS APPLY TO THE EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION.

6. Governing Law

This Agreement shall be governed by and interpreted in accordance with the laws
of the Province of Quebec, Canada.

7. General Provisions

If any part of this Agreement is found void and unenforceable, it will not
affect the validity of the balance of the Agreement, which shall remain valid
and enforceable according to its terms. This Agreement may only be
modified by a writing signed by an authorized officer of SCIL.
Updates may be licensed to you by SCIL with additional or
different terms. This is the entire agreement between SCIL and
you relating to the Application and it supersedes any prior representations,
discussions, undertakings, communications or advertising relating to the
Application.

8. Compliance with Licenses

If you have any question regarding this Agreement or if you wish to request any
information from SCIL, please use the following contact information:

Maxime Descoteaux (maxime.descoteaux@usherbrooke.ca)

References

If TractoFlow is used in a publication, please cite the following references:

[Theaud19]G Theaud, JC Houde, A Bore, F Rheault, F Morency, M Descoteaux TractoFlow: A robust, efficient and reproducible diffusion MRI pipeline leveraging Nextflow & Singularity https://www.biorxiv.org/content/10.1101/631952v1
[Kurtzer17]Kurtzer GM, Sochat V, Bauer MW Singularity: Scientific containers for mobility of compute. PLoS ONE 12(5) (2017): e0177459. https://doi.org/10.1371/journal.pone.0177459
[DiTomaso17]
  1. Di Tommaso, et al. Nextflow enables reproducible computational workflows. Nature Biotechnology 35, 316–319 (2017) doi:10.1038/nbt.3820
[Garyfallidis14]Garyfallidis, E., Brett, M., Amirbekian, B., Rokem, A., Van Der Walt, S., Descoteaux, M., Nimmo-Smith, I., 2014. Dipy, a library for the analysis of diffusion mri data. Frontiers in neuroinformatics 8, 8.
[Tournier19]Tournier, J. D., Smith, R. E., Raffelt, D. A., Tabbara, R., Dhollander, T., Pietsch, M., … & Connelly, A. (2019). MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation. bioRxiv, 551739.
[Avants09]Avants, B.B., Tustison, N., Song, G., 2009. Advanced normalization tools (ants). Insight j 2, 1–35.
[Jenkinson12]Jenkinson, M., Beckmann, C.F., Behrens, T.E., Woolrich, M.W., Smith, S.M., 2012. Fsl. Neuroimage 62, 782–790.

A NeuroImage Toolbox paper for TractoFlow is currently under review.

Download:

References Bibtex