Welcome to the TractoFlow user documentation!

Note

New release available: 2.4.2.

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.

Use TractoFlow in published works should be accompanied by the following citation:

Theaud, G., Houde, J.-C., Boré, A., Rheault, F., Morency, F., Descoteaux, M.,TractoFlow: A robust, efficient and reproducible diffusion MRI pipeline leveraging Nextflow & Singularity, NeuroImage, https://doi.org/10.1016/j.neuroimage.2020.116889.

Other citations can be added if TractoFlow is used in a publication. Please see How to cite TractoFlow

For Linux users, please see this section Singularity for TractoFlow for setup.

For MacOS users, please see this section Docker for TractoFlow for setup.

For any issues or difficulties with TractoFlow, please use our Neurostar tag: https://neurostars.org/tag/tractoflow

Tip

If you want to analyse datasets with white-matter lesions use profile ABS.

Requirements

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

Nextflow

Note that the below sections use nextflow version v19.04.0 for illustrative purposes: newer versions might work or be required depending on the pipeline at issue.

Local Computer

  1. Before installing check your current version java -version. If return something as java version "1.X" and X is 8 up to 11, you can skip this step else install java.
  2. Install Nextflow:
$> wget https://github.com/nextflow-io/nextflow/releases/download/v21.10.6/nextflow && chmod +x nextflow && \
echo 'export PATH=$PATH:'$(pwd) >> ~/.bash_profile && source ~/.bash_profile

High Performance computer (HPC)

  1. Try module load nixpkgs/16.09 module load java/1.8.0_192 or check with your administrator or on the HPC website.
  2. Use wget to install Nextflow, change the name, add execution rights and add the Nextflow path in the bash_profile.
$> wget https://github.com/nextflow-io/nextflow/releases/download/v21.10.6/nextflow-21.10.6-all && \
mv nextflow-21.10.6-all nextflow && \
chmod +x nextflow && echo 'export PATH=$PATH:'$(pwd) >> ~/.bash_profile && source ~/.bash_profile

Note that a given HPC system might offer (a) readily available nextflow version(s). If any of provided versions suffice for the pipeline at issue, the above step can be omitted, and reading the documentation of the HPC system is encouraged in order to load the suitable version. In the case of the Allianca Canada clusters, the above step might be substituted by adding the line module load nextflow/19.04.0 (depending on the desired and available versions) to the .bash_profile file and sourcing it.

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 for TractoFlow 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

Note that the first command contains the OS codename xenial (corresponding to Ubuntu 16.04) as an example; if your OS is different, you will need to retrieve the corresponding type/version from the menus in https://neuro.debian.net/index.html#get-neurodebian so that you can use the appropriate URL for the wget command.

High Performance computer (HPC)

Please try module load singularity/3.7 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

Fast Installation

Easy install method

Enter this command in your terminal (it downloads the container and TractoFlow code in the current directory - Make sure nextflow is already installed before running this command):

curl -s https://tractoflow-documentation.readthedocs.io/en/2.4.2/install.sh | bash

Detailed Installation

TractoFlow pipeline

Release

Download TractoFlow pipeline:

$> nextflow pull scilus/tractoflow

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

As a developer you will have to run tractoflow using this command:

nextflow run tractoflow/main.nf --help

Singularity for TractoFlow

Release

Download the last release of the Singularity container for TractoFlow:

$> wget https://scil.usherbrooke.ca/containers/scilus_1.5.0.sif

Or if you have sudo privileges

$> sudo singularity build scilus_1.5.0.sif docker://scilus/scilus:1.5.0

For developers

Clone the singularity repository for TractoFlow pipeline:

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

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

Then, you can build the singularity image:

$> singularity build scilus_1.5.0.sif singularity_scilus.def

Docker for TractoFlow

First, change the number of CPUs and RAM (recommended: 8 CPUs and 16Gb of RAM) in Docker (Preferences -> Advanced) and click on Apply & Restart.

Download the last release of the Docker container for TractoFlow:

