nifreeze.data.dmri.utils module

Utilities for handling diffusion gradient tables.

nifreeze.data.dmri.utils.DEFAULT_GRADIENT_ATOL = 0.01

Absolute dissimmilarity tolerance to trigger b-vector normalization.

nifreeze.data.dmri.utils.DEFAULT_HIGHB_THRESHOLD = 8000

A b-value cap for DWI data.

nifreeze.data.dmri.utils.DEFAULT_LOWB_THRESHOLD = 50

The lower bound for the b-value so that the orientation is considered a DW volume.

nifreeze.data.dmri.utils.DEFAULT_MAX_S0 = 1.0

Maximum value when considering the \(S_{0}\) DWI signal.

nifreeze.data.dmri.utils.DEFAULT_MIN_S0 = 1e-05

Minimum value when considering the \(S_{0}\) DWI signal.

nifreeze.data.dmri.utils.DEFAULT_MULTISHELL_BIN_COUNT_THR = 7

Default bin count to consider a multishell scheme.

nifreeze.data.dmri.utils.DEFAULT_NUM_BINS = 15

Number of bins to classify b-values.

nifreeze.data.dmri.utils.DTI_MIN_ORIENTATIONS = 6

Minimum number of nonzero b-values in a DWI dataset.

nifreeze.data.dmri.utils.GRADIENT_ABSENCE_ERROR_MSG = 'No gradient table was provided.'

Gradient absence error message.

nifreeze.data.dmri.utils.GRADIENT_EXPECTED_COLUMNS_ERROR_MSG = 'Gradient table must have four columns (3 direction components and one b-value).'

dMRI gradient expected columns error message.

nifreeze.data.dmri.utils.GRADIENT_NDIM_ERROR_MSG = 'Gradient table must be a 2D array'

dMRI gradient dimensionality error message.

nifreeze.data.dmri.utils.GRADIENT_OBJECT_ERROR_MSG = 'Gradient table must be a numeric homogeneous array-like object'

Gradient object error message.

nifreeze.data.dmri.utils.GRADIENT_VOLUME_DIMENSIONALITY_MISMATCH_ERROR = 'Gradient table shape does not match the number of diffusion volumes: expected {n_volumes} rows, found {n_gradients}.'

dMRI volume count vs. gradient count mismatch error message.

nifreeze.data.dmri.utils.find_shelling_scheme(bvals: ndarray, num_bins: int = 15, multishell_nonempty_bin_count_thr: int = 7, bval_cap: float = 8000) → tuple[str, list[ndarray[tuple[Any, ...], dtype[floating]]], list[floating]][source]

Find the shelling scheme on the given b-values.

Computes the histogram of the b-values according to num_bins and depending on the nonempty bin count, classify the shelling scheme as single-shell if they are 2 (low-b and a shell); multi-shell if they are below the multishell_nonempty_bin_count_thr value; and DSI otherwise.

Parameters:

  • bvals (list or ndarray) – List or array of b-values.

  • num_bins (int, optional) – Number of bins.

  • multishell_nonempty_bin_count_thr (int, optional) – Bin count to consider a multi-shell scheme.

  • bval_cap (float, optional) – Maximum b-value to be considered in a multi-shell scheme.

Returns:

  • scheme (str) – Shelling scheme.

  • bval_groups (list) – List of grouped b-values.

  • bval_estimated (list) – List of ‘estimated’ b-values as the median value of each b-value group.

nifreeze.data.dmri.utils.format_gradients(value: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None, norm_atol: float = 0.01, skip_normalization: bool = False) → ndarray | None[source]

Validate and orient gradient tables to row-major convention.

Parameters:

  • value (ArrayLike) – The value to format.

  • norm_atol (float, optional) – Absolute tolerance to consider a b-vector as unitary or b=0.

  • skip_normalization (bool, optional) – If True, skip b-vector normalization.

Returns:

Row-major convention gradient table.

Return type:

ndarray

:raises exc:ValueError: If value is not a 2D ndarray (value.ndim != 2).

Examples

Passing an already well-formed table returns the data unchanged:

>>> format_gradients(
...     [
...         [1, 0, 0, 0],
...         [0, 1, 0, 1000],
...         [0, 0, 1, 2000],
...         [0, 0, 0, 0],
...         [0, 0, 0, 1000],
...     ]
... )
array([[   1,    0,    0,    0],
       [   0,    1,    0, 1000],
       [   0,    0,    1, 2000],
       [   0,    0,    0,    0],
       [   0,    0,    0,    0]], dtype=int16)

Column-major inputs are automatically transposed when an expected number of diffusion volumes is provided:

>>> format_gradients(
...     [[1, 0], [0, 1], [0, 0], [1000, 2000]],
... )
array([[   1,    0,    0, 1000],
       [   0,    1,    0, 2000]], dtype=int16)

Oversized b-vectors are normalized and the b-value is scaled accordingly:

>>> format_gradients([[2.0, 0.0, 0.0, 1000]])
array([[1.e+00, 0.e+00, 0.e+00, 2.e+03]])

Near-zero b-vectors are suppressed to treat them as b0 measurements:

>>> format_gradients([[1e-9, 0.0, 0.0, 1200], [1.0, 0.0, 0.0, 1000]])
array([[   0,    0,    0,    0],
       [   1,    0,    0, 1000]], dtype=int16)

Normaliztion can be skipped:

>>> format_gradients([[2.0, 0.0, 0.0, 1000]], skip_normalization=True)
array([[   2,    0,    0, 1000]], dtype=int16)

Integer-like inputs are preserved when no rescaling is needed:

>>> import numpy as np
>>> format_gradients(np.array([[0, 0, 0, 0], [0, 0, 1, 1000]], dtype=np.int16)).dtype
dtype('int16')

Passing None raises the absence error:

>>> format_gradients(None)
Traceback (most recent call last):
...
ValueError: No gradient table was provided.

Gradient tables must always have two dimensions:

>>> format_gradients([0, 1, 0, 1000])
Traceback (most recent call last):
...
ValueError: Gradient table must be a 2D array

Gradient tables must have a regular shape:

>>> format_gradients([[1, 2], [3, 4, 5]])
Traceback (most recent call last):
...
TypeError: Gradient table must be a numeric homogeneous array-like object

Gradient tables must always have two dimensions:

>>> format_gradients([0, 1, 0, 1000])
Traceback (most recent call last):
...
ValueError: Gradient table must be a 2D array
nifreeze.data.dmri.utils.transform_fsl_bvec(b_ijk: ndarray, xfm: ndarray, imaffine: ndarray, invert: bool = False) → ndarray[source]

Transform a b-vector from the original space to the new space defined by the affine.

Parameters:

  • b_ijk (ndarray) – The b-vector in FSL/DIPY conventions (i.e., voxel coordinates).

  • xfm (ndarray) – The affine transformation to apply. Please note that this is the inverse of the head-motion-correction affine, which maps coordinates from the realigned space to the moved (scan) space. In this case, we want to move the b-vector from the moved (scan) space into the realigned space.

  • imaffine (ndarray) – The image’s affine, to convert.

  • invert (bool, optional) – If True, the transformation will be inverted.

Returns:

The transformed b-vector in voxel coordinates (FSL/DIPY).

Return type:

ndarray