cbf

cbf ¶

ASL CBF quantification.

This module implements absolute CBF quantification from ASL difference images using the single-compartment kinetic model recommended by the ISMRM Perfusion Study Group. Parameter naming follows the OSIPI ASL Lexicon conventions.

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] Buxton RB et al. (1998). A general kinetic model for quantitative perfusion imaging with arterial spin labeling. Magn Reson Med 40(3):383-396.

ASLQuantificationParams `dataclass` ¶

ASLQuantificationParams(
    labeling_scheme=PCASL,
    t1_blood=1650.0,
    t1_tissue=1330.0,
    partition_coefficient=0.9,
    labeling_efficiency=0.85,
    pld=1800.0,
    label_duration=1800.0,
    bolus_duration=None,
)

Parameters for ASL CBF quantification.

ATTRIBUTE	DESCRIPTION
`labeling_scheme`	Type of labeling (PASL, CASL, pCASL). TYPE: `LabelingScheme`
`t1_blood`	T1 of arterial blood in milliseconds. Default 1650 ms at 3T (Alsop et al., 2015). TYPE: `float`
`t1_tissue`	T1 of gray matter tissue in milliseconds. Default 1330 ms at 3T. TYPE: `float`
`partition_coefficient`	Blood-brain partition coefficient (λ). Default 0.9 ml/g for whole brain. TYPE: `float`
`labeling_efficiency`	Labeling efficiency (α). Default depends on scheme. TYPE: `float`
`pld`	Post-labeling delay in milliseconds. TYPE: `float`
`label_duration`	Labeling duration in milliseconds (for pCASL/CASL). TYPE: `float`
`bolus_duration`	Bolus duration for PASL in milliseconds. TYPE: `float \| None`

ASLQuantificationResult `dataclass` ¶

ASLQuantificationResult(
    cbf_map, quality_mask, m0_used=None, scaling_factor=1.0
)

Result of ASL CBF quantification.

ATTRIBUTE	DESCRIPTION
`cbf_map`	CBF map in mL/100g/min (OSIPI ASL Lexicon). TYPE: `ParameterMap`
`quality_mask`	Mask of reliable voxels. TYPE: `NDArray[bool_]`
`m0_used`	M0 values (a.u.) used for calibration. TYPE: `NDArray[floating] \| None`
`scaling_factor`	Conversion factor used. TYPE: `float`

PCASLSinglePLDModel ¶

Bases: BaseASLModel

pCASL single-PLD CBF quantification model (OSIPI ASL Lexicon).

Implements the ISMRM consensus pCASL equation. Returns CBF in mL/100g/min per the OSIPI ASL Lexicon.

References

.. [1] OSIPI ASL Lexicon, https://osipi.github.io/ASL-Lexicon/ .. [2] Alsop DC et al. MRM 2015;73(1):102-116.

name `property` ¶

name

Return model registry name.

parameters `property` ¶

parameters

Return fitted parameter names.

parameter_units `property` ¶

parameter_units

Return parameter units per OSIPI ASL Lexicon.

reference `property` ¶

reference

Return literature reference for this model.

labeling_type `property` ¶

labeling_type

Return ASL labeling type.

get_bounds ¶

get_bounds()

Return parameter bounds for CBF fitting.

quantify ¶

quantify(delta_m, m0, params)

Compute CBF from delta-M and M0 using the pCASL equation.

PASLSinglePLDModel ¶

Bases: BaseASLModel

PASL single-PLD CBF quantification model (OSIPI ASL Lexicon).

Implements the QUIPSS II PASL equation. Returns CBF in mL/100g/min per the OSIPI ASL Lexicon.

References

.. [1] OSIPI ASL Lexicon, https://osipi.github.io/ASL-Lexicon/ .. [2] Alsop DC et al. MRM 2015;73(1):102-116.

name `property` ¶

name

Return model registry name.

parameters `property` ¶

parameters

Return fitted parameter names.

parameter_units `property` ¶

parameter_units

Return parameter units per OSIPI ASL Lexicon.

reference `property` ¶

reference

Return literature reference for this model.

labeling_type `property` ¶

labeling_type

Return ASL labeling type.

get_bounds ¶

get_bounds()

Return parameter bounds for CBF fitting.

quantify ¶

quantify(delta_m, m0, params)

Compute CBF from delta-M and M0 using the PASL equation.

