sdcflows.interfaces.bspline module

Filtering of \(B_0\) field mappings with B-Splines.

class sdcflows.interfaces.bspline.ApplyCoeffsField(from_file=None, resource_monitor=None, **inputs)[source]

Bases: nipype.interfaces.base.core.SimpleInterface

Convert a set of B-Spline coefficients to a full displacements map.

Mandatory Inputs

in_coeff (a list of items which are a pathlike object or string representing an existing file) – Input coefficients, after alignment to the EPI data.

Optional Inputs

  • in_data (a list of items which are a pathlike object or string representing a file)

  • in_xfms (a list of items which are a pathlike object or string representing an existing file) – List of head-motion correction matrices.

  • num_threads (an integer) – Number of threads.

  • pe_dir (a list of items which are ‘i’ or ‘i-’ or ‘j’ or ‘j-’ or ‘k’ or ‘k-’)

  • ro_time (a list of items which are a float)

Outputs

  • out_corrected (a list of items which are a pathlike object or string representing an existing file)

  • out_field (a list of items which are a pathlike object or string representing an existing file)

  • out_warp (a list of items which are a pathlike object or string representing an existing file)

class sdcflows.interfaces.bspline.BSplineApprox(from_file=None, resource_monitor=None, **inputs)[source]

Bases: nipype.interfaces.base.core.SimpleInterface

Approximate the \(B_0\) field using tensor-product B-Splines.

The approximation effectively smooths the data, removing spikes and other sources of noise, as well as enables the extrapolation of the \(B_0\) field beyond the brain mask, which alleviates boundary effects in correction.

This interface resolves the optimization problem of obtaining the B-Spline coefficients \(c(\mathbf{k})\) that best approximate the data samples within the brain mask \(f(\mathbf{s})\), following Eq. (17) – in that case for 2D – of [Unser1999]. Here, and adapted to 3D:

\[f(\mathbf{s}) = \sum_{k_1} \sum_{k_2} \sum_{k_3} c(\mathbf{k}) \Psi^3(\mathbf{k}, \mathbf{s}). \label{eq:1}\tag{1}\]

References

Unser1999

M. Unser, “Splines: A Perfect Fit for Signal and Image Processing,” IEEE Signal Processing Magazine 16(6):22-38, 1999.

See also

bspline_weights() - for Eq. \(\eqref{eq:2}\) and the evaluation of the tri-cubic B-Splines \(\Psi^3(\mathbf{k}, \mathbf{s})\).

Mandatory Inputs

in_data (a pathlike object or string representing an existing file) – Path to a fieldmap.

Optional Inputs

  • bs_spacing (a list of items which are a tuple of the form: (a float, a float, a float)) – Spacing between B-Spline control points. (Nipype default value: [(40.0, 40.0, 20.0)])

  • extrapolate (a boolean) – Generate a field, extrapolated outside the brain mask. (Nipype default value: True)

  • in_mask (a pathlike object or string representing an existing file) – Path to a brain mask.

  • recenter (‘mode’ or ‘median’ or ‘mean’ or False) – Strategy to recenter the distribution of the input fieldmap. (Nipype default value: mode)

  • ridge_alpha (a float) – Controls the regularization. (Nipype default value: 0.01)

Outputs

  • out_coeff (a list of items which are a pathlike object or string representing an existing file)

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

  • out_extrapolated (a pathlike object or string representing a file)

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

class sdcflows.interfaces.bspline.TOPUPCoeffReorient(from_file=None, resource_monitor=None, **inputs)[source]

Bases: nipype.interfaces.base.core.SimpleInterface

Revise the orientation of TOPUP-generated B-Spline coefficients.

TOPUP-generated “fieldcoeff” files are just B-Spline fields, where the shape of the field is fixated to be a decimated grid of the original image by an integer factor and added 3 pixels on each dimension. This is one root reason why TOPUP errors (FSL 6) or segfaults (FSL 5), when the input image has odd number of voxels along one or more directions.

These “fieldcoeff” are fixated to be zero-centered, and have “plumb” orientation (as in, aligned with cardinal/imaging axes). The q-form of these NIfTI files is always diagonal, with the decimation factors set on the diagonal (and hence, the voxel zooms). The origin of the q-form is set to the reference image’s shape.

This interface modifies these coefficient files to be fully-fledged NIfTI images aligned with the reference image. Therefore, the s-form header of the coefficients file is updated to match that of the reference file. The s-form header is used because the imaging axes may be oblique.

The q-form retains the original header and is marked with code 0.

Mandatory Inputs

  • fmap_ref (a pathlike object or string representing an existing file) – The fieldmap reference.

  • in_coeff (a list of items which are a pathlike object or string representing a file) – Input coefficients file(s) from TOPUP.

Optional Inputs

pe_dir (‘+’ or ‘-’ or ‘i’ or ‘i-’ or ‘j’ or ‘j-’ or ‘k’ or ‘k-’) – The polarity of the phase-encoding direction corresponding to fmap_ref. (Nipype default value: +)

Outputs

out_coeff (a list of items which are a pathlike object or string representing an existing file) – Patched coefficients.

class sdcflows.interfaces.bspline.TransformCoefficients(from_file=None, resource_monitor=None, **inputs)[source]

Bases: nipype.interfaces.base.core.SimpleInterface

Project coefficients files to another space through a rigid-body transform.

Mandatory Inputs

  • fmap_ref (a pathlike object or string representing an existing file) – The fieldmap reference.

  • in_coeff (a list of items which are a pathlike object or string representing a file) – Input coefficients file(s).

  • transform (a pathlike object or string representing an existing file) – Rigid-body transform file.

Outputs

out_coeff (a list of items which are a pathlike object or string representing an existing file) – Moved coefficients.

sdcflows.interfaces.bspline.bspline_grid(img, control_zooms_mm=(40.0, 40.0, 20.0))[source]

Create a Nifti1Image embedding the location of control points.