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)])

  • debug (a boolean) – Generate extra assets for debugging. (Nipype default value: False)

  • 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)

  • zooms_min (a float or a legal value) – Limit minimum image zooms, set 0.0 to use the original image. (Nipype default value: 4.0)

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. All the director cosines of the output coefficients will be positive. In other words, the output orientation is either RAS, ARS, ASR, SAR, or SRA.

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.

  • pe_dir (‘i’ or ‘i-’ or ‘j’ or ‘j-’ or ‘k’ or ‘k-’ or ‘x’ or ‘x-’ or ‘y’ or ‘y-’ or ‘z’ or ‘z-’) – Phase encoding direction.

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.

Optional Inputs

fmap_target (a pathlike object or string representing an existing file) – The distorted EPI target (feed to set debug mode on).

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.