two_compartment

two_compartment

Two-Compartment Exchange Model (2CXM) (OSIPI: M.IC1.009).

This module implements the Two-Compartment Exchange Model for DCE-MRI, which provides a more complete description of tracer kinetics with separate plasma and EES compartments.

GPU/CPU agnostic using the xp array module pattern. NO scipy dependency - uses xp.linalg operations.

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [2] Dickie BR et al. MRM 2024. doi:10.1002/mrm.30101 .. [3] Sourbron SP, Buckley DL. MRM 2011;66(3):735-745. .. [4] Brix G et al. MRM 2004;52(2):420-429.

TwoCompartmentParams dataclass

TwoCompartmentParams(fp=15.0, ps=8.0, ve=0.2, vp=0.02)

Bases: ModelParameters

Parameters for Two-Compartment Exchange Model (OSIPI: M.IC1.009).

ATTRIBUTE	DESCRIPTION
fp	Plasma flow (OSIPI: Q.PH1.002) in mL/min/100mL. TYPE: float
ps	Permeability-surface area product (OSIPI: Q.PH1.004) in mL/min/100mL. TYPE: float
ve	Extravascular extracellular volume fraction (OSIPI: Q.PH1.001), mL/100mL. TYPE: float
vp	Plasma volume fraction (OSIPI: Q.PH1.001), mL/100mL. TYPE: float

TwoCompartmentModel

Bases: BasePerfusionModel[TwoCompartmentParams]

Two-Compartment Exchange Model (OSIPI: M.IC1.009).

Implements the 2CXM with explicit plasma and EES compartments connected by bidirectional exchange.

ATTRIBUTE	DESCRIPTION
Fp	Plasma flow (OSIPI: Q.PH1.002), mL/min/100mL. TYPE: float
PS	Permeability-surface area product (OSIPI: Q.PH1.004), mL/min/100mL. TYPE: float
ve	Extravascular extracellular volume fraction (OSIPI: Q.PH1.001), mL/100mL. TYPE: float
vp	Plasma volume fraction (OSIPI: Q.PH1.001), mL/100mL. TYPE: float

Notes

The tissue concentration is the bi-exponential convolution: Ct(t) = Fp * [A1exp(λ1t) + A2exp(λ2t)] ⊛ Ca(t)

where λ1, λ2 are eigenvalues of the rate matrix and the amplitudes A_i = Fp(λ_i + β)/(λ_i - λ_j) with β = PS/ve + PS/vp account for tracer in both plasma (vpCp) and EES (ve*Ce).

Derived from the coupled ODEs: vpdCp/dt = Fp(Ca - Cp) - PS(Cp - Ce) vedCe/dt = PS*(Cp - Ce)

where: - Cp, Ce are plasma and EES concentrations - Ca is arterial concentration (AIF) - Fp is plasma flow (OSIPI: Q.PH1.002) - PS is permeability-surface area product (OSIPI: Q.PH1.004) - vp, ve are volume fractions (OSIPI: Q.PH1.001)

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

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [2] Dickie BR et al. MRM 2024. doi:10.1002/mrm.30101 .. [3] Sourbron SP, Buckley DL. MRM 2011;66(3):735-745.

time_unit property

time_unit

Return time unit (minutes for 2CXM).

name property

name

Return model name.

parameters property

parameters

Return parameter names.

parameter_units property

parameter_units

Return parameter units.

reference property

reference

Return literature citation.

get_initial_guess_batch

get_initial_guess_batch(ct_batch, aif, t, xp)

Compute vectorized initial guesses for a batch of voxels.

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 (4, n_voxels).

get_bounds

get_bounds()

Return physiological parameter bounds.

get_initial_guess

get_initial_guess(ct, aif, t)

Compute initial parameter guess.

GPU/CPU agnostic - converts to numpy for scalar extraction.

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

RETURNS	DESCRIPTION
TwoCompartmentParams	Initial parameter estimates.