population

population

Population-based arterial input functions.

This module implements standard population AIFs for DCE-MRI analysis, providing consistent reference functions when individual AIF measurement is not possible.

OSIPI CAPLEX model codes: - Parker AIF: M.IC2.001 - Georgiou AIF: M.IC2.002

GPU/CPU agnostic using the xp array module pattern.

References

.. [1] Parker GJM et al. (2006). Experimentally-derived functional form for a population-averaged high-temporal-resolution arterial input function for dynamic contrast-enhanced MRI. Magn Reson Med 56(5):993-1000. .. [2] Georgiou L et al. (2014). A functional form for a representative individual arterial input function. Magn Reson Med 73(3):1241-1249. .. [3] Fritz-Hansen T et al. (1996). Capillary transfer constant of Gd-DTPA in the myocardium at rest and during vasodilation assessed by MRI. Magn Reson Med 35(2):139-144. .. [4] Weinmann HJ et al. (1984). Pharmacokinetics of GdDTPA/dimeglumine after intravenous injection into healthy volunteers. Physiological Chemistry and Physics and Medical NMR 16(2):167-172. .. [5] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [6] Dickie BR et al. MRM 2024. doi:10.1002/mrm.29840

PopulationAIFType

Bases: Enum

Enumeration of available population AIF models.

ParkerAIFParams dataclass

ParkerAIFParams(a1=0.809, t1=0.17046, sigma1=0.0563, a2=0.33, t2=0.365, sigma2=0.132, alpha=1.05, beta=0.1685, s=38.078, tau=0.483)

Parameters for the Parker population AIF.

The Parker AIF is described by: Cb(t) = A1/(σ1√(2π)) * exp(-(t-T1)²/(2σ1²)) + A2/(σ2√(2π)) * exp(-(t-T2)²/(2σ2²)) + α * exp(-β*t) / (1 + exp(-s(t-τ)))

Default values are from Parker et al. (2006).

ParkerAIF

ParkerAIF(params=None)

Bases: BaseAIF

Parker population AIF (OSIPI M.IC2.001).

The Parker AIF is a widely-used population-averaged arterial input function derived from measurements in a cohort of cancer patients. It consists of two Gaussian components (bolus arrival and recirculation) and a modified exponential tail.

Derivation context (Parker 2006, PMID 17036301): the canonical parameters were fit from 23 abdominal cancer patients at 1.5T receiving gadodiamide, across 113 visits. Use with caution outside that regime — 3T, brain / head-and-neck studies, or different contrast agents (e.g. gadobutrol, protein-binding agents) may require a different population AIF (consider GeorgiouAIF, OSIPI M.IC2.002) or a subject-specific measured AIF.

GPU/CPU agnostic - operates on same device as input time array.

References

.. [1] Parker GJM et al. (2006). Magn Reson Med 56(5):993-1000. doi:10.1002/mrm.21066, PMID 17036301. .. [2] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/

Initialize Parker AIF.

PARAMETER	DESCRIPTION
params	Model parameters. Uses published defaults if not provided. TYPE: ParkerAIFParams DEFAULT: None

name property

name

Return AIF model name.

reference property

reference

Return literature citation.

get_parameters

get_parameters()

Return current AIF model parameters.

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

get_concentration

get_concentration(t)

Get AIF concentration values at specified time points.

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

RETURNS	DESCRIPTION
NDArray[floating]	AIF concentration values (mM).

__call__

__call__(t)

Generate AIF at specified time points.

GPU/CPU agnostic - operates on same device as input.

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

RETURNS	DESCRIPTION
ArterialInputFunction	Generated AIF with concentration values.

GeorgiouAIFParams dataclass

GeorgiouAIFParams(a1=0.37, m1=0.11, sigma1=0.055, a2=0.33, m2=0.28, sigma2=0.095, alpha=5.0, beta=0.05)

Parameters for the Georgiou population AIF.

The Georgiou AIF extends the Parker model with improved individual variability handling.

Default values are from Georgiou et al. (2014).

GeorgiouAIF

GeorgiouAIF(params=None)

Bases: BaseAIF

Georgiou population AIF (OSIPI M.IC2.002).

The Georgiou AIF provides a simplified functional form for individual AIF representation, useful for population-based corrections.

GPU/CPU agnostic - operates on same device as input time array.

References

.. [1] Georgiou L et al. (2014). Magn Reson Med 73(3):1241-1249. .. [2] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/

Initialize Georgiou AIF.

PARAMETER	DESCRIPTION
params	Model parameters. Uses published defaults if not provided. TYPE: GeorgiouAIFParams DEFAULT: None

name property

name

Return AIF model name.

reference property

reference

Return literature citation.

get_parameters

get_parameters()

Return current AIF model parameters.

get_concentration

get_concentration(t)

Get AIF concentration values at specified time points.

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

RETURNS	DESCRIPTION
NDArray[floating]	AIF concentration values (mM).

__call__

__call__(t)

Generate AIF at specified time points.

GPU/CPU agnostic - operates on same device as input.

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

RETURNS	DESCRIPTION
ArterialInputFunction	Generated AIF with concentration values.

FritzHansenAIFParams dataclass

FritzHansenAIFParams(a1=3.99, m1=0.144, a2=4.78, m2=0.0111)

Parameters for the Fritz-Hansen population AIF.

The Fritz-Hansen AIF uses a bi-exponential model commonly used for cardiac perfusion studies.

Default values are from Fritz-Hansen et al. (1996).

FritzHansenAIF

FritzHansenAIF(params=None)

Bases: BaseAIF

Fritz-Hansen population AIF.

The Fritz-Hansen AIF is a bi-exponential model originally developed for cardiac MRI studies. It provides a simpler representation suitable for myocardial perfusion analysis.

GPU/CPU agnostic - operates on same device as input time array.

References

Fritz-Hansen T et al. (1996). Magn Reson Med 35(2):139-144.

Initialize Fritz-Hansen AIF.

PARAMETER	DESCRIPTION
params	Model parameters. Uses published defaults if not provided. TYPE: FritzHansenAIFParams DEFAULT: None

name property

name

Return AIF model name.

reference property

reference

Return literature citation.

get_parameters

get_parameters()

Return current AIF model parameters.

get_concentration

get_concentration(t)

Get AIF concentration values at specified time points.

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

RETURNS	DESCRIPTION
NDArray[floating]	AIF concentration values (mM).

__call__

__call__(t)

Generate AIF at specified time points.

GPU/CPU agnostic - operates on same device as input.

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

RETURNS	DESCRIPTION
ArterialInputFunction	Generated AIF with concentration values.

WeinmannAIFParams dataclass

WeinmannAIFParams(a1=3.99, m1=0.144, a2=4.78, m2=0.0111, dose=0.1)

Parameters for the Weinmann population AIF.

The Weinmann AIF uses a bi-exponential model for Gd-DTPA clearance.

Default values are from Weinmann et al. (1984).

WeinmannAIF

WeinmannAIF(params=None)

Bases: BaseAIF

Weinmann population AIF.

The Weinmann AIF is a bi-exponential model describing the pharmacokinetics of Gd-DTPA after intravenous injection. It is one of the earliest population AIFs and is still widely used as a reference.

GPU/CPU agnostic - operates on same device as input time array.

References

Weinmann HJ et al. (1984). Physiological Chemistry and Physics and Medical NMR 16(2):167-172.

Initialize Weinmann AIF.

PARAMETER	DESCRIPTION
params	Model parameters. Uses published defaults if not provided. TYPE: WeinmannAIFParams DEFAULT: None

name property

name

Return AIF model name.

reference property

reference

Return literature citation.

get_parameters

get_parameters()

Return current AIF model parameters.

get_concentration

get_concentration(t)

Get AIF concentration values at specified time points.

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

RETURNS	DESCRIPTION
NDArray[floating]	AIF concentration values (mM).

__call__

__call__(t)

Generate AIF at specified time points.

GPU/CPU agnostic - operates on same device as input.

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

RETURNS	DESCRIPTION
ArterialInputFunction	Generated AIF with concentration values.

McGrathAIFParams dataclass

McGrathAIFParams(a_gv=4.0, alpha=2.0, tau=0.15, a_exp=0.5, beta=0.1)

Parameters for the McGrath preclinical population AIF.

The McGrath AIF is modeled as a gamma-variate plus exponential washout: Cp(t) = A * (t/tau)^alpha * exp(-(t - tau)/tau) * H(t) + B * exp(-beta * t) * H(t)

Default values are from McGrath DM et al. (2009), Table 1, Model B. Designed for small animal (rodent) DCE-MRI studies.

McGrathAIF

McGrathAIF(params=None)

Bases: BaseAIF

McGrath preclinical population AIF.

A population AIF for small animal (rodent) DCE-MRI studies, modeled as a gamma-variate plus exponential washout.

GPU/CPU agnostic - operates on same device as input time array.

References

.. [1] McGrath DM et al. (2009). Magn Reson Med 61(5):1173-1184.

Initialize McGrath AIF.

PARAMETER	DESCRIPTION
params	Model parameters. Uses published defaults if not provided. TYPE: McGrathAIFParams DEFAULT: None

name property

name

Return AIF model name.

reference property

reference

Return literature citation.

get_parameters

get_parameters()

Return current AIF model parameters.

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

get_concentration

get_concentration(t)

Get AIF concentration values at specified time points.

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

RETURNS	DESCRIPTION
NDArray[floating]	AIF concentration values (mM).

__call__

__call__(t)

Generate AIF at specified time points.

GPU/CPU agnostic - operates on same device as input.

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

RETURNS	DESCRIPTION
ArterialInputFunction	Generated AIF with concentration values.

register_aif

register_aif(name)

Decorator to register a population AIF model.

Registers a BaseAIF subclass in AIF_REGISTRY so it can be looked up by name via get_population_aif().

PARAMETER	DESCRIPTION
name	Registry key for the AIF (e.g. 'my_aif'). TYPE: str

RETURNS	DESCRIPTION
Callable	Class decorator.

Examples:

>>> from osipy.common.aif.population import register_aif
>>> from osipy.common.aif.base import BaseAIF
>>> @register_aif("custom")
... class CustomAIF(BaseAIF):
...     # implement abstract methods ...
...     pass

get_population_aif

get_population_aif(aif_type)

Get a population AIF model instance.

PARAMETER	DESCRIPTION
aif_type	Type of population AIF: 'parker', 'georgiou', 'fritz_hansen', 'weinmann', or any name added via register_aif(). TYPE: str or PopulationAIFType

RETURNS	DESCRIPTION
BaseAIF	AIF model instance.

RAISES	DESCRIPTION
AIFError	If AIF type is not recognized.

list_aifs

list_aifs()

Return names of all registered AIF models.

Returns only canonical names, filtering out aliases (e.g. hyphenated variants like 'fritz-hansen').

RETURNS	DESCRIPTION
list[str]	Sorted list of registered AIF names.

parker_aif_curve

parker_aif_curve(t, params=None)

Compute Parker AIF concentration values directly.

Convenience function that returns just the concentration array without wrapping in an ArterialInputFunction object.

GPU/CPU agnostic - operates on same device as input.

PARAMETER	DESCRIPTION
t	Time points in seconds. TYPE: NDArray[floating]
params	Model parameters. Uses published defaults if not provided. TYPE: ParkerAIFParams DEFAULT: None

RETURNS	DESCRIPTION
NDArray[floating]	AIF concentration values (mM).