qsiprep.interfaces.bias module

Keep N4’s bias-field fit from being dragged around by dark voxels.

dwibiascorrect ants hands the brain mask to N4 as a weight image (-w, never -x – see mrtrix3/dwibiascorrect/ants.py). That weight is binary, so every voxel inside the mask counts equally in a least-squares fit performed on log intensities – and the near-zero voxels a b=0 EPI always contains (susceptibility dropout, the ragged mask edge) become enormous negative outliers there, which can make the fit diverge.

This dampens the weights rather than shrinking the mask, so the correction is still applied everywhere the mask covers; only the influence of unreliable voxels on the fit is reduced.

class qsiprep.interfaces.bias.N4WeightMask(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Zero out near-background voxels in a mask destined for N4 -w.

Mandatory Inputs:

  • bval_file (a pathlike object or string representing an existing file) – Bvals for dwi_file.

  • dwi_file (a pathlike object or string representing an existing file) – 4D DWI series.

  • mask_file (a pathlike object or string representing an existing file) – Brain mask to condition.

Optional Inputs:

  • b0_threshold (an integer) – (Nipype default value: 100)

  • background_factor (a float) – Drop in-mask voxels dimmer than this multiple of the background mean. (Nipype default value: 2.0)

  • min_retained (a float) – Never discard more than this fraction of the mask; bail out instead. (Nipype default value: 0.5)

  • out_file (a pathlike object or string representing a file) – (Nipype default value: n4_weights.nii.gz)

Outputs:

  • fraction_dropped (a float)

  • n_dropped (an integer)

  • out_file (a pathlike object or string representing an existing file)