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, sidecar_json=None, interactive=False)

Load NIfTI file as PerfusionDataset.

PARAMETER	DESCRIPTION
`path`	Path to NIfTI file (.nii or .nii.gz). TYPE: `str \| Path`
`modality`	Perfusion modality. Defaults to :class:`Modality.DCE` when unset. TYPE: `Modality \| None` DEFAULT: `None`
`acquisition_params`	Acquisition parameters. When provided, takes precedence over any values derived from the sidecar JSON. When None and a sidecar is available, parameters are mapped via `MetadataMapper`. TYPE: `AcquisitionParams \| None` DEFAULT: `None`
`sidecar_json`	Optional BIDS-style sidecar JSON. If None, a file sharing the NIfTI's stem with a `.json` extension is loaded automatically when present. TYPE: `str \| Path \| None` DEFAULT: `None`
`interactive`	Forwarded to `MetadataMapper` — when True, prompts for any modality-required fields missing from the sidecar. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`PerfusionDataset`	Loaded imaging data with metadata. `time_points` is derived from `RepetitionTimePreparation` / `RepetitionTime` in the sidecar when present, otherwise from the NIfTI header's temporal zoom, otherwise defaults to integer frame indices.

RAISES	DESCRIPTION
`FileNotFoundError`	If the NIfTI file does not exist.
`IOError`	If the file is not a valid NIfTI.
`DataValidationError`	If the data is not 3D or 4D.

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)

Load with an explicit sidecar:

>>> dataset = load_nifti(
...     "asl.nii.gz",
...     modality="ASL",
...     sidecar_json="asl.json",
... )

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