preproc_topup

Run magnetic susceptibility distortions correction using FSL Topup. The module can take either b0 or DWI volumes. The latter activates b0 extraction prior to running Topup. Extraction can be configured to take one (default) or many b0 volumes in each forward and reverse acquired DWI and perform averaging if needed. Note that running Topup with more than one volume per encoding direction greatly increases computation time.

Keywords : DWI, distorsion, topup

---

Inputs

Input 1

Format : tuple val(meta), path(dwi), path(bval), path(bvec), path(b0), path(rev_dwi), path(rev_bval), path(rev_bvec), path(rev_b0)

	Type	Description	Mandatory	Pattern
meta	map	Groovy Map containing sample information e.g. [ id:'test', single_end:false ]	True
dwi	file	DWI Nifti image	True	*.{nii,nii.gz}
bval	file	B-values in FSL format [DWI].	True	*.bval
bvec	file	B-values in FSL format [DWI].	True	*.bvec
b0	file	b0 [DWI].	True	*.bvec
rev_dwi	file	DWI Nifti image [rev-DWI].	True	*.{nii,nii.gz}
rev_bval	file	B-values in FSL format [rev-DWI].	True	*.bval
rev_bvec	file	B-vectors in FSL format [rev-DWI].	True	*.bvec
rev_b0	file	Reversed b0 [rev-DWI].	True	*.{nii,nii.gz}

Input 2

Format : path(config_topup)

	Type	Description	Mandatory	Pattern
config_topup	file	topup config file. See https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup/TopupUsersGuide#Configuration_files	True	*cnf

---

Outputs

topup_corrected_b0s

Format : tuple val(meta), path(*__corrected_b0s.nii.gz)

	Type	Description	Mandatory	Pattern
meta	map	Groovy Map containing sample information e.g. [ id:'test', single_end:false ]	True
*__corrected_b0s.nii.gz	file	Nifti volume - b0 corrected	True	*__corrected_b0s.nii.gz

topup_fieldcoef

Format : tuple val(meta), path(*_fieldcoef.nii.gz)

	Type	Description	Mandatory	Pattern
meta	map	Groovy Map containing sample information e.g. [ id:'test', single_end:false ]	True
*_fieldcoef.nii.gz	file	Nifti volume - topup field to correct for distorsion	True	*_fieldcoef.nii.gz

topup_movpart

Format : tuple val(meta), path(*_movpar.txt)

	Type	Description	Mandatory	Pattern
meta	map	Groovy Map containing sample information e.g. [ id:'test', single_end:false ]	True
*_movpar.txt	file	Text file - topup movpart	True	*_movpar.txt

rev_b0_warped

Format : tuple val(meta), path(*__rev_b0_warped.nii.gz)

	Type	Description	Mandatory	Pattern
meta	map	Groovy Map containing sample information e.g. [ id:'test', single_end:false ]	True
*__rev_b0_warped.nii.gz	file	Nifti volume - rev b0 warped on b0	True	*__rev_b0_warped.nii.gz

rev_b0_mean

Format : tuple val(meta), path(*__rev_b0_mean.nii.gz)

	Type	Description	Mandatory	Pattern
meta	map	Groovy Map containing sample information e.g. [ id:'test', single_end:false ]	True
*__rev_b0_mean.nii.gz	file	Nifti volume - rev b0 mean	True	*__rev_b0_mean.nii.gz

b0_mean

Format : tuple val(meta), path(*__b0_mean.nii.gz)

	Type	Description	Mandatory	Pattern
meta	map	Groovy Map containing sample information e.g. [ id:'test', single_end:false ]	True
*__b0_mean.nii.gz	file	Nifti volume - b0 mean	True	*__b0_mean.nii.gz

mqc

Format : tuple val(meta), path(*_b0_topup_mqc.gif)

	Type	Description	Mandatory	Pattern
meta	map	Groovy Map containing sample information e.g. [ id:'test', single_end:false ]	True
*_b0_topup_mqc.gif	file	.gif file containing quality control image for the topup process (Comparison with dwi and rev_dwi). Made for use in MultiQC report.	True	*_b0_topup_mqc.gif

versions

Format : path(versions.yml)

	Type	Description	Mandatory	Pattern
versions.yml	file	File containing software versions.	True	versions.yml

---

Arguments (see process.ext)

	Type	Description	Default	Choices
encoding	string	Encoding direction of the forward DWI.	y	- x - y - z
readout	float	Total readout time from the DICOM metadata.	0.062
b0_thr_extract_b0	integer	Threshold under which b-values are considered to be b0s.	10
prefix_topup	string	Prefix to prepend to Topup output files.
default_config_topup	string	Default Topup configuration to use.	b02b0.cnf	- b02b0.cnf - b02b0_1.cnf - b02b0_2.cnf - b02b0_4.cnf - b02b0_7T.cnf
run_qc	boolean	Run quality control.	True

---

Tools

	Description	DOI
ANTs	Advanced Normalization Tools (ANTs) for image processing.	10.1038/s41598-021-87564-6
FSL	FSL Toolbox	10.1016/j.neuroimage.2011.09.015
scilpy	The Sherbrooke Connectivity Imaging Lab (SCIL) Python dMRI processing toolbox.

---

Authors

• @arnaudbore

---

Last updated : 2025-10-20