tractoflow
This subworkflow implements the TractoFlow [1] pipeline. It can process raw diffusion and T1 weighted image to reduce acquisition biases, align anatomical and diffusion space, compute DTI and fODF metrics and generate whole brain tractograms.
---------- Configuration ----------
- nextflow.config : contains an example configuration for the subworkflow. Imports modules.config.
- modules.config : contains the bindings to the modules parameters and some defaults making it Tractoflow.
-------------- Steps --------------
1. PREPROCESS DWI (preproc_dwi, nf-neuro)
Preprocess the DWI image including brain extraction, MP-PCA denoising, eddy current and motion correction, N4 bias correction, normalization and resampling.
2. PREPROCESS T1 (preproc_t1, nf-neuro)
Preprocess the T1 image including brain extraction, NL-Means denoising, bias field correction and resampling.
3. T1 REGISTRATION (anatomical_registration, nf-neuro)
Register the T1 image to the DWI image, using the b0 and the FA map as target for the diffusion space.
4. SEGMENTATION (anatomical_segmentation, nf-neuro)
Segment the T1 image into white matter, gray matter and CSF, in diffusion space.
5. DTI FITTING (dipy)
Fit the diffusion tensor model on the preprocessed DWI image and extract relevant metrics.
6. FRF ESTIMATION (scilpy)
Estimate the Fiber Response Function (FRF) from the preprocessed DWI image.
7. FODF FITTING (dipy)
Fit the Fiber Orientation Distribution Function (fODF), using Single or Multi Shell, Single or Multi Tissues models, on the preprocessed DWI image and extract relevant metrics.
8. PFT TRACKING (dipy)
Perform Particle Filtering Tractography (PFT) on the FODF to generate whole brain tractograms.
9. LOCAL TRACKING (dipy on CPU, scilpy on GPU)
Perform Local Tracking on the FODF to generate whole brain tractograms.
[1] https://tractoflow-documentation.readthedocs.io
Keywords : diffusion, MRI, end-to-end, tractography, preprocessing, fodf, dti
Components : anatomical_segmentation, preproc_dwi, preproc_t1, registration, reconst/dtimetrics, reconst/frf, reconst/fodf, reconst/qball, reconst/meanfrf, registration/antsapplytransforms, tracking/localtracking, tracking/pfttracking
Inputs
Section titled “Inputs”| Type | Description | Mandatory | Pattern | |
|---|---|---|---|---|
| ch_dwi | file | The input channel containing the DWI file, B-values and B-vectors in FSL format files. Structure: [ val(meta), path(dwi), path(bval), path(bvec) ] | True | |
| ch_t1 | file | The input channel containing the anatomical T1 weighted image. Structure: [ val(meta), path(t1) ] | True | |
| ch_sbref | file | The input channel containing the single-band b0 reference for the DWI. Structure: [ val(meta), path(rev_b0) ] | False | |
| ch_rev_dwi | file | The input channel containing the reverse DWI file, B-values and B-vectors in FSL format files. Structure: [ val(meta), path(rev_dwi), path(bval), path(bvec) ] | False | |
| ch_rev_sbref | file | The input channel containing the reverse b0 file. Structure: [ val(meta), path(rev_b0) ] | False | |
| ch_aparc_aseg | file | The input channel containing freesurfer brain segmentation and gray matter parcellation (aparc+aseg). Must be supplied with ch_wm_parc. When supplied, those are used to generate tissues masks and probability maps. Structure: [ val(meta), path(aparc_aseg) ] | False | |
| ch_wm_parc | file | The input channel containing freesurfer white matter parcellations (wmparc). Must be supplied with ch_aparc_aseg. When supplied, those are used to generate tissues masks and probability maps. Structure: [ val(meta), path(wmparc) ] | False | |
| ch_topup_config | file | The input channel containing the config file for Topup. This input is optional. See https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup/TopupUsersGuide#Configuration_files. Structure: [ path(config_file) ] | False | |
| ch_bet_template | file | The input channel containing the anatomical template for antsBET. Structure: [ val(meta), path(bet_template) ] | False | |
| ch_bet_probability_map | file | The input channel containing the brain probability mask for antsBET, with intensity range 1 (definitely brain) to 0 (definitely background). Structure: [ val(meta), path(probability_map) ] | False | |
| ch_synthstrip_weights | file | The input channel containing the SynthStrip model weights for brain extraction. Structure: [ val(meta), path(synthstrip_weights) ] or [ path(synthstrip_weights) ] | False | |
| ch_lesion_mask | file | The input channel containing the lesion mask for segmentation. Structure: [ val(meta), path(lesion_mask) ] | False | |
| options | map | Map of options for the subworkflow. - preproc_dwi_run_denoising (bool): If ‘true’, the DWI will be denoised using the MPPCA method from MRtrix3. - preproc_dwi_run_degibbs (bool): If ‘true’, the Gibbs artifact removal will be performed using the mrdegibbs method from MRtrix3. - topup_eddy_run_topup (bool): If ‘true’, the Topup correction will be performed using FSL’s Topup. - topup_eddy_run_eddy (bool): If ‘true’, the Eddy correction will be performed using FSL’s Eddy. - preproc_dwi_run_synthstrip (bool): If ‘true’, the brain extraction will be performed using SynthStrip. If ‘false’, FSL’s BET will be used. - preproc_dwi_keep_dwi_with_skull (bool): If ‘true’, the DWI before brain extraction will be kept and used for the following steps. If ‘false’, the DWI after brain extraction will be used for the following steps. - preproc_dwi_run_N4 (bool): If ‘true’, the N4 bias field correction will be performed using ANTs’ N4BiasFieldCorrection. - preproc_dwi_run_normalize (bool): If ‘true’, the DWI will be normalized to have a mean value in the WM of approximately 1000 using MRtrix3’s dwinormalise. - preproc_dwi_run_resampling (bool): If ‘true’, the DWI will be resampled to 1 mm isotropic spatial resolution using DIPY’s resample. - preproc_t1_run_denoising (bool): If ‘true’, the anatomical image will be denoised using the nlmeans method from scilpy. - preproc_t1_run_N4 (bool): If ‘true’, the N4 bias field correction will be performed using the N4BiasFieldCorrection method from ANTs. - preproc_t1_run_resample (bool): If ‘true’, the anatomical image will be resampled using the resample method from DIPY. - preproc_t1_run_synthstrip (bool): If ‘true’, the subworkflow will use SynthStrip for brain extraction. - preproc_t1_run_ants_bet (bool): If ‘true’, the subworkflow will use ANTs’ BET for brain extraction. - preproc_t1_run_crop (bool): If ‘true’, the subworkflow will crop the image after brain extraction. - frf_average_from_data (bool): If ‘true’, the fiber response function will be averaged across all subjects. If ‘false’, the fiber response function will be estimated for each subject independently. - run_qball (bool): If ‘true’, the Q-Ball model will be fitted on the DWI data and used for fODF reconstruction and tracking. - use_qball_for_tracking (bool): If ‘true’, the Q-Ball model will be used for tractography instead of the fODF model. This option is only relevant if run_qball is ‘true’. - run_pft_tracking (bool): If ‘true’, Particle Filtering Tractography (PFT) will be performed using DIPY. - run_local_tracking (bool): If ‘true’, Local Tracking will be performed. | True |
Outputs
Section titled “Outputs”| Type | Description | Mandatory | Pattern | |
|---|---|---|---|---|
| dwi | file | Preprocessed DWI image. Structure: [ val(meta), path(dwi), path(bval), path(bvec) ] | True | |
| t1 | file | T1 image warped to the DWI space. Structure: [ val(meta), path(t1) ] | True | |
| wm_mask | file | White matter mask. Structure: [ val(meta), path(wm_mask) ] | True | |
| gm_mask | file | Gray matter mask. Structure: [ val(meta), path(gm_mask) ] | True | |
| csf_mask | file | Cerebrospinal fluid mask. Structure: [ val(meta), path(csf_mask) ] | True | |
| wm_map | file | White matter probability map. Structure: [ val(meta), path(wm_map) ] | True | |
| gm_map | file | Gray matter probability map. Structure: [ val(meta), path(gm_map) ] | True | |
| csf_map | file | Cerebrospinal fluid probability map. Structure: [ val(meta), path(csf_map) ] | True | |
| aparc_aseg | file | Freesurfer brain segmentation and gray matter parcellation (aparc+aseg) in diffusion space. Only available if ch_aparc_aseg is provided in inputs. Structure: [ val(meta), path(aparc_aseg) ] | False | |
| wmparc | file | Freesurfer white matter parcellations (wmparc) in diffusion space. Only available if ch_wm_parc is provided in inputs. Structure: [ val(meta), path(wmparc) ] | False | |
| anatomical_to_diffusion | file | Transformation matrix from the anatomical space to the diffusion space. Structure: [ val(meta), [path(warp), path(affine)] ] | True | |
| diffusion_to_anatomical | file | Transformation matrix from the diffusion space to the anatomical space. Structure: [ val(meta), [path(affine), path(warp)] ] | True | |
| t1_native | file | Preprocessed T1 in anatomical space. Structure: [ val(meta), path(t1) ] | True | |
| dti_tensor | file | 4-D Diffusion tensor image, with 6 components in the last dimensions, ordered by FSL convention (row-major : Dxx, Dxy, Dxz, Dyy, Dyz, Dzz). Structure: [ val(meta), path(dti_tensor) ] | True | |
| dti_md | file | Mean diffusivity map. Structure: [ val(meta), path(dti_md) ] | True | |
| dti_rd | file | Radial diffusivity map. Structure: [ val(meta), path(dti_rd) ] | True | |
| dti_ad | file | Axial diffusivity map. Structure: [ val(meta), path(dti_ad) ] | True | |
| dti_fa | file | Fractional anisotropy map. Structure: [ val(meta), path(dti_fa) ] | True | |
| dti_rgb | file | RGB map of the diffusion tensor. Structure: [ val(meta), path(dti_rgb) ] | True | |
| dti_peaks | file | Principal direction of the diffusion tensor. Structure: [ val(meta), path(dti_peaks) ] | True | |
| dti_evecs | file | Eigenvectors of the diffusion tensor, ordered by eigenvalue. Structure: [ val(meta), path(dti_evecs) ] | True | |
| dti_evals | file | Eigenvalues of the diffusion tensor. Structure: [ val(meta), path(dti_evals) ] | True | |
| dti_residual | file | Residuals of the diffusion tensor fitting. Structure: [ val(meta), path(dti_residual) ] | True | |
| dti_ga | file | Generalized anisotropy map. Structure: [ val(meta), path(dti_ga) ] | True | |
| dti_mode | file | Mode of the diffusion tensor. Structure: [ val(meta), path(dti_mode) ] | True | |
| dti_norm | file | Norm of the diffusion tensor. Structure: [ val(meta), path(dti_norm) ] | True | |
| fiber_response | file | Fiber Response Function (FRF) estimated from the DWI image. If using Single Tissue If using Multi Tissues Structure: [ val(meta), path(wm_fiber_response), path(gm_fiber_response), path(csf_fiber_response) ] Structure: [ val(meta), path(fiber_response) ] | True | |
| fodf | file | Fiber Orientation Distribution Function (fODF) estimated from the DWI image. If using Single Tissue If using Multi Tissues Structure: [ val(meta), path(wm_fodf), path(gm_fodf), path(csf_fodf) ] Structure: [ val(meta), path(fodf) ] | True | |
| fodf_rgb | file | RGB map of the fODF, normalized by volume fraction of WM. Structure: [ val(meta), path(fodf_rgb) ] | True | |
| fodf_peaks | file | Peaks of the fODF. Structure: [ val(meta), path(fodf_peaks) ] | True | |
| afd_max | file | Maximum Apparent Fiber Density (AFD) map. Structure: [ val(meta), path(afd_max) ] | True | |
| afd_total | file | Total Apparent Fiber Density (AFD) map. Structure: [ val(meta), path(afd_total) ] | True | |
| afd_sum | file | Sum of Apparent Fiber Density (AFD) map. Structure: [ val(meta), path(afd_sum) ] | True | |
| nufo | file | Number of Unique Fibers Orientations (NUFO) map. Structure: [ val(meta), path(nufo) ] | True | |
| volume_fraction | file | Tissues volume fraction map. Structure: [ val(meta), path(volume_fraction) ] | True | |
| qball | file | Qball spherical harmonics coefficients. Structure: [ val(meta), path(qball) ] | False | |
| qball_a_power | file | Anisotropic power map. Structure: [ val(meta), path(qball_a_power) ] | False | |
| qball_peaks | file | Extracted peaks from Qball model. Structure: [ val(meta), path(qball_peaks) ] | False | |
| qball_peaks_indices | file | Generated peaks indices on the sphere from Qball model. Structure: [ val(meta), path(qball_peak_indices) ] | False | |
| qball_gfa | file | Generalized fractional anisotropy. Structure: [ val(meta), path(qball_gfa) ] | False | |
| qball_nufo | file | NUFO map from Qball model. Structure: [ val(meta), path(qball_nufo) ] | False | |
| pft_tractogram | file | Whole brain tractogram generated with Particle Filtering Tractography (PFT). Structure: [ val(meta), path(pft_tractogram) ] | False | |
| pft_config | file | Configuration file used for Particle Filtering Tractography (PFT). Structure: [ val(meta), path(pft_config) ] | False | |
| pft_map_include | file | Include map used for Particle Filtering Tractography (PFT). Structure: [ val(meta), path(pft_map_include) ] | False | |
| pft_map_exclude | file | Exclude map used for Particle Filtering Tractography (PFT). Structure: [ val(meta), path(pft_map_exclude) ] | False | |
| pft_seeding_mask | file | Seeding mask used for Particle Filtering Tractography (PFT). Structure: [ val(meta), path(pft_seeding_mask) ] | False | |
| local_tractogram | file | Whole brain tractogram generated with Local Tracking. Structure: [ val(meta), path(local_tractogram) ] | False | |
| local_config | file | Configuration file used for Local Tracking. Structure: [ val(meta), path(local_config) ] | False | |
| local_seeding_mask | file | Seeding mask used for Local Tracking. Structure: [ val(meta), path(local_seeding_mask) ] | False | |
| local_tracking_mask | file | Tracking mask used for Local Tracking. Structure: [ val(meta), path(local_tracking_mask) ] | False | |
| mqc | file | QC files (png, gif, etc.) generated by all modules that can be leveraged in a subject-level MultiQC report. Structure: [ val(meta), path(*mqc.*) ] | False | |
| global_mqc | file | QC files (txt, npy, etc.) generated by all modules that can be leveraged in a global-level MultiQC report (all subjects). Structure: [ val(meta), path(*mqc.*) ] | False | |
| versions | file | File containing software versions Structure: [ path(versions.yml) ] | True | versions.yml |
Parameters (see configuration)
Section titled “Parameters (see configuration)”| Type | Description | Default | Choices | |
|---|---|---|---|---|
| b0_max_threshold | float | Maximum b-value threshold to consider as b0 volumes. | 10 | |
| bvalue_tolerance | float | Tolerance for b-value shell extraction and processing. | 20 | |
| dwi_signal_sh_fit | boolean | Enable spherical harmonics fitting of the DWI signal. | True | |
| dwi_signal_sh_fit_order | integer | Spherical harmonics order for DWI signal fitting. | 6 | |
| dwi_signal_sh_fit_basis | string | Spherical harmonics basis for DWI signal fitting. | descoteaux07 | - descoteaux07 - descoteaux07_legacy - tournier07 - tournier07_legacy |
| dwi_signal_sh_fit_shell | boolean | Fit spherical harmonics on specific shell instead of all shells. | False | |
| dwi_denoise_patch_size | integer | Patch size for MP-PCA denoising algorithm. | 7 | |
| dwi_topup_config_file | string | Configuration file for TOPUP processing (e.g., “b02b0.cnf”). | b02b0.cnf | |
| dwi_eddy_executable | string | EDDY executable to use (e.g., “eddy_cpu” or “eddy_cuda10.2”). | eddy_cpu | - eddy_cpu - eddy_cuda10.2 |
| dwi_eddy_restore_slices | boolean | Enable slice-wise outlier detection and replacement in EDDY. | True | |
| preproc_t1_run_denoising | boolean | Enable NL-Means denoising of the T1 image. | True | |
| preproc_t1_run_N4 | boolean | Enable N4 bias field correction for T1 image. | True | |
| preproc_t1_run_synthstrip | boolean | Enable SynthStrip brain extraction for T1 image. | False | |
| preproc_t1_run_ants_bet | boolean | Enable ANTs-based brain extraction for T1 image. | True | |
| preproc_t1_run_crop | boolean | Enable cropping of the T1 image to remove padding. | True | |
| preproc_t1_run_resampling | boolean | Enable resampling of the T1 image to isotropic resolution. | True | |
| t1_resample_resolution_mm_iso | integer | Isotropic resolution in mm for T1 resampling. | 1 | |
| t1_resample_interpolation | string | Interpolation method for T1 resampling (e.g., “lin”, “cubic”). | lin | - nn - lin - quad - cubic |
| dwi_n4_knot_interval | integer | Number of voxels between splines’ knots for DWI N4 bias correction. | 1 | |
| dwi_n4_subsampling | integer | Subsampling factor for DWI N4 bias correction. | 2 | |
| dwi_resample_resolution_mm_iso | integer | Isotropic resolution in mm for DWI resampling. | 1 | |
| dwi_resample_interpolation | string | Interpolation method for DWI resampling (e.g., “lin”, “cubic”). | lin | - nn - lin - quad - cubic |
| dti_max_bvalue | integer | Maximum b-value to consider for DTI shell extraction. | 1200 | |
| dti_shells_to_fit | string | Specific shells to use for DTI fitting (e.g., “0,1000” for b-values). | None | |
| fodf_min_bvalue | integer | Minimum b-value to consider for fODF shell extraction. | 700 | |
| fodf_shells_to_fit | string | Specific shells to use for fODF fitting (e.g., “0,1000,2000” for b-values). | None | |
| frf_fa_max_threshold | float | Maximum FA threshold for fiber response function estimation. | 0.7 | |
| frf_fa_min_threshold | float | Minimum FA threshold for fiber response function estimation. | 0.5 | |
| frf_min_n_voxels | integer | Minimum number of voxels required for FRF estimation. | 300 | |
| frf_roi_radius | integer | ROI radius in mm for fiber response function estimation. | 20 | |
| frf_value_to_force | string | Force specific FRF values instead of estimation (e.g., “15,4,4” for eigenvalues). | None | |
| fodf_sh_order | integer | Spherical harmonics order for fODF reconstruction (must be even). | 8 | |
| fodf_sh_basis | string | Spherical harmonics basis for fODF reconstruction. | descoteaux07 | - descoteaux07 - descoteaux07_legacy - tournier07 - tournier07_legacy |
| fodf_peaks_absolute_factor | float | Absolute threshold factor for fODF peak extraction. | 2.0 | |
| fodf_peaks_relative_threshold | float | Relative threshold for fODF peak extraction. | 0.1 | |
| fodf_peaks_ventricle_max_fa | float | Maximum FA value for ventricle mask creation. | 0.1 | |
| fodf_peaks_ventricle_min_md | float | Minimum MD value for ventricle mask creation. | 0.003 | |
| pft_random_seed | integer | Random seed for PFT tractography reproducibility. | 0 | |
| pft_algorithm | string | Algorithm to use for PFT tractography (e.g., “prob”, “det”). | prob | - prob - det |
| pft_step_mm | float | Step size in mm for PFT tractography. | 0.5 | |
| pft_theta_max_deviation | integer | Maximum angular deviation in degrees for PFT tracking. | 20 | |
| pft_min_streamline_length | integer | Minimum streamline length in mm for PFT tracking. | 20 | |
| pft_max_streamline_length | integer | Maximum streamline length in mm for PFT tracking. | 200 | |
| pft_seeding_type | string | Tissue type for PFT seeding mask generation (e.g., “wm”, “fa”). | wm | - wm - interface - fa |
| pft_seeding_strategy | string | Seeding strategy for PFT tractography (e.g., “npv”, “nt”). | npv | - npv - nt |
| pft_number_of_seeds | integer | Number of seeds per voxel - npv (or total - nt) for PFT tracking. | 10 | |
| pft_fa_min_threshold | float | Minimum FA threshold for PFT tracking. | 0.1 | |
| pft_number_of_particles | integer | Number of particles for PFT algorithm. | 15 | |
| pft_backward_step_mm | integer | Backward step size in mm for PFT tracking. | 2 | |
| pft_forward_step_mm | integer | Forward step size in mm for PFT tracking. | 1 | |
| pft_compression_step_mm | float | Compression step size in mm for PFT streamlines. | 0.2 | |
| lt_processor | string | Processor type for local tracking (e.g., “cpu”, “gpu”). | cpu | - cpu - gpu |
| lt_gpu_batch_size | integer | Batch size for GPU-based local tracking. | 10000 | |
| lt_random_seed | integer | Random seed for local tracking reproducibility. | 0 | |
| lt_algorithm | string | Algorithm to use for local tractography (e.g., “prob”, “det”). | prob | - prob - det - ptt - eudx |
| lt_step_mm | float | Step size in mm for local tracking. | 0.5 | |
| lt_theta_max_deviation | integer | Maximum angular deviation in degrees for local tracking. | 20 | |
| lt_min_streamline_length | integer | Minimum streamline length in mm for local tracking. | 20 | |
| lt_max_streamline_length | integer | Maximum streamline length in mm for local tracking. | 200 | |
| lt_seeding_type | string | Tissue type for local tracking seeding mask generation (e.g., “wm”, “fa”). | wm | - wm - fa |
| lt_seeding_strategy | string | Seeding strategy for local tractography (e.g., “npv”, “nt”). | npv | - npv - nt |
| lt_number_of_seeds | integer | Number of seeds per voxel for local tracking. | 10 | |
| lt_fa_min_threshold_for_seeding | float | Minimum FA threshold for local tracking seeding mask. | 0.1 | |
| lt_tracking_type | string | Tissue type for local tracking mask generation (e.g., “wm”, “fa”). | wm | - wm - fa |
| lt_fa_min_threshold_for_tracking | float | Minimum FA threshold for local tracking mask. | 0.1 | |
| lt_compression_step_mm | float | Compression step size in mm for local tracking streamlines. | 0.2 |
Authors
Section titled “Authors”Maintainers
Section titled “Maintainers”Last updated : 2026-02-12