bids

bids

BIDS I/O for osipy.

This module provides functions for loading and exporting perfusion data in BIDS-compliant format, including ASL-BIDS input support.

References

BIDS Specification: https://bids-specification.readthedocs.io/ BIDS Derivatives: https://bids-specification.readthedocs.io/en/stable/derivatives/ ASL-BIDS: https://bids-specification.readthedocs.io/en/stable/modality-specific-files/magnetic-resonance-imaging-data.html#arterial-spin-labeling-perfusion-data

export_bids

export_bids(parameter_maps, output_dir, subject_id, session_id=None, metadata=None)

Export parameter maps in BIDS derivatives format.

PARAMETER	DESCRIPTION
parameter_maps	Parameter maps to export, keyed by parameter name. TYPE: dict[str, ParameterMap]
output_dir	BIDS derivatives root directory. TYPE: str | Path
subject_id	Subject identifier (without 'sub-' prefix). TYPE: str
session_id	Session identifier (without 'ses-' prefix), optional. TYPE: str | None DEFAULT: None
metadata	Additional metadata for sidecar JSON files. TYPE: dict | None DEFAULT: None

RETURNS	DESCRIPTION
Path	Path to created subject directory.

RAISES	DESCRIPTION
ValueError	If parameter_maps is empty or subject_id is invalid.

Examples:

>>> from osipy.common.io.bids import export_bids
>>> results = {"Ktrans": ktrans_map, "ve": ve_map}
>>> path = export_bids(results, "derivatives/osipy", "01")
>>> print(path)
derivatives/osipy/sub-01/perf

Notes

Creates the following structure:

derivatives/osipy/
├── dataset_description.json
└── sub-XX/
    └── [ses-XX/]
        └── perf/
            ├── sub-XX_Ktrans.nii.gz
            ├── sub-XX_ve.nii.gz
            └── sub-XX_perf.json

load_bids

load_bids(bids_dir, subject, modality=ASL, session=None, run=None, interactive=True)

Load perfusion data from a BIDS dataset.

PARAMETER	DESCRIPTION
bids_dir	Path to BIDS dataset root directory. TYPE: str | Path
subject	Subject ID (without 'sub-' prefix). TYPE: str
modality	Perfusion modality to load. TYPE: Modality DEFAULT: Modality.ASL
session	Session ID (without 'ses-' prefix), optional. TYPE: str | None DEFAULT: None
run	Run number, optional. TYPE: int | None DEFAULT: None
interactive	Whether to prompt for missing required parameters. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
PerfusionDataset	Loaded perfusion data with metadata.

RAISES	DESCRIPTION
FileNotFoundError	If BIDS directory or required files not found.
IOError	If BIDS dataset structure is invalid.

Examples:

>>> from osipy.common.io.bids import load_bids
>>> from osipy.common.types import Modality
>>> dataset = load_bids("bids_dataset/", "01", Modality.ASL)
>>> print(dataset.shape)
(64, 64, 24, 80)

load_bids_with_m0

load_bids_with_m0(bids_dir, subject, session=None, run=None, interactive=True)

Load ASL data with separate M0 calibration scan from BIDS.

PARAMETER	DESCRIPTION
bids_dir	Path to BIDS dataset root directory. TYPE: str | Path
subject	Subject ID (without 'sub-' prefix). TYPE: str
session	Session ID (without 'ses-' prefix), optional. TYPE: str | None DEFAULT: None
run	Run number, optional. TYPE: int | None DEFAULT: None
interactive	Whether to prompt for missing required parameters. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
tuple[PerfusionDataset, PerfusionDataset | None]	Tuple of (ASL data, M0 calibration data). M0 is None if not found.

Examples:

>>> asl_data, m0_data = load_bids_with_m0("bids_dataset/", "01")
>>> if m0_data is not None:
...     print(f"M0 shape: {m0_data.shape}")

Notes

BIDS ASL M0 scans can be: - Separate file: *_m0scan.nii.gz - Included in ASL timeseries (indicated by M0Type in sidecar)

load_asl_context

load_asl_context(bids_dir, subject, session=None, run=None)

Load ASL context (control/label order) from BIDS.

PARAMETER	DESCRIPTION
bids_dir	Path to BIDS dataset root directory. TYPE: str | Path
subject	Subject ID (without 'sub-' prefix). TYPE: str
session	Session ID, optional. TYPE: str | None DEFAULT: None
run	Run number, optional. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[str]	List of volume types: 'control', 'label', 'm0scan', 'cbf', 'deltam'.

Examples:

>>> context = load_asl_context("bids_dataset/", "01")
>>> print(context[:4])
['control', 'label', 'control', 'label']

Notes

The aslcontext.tsv file is required by BIDS ASL and indicates the type of each volume in the ASL timeseries.

is_bids_dataset

is_bids_dataset(path)

Check if a path is a valid BIDS dataset.

PARAMETER	DESCRIPTION
path	Path to check. TYPE: str | Path

RETURNS	DESCRIPTION
bool	True if path appears to be a BIDS dataset.

get_bids_subjects

get_bids_subjects(bids_dir)

Get list of subjects in a BIDS dataset.

PARAMETER	DESCRIPTION
bids_dir	Path to BIDS dataset root. TYPE: str | Path

RETURNS	DESCRIPTION
list[str]	List of subject IDs (without 'sub-' prefix).