base

base

Base class for pharmacokinetic perfusion models.

This module provides the abstract base class for all DCE/DSC pharmacokinetic models following the OSIPI CAPLEX lexicon.

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [2] Tofts PS et al. J Magn Reson Imaging 1999;10(3):223-232. .. [3] Sourbron SP, Buckley DL. MRM 2011;66(3):735-745.

ModelParameters dataclass

ModelParameters()

Base class for model parameter dataclasses.

BasePerfusionModel

Bases: BaseSignalModel

Abstract base class for perfusion pharmacokinetic models.

All DCE/DSC models must inherit from this class and implement the required methods.

Notes

Type parameter P is a ModelParameters dataclass type for model-specific parameters.

Examples:

>>> class ToftsParams(ModelParameters):
...     ktrans: float
...     ve: float
>>> class ToftsModel(BasePerfusionModel[ToftsParams]):
...     # Implementation
...     pass

References

All implementations MUST include primary literature reference.

time_unit property

time_unit

Return the time unit used internally by this model.

RETURNS	DESCRIPTION
str	"seconds" or "minutes".

name abstractmethod property

name

Return human-readable model name.

RETURNS	DESCRIPTION
str	Model name for display and logging.

parameters abstractmethod property

parameters

Return list of parameter names following OSIPI terminology.

RETURNS	DESCRIPTION
list[str]	Parameter names (e.g., ['Ktrans', 've', 'vp']).

predict

predict(t, aif, params, xp=None)

Predict tissue concentration given parameters.

Accepts both dict/dataclass and array parameters transparently.

PARAMETER	DESCRIPTION
t	Time points in seconds. TYPE: NDArray[floating]
aif	Arterial input function concentration. TYPE: NDArray[floating]
params	Parameter array (n_params,) / (n_params, n_voxels), or a dict / dataclass that will be converted automatically. TYPE: NDArray or dict or ModelParameters
xp	Array module (numpy or cupy). Inferred from t when omitted. TYPE: module DEFAULT: None

RETURNS	DESCRIPTION
NDArray[floating]	Predicted tissue concentration.

get_bounds abstractmethod

get_bounds()

Return physiological parameter bounds.

RETURNS	DESCRIPTION
dict[str, tuple[float, float]]	Mapping of parameter names to (lower, upper) bounds.

get_initial_guess abstractmethod

get_initial_guess(ct, aif, t)

Compute initial parameter guess from data.

PARAMETER	DESCRIPTION
ct	Tissue concentration curve. TYPE: NDArray[floating]
aif	Arterial input function. TYPE: NDArray[floating]
t	Time points. TYPE: NDArray[floating]

RETURNS	DESCRIPTION
P	Initial parameter estimates.

get_initial_guess_batch

get_initial_guess_batch(ct_batch, aif, t, xp)

Compute initial parameter guesses for a batch of voxels.

Default implementation loops over voxels using get_initial_guess(). Subclasses should override with vectorized implementations.

PARAMETER	DESCRIPTION
ct_batch	Tissue concentration curves, shape (n_timepoints, n_voxels). TYPE: NDArray[floating]
aif	Arterial input function, shape (n_timepoints,). TYPE: NDArray[floating]
t	Time points in seconds, shape (n_timepoints,). TYPE: NDArray[floating]
xp	Array module (numpy or cupy). TYPE: module

RETURNS	DESCRIPTION
NDArray[floating]	Initial parameter guesses, shape (n_params, n_voxels).

predict_batch

predict_batch(t, aif, params_batch, xp)

Predict tissue concentration for multiple voxels simultaneously.

Reshapes t and aif to column vectors and delegates to :meth:predict, which uses broadcasting to handle the batch dimension automatically. No per-voxel loop is needed.

PARAMETER	DESCRIPTION
t	Time points in seconds, shape (n_timepoints,). TYPE: NDArray[floating]
aif	Arterial input function, shape (n_timepoints,) or (n_timepoints, n_voxels) for per-voxel shifted AIFs. TYPE: NDArray[floating]
params_batch	Parameter values for all voxels, shape (n_params, n_voxels). Row order must match self.parameters. TYPE: NDArray[floating]
xp	Array module to use (numpy or cupy). TYPE: module

RETURNS	DESCRIPTION
NDArray[floating]	Predicted tissue concentrations, shape (n_timepoints, n_voxels).