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.
MetadataError	If required metadata is missing and interactive=False.

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