CASLSinglePLDModel ¶

Bases: BaseASLModel

CASL single-PLD CBF quantification model (OSIPI ASL Lexicon).

Uses same equation as pCASL. Returns CBF in mL/100g/min per the OSIPI ASL Lexicon.

References

.. [1] OSIPI ASL Lexicon, https://osipi.github.io/ASL-Lexicon/ .. [2] Alsop DC et al. MRM 2015;73(1):102-116.

name `property` ¶

name

Return model registry name.

parameters `property` ¶

parameters

Return fitted parameter names.

parameter_units `property` ¶

parameter_units

Return parameter units per OSIPI ASL Lexicon.

reference `property` ¶

reference

Return literature reference for this model.

labeling_type `property` ¶

labeling_type

Return ASL labeling type.

get_bounds ¶

get_bounds()

Return parameter bounds for CBF fitting.

quantify ¶

quantify(delta_m, m0, params)

Compute CBF from delta-M and M0 using the pCASL/CASL equation.

register_difference_method ¶

register_difference_method(name)

Decorator to register an ASL difference method.

PARAMETER	DESCRIPTION
`name`	Registry key for the method (e.g. `'pairwise'`). TYPE: `str`

RETURNS	DESCRIPTION
`Callable`	Function decorator.

get_difference_method ¶

get_difference_method(name)

Get a difference method by name.

PARAMETER	DESCRIPTION
`name`	Method name (e.g. `'pairwise'`). TYPE: `str`

RETURNS	DESCRIPTION
`Callable`	Difference computation function.

RAISES	DESCRIPTION
`DataValidationError`	If method name is not recognized.

list_difference_methods ¶

list_difference_methods()

Return names of all registered difference methods.

RETURNS	DESCRIPTION
`list[str]`	Sorted list of registered method names.

quantify_cbf ¶

quantify_cbf(delta_m, m0, params=None, mask=None)

Quantify absolute CBF from ASL difference images.

Uses the single-compartment model from ISMRM consensus. CBF is returned in mL/100g/min per the OSIPI ASL Lexicon.

For pCASL/CASL: CBF = (6000 * lambda * DeltaM * exp(PLD/T1b)) / (2 * alpha * T1b * M0 * (1 - exp(-tau/T1b)))

For PASL: CBF = (6000 * lambda * DeltaM * exp(TI/T1b)) / (2 * alpha * TI1 * M0)

PARAMETER	DESCRIPTION
`delta_m`	Difference magnetization (label - control), shape (...). TYPE: `NDArray[floating]`
`m0`	Equilibrium magnetization (M0, a.u.) from calibration. Either a single value or array matching delta_m spatial shape. TYPE: `NDArray[floating] \| float`
`params`	Quantification parameters. TYPE: `ASLQuantificationParams \| None` DEFAULT: `None`
`mask`	Brain mask. TYPE: `NDArray[bool_] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`ASLQuantificationResult`	CBF map (mL/100g/min) and quality metrics.

Examples:

>>> import numpy as np
>>> from osipy.asl import quantify_cbf, ASLQuantificationParams, LabelingScheme
>>> delta_m = np.random.rand(64, 64, 20) * 100
>>> m0 = 1000.0
>>> params = ASLQuantificationParams(
...     labeling_scheme=LabelingScheme.PCASL,
...     pld=1800.0,
...     label_duration=1800.0,
... )
>>> result = quantify_cbf(delta_m, m0, params)

References

.. [1] OSIPI ASL Lexicon, https://osipi.github.io/ASL-Lexicon/

compute_control_label_difference ¶

compute_control_label_difference(
    asl_data, context, method="pairwise", mask=None
)

Compute ASL difference from interleaved control/label data.

Extracts control and label volumes from raw 4D ASL data using the aslcontext volume type information and computes ΔM = control - label.

PARAMETER	DESCRIPTION
`asl_data`	Raw 4D ASL timeseries, shape (x, y, z, n_volumes). TYPE: `NDArray[floating]`
`context`	Volume types from aslcontext.tsv. Should contain 'control' and 'label'. Other types like 'm0scan', 'deltam', 'cbf' are filtered out. TYPE: `list[str]`
`method`	Subtraction method: - 'pairwise': Subtract adjacent control-label pairs, then average. - 'surround': Average surrounding controls for each label. - 'mean': Average all controls and labels separately, then subtract. TYPE: `str` DEFAULT: `'pairwise'`
`mask`	Brain mask. If provided, sets non-brain voxels to 0. TYPE: `NDArray[bool_] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`NDArray[floating]`	Difference magnetization (ΔM), shape (x, y, z) or (x, y, z, n_pairs) depending on method. For 'pairwise' and 'mean', returns averaged 3D.

