types

types

Core type definitions for osipy.

This module defines enumerations and base dataclasses used across all perfusion modality modules. Acquisition parameter names follow MRI conventions and OSIPI lexicon definitions where applicable.

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [2] OSIPI ASL Lexicon, https://osipi.github.io/ASL-Lexicon/ .. [3] Dickie BR et al. MRM 2024. doi:10.1002/mrm.30101 .. [4] Suzuki Y et al. MRM 2024;91(4):1411-1421.

Modality

Bases: Enum

Perfusion imaging modality.

ATTRIBUTE	DESCRIPTION
DCE	Dynamic Contrast-Enhanced MRI. TYPE: str
DSC	Dynamic Susceptibility Contrast MRI. TYPE: str
ASL	Arterial Spin Labeling. TYPE: str
IVIM	Intravoxel Incoherent Motion. TYPE: str

LabelingType

Bases: Enum

ASL labeling scheme type.

ATTRIBUTE	DESCRIPTION
PCASL	Pseudo-continuous Arterial Spin Labeling. TYPE: str
PASL_FAIR	Pulsed ASL with Flow-sensitive Alternating Inversion Recovery. TYPE: str
PASL_EPISTAR	Pulsed ASL with Echo Planar Imaging and Signal Targeting with Alternating Radiofrequency. TYPE: str
PASL_PICORE	Pulsed ASL with Proximal Inversion with Control for Off-Resonance Effects. TYPE: str
VSASL	Velocity-Selective Arterial Spin Labeling. TYPE: str

References

Alsop DC et al. (2015). Recommended implementation of ASL. MRM.

FittingMethod

Bases: Enum

Model fitting algorithm.

ATTRIBUTE	DESCRIPTION
LM	Levenberg-Marquardt non-linear least squares optimization. TYPE: str
BAYESIAN	Bayesian inference with uncertainty estimation. TYPE: str
NEURAL_NETWORK	Neural network-based fitting (future). TYPE: str

AIFType

Bases: Enum

Arterial Input Function type.

ATTRIBUTE	DESCRIPTION
MEASURED	AIF extracted from image data. TYPE: str
POPULATION	Published population-based AIF model. TYPE: str
AUTOMATIC	Automatically detected from image data. TYPE: str

AcquisitionParams dataclass

AcquisitionParams(
    tr=None, te=None, flip_angle=None, field_strength=None
)

Base acquisition parameters common to all modalities.

ATTRIBUTE	DESCRIPTION
tr	Repetition time in milliseconds. TYPE: float | None
te	Echo time in milliseconds. TYPE: float | None
flip_angle	Flip angle in degrees. TYPE: float | None
field_strength	Magnetic field strength in Tesla. TYPE: float | None

DCEAcquisitionParams dataclass

DCEAcquisitionParams(
    tr=None,
    te=None,
    flip_angle=None,
    field_strength=None,
    flip_angles=list(),
    baseline_frames=5,
    temporal_resolution=1.0,
    relaxivity=4.5,
    t1_assumed=None,
)

Bases: AcquisitionParams

DCE-MRI specific acquisition parameters.

ATTRIBUTE	DESCRIPTION
flip_angles	Flip angles for variable flip angle T1 mapping in degrees. TYPE: list[float]
baseline_frames	Number of pre-contrast frames for baseline calculation. TYPE: int
temporal_resolution	Time between dynamic acquisitions in seconds. TYPE: float
relaxivity	Contrast agent relaxivity in mM⁻¹s⁻¹. Default is 4.5 for gadolinium-based agents at 3T. TYPE: float
t1_assumed	Assumed pre-contrast T1 value in milliseconds when T1 mapping data is unavailable. If None, a measured T1 map is required for signal-to-concentration conversion. Typical values at 3T: - Breast tissue: ~1400 ms - Brain white matter: ~800 ms - Brain gray matter: ~1200 ms - Blood: ~1600 ms TYPE: float | None

References

Tofts PS (1997). Modeling tracer kinetics in DCE-MRI. JMRI.

DSCAcquisitionParams dataclass

DSCAcquisitionParams(
    tr=None,
    te=None,
    flip_angle=None,
    field_strength=None,
    baseline_frames=10,
)

Bases: AcquisitionParams

DSC-MRI specific acquisition parameters.

ATTRIBUTE	DESCRIPTION
baseline_frames	Number of pre-bolus frames for baseline calculation. TYPE: int

Notes

The te parameter from the base class is required for ΔR2* calculation.

References

Ostergaard L et al. (1996). High resolution CBF measurement. MRM.

ASLAcquisitionParams dataclass

ASLAcquisitionParams(
    tr=None,
    te=None,
    flip_angle=None,
    field_strength=None,
    labeling_type=PCASL,
    pld=1800.0,
    labeling_duration=1800.0,
    background_suppression=False,
    bs_efficiency=1.0,
    m0_scale=None,
)

Bases: AcquisitionParams

ASL specific acquisition parameters.

ATTRIBUTE	DESCRIPTION
labeling_type	ASL labeling scheme. TYPE: LabelingType
pld	Post-labeling delay(s) in milliseconds. TYPE: float | list[float]
labeling_duration	Labeling duration in milliseconds. TYPE: float
background_suppression	Whether background suppression was applied. TYPE: bool
bs_efficiency	Background suppression efficiency factor (0 to 1). TYPE: float
m0_scale	M0 calibration scaling value. TYPE: float | None

References

Alsop DC et al. (2015). Recommended implementation of ASL. MRM.

IVIMAcquisitionParams dataclass

IVIMAcquisitionParams(
    tr=None,
    te=None,
    flip_angle=None,
    field_strength=None,
    b_values=(
        lambda: array(_get_default_ivim_b_values())
    )(),
)

Bases: AcquisitionParams

IVIM specific acquisition parameters.

ATTRIBUTE	DESCRIPTION
b_values	Array of b-values in s/mm². TYPE: NDArray[floating]

References

Le Bihan D et al. (1988). IVIM MR imaging. Radiology.