nifreeze.data.dmri.base module

DWI data representation type.

nifreeze.data.dmri.base.BZERO_SHAPE_MISMATCH_ERROR_MSG = "DWI 'bzero' shape ({bzero_shape}) does not match dataset volumes ({data_shape}). If you have multiple b0 volumes, either provide one of them or provide a single, representative b0."

DWI bzero shape mismatch error message.

class nifreeze.data.dmri.base.DWI(self, dataobj: 'np.ndarray' = None, affine: 'np.ndarray' = None, brainmask: 'np.ndarray | None' = None, motion_affines: 'np.ndarray | None' = None, datahdr: 'nb.Nifti1Header | None' = None, filepath: 'Path' = NOTHING, gradients: 'npt.ArrayLike | None' = None, bzero: 'np.ndarray | None' = None, eddy_xfms: 'list' = None) → None[source]

Bases: BaseDataset[ndarray]

Data representation structure for dMRI data.

Method generated by attrs for class DWI.

property bvals
property bvecs
bzero: np.ndarray | None

A b=0 reference map, computed automatically when low-b frames are present.

eddy_xfms: list

List of transforms to correct for estimated eddy current distortions.

classmethod from_filename(filename: Path | str) → Self[source]

Read an HDF5 file from disk and create a DWI object.

Parameters:

filename (os.pathlike) – The HDF5 file path to read.

Returns:

The constructed dataset with data loaded from the file.

Return type:

DWI

get_shells(num_bins: int = 15, multishell_nonempty_bin_count_thr: int = 7, bval_cap: int = 8000) → list[source]

Get the shell data according to the b-value groups.

Bin the shell data according to the b-value groups found by find_shelling_scheme.

Parameters:

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

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

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

Returns:

Tuples of binned b-values and corresponding data/gradients indices.

Return type:

list

gradients: np.ndarray

A 2D numpy array of the gradient table (N orientations x C components).

to_filename(filename: Path | str, compression: str | None = None, compression_opts: Any = None) → None[source]

Write the dMRI dataset to an HDF5 file on disk.

Parameters:

  • filename (os.pathlike) – The HDF5 file path to write to.

  • compression (str, optional) – Compression strategy. See create_dataset documentation.

  • compression_opts (Any, optional) – Parameters for compression filters.

to_nifti(filename: Path | str | None = None, write_hmxfms: bool = False, order: int = 3, insert_b0: bool = False, bvals_dec_places: int = 2, bvecs_dec_places: int = 6) → nibabel.nifti1.Nifti1Image[source]

Export the dMRI object to disk (NIfTI, b-vecs, & b-vals files).

Parameters:

  • filename (os.pathlike, optional) – The output NIfTI file path.

  • write_hmxfms (bool, optional) – If True, the head motion affines will be written out to filesystem with BIDS’ X5 format.

  • order (int, optional) – The interpolation order to use when resampling the data. Defaults to 3 (cubic interpolation).

  • insert_b0 (bool, optional) – Insert a \(b=0\) at the front of the output NIfTI and add the corresponding null gradient value to the output bval/bvec files.

  • bvals_dec_places (int, optional) – Decimal places to use when serializing b-values.

  • bvecs_dec_places (int, optional) – Decimal places to use when serializing b-vectors.

Returns:

NIfTI image written to disk.

Return type:

Nifti1Image

nifreeze.data.dmri.base.DWI_B0_MULTIPLE_VOLUMES_WARN_MSG = 'The DWI data contains multiple b0 volumes; computing median across them.'

DWI bzero shape mismatch warning message.

nifreeze.data.dmri.base.DWI_REDUNDANT_B0_WARN_MSG = 'The DWI data contains b0 volumes, but the \'bzero\' attribute was set. DWI b0 "\nvolumes will be discarded, and the corresponding \'dataobj\' and \'gradient\' data removed.'

DWI b0 and bzero provided warning message.

nifreeze.data.dmri.base.validate_gradients(inst: DWI, attr: Attribute, value: ndarray[tuple[Any, ...], dtype[floating]]) → None[source]

Strict validator for use in attribute validation (e.g. attrs / validators).

Ensures row-major convention for gradient table.

This function is intended for use as an attrs-style validator.

Parameters:

  • inst (DWI) – The instance being validated (unused; present for validator signature).

  • attr (Attribute) – The attribute being validated; attr.name is used in the error message.

  • value (NDArray) – The value to validate.

Raises:

ValueError – If the gradient table is invalid.

Examples

Non-row-major inputs are rejected::
>>> validate_gradients(None, None, [[0.0, 0.0], [0.0, 1000]])
Traceback (most recent call last):
...
ValueError: Gradient table must have four columns (3 direction components and one b-value).

Non-finite inputs are rejected:

>>> validate_gradients(None, None, [[np.inf, 0.0, 0.0, 1000]])
Traceback (most recent call last):
...
ValueError: Gradient table contains NaN or infinite values.
>>> validate_gradients(None, None, [[np.nan, 0.0, 0.0, 1000]])
Traceback (most recent call last):
...
ValueError: Gradient table contains NaN or infinite values.