nifreeze.data.base module

Four-dimensional data representation in hard-disk and memory.

class nifreeze.data.base.BaseDataset(self, dataobj=None, affine=None, brainmask=None, motion_affines=None, datahdr=None, filepath=NOTHING) → None[source]

Bases: object

Base dataset representation structure.

A general data structure to represent 4D images and the necessary metadata for head-motion estimation (that is, potentially a brain mask and the head-motion estimates).

The data structure has a direct HDF5 mapping to facilitate memory efficiency. For modalities requiring additional metadata such as DWI (which requires the gradient table and potentially a b=0 reference), this class may be derived to override certain behaviors (in the case of DWIs, the indexed access should also return the corresponding gradient specification).

Method generated by attrs for class BaseDataset.

__len__() → int[source]

Obtain the number of volumes/frames in the dataset.

affine

Best affine for RAS-to-voxel conversion of coordinates (NIfTI header).

brainmask

A boolean ndarray object containing a corresponding brainmask.

datahdr

A SpatialHeader header corresponding to the data.

dataobj

A ndarray object for the data array.

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

Read an HDF5 file from disk and create a BaseDataset.

Parameters:

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

Returns:

The constructed dataset with data loaded from the file.

Return type:

BaseDataset

get_filename() → Path[source]

Get the filepath of the HDF5 file.

motion_affines

List of Affine realigning the dataset.

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.

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 an HDF5 file to 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) → None[source]

Write a NIfTI file to disk.

Parameters:

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

nifreeze.data.base.load(filename: Path | str, brainmask_file: Path | str | None = None, motion_file: Path | str | None = None) → BaseDataset[source]

Load 4D data from a filename or an HDF5 file.

Parameters:

  • filename (os.pathlike) – The NIfTI or HDF5 file.

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

Returns:

The loaded dataset.

Return type:

BaseDataset

Raises:

ValueError – If the file extension is not supported or the file cannot be loaded.