nifti

nifti ¶

NIfTI file loading and saving for osipy.

This module provides functions for loading and saving NIfTI files, including PerfusionDataset containers and ParameterMap objects.

References

NIfTI-1 Data Format: https://nifti.nimh.nih.gov/

load_nifti ¶

load_nifti(path, modality=None, acquisition_params=None)

Load NIfTI file as PerfusionDataset.

PARAMETER	DESCRIPTION
`path`	Path to NIfTI file (.nii or .nii.gz). TYPE: `str \| Path`
`modality`	Perfusion modality. If None, must be inferred from filename or provided later. TYPE: `Modality \| None` DEFAULT: `None`
`acquisition_params`	Acquisition parameters. If None, uses default AcquisitionParams. TYPE: `AcquisitionParams \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`PerfusionDataset`	Loaded imaging data with metadata.

RAISES	DESCRIPTION
`FileNotFoundError`	If file does not exist.
`IOError`	If file is not valid NIfTI format.
`DataValidationError`	If data dimensions are invalid.

Examples:

>>> from osipy.common.io.nifti import load_nifti
>>> from osipy.common.types import Modality
>>> dataset = load_nifti("dce_data.nii.gz", modality=Modality.DCE)
>>> print(dataset.shape)
(64, 64, 20, 30)

save_nifti ¶

save_nifti(data, path, affine=None, dtype=None)

Save data as a NIfTI file with proper orientation preservation.

This function ensures the affine matrix is correctly applied to preserve spatial orientation when saving parameter maps or datasets.

PARAMETER	DESCRIPTION
`data`	Data to save. Can be: - A numpy array (requires affine parameter) - A ParameterMap (uses embedded affine) - A PerfusionDataset (uses embedded affine) TYPE: `NDArray \| ParameterMap \| PerfusionDataset`
`path`	Output path. Will add .nii.gz extension if not present. TYPE: `str \| Path`
`affine`	4x4 affine transformation matrix. Required if data is a numpy array. Ignored if data is a ParameterMap or PerfusionDataset. TYPE: `NDArray \| None` DEFAULT: `None`
`dtype`	Output data type. Defaults to float32 for parameter maps. TYPE: `dtype \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Path`	Path to the saved file.

RAISES	DESCRIPTION
`ValueError`	If data is a numpy array and affine is not provided.
`IOError`	If saving fails.

Examples:

>>> from osipy.common.io import save_nifti
>>> import numpy as np
>>> data = np.random.rand(64, 64, 20)
>>> affine = np.eye(4)
>>> save_nifti(data, "output.nii.gz", affine=affine)

>>> from osipy.common.parameter_map import ParameterMap
>>> ktrans = ParameterMap(name="Ktrans", ...)
>>> save_nifti(ktrans, "Ktrans.nii.gz")  # Uses embedded affine