nifreeze.data.base module¶

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

nifreeze.data.base.AFFINE_ABSENCE_ERROR_MSG = "BaseDataset 'affine' may not be None"¶: BaseDataset initialization affine absence error message.

nifreeze.data.base.AFFINE_NDIM_ERROR_MSG = "BaseDataset 'affine' must be a 2D array"¶: Affine dimensionality error message.

nifreeze.data.base.AFFINE_OBJECT_ERROR_MSG = "BaseDataset 'affine' must be a numpy array."¶: BaseDataset initialization affine object error message.

nifreeze.data.base.AFFINE_SHAPE_ERROR_MSG = "BaseDataset 'affine' must be a 2D numpy array (4 x 4)"¶: BaseDataset initialization affine shape error message.

nifreeze.data.base.BRAINMASK_SHAPE_MISMATCH_ERROR_MSG = "BaseDataset 'brainmask' shape ({brainmask_shape}) does not match dataset volumes ({data_shape})."¶: BaseDataset brainmask shape mismatch error message.

class nifreeze.data.base.BaseDataset(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) → None[source]¶

Bases: Generic[Unpack[Ts]]

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: np.ndarray¶: Best affine for RAS-to-voxel conversion of coordinates (NIfTI header).

brainmask: np.ndarray | None¶: A boolean ndarray object containing a corresponding brainmask.

datahdr: nb.Nifti1Header | None¶: A Nifti1Header header corresponding to the data.

dataobj: np.ndarray¶: A ndarray object for the data array.

classmethod from_filename(filename: Path | str) → Self[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: np.ndarray | None¶: Array of Affine realigning the dataset.

set_transform(index: int, affine: ndarray) → None[source]¶

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

Parameters:

index (int) – The volume index to transform.
affine (ndarray) – The 4x4 affine matrix to be applied.

property shape3d¶: Get the shape of the 3D volume.

property size3d¶: Get the number of voxels in the 3D volume.

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 | str | None = None, write_hmxfms: bool = False, order: int = 3) → nibabel.nifti1.Nifti1Image[source]¶

Write a NIfTI file to disk.

Volumes are resampled to the reference affine if motion affines have been set, otherwise the original data are written.

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

Returns:

NIfTI image written to disk.

Return type:

Nifti1Image

nifreeze.data.base.DATAOBJ_ABSENCE_ERROR_MSG = "BaseDataset 'dataobj' may not be None"¶: BaseDataset initialization dataobj absence error message.

nifreeze.data.base.DATAOBJ_NDIM_ERROR_MSG = "BaseDataset 'dataobj' must be a 4-D numpy array"¶: BaseDataset initialization dataobj dimensionality error message.

nifreeze.data.base.DATAOBJ_OBJECT_ERROR_MSG = "BaseDataset 'dataobj' must be a numpy array."¶: BaseDataset initialization dataobj object error message.

class nifreeze.data.base.ImageGrid(self, /, *args, **kwargs)¶

Bases: tuple

Create new instance of ImageGrid(shape, affine)

affine¶: Alias for field number 1

shape¶: Alias for field number 0

nifreeze.data.base.to_nifti(dataset: BaseDataset, filename: Path | str | None = None, write_hmxfms: bool = False, order: int = 3) → nibabel.nifti1.Nifti1Image[source]¶

Write a NIfTI file to disk.

Volumes are resampled to the reference affine if motion affines have been set, otherwise the original data are written.

Parameters:

dataset (BaseDataset) – The dataset to serialize.
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).

Returns:

NIfTI image written to disk.

Return type:

Nifti1Image

nifreeze.data.base.validate_affine(inst: BaseDataset, attr: Attribute, value: Any) → None[source]¶

Strict validator for affine matrices.

Enforces that value is present and is a 4x4 NumPy array.

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

Parameters:

inst (BaseDataset) – The instance being validated (unused, present for validator signature).
attr (Attribute) – The attribute being validated (unused, present for validator signature).
value (Any) – The value to validate.

:raises exc:TypeError: If the input cannot be converted to a float ndarray. :raises exc:ValueError: If the value is None, or not shaped (4, 4).

nifreeze.data.base.validate_dataobj(inst: BaseDataset, attr: Attribute, value: Any) → None[source]¶

Strict validator for data objects.

Enforces that value is present and is a NumPy array with exactly 4 dimensions (ndim == 4).

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

Parameters:

inst (BaseDataset) – The instance being validated (unused, present for validator signature).
attr (Attribute) – The attribute being validated (unused, present for validator signature).
value (Any) – The value to validate.

:raises exc:TypeError: If the input cannot be converted to a float ndarray. :raises exc:ValueError: If the value is None, or not 4-dimensional.