$> docker pull scilus/scilus:1.5.0

Please see Profiles section to use macos profile.

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

  • Particule Filter Tractography
  • Local tracking (Optional)

The particle filter tractography is performed by default. Three types of seeding are available: WM-GM interface, WM mask or FA.

Input structure

Two types of input are available in TractoFlow: BIDS and an in-house structure.

BIDS parameter

We recommend to use dcm2bids (https://github.com/unfmontreal/Dcm2Bids) or heuviconv (https://github.com/nipy/heudiconv) to create BIDS datasets.

TractoFlow supports BIDS as input data using --bids YOUR_BIDS_DATASET. TractoFlow does some verifications before launching the processing to valide the BIDS format.

If you need to filter some subjects/sessions/runs or some files you can create a bidsignore file using --bidsignore bids_ignore_path. (Check: https://github.com/bids-standard/bids-validator#bidsignore)

In the case that some tags or informations are missing, TractoFlow will create a json file in results/Read_BIDS. Please complete missing informations and relaunch the pipeline replacing --bids YOUR_BIDS_DATASET with --bids_config results/Read_BIDS/tractoflow_bids_struct.json.

If you have a BIDS structure and want to use -profile ABS you need to use the –fs option to point to your freesurfer folder output.

If you have any problems, contact us on NeuroStar (https://neurostars.org/tag/tractoflow).

Root parameter

It is possible not to follow the BIDS format. In that case, the input root parameter is called using --input and requires the following file structure:

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

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.
  • t1.nii.gz is the T1 weighted image.
  • 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).
  • aparc+aseg.nii.gz (optional) is the freesurfer gm segmented image.
  • wmparc.nii.gz (optional) is the freesurfer wm segmented image.

Options

To display the options of Tractoflow, please use nextflow run tractoflow -r 2.4.2 --help.

Optional BIDS arguments

--bidsignore "bids_ignore_path" (default: none)
If you want to ignore some subjects/sessions/runs or some files, you can provide an extra bidsignore file. Check: https://github.com/bids-standard/bids-validator#bidsignore
-clean_bids BOOL (default: false)
If set, it will remove all the participants that are missing any information.
--fs "freesurfer_output_folder" (default: none)
If you want to run Tractoflow-ABS (Atlas Based Segmentation) combined with a BIDS structure input you need to have this argument.

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.
--readout VALUE (default: 0.062)
Readout 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.
--fa_mask_threshold THRESHOLD (default: 0.4)
FA maximum value to be considered as WM for Normalize DWI.
--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].
--max_dti_shell_value (default: 1200)
Maximum shell threshold to be consider as a DTI shell (b <= 1200). This is the default behaviour to select DTI shells.
--dti_shells
Shells selected to compute the DTI metrics (generally b <= 1200). Please write them between quotes e.g. (–dti_shells “0 300 1000”). If selected, it will overwrite max_dti_shell_value.
--min_fodf_shell_value (default: 700)
Minimum shell threshold to be consider as a fODF shell (b >= 700). This is the default behaviour to select fODF shells.
--fodf_shells
Shells selected to compute the fODF metrics (generally b >= 700). Please write them between quotes e.g. (–fodf_shells “0 1000 2000”). If selected, it will overwrite min_fodf_shell_value.
--run_t1_denoising BOOL (default: true)
Run T1 denoising using NLmean algorithm.
--run_resample_t1 BOOL (default: true)
Run resample T1. Resampling is done at the resolution given by –t1_resolution option.
--t1_resolution RESOLUTION (default: 1)
T1 resolution (in mm).
--t1_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.
--min_nvox MIN_NVOX_THRESHOLD (default: 300)
Minimum number of voxels 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.

Optional PFT Tracking arguments

--run_pft_tracking BOOL (default: true).
[PFT] Run Particle Filter Tracking (PFT)
--pft_seeding_mask_type TYPE (default: wm)
[PFT] Seeding mask type [wm, interface, fa].
--pft_fa_seeding_mask_threshold THRESHOLD (default: 0.1)
[PFT] FA threshold for FA seeding mask.
--pft_algo ALGO (default: prob)
[PFT] Tracking algorithm [prob, det].
--pft_seeding SEEDING (default: npv)
[PFT] Seeding type [npv, nt].
--pft_nbr_seeds NBRSEEDS (default: 10)
[PFT] Number of seeds related to the seeding type param.
--pft_step SIZE (default: 0.5)
[PFT] Step size.
--pft_theta ANGLE (default: 20)
[PFT] Maximum angle between 2 steps.
--pft_min_len LENGTH (default: 20)
[PFT] Minimum length.
--pft_max_len LENGTH (default: 200)
[PFT] Maximum length.
--pft_compress_streamlines BOOL (default: true)
[PFT] Compress streamlines.
--pft_compress_value THRESHOLD (default: 0.2)
[PFT] Compression error threshold. See [Presseau et al Neuroimage 2015] and [Rheault et al Front Neuroinform 2017].
--pft_random_seed RANDOMSEED (default: 0)
[PFT] List of random seed numbers for the random number generator. Please write them as list separated using commat WITHOUT SPACE e.g. (–pft_random_seed 0,1,2)

Optional Local Tracking arguments

--run_local_tracking BOOL (default: false).
[LOCAL] Run Local Tracking
--local_seeding_mask_type TYPE (default: wm)
[LOCAL] Seeding mask type [wm, interface, fa].
--local_fa_seeding_mask_threshold THRESHOLD (default: 0.1)
[LOCAL] FA threshold for FA seeding mask.
--local_algo ALGO (default: prob)
[LOCAL] Tracking algorithm [prob, det].
--local_seeding SEEDING (default: npv)
[LOCAL] Seeding type [npv, nt].
--local_nbr_seeds NBRSEEDS (default: 10)
[LOCAL] Number of seeds related to the seeding type param.
--local_step SIZE (default: 0.5)
[LOCAL] Step size.
--local_theta ANGLE (default: 20)
[LOCAL] Maximum angle between 2 steps.
--local_min_len LENGTH (default: 20)
[LOCAL] Minimum length.
--local_max_len LENGTH (default: 200)
[LOCAL] Maximum length.
--local_compress_streamlines BOOL (default: true)
[LOCAL] Compress streamlines.
--local_compress_value THRESHOLD (default: 0.2)
[LOCAL] Compression error threshold. See [Presseau et al Neuroimage 2015] and [Rheault et al Front Neuroinform 2017].
--local_random_seed RANDOMSEED (default: 0)
[LOCAL] List of random seed numbers for the random number generator. Please write them as list separated using commat WITHOUT SPACE e.g. (–local_random_seed 0,1,2)
--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.

Profiles

To select one or multiple profiles, please use the -profile option. For example:

$> nextflow run tractoflow -r 2.4.2 --input input_folder -profile macos,fully_reproducible -with-singularity singularity_name.sif -resume

Profiles available

macos
When this profile is used, TractoFlow will modify a parameter (scratch) for MacOS users.
use_cuda
When this profile is used, TractoFlow will use eddy_cuda for Eddy process. This feature is available with NVidia GPUs only. Without this profile, TractoFlow will run eddy_openmp.
fully_reproducible
When this profile is used, all the parameters will be set to have 100% reproducible results. This profile consist to set multi-thread parameters to be fully reproducible [Theaud20].
cbrain
When this profile is used, Nextflow will copy all the output files in publishDir and not use symlinks.
ABS
When this profile is used, TractoFlow-ABS (Atlas Based Segmentation) is used. This profile must be used for pathological data. The aparc+aseg.nii.gz and wmparc.nii.gz must be in the same space than t1.nii.gz
bundling
When this profile is used, it will activate custom tracking parameters to improve recobundle results.
connectomics
When this profile is used, it will activate custom tracking parameters to improve connectomics analysis.

How to launch TractoFlow

Local computer

To run the pipeline, use the following command:

# With Singularity
$> nextflow run tractoflow -r 2.4.2 --bids input_bids -with-singularity scilus_1.5.0.sif -resume
# Or
$> nextflow run tractoflow -r 2.4.2 --input input_folder -with-singularity scilus_1.5.0.sif -resume

# With Docker
$> nextflow run tractoflow -r 2.4.2 --bids input_bids -with-docker scilus/scilus:1.5.0 -resume
# Or
$> nextflow run tractoflow -r 2.4.2 --input input_folder -with-docker scilus/scilus:1.5.0 -resume

If you want to skip steps already processed by an anterior run, you can add -resume option in the command line.

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 -r 2.4.2 --input input_folder -with-singularity singularity_name.sif -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 -r 2.4.2 --input input_folder -with-singularity singularity_name.sif -with-mpi -resume

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
# Or compress before and rsync after
$> tar cvzfh /HPC_PATH/results.tar.gz /HPC_PATH/results
$> rsync login@adress:/HPC_PATH/results.tar.gz NEW_PATH/results.tar.gz

How to cite TractoFlow

Tip

If you want to analyse datasets with white-matter lesions, we highly recommends to use our devrived version of TractoFlow: TractoFlow Atlas based Segmentation (ABS) https://github.com/scilus/TractoFlow-ABS

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

[Theaud20]Theaud, G., Houde, J.-C., Boré, A., Rheault, F., Morency, F., Descoteaux, M.,TractoFlow: A robust, efficient and reproducible diffusion MRI pipeline leveraging Nextflow & Singularity, NeuroImage, https://doi.org/10.1016/j.neuroimage.2020.116889.
[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.

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

[Theaud20]Theaud, G., Houde, J.-C., Boré, A., Rheault, F., Morency, F., Descoteaux, M.,TractoFlow: A robust, efficient and reproducible diffusion MRI pipeline leveraging Nextflow & Singularity, NeuroImage, https://doi.org/10.1016/j.neuroimage.2020.116889.
[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

Download:

References Bibtex

Contact

For any issues, difficulties or questions about TractoFlow please use our Neurostar tag: https://neurostars.org/tag/tractoflow

Changelog

2.4.2

Date: March 2023

New features
  • Tractoflow is not fully working with a python 3.10 environnment with scilpy 1.5.0

2.4.1

Date: November 2022

New features
  • Automatic extraction of shells when computing DTI and fODF
  • Skip step bet_prelim_dwi when not needed
  • Add remove_invalid step in Tracking processes
  • Add possibility for complex BIDS structure with multiband acquisition and full reverse encoding acquisitions. (only available with cuda profile)
  • New profile “bundling”. It will activate custom tracking parameters to improve recobundle results. Local tracking will be enable with fa seeding mask and tracking mask.
  • New profile “connectomics”. It will activate custom tracking parameters to improve connectomics analysis.

2.3.0

Date: 05 April 2022

New features
  • New profile Atlas Based Segmentation (-profile ABS)
  • New profile “skip preprocessing” for HCP dataset (-profile skip_preprocessing)
  • Add option to compute dwi sh (-sh_fitting true)
  • Gibbs correction (-run_gibbs_correction true)

2.2.1

Date: 09 April 2021

Bug Fixed:
  • fully reproducible (ANTS_RANDOM_SEED fixed)
  • Tracking with FA (typo)
New options:
  • participants_label: select specific subjects (BIDS input)
  • clean_bids: remove subject that are not complete (BIDS input)

2.1.1

Date: 08 Jul 2020

New features:

  • Support 4D reverse B0 images.

2.1.0

Date: 29 Jun 2020

New features:

  • BIDS support
  • Partitions (External drive, etc) automatically mounted. No supplementary config file needed
  • New processing profiles: use_cuda (for eddy_cuda use), fully_reproducible, macos

New options:

  • run_t1_denoising: Activate or deactivate T1 denoising

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 Containers repository: Containers-Scilus

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)