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

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.
PREPROCESS T1 (preproc_t1, nf-neuro) Preprocess the T1 image including brain extraction, NL-Means denoising, bias field correction and resampling.
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.
SEGMENTATION (anatomical_segmentation, nf-neuro) Segment the T1 image into white matter, gray matter and CSF, in diffusion space.
DTI FITTING (dipy) Fit the diffusion tensor model on the preprocessed DWI image and extract relevant metrics.
FRF ESTIMATION (scilpy) Estimate the Fiber Response Function (FRF) from the preprocessed DWI image.
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.
PFT TRACKING (dipy) Perform Particle Filtering Tractography (PFT) on the FODF to generate whole brain tractograms.
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

	Type	Description	Mandatory
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_lesion_mask	file	The input channel containing the lesion mask for segmentation. Structure: `[ val(meta), path(lesion_mask) ]`	False

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)

	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
preproc_dwi_run_denoising	boolean	Enable MP-PCA denoising of the DWI image.	True
dwi_denoise_patch_size	integer	Patch size for MP-PCA denoising algorithm.	7
preproc_dwi_run_degibbs	boolean	Enable Gibbs ringing removal correction.	False
topup_eddy_run_topup	boolean	Enable TOPUP correction for susceptibility distortions.	True
dwi_topup_config_file	string	Configuration file for TOPUP processing (e.g., “b02b0.cnf”).	b02b0.cnf
topup_eddy_run_eddy	boolean	Enable EDDY correction for motion and eddy currents.	True
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
preproc_dwi_run_N4	boolean	Enable N4 bias field correction for DWI image.	True
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
preproc_dwi_run_resampling	boolean	Enable resampling of the DWI image to isotropic resolution.	True
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
frf_average_from_data	boolean	Average fiber response functions across all subjects.	False
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
run_qball	boolean	Enable Q-Ball modeling.	False
use_qball_for_tracking	boolean	Use Q-Ball model for tractography instead of fODFs.	False
run_pft	boolean	Enable Particle Filtering Tractography.	True
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
run_local_tracking	boolean	Enable Local Tractography.	True
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

@AlexVCaron

Maintainers

@AlexVCaron

Last updated : 2025-12-22