m0

m0

M0 calibration for ASL quantification.

This module implements M0 calibration methods for absolute CBF quantification in ASL imaging. The equilibrium magnetization (M0) is reported in arbitrary units (a.u.) per the OSIPI ASL Lexicon.

GPU/CPU agnostic using the xp array module pattern. NO scipy dependency - uses custom morphological operations.

References

.. [1] OSIPI ASL Lexicon, https://osipi.github.io/ASL-Lexicon/ .. [2] Alsop DC et al. (2015). Recommended implementation of arterial spin-labeled perfusion MRI for clinical applications. Magn Reson Med 73(1):102-116. .. [3] Chappell MA et al. (2009). Separation of macrovascular signal in multi-inversion time arterial spin labeling MRI. Magn Reson Med 63(5):1357-1365.

M0CalibrationParams dataclass

M0CalibrationParams(
    method="single",
    reference_region="csf",
    t1_tissue=1330.0,
    t2_star_tissue=None,
    tr_m0=6000.0,
    te_m0=13.0,
)

Parameters for M0 calibration.

ATTRIBUTE	DESCRIPTION
method	Calibration method: 'single', 'voxelwise', or 'reference_region'. TYPE: str
reference_region	Reference region for calibration: 'csf', 'white_matter', or 'custom'. TYPE: str
t1_tissue	T1 of calibration tissue in milliseconds. TYPE: float
t2_star_tissue	T2* of calibration tissue in milliseconds (for GRE). TYPE: float | None
tr_m0	TR of M0 acquisition in milliseconds. TYPE: float
te_m0	TE of M0 acquisition in milliseconds. TYPE: float

VoxelwiseM0Calibration

Bases: BaseM0Calibration

Voxel-by-voxel M0 calibration.

name property

name

Return calibration method name.

reference property

reference

Return literature reference for this method.

calibrate

calibrate(asl_data, m0_image, params, mask=None)

Calibrate ASL data by dividing each voxel by its corrected M0 value.

PARAMETER	DESCRIPTION
asl_data	ASL difference images. TYPE: NDArray
m0_image	M0 calibration image. TYPE: NDArray
params	M0 calibration parameters. TYPE: Any
mask	Brain mask. TYPE: NDArray[bool_] | None DEFAULT: None

RETURNS	DESCRIPTION
calibrated	Calibrated ASL data (delta-M / M0). TYPE: NDArray
m0_corrected	M0 after T1 recovery and T2* corrections. TYPE: NDArray

ReferenceRegionM0Calibration

Bases: BaseM0Calibration

Reference region M0 calibration.

name property

name

Return calibration method name.

reference property

reference

Return literature reference for this method.

calibrate

calibrate(asl_data, m0_image, params, mask=None)

Calibrate ASL data using a single M0 value from a reference region.

PARAMETER	DESCRIPTION
asl_data	ASL difference images. TYPE: NDArray
m0_image	M0 calibration image. TYPE: NDArray
params	M0 calibration parameters. TYPE: Any
mask	Brain mask. TYPE: NDArray[bool_] | None DEFAULT: None

RETURNS	DESCRIPTION
calibrated	Calibrated ASL data (delta-M / M0_ref). TYPE: NDArray
m0_corrected	M0 after T1 recovery and T2* corrections. TYPE: NDArray

SingleM0Calibration

Bases: BaseM0Calibration

Single (mean) M0 calibration.

name property

name

Return calibration method name.

reference property

reference

Return literature reference for this method.

calibrate

calibrate(asl_data, m0_image, params, mask=None)

Calibrate ASL data using the mean M0 across masked voxels.

PARAMETER	DESCRIPTION
asl_data	ASL difference images. TYPE: NDArray
m0_image	M0 calibration image. TYPE: NDArray
params	M0 calibration parameters. TYPE: Any
mask	Brain mask. TYPE: NDArray[bool_] | None DEFAULT: None

RETURNS	DESCRIPTION
calibrated	Calibrated ASL data (delta-M / mean(M0)). TYPE: NDArray
m0_corrected	M0 after T1 recovery and T2* corrections. TYPE: NDArray

apply_m0_calibration

apply_m0_calibration(
    asl_data, m0_image, params=None, mask=None
)

Apply M0 calibration to ASL data.

PARAMETER	DESCRIPTION
asl_data	ASL difference images (ΔM), shape (...). TYPE: NDArray[floating]
m0_image	M0 calibration image, shape (...). TYPE: NDArray[floating]
params	Calibration parameters. TYPE: M0CalibrationParams | None DEFAULT: None
mask	Brain mask. TYPE: NDArray[bool_] | None DEFAULT: None

RETURNS	DESCRIPTION
calibrated_data	Calibrated ASL data (ΔM/M0 ratio scaled appropriately). TYPE: NDArray[floating]
m0_corrected	M0 values after T1/T2* corrections. TYPE: NDArray[floating]

Examples:

>>> import numpy as np
>>> from osipy.asl.calibration import apply_m0_calibration
>>> asl_data = np.random.rand(64, 64, 20) * 100
>>> m0_image = np.random.rand(64, 64, 20) * 1000 + 500
>>> calibrated, m0 = apply_m0_calibration(asl_data, m0_image)

compute_m0_from_pd

compute_m0_from_pd(
    pd_image,
    t1_tissue=1330.0,
    t2_tissue=80.0,
    tr=6000.0,
    te=13.0,
)

Compute M0 from proton density image.

PARAMETER	DESCRIPTION
pd_image	Proton density weighted image. TYPE: NDArray[floating]
t1_tissue	T1 of tissue in milliseconds. TYPE: float DEFAULT: 1330.0
t2_tissue	T2 of tissue in milliseconds. TYPE: float DEFAULT: 80.0
tr	TR of PD acquisition in milliseconds. TYPE: float DEFAULT: 6000.0
te	TE of PD acquisition in milliseconds. TYPE: float DEFAULT: 13.0

RETURNS	DESCRIPTION
NDArray[floating]	Estimated M0 values.