nifreeze.data.dmri package

dMRI data representation

This submodule implements data structures and I/O utilities for diffusion MRI data. Please, beware that NiFreeze is very opinionated about the gradients and diffusion data representation.

Gradient Table Representation. The DWI class represents diffusion MRI data must be provided a gradient table, which is a numpy.ndarray of shape (N, 4), where N is the number of diffusion-weighted volumes. The first three columns represent the gradient directions (b-vectors), and the fourth column represents the b-values in s/mm². NiFreeze expects that the gradient directions are normalized to unit length for non-zero b-values, and that the \(b=0\) volumes have a gradient direction of \((0, 0, 0)\). When non-unit b-vectors are detected, the corresponding b-value is automatically adjusted to reflect the actual diffusion weighting. If the input gradient table does not conform to these expectations, it will be automatically corrected upon loading. This means that, if you need to prepare the gradient table in a specific way (e.g., you don’t want normalization of b-vectors to modify the b-values), you should do so before initializing the DWI object.

Data Representation. The DWI class requires a dataobj that can be an array-like object. The final step of the initialization process examines the data object and the gradient table, and removes \(b=0\) volumes from the data AND the gradient table. If a bzero parameter is provided, the bzero attribute is set to its value. Note that a 3D volume is accepted. If no bzero parameter is provided, a reference low-b volume is computed as the median of all the low-b volumes (b < DEFAULT_LOWB_THRESHOLD s/mm²) and inserted in the bzero attribute. If \(b=0\) values are detected in the gradient table the dataobj and gradients attributes will have their \(b=0\) indices data removed. If both a bzero value is provided and \(b=0\) values are detected in the gradient table, the :math:`b=0 volumes will be discarded, and the corresponding dataobj and gradients indices data will be removed. Therefore, *NiFreeze* WILL NOT be able to reconstruct the original data organization. This design choice simplifies the internal representation and processing of diffusion MRI data. If you want to calculate a \(b=0\) reference map in a more sophisticated way (e.g., after realignment of all the low-b volumes), you should handle this separately and feed your own reference through the bzero parameter.

class nifreeze.data.dmri.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.from_nii(filename: Path | str, brainmask_file: Path | str | None = None, gradients_file: Path | str | None = None, bvec_file: Path | str | None = None, bval_file: Path | str | None = None, b0_file: Path | str | None = None) → DWI[source]

Load DWI data from NIfTI and construct a DWI object.

This function loads data from a NIfTI file, optionally loading a gradient table from either a separate gradients file or from .bvec / .bval files.

Parameters:

  • filename (os.pathlike) – The main DWI data file (NIfTI).

  • brainmask_file (os.pathlike, optional) – A brainmask NIfTI file. If provided, will be loaded and stored in the returned dataset.

  • gradients_file (os.pathlike, optional) – A text file containing the gradients table, shape (N, C) where the last column stores the b-values. If provided following the column-major convention (C, N), it will be transposed automatically. If provided, it supersedes any .bvec / .bval combination.

  • bvec_file (os.pathlike, optional) – A text file containing b-vectors, shape (N, 3) or (3, N).

  • bval_file (os.pathlike, optional) – A text file containing b-values, shape (N,).

  • b0_file (os.pathlike, optional) – A NIfTI file containing a b=0 volume (possibly averaged or reference). If not provided, and the data contains at least one b=0 volume, one will be computed.

Returns:

dwi – A DWI object containing the loaded data, gradient table, and optional b-zero volume, and brainmask.

Return type:

DWI

Raises:

RuntimeError – If no gradient information is provided (neither gradients_file nor bvec_file + bval_file).

Submodules