sdcflows.transform module

The \(B_0\) unwarping transform formalism.

class sdcflows.transform.B0FieldTransform(coeffs=None, xfm=<nitransforms.linear.Affine object>)[source]

Bases: object

Represents and applies the transform to correct for susceptibility distortions.

apply(spatialimage, pe_dir, ro_time, order=3, mode='constant', cval=0.0, prefilter=True, output_dtype=None)[source]

Apply a transformation to an image, resampling on the reference spatial object.

Parameters

  • spatialimage (spatialimage) – The image object containing the data to be resampled in reference space

  • reference (spatial object, optional) – The image, surface, or combination thereof containing the coordinates of samples that will be sampled.

  • order (int, optional) – The order of the spline interpolation, default is 3. The order has to be in the range 0-5.

  • mode ({‘constant’, ‘reflect’, ‘nearest’, ‘mirror’, ‘wrap’}, optional) – Determines how the input image is extended when the resamplings overflows a border. Default is ‘constant’.

  • cval (float, optional) – Constant value for mode='constant'. Default is 0.0.

  • prefilter (bool, optional) – Determines if the image’s data array is prefiltered with a spline filter before interpolation. The default is True, which will create a temporary float64 array of filtered values if order > 1. If setting this to False, the output will be slightly blurred if order > 1, unless the input is prefiltered, i.e. it is the result of calling the spline filter on the original input.

Returns

resampled – The data imaged after resampling to reference space.

Return type

spatialimage or ndarray

coeffs
fit(spatialimage)[source]

Generate the interpolation matrix (and the VSM with it).

Implements Eq. \(\eqref{eq:1}\), interpolating \(f(\mathbf{s})\) for all voxels in the target-image’s extent.

Returns

updated – True if the internal field representation was fit, False if cache was valid and will be reused.

Return type

bool

shifts
to_displacements(ro_time, pe_dir, itk_format=True)[source]

Generate a NIfTI file containing a displacements field transform compatible with ITK/ANTs.

The displacements field can be calculated following Eq. (2) in the fieldmap fitting section.

Parameters

  • ro_time (float) – The total readout time in seconds (only if vsm=False).

  • pe_dir (str) – The PhaseEncodingDirection metadata value (only if vsm=False).

Returns

spatialimage – A NIfTI 1.0 object containing the distortion.

Return type

nibabel.nifti.Nifti1Image

xfm
sdcflows.transform.disp_to_fmap(xyz_nii, ro_time, pe_dir, itk_format=True)[source]

Convert a displacements field into a fieldmap in Hz.

This is the inverse operation to the previous function.

Parameters

  • xyz_nii (os.pathlike) – Path to a displacements field in NIfTI format.

  • ro_time (float) – The total readout time in seconds.

  • pe_dir (str) – The PhaseEncodingDirection metadata value.

Returns

spatialimage – A NIfTI 1.0 object containing the field in Hz.

Return type

nibabel.nifti.Nifti1Image

sdcflows.transform.fmap_to_disp(fmap_nii, ro_time, pe_dir, itk_format=True)[source]

Convert a fieldmap in Hz into an ITK/ANTs-compatible displacements field.

The displacements field can be calculated following Eq. (2) in the fieldmap fitting section.

Parameters

  • fmap_nii (os.pathlike) – Path to a voxel-shift-map (VSM) in NIfTI format

  • ro_time (float) – The total readout time in seconds

  • pe_dir (str) – The PhaseEncodingDirection metadata value

Returns

spatialimage – A NIfTI 1.0 object containing the distortion.

Return type

nibabel.nifti.Nifti1Image

sdcflows.transform.grid_bspline_weights(target_nii, ctrl_nii)[source]

Evaluate tensor-product B-Spline weights on a grid.

For each of the N input samples \((s_1, s_2, s_3)\) and K control points or knots \(\mathbf{k} =(k_1, k_2, k_3)\), the tensor-product cubic B-Spline kernel weights are calculated:

\[\Psi^3(\mathbf{k}, \mathbf{s}) = \beta^3(s_1 - k_1) \cdot \beta^3(s_2 - k_2) \cdot \beta^3(s_3 - k_3), \label{eq:2}\tag{2}\]

where each \(\beta^3\) represents the cubic B-Spline for one dimension. The 1D B-Spline kernel implementation uses numpy.piecewise, and is based on the closed-form given by Eq. (6) of [Unser1999].

By iterating over dimensions, the data samples that fall outside of the compact support of the tensor-product kernel associated to each control point can be filtered out and dismissed to lighten computation.

Finally, the resulting weights matrix \(\Psi^3(\mathbf{k}, \mathbf{s})\) can be easily identified in Eq. \(\eqref{eq:1}\) and used as the design matrix for approximation of data.

Parameters

  • target_nii (nibabel.spatialimages) – An spatial image object (typically, a Nifti1Image) embedding the target EPI image to be corrected. Provides the location of the N samples (total number of voxels) in the space.

  • ctrl_nii (nibabel.spatialimages) – An spatial image object (typically, a Nifti1Image) embedding the location of the control points of the B-Spline grid. The data array should contain a total of \(K\) knots (control points).

Returns

weights – A sparse matrix of interpolating weights \(\Psi^3(\mathbf{k}, \mathbf{s})\) for the N voxels of the target EPI, for each of the total K knots. This sparse matrix can be directly used as design matrix for the fitting step of approximation/extrapolation.

Return type

numpy.ndarray (\(K \times N\))