nifreeze.data.dmri.base module

DWI data representation type.

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 (typing.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.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.

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.