n4

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

	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

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

---

Tools

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

---

Authors

arnaudbore

---

Last updated : 2025-07-15