nifreeze.data.dmri module

dMRI data representation.

class nifreeze.data.dmri.DWI(self, dataobj=None, affine=None, brainmask=None, motion_affines=None, datahdr=None, filepath=NOTHING, bzero=None, gradients=None, eddy_xfms=None) → None[source]

Bases: BaseDataset

Data representation structure for dMRI data.

Method generated by attrs for class DWI.

bzero

A b=0 reference map, preferably obtained by some smart averaging.

eddy_xfms

List of transforms to correct for estimatted eddy current distortions.

classmethod from_filename(filename: Path | str) → DWI[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

gradients

A 2D numpy array of the gradient table (4xN).

set_transform(index: int, affine: numpy.ndarray, order: int = 3) → None[source]

Set an affine transform for a particular index and update the data object.

The new affine is set as in set_transform, and, in addition, the corresponding gradient vector is rotated.

Parameters:

  • index (int) – The volume index to transform.

  • affine (numpy.ndarray) – The 4x4 affine matrix to be applied.

  • order (int, optional) – The order of the spline interpolation.

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, insert_b0: bool = False) → None[source]

Write a NIfTI file to disk.

Parameters:

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

  • insert_b0 (bool) – Insert a \(b=0\) at the front of the output NIfTI.

nifreeze.data.dmri.load(filename: Path | str, brainmask_file: Path | str | None = None, motion_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, b0_thres: float = 50.0) → DWI[source]

Load DWI data and construct a DWI object.

This function can load data from either an HDF5 file (if the filename ends with .h5) or 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 or HDF5).

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

  • motion_file (os.pathlike) – A file containing head-motion affine matrices (linear)

  • gradients_file (os.pathlike, optional) – A text file containing the gradients table, shape (4, N) or (N, 4). If provided, it supersedes any .bvec / .bval combination.

  • bvec_file (os.pathlike, optional) – A text file containing b-vectors, shape (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.

  • b0_thres (float, optional) – Threshold for determining which volumes are considered DWI vs. b=0 if you combine them in the same file.

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