RAISES	DESCRIPTION
`DataValidationError`	If context length doesn't match data or no control/label volumes found.

Examples:

>>> import numpy as np
>>> from osipy.asl import compute_control_label_difference
>>> # Simulated interleaved ASL data
>>> data = np.random.rand(64, 64, 20, 80) * 1000
>>> context = ['control', 'label'] * 40
>>> delta_m = compute_control_label_difference(data, context)
>>> print(delta_m.shape)  # (64, 64, 20)

Notes

The context list should match the aslcontext.tsv format: - 'control': Control (no labeling) images - 'label': Labeled blood images - 'm0scan': M0 calibration images (excluded from difference) - 'deltam': Already-computed difference images (returned as-is) - 'cbf': Already-quantified CBF maps (excluded)

compute_pcasl_difference ¶

compute_pcasl_difference(label, control, mask=None)

Compute ASL difference image (control - label).

For pCASL/CASL, the difference magnetization is ΔM = M_control - M_label, which is positive where there is blood flow (labeled blood reduces signal).

PARAMETER	DESCRIPTION
`label`	Label images, shape (..., n_pairs) or (...,). TYPE: `NDArray[floating]`
`control`	Control images, shape (..., n_pairs) or (...,). TYPE: `NDArray[floating]`
`mask`	Brain mask for averaging (optional). TYPE: `NDArray[bool_] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`NDArray[floating]`	Difference magnetization (ΔM = control - label). If multiple pairs, returns mean across pairs.

Examples:

>>> import numpy as np
>>> from osipy.asl import compute_pcasl_difference
>>> control = np.random.rand(64, 64, 20, 10) * 1000 + 100
>>> label = control - 50  # Simulated signal reduction
>>> delta_m = compute_pcasl_difference(label, control)
>>> print(delta_m.shape)  # (64, 64, 20)

compute_cbf_uncertainty ¶

compute_cbf_uncertainty(
    delta_m, delta_m_std, m0, m0_std, params
)

Compute CBF uncertainty from error propagation.

PARAMETER	DESCRIPTION
`delta_m`	Mean difference magnetization. TYPE: `NDArray`
`delta_m_std`	Standard deviation of difference magnetization. TYPE: `NDArray`
`m0`	M0 value. TYPE: `NDArray`
`m0_std`	M0 uncertainty (if available). TYPE: `NDArray \| None`
`params`	Quantification parameters. TYPE: `ASLQuantificationParams`

RETURNS	DESCRIPTION
`NDArray`	CBF standard error in ml/100g/min.

cbf

cbf ¶

ASLQuantificationParams dataclass ¶

ASLQuantificationResult dataclass ¶

PCASLSinglePLDModel ¶

name property ¶

parameters property ¶

parameter_units property ¶

reference property ¶

labeling_type property ¶

get_bounds ¶

quantify ¶

PASLSinglePLDModel ¶

name property ¶

parameters property ¶

parameter_units property ¶

reference property ¶

labeling_type property ¶

get_bounds ¶

quantify ¶

CASLSinglePLDModel ¶

name property ¶

parameters property ¶

parameter_units property ¶

reference property ¶

labeling_type property ¶

get_bounds ¶

quantify ¶

register_difference_method ¶

get_difference_method ¶

list_difference_methods ¶

quantify_cbf ¶

compute_control_label_difference ¶

compute_pcasl_difference ¶

compute_cbf_uncertainty ¶

ASLQuantificationParams `dataclass` ¶

ASLQuantificationResult `dataclass` ¶

name `property` ¶

parameters `property` ¶

parameter_units `property` ¶

reference `property` ¶

labeling_type `property` ¶

name `property` ¶

parameters `property` ¶

parameter_units `property` ¶

reference `property` ¶

labeling_type `property` ¶

name `property` ¶

parameters `property` ¶

parameter_units `property` ¶

reference `property` ¶

labeling_type `property` ¶