load

load ¶

Unified data loading interface for osipy.

This module provides a universal load_perfusion() function that auto-detects file format and loads perfusion data from DICOM, NIfTI, or BIDS sources.

load_perfusion ¶

load_perfusion(
    path,
    modality=None,
    format="auto",
    subject=None,
    session=None,
    interactive=True,
    use_dcm2niix=True,
    sidecar_json=None,
    **kwargs,
)

Universal perfusion data loader with format auto-detection.

This is the primary entry point for loading perfusion imaging data. It automatically detects the file format and delegates to the appropriate loader.

PARAMETER	DESCRIPTION
`path`	Path to data. Can be: - NIfTI file (.nii or .nii.gz) - DICOM directory or file - BIDS dataset directory TYPE: `str \| Path`
`modality`	Perfusion modality (DCE, DSC, ASL, IVIM). If None, attempts to infer from data or defaults to DCE. TYPE: `Modality \| str \| None` DEFAULT: `None`
`format`	Data format. If 'auto', format is detected from path. TYPE: `(auto, nifti, dicom, bids)` DEFAULT: `'auto'`
`subject`	Subject ID for BIDS loading (without 'sub-' prefix). Required when format='bids'. TYPE: `str \| None` DEFAULT: `None`
`session`	Session ID for BIDS loading (without 'ses-' prefix). TYPE: `str \| None` DEFAULT: `None`
`interactive`	Whether to prompt for missing required parameters. TYPE: `bool` DEFAULT: `True`
`use_dcm2niix`	Whether to use dcm2niix for DICOM conversion when available. Falls back to direct DICOM loading if dcm2niix not found. TYPE: `bool` DEFAULT: `True`
`sidecar_json`	Optional path to BIDS-style sidecar JSON with metadata. Useful when loading NIfTI files without embedded metadata. TYPE: `str \| Path \| None` DEFAULT: `None`
`**kwargs`	Additional arguments passed to format-specific loaders. TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`PerfusionDataset`	Loaded imaging data with metadata.

RAISES	DESCRIPTION
`FileNotFoundError`	If path does not exist.
`IOError`	If format cannot be determined or data cannot be loaded.
`MetadataError`	If required metadata is missing and interactive=False.

Examples:

Load NIfTI file:

>>> from osipy.common.io import load_perfusion
>>> dataset = load_perfusion("data/asl.nii.gz", modality="ASL")

Load DICOM directory:

>>> dataset = load_perfusion("data/dicom_series/", modality="DCE")

Load from BIDS dataset:

>>> dataset = load_perfusion(
...     "bids_dataset/",
...     format="bids",
...     subject="01",
...     modality="ASL",
... )

Load NIfTI with sidecar JSON:

>>> dataset = load_perfusion(
...     "data/asl.nii.gz",
...     sidecar_json="data/asl.json",
...     modality="ASL",
... )