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.30101

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.

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. .. [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).

population

population ¶

PopulationAIFType ¶

ParkerAIFParams dataclass ¶

ParkerAIF ¶

name property ¶

reference property ¶

get_parameters ¶

get_concentration ¶

__call__ ¶

GeorgiouAIFParams dataclass ¶

GeorgiouAIF ¶

name property ¶

reference property ¶

get_parameters ¶

get_concentration ¶

__call__ ¶

FritzHansenAIFParams dataclass ¶

FritzHansenAIF ¶

name property ¶

reference property ¶

get_parameters ¶

get_concentration ¶

__call__ ¶

WeinmannAIFParams dataclass ¶

WeinmannAIF ¶

name property ¶

reference property ¶

get_parameters ¶

get_concentration ¶

__call__ ¶

McGrathAIFParams dataclass ¶

McGrathAIF ¶

name property ¶

reference property ¶

get_parameters ¶

get_concentration ¶

__call__ ¶

register_aif ¶

get_population_aif ¶

list_aifs ¶

parker_aif_curve ¶

ParkerAIFParams `dataclass` ¶

name `property` ¶

reference `property` ¶

call ¶

GeorgiouAIFParams `dataclass` ¶

name `property` ¶

reference `property` ¶

call ¶

FritzHansenAIFParams `dataclass` ¶

name `property` ¶

reference `property` ¶

call ¶

WeinmannAIFParams `dataclass` ¶

name `property` ¶

reference `property` ¶

call ¶

McGrathAIFParams `dataclass` ¶

name `property` ¶

reference `property` ¶

call ¶