base

base

Base classes and dataclasses for Arterial Input Functions.

This module provides the abstract base class for AIF implementations and the ArterialInputFunction dataclass for storing AIF data.

Population AIF models registered with @register_aif follow the OSIPI CAPLEX convention for model identification (e.g. M.IC2.001 for the Parker AIF, M.IC2.002 for the Georgiou AIF).

References

.. [1] Parker GJM et al. (2006). Experimentally-derived functional form for a population-averaged AIF. Magn Reson Med 56(5):993-1000. .. [2] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [3] Dickie BR et al. MRM 2024. doi:10.1002/mrm.30101

ArterialInputFunction dataclass

ArterialInputFunction(
    time,
    concentration,
    aif_type,
    population_model=None,
    model_parameters=dict(),
    source_roi=None,
    extraction_method=None,
    reference="",
)

Container for arterial input function data.

This dataclass holds the AIF concentration values, timing information, and metadata about how the AIF was obtained.

ATTRIBUTE	DESCRIPTION
time	Time points in seconds. TYPE: NDArray[floating]
concentration	Concentration values at each time point in mM. TYPE: NDArray[floating]
aif_type	Type of AIF (MEASURED, POPULATION, AUTOMATIC). TYPE: AIFType
population_model	Name of population model if aif_type is POPULATION. TYPE: str | None
model_parameters	Model-specific parameters if using a population AIF. TYPE: dict[str, float] | None
source_roi	ROI mask used for extraction if aif_type is MEASURED. TYPE: NDArray[bool_] | None
extraction_method	Method used for extraction ('manual', 'automatic'). TYPE: str | None
reference	Literature citation for the AIF model or extraction method. TYPE: str

Examples:

>>> import numpy as np
>>> from osipy.common.aif.base import ArterialInputFunction
>>> from osipy.common.types import AIFType
>>> time = np.linspace(0, 300, 60)
>>> conc = np.exp(-time / 100) * 5  # Simple exponential decay
>>> aif = ArterialInputFunction(
...     time=time,
...     concentration=conc,
...     aif_type=AIFType.POPULATION,
...     population_model="parker",
...     reference="Parker GJM et al. (2006). MRM.",
... )

n_timepoints property

n_timepoints

Return number of time points.

peak_concentration property

peak_concentration

Return peak concentration value.

peak_time property

peak_time

Return time of peak concentration.

__post_init__

__post_init__()

Validate AIF after initialization.

BaseAIF

Bases: BaseComponent

Abstract base class for arterial input function models.

All AIF models (population-based or extraction algorithms) must inherit from this class and implement the required methods.

This enables a consistent interface for using different AIF sources in pharmacokinetic modeling.

Examples:

>>> class MyAIF(BaseAIF):
...     @property
...     def name(self) -> str:
...         return "MyAIF"
...     @property
...     def reference(self) -> str:
...         return "Author et al. (2024)"
...     def __call__(self, t):
...         return np.exp(-t / 100)
...     def get_parameters(self):
...         return {"tau": 100.0}

name abstractmethod property

name

Return human-readable AIF model name.

RETURNS	DESCRIPTION
str	Name of the AIF model.

reference abstractmethod property

reference

Return literature citation for this AIF model.

RETURNS	DESCRIPTION
str	Citation string.

__call__ abstractmethod

__call__(t)

Evaluate AIF at given time points.

PARAMETER	DESCRIPTION
t	Time points in seconds. TYPE: NDArray[floating]

RETURNS	DESCRIPTION
NDArray[floating]	Concentration values at each time point in mM.

get_parameters abstractmethod

get_parameters()

Return current AIF model parameters.

RETURNS	DESCRIPTION
dict[str, float]	Parameter names and values.

to_arterial_input_function

to_arterial_input_function(time)

Convert to ArterialInputFunction dataclass.

PARAMETER	DESCRIPTION
time	Time points at which to evaluate the AIF. TYPE: NDArray[floating]

RETURNS	DESCRIPTION
ArterialInputFunction	AIF data container.