tractoflow

Subworkflow: 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. └── modules.config : contains the bindings to the modules parameters and some defaults making it Tractoflow.

  i.e: nextflow.config import modules.config -------------- 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

---

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) ]
ch_t1	file	The input channel containing the anatomical T1 weighted image. Structure: [ val(meta), path(t1) ]
ch_sbref	file	(Optional) The input channel containing the single-band b0 reference for the DWI. Structure: [ val(meta), path(rev_b0) ]
ch_rev_dwi	file	(Optional) 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) ]
ch_rev_sbref	file	(Optional) The input channel containing the reverse b0 file. Structure: [ val(meta), path(rev_b0) ]
ch_aparc_aseg	file	(Optional) 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) ]
ch_wm_parc	file	(Optional) 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) ]
ch_topup_config	file	(Optional) 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) ]
ch_bet_template	file	(Optional) The input channel containing the anatomical template for antsBET. Structure: [ val(meta), path(bet_template) ]
ch_bet_probability_map	file	(Optional) 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) ]
ch_lesion_mask	file	(Optional) The input channel containing the lesion mask for segmentation. Structure: [ val(meta), path(lesion_mask) ]

Outputs

	Type	Description	Pattern
dwi	file	Preprocessed DWI image. Structure: [ val(meta), path(dwi), path(bval), path(bvec) ]
t1	file	T1 image warped to the DWI space. Structure: [ val(meta), path(t1) ]
wm_mask	file	White matter mask. Structure: [ val(meta), path(wm_mask) ]
gm_mask	file	Gray matter mask. Structure: [ val(meta), path(gm_mask) ]
csf_mask	file	Cerebrospinal fluid mask. Structure: [ val(meta), path(csf_mask) ]
wm_map	file	White matter probability map. Structure: [ val(meta), path(wm_map) ]
gm_map	file	Gray matter probability map. Structure: [ val(meta), path(gm_map) ]
csf_map	file	Cerebrospinal fluid probability map. Structure: [ val(meta), path(csf_map) ]
aparc_aseg	file	(Optional) 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) ]
wmparc	file	(Optional) Freesurfer white matter parcellations (wmparc) in diffusion space. Only available if ch_wm_parc is provided in inputs. Structure: [ val(meta), path(wmparc) ]
anatomical_to_diffusion	file	Transformation matrix from the anatomical space to the diffusion space. Structure: [ val(meta), [path(warp), path(affine)] ]
diffusion_to_anatomical	file	Transformation matrix from the diffusion space to the anatomical space. Structure: [ val(meta), [path(affine), path(warp)] ]
t1_native	file	Preprocessed T1 in anatomical space. Structure: [ val(meta), path(t1) ]
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) ]
dti_md	file	Mean diffusivity map. Structure: [ val(meta), path(dti_md) ]
dti_rd	file	Radial diffusivity map. Structure: [ val(meta), path(dti_rd) ]
dti_ad	file	Axial diffusivity map. Structure: [ val(meta), path(dti_ad) ]
dti_fa	file	Fractional anisotropy map. Structure: [ val(meta), path(dti_fa) ]
dti_rgb	file	RGB map of the diffusion tensor. Structure: [ val(meta), path(dti_rgb) ]
dti_peaks	file	Principal direction of the diffusion tensor. Structure: [ val(meta), path(dti_peaks) ]
dti_evecs	file	Eigenvectors of the diffusion tensor, ordered by eigenvalue. Structure: [ val(meta), path(dti_evecs) ]
dti_evals	file	Eigenvalues of the diffusion tensor. Structure: [ val(meta), path(dti_evals) ]
dti_residual	file	Residuals of the diffusion tensor fitting. Structure: [ val(meta), path(dti_residual) ]
dti_ga	file	Generalized anisotropy map. Structure: [ val(meta), path(dti_ga) ]
dti_mode	file	Mode of the diffusion tensor. Structure: [ val(meta), path(dti_mode) ]
dti_norm	file	Norm of the diffusion tensor. Structure: [ val(meta), path(dti_norm) ]
fiber_response	file	Fiber Response Function (FRF) estimated from the DWI image. If using Single Tissue Structure: [ val(meta), path(fiber_response) ] If using Multi Tissues Structure: [ val(meta), path(wm_fiber_response), path(gm_fiber_response), path(csf_fiber_response) ]
fodf	file	Fiber Orientation Distribution Function (fODF) estimated from the DWI image. If using Single Tissue Structure: [ val(meta), path(fodf) ] If using Multi Tissues Structure: [ val(meta), path(wm_fodf), path(gm_fodf), path(csf_fodf) ]
fodf_rgb	file	RGB map of the fODF, normalized by volume fraction of WM. Structure: [ val(meta), path(fodf_rgb) ]
fodf_peaks	file	Peaks of the fODF. Structure: [ val(meta), path(fodf_peaks) ]
afd_max	file	Maximum Apparent Fiber Density (AFD) map. Structure: [ val(meta), path(afd_max) ]
afd_total	file	Total Apparent Fiber Density (AFD) map. Structure: [ val(meta), path(afd_total) ]
afd_sum	file	Sum of Apparent Fiber Density (AFD) map. Structure: [ val(meta), path(afd_sum) ]
nufo	file	Number of Unique Fibers Orientations (NUFO) map. Structure: [ val(meta), path(nufo) ]
volume_fraction	file	Tissues volume fraction map. Structure: [ val(meta), path(volume_fraction) ]
pft_tractogram	file	Whole brain tractogram generated with Particle Filtering Tractography (PFT). Structure: [ val(meta), path(pft_tractogram) ]
pft_config	file	Configuration file used for Particle Filtering Tractography (PFT). Structure: [ val(meta), path(pft_config) ]
pft_map_include	file	Include map used for Particle Filtering Tractography (PFT). Structure: [ val(meta), path(pft_map_include) ]
pft_map_exclude	file	Exclude map used for Particle Filtering Tractography (PFT). Structure: [ val(meta), path(pft_map_exclude) ]
pft_seeding_mask	file	Seeding mask used for Particle Filtering Tractography (PFT).
local_tractogram	file	Whole brain tractogram generated with Local Tracking. Structure: [ val(meta), path(local_tractogram) ]
local_config	file	Configuration file used for Local Tracking. Structure: [ val(meta), path(local_config) ]
local_seeding_mask	file	Seeding mask used for Local Tracking. Structure: [ val(meta), path(local_seeding_mask) ]
local_tracking_mask	file	Tracking mask used for Local Tracking. Structure: [ val(meta), path(local_tracking_mask) ]
versions	file	File containing software versions Structure: [ path(versions.yml) ]	versions.yml

Parameters (see parameters)

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

---

Components

• anatomical_segmentation
• preproc_dwi
• preproc_t1
• registration
• reconst/dtimetrics
• reconst/frf
• reconst/fodf
• reconst/meanfrf
• registration/antsapplytransforms
• tracking/localtracking
• tracking/pfttracking

---

Authors

@AlexVCaron

Maintainers

@AlexVCaron

---

Last updated : 2025-07-15