preproc_n4

Perform N4 bias field correction on either an anatomical image or a diffusion volume. For diffusion volumes, the module automatically derives the bspline parameter, number of stages, and iteration pyramid based on the image resolution and size. The formula used are as follows: For the BSpline parameter: BSplineParam = 2 ** (NbStages - 1) * NbVoxelsBetweenKnots * ShrinkFactor * ImageResolution For the number of stages in the iteration pyramid: If SmallestDimension ≤ NbVoxelsBetweenKnots * ShrinkFactor: NbStages = 1 Else: NbStages = ceil( log2(SmallestDimension / (NbVoxelsBetweenKnots * ShrinkFactor)) ) For the iteration pyramid: Slope = (MinIter - MaxIter) / (1 - Retain) Intercept = MaxIter - Slope * Retain For i in linspace(0, 1, NbStages): If i < Retain: Iteration = MaxIter Else: Iteration = round(Slope * i + Intercept) The default values for the shrink_factor and nb_voxels_between_knots are set to 4 and 8, respectively, which are suitable for most diffusion and anatomical volumes from a large age range of subjects and species. For a human T1w image of 1 mm isotropic resolution and a size of 193x229x193, a typical N4 call (with automatically derived parameters) would look like this:

N4BiasFieldCorrection -i T1w.nii.gz \
  -o [output__image_n4.nii.gz, bias_field.nii.gz] \
  -c [1000x1000x850x100, 1e-6] \
  -b [256, 3] \
  -s 4

For more information on how this formula was derived, please view those references: [1] N4 Wiki: https://github.com/ANTsX/ANTs/wiki/N4BiasFieldCorrection [2] Tustison, N. J., Avants, B. B., Cook, P. A., Zheng, Y., Egan, A., Yushkevich, P. A., & Gee, J. C. (2010). N4ITK: Improved N3 Bias Correction. IEEE Transactions on Medical Imaging, 29(6), 1310–1320. https://doi.org/10.1109/TMI.2010.2046908 [3] Valcourt Caron, A., Shmuel, A., Hao, Z., & Descoteaux, M. (2023). versaFlow: A versatile pipeline for resolution adapted diffusion MRI processing and its application to studying the variability of the PRIME-DE database. Frontiers in Neuroinformatics, Volume 17-2023. https://doi.org/10.3389/fninf.2023.1191200

Keywords : correction, N4, bias field

---

Inputs

Input 1

Format : tuple val(meta), path(image), path(bval), path(bvec), path(mask)

	Type	Description	Mandatory	Pattern
meta	map	Groovy Map containing sample information e.g. [ id:'test', single_end:false ]	True
image	file	Nifti image file to correct	True	*.{nii,nii.gz}
bval	file	B-value file for the diffusion image	False	*.bval
bvec	file	B-vector file for the diffusion image	False	*.bvec
mask	file	Nifti image file mask for the reference	False	*.{nii,nii.gz}

---

Outputs

image

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

	Type	Description	Mandatory	Pattern
meta	map	Groovy Map containing sample information e.g. [ id:'test', single_end:false ]	True
*__image_n4.nii.gz	file	N4 corrected image	True	*__image_n4.{nii,nii.gz}

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
prefix	string	Prefix to add to the output file name (e.g. “n4_“)
b0threshold	integer	Threshold for the b0 volume to be used as a mask.	10
nb_voxels_between_knots	integer	Number of voxels between B-spline knots.	8
shrink_factor	integer	Shrink factor for the image resampling.	4
maxiter	integer	Maximum number of iterations for the N4 algorithm.	1000
miniter	integer	Minimum number of iterations for the N4 algorithm.	100
retain	number	Ratio of stages for which the number of iterations is fixed to the maximum iterations defined.	0.6

---

Tools

	Description	DOI
scilpy	The Sherbrooke Connectivity Imaging Lab (SCIL) Python dMRI processing toolbox.

---

Authors

• @arnaudbore

---

Last updated : 2025-10-30