fitting

fitting

High-level fitting functions for DCE-MRI analysis.

This module provides user-friendly interfaces for fitting pharmacokinetic models to DCE-MRI data, with automatic parameter estimation, uncertainty quantification, and quality assessment.

Fits OSIPI CAPLEX quantities including: - Ktrans (OSIPI: Q.PH1.008): Volume transfer constant, 1/min - ve (OSIPI: Q.PH1.001): Extravascular extracellular volume fraction, mL/100mL - vp (OSIPI: Q.PH1.001): Plasma volume fraction, mL/100mL - Fp (OSIPI: Q.PH1.002): Plasma flow, mL/min/100mL - PS (OSIPI: Q.PH1.004): Permeability-surface area product, mL/min/100mL

GPU Acceleration Note: This module accepts GPU arrays (CuPy) as input. The default LevenbergMarquardtFitter automatically uses GPU when available, falling back to CPU. No scipy dependency.

References

.. [1] OSIPI CAPLEX, https://osipi.github.io/OSIPI_CAPLEX/ .. [2] Tofts PS et al. J Magn Reson Imaging 1999;10(3):223-232.

DCEFitResult dataclass

DCEFitResult(
    parameter_maps,
    quality_mask,
    model_name,
    r_squared_map=None,
    residual_map=None,
    fitting_stats=dict(),
)

Result container for DCE model fitting.

ATTRIBUTE	DESCRIPTION
parameter_maps	Parameter maps with uncertainty and quality information. TYPE: dict[str, ParameterMap]
quality_mask	Boolean mask indicating successfully fitted voxels. TYPE: NDArray[bool_]
model_name	Name of the fitted model. TYPE: str
r_squared_map	R-squared goodness-of-fit map. TYPE: NDArray[floating] | None
residual_map	Sum of squared residuals per voxel. TYPE: NDArray[floating] | None
fitting_stats	Summary statistics from the fitting process. TYPE: dict[str, Any]

fit_model

fit_model(
    model_name,
    concentration,
    aif,
    time,
    mask=None,
    fitter=None,
    progress_callback=None,
    bounds_override=None,
    fit_delay=False,
)

Fit a named DCE pharmacokinetic model to concentration data.

This is the unified fitting entry point. It looks up the model from the registry and delegates to the shared fitting implementation.

PARAMETER	DESCRIPTION
model_name	Model name: 'tofts', 'extended_tofts', 'patlak', '2cxm', or any name added via register_model(). TYPE: str
concentration	Concentration data, shape (x, y, z, t) or (x, y, t) or (n_voxels, t). TYPE: NDArray[floating]
aif	Arterial input function. Can be an ArterialInputFunction object or a 1D array of concentration values. TYPE: ArterialInputFunction or NDArray[floating]
time	Time points in seconds. TYPE: NDArray[floating]
mask	Optional mask of voxels to fit. If None, fits all voxels. TYPE: NDArray[bool_] | None DEFAULT: None
fitter	Fitter instance or registry name (e.g., 'lm', 'bayesian'). Uses LevenbergMarquardtFitter by default. TYPE: BaseFitter | str | None DEFAULT: None
progress_callback	Optional callback for progress updates. TYPE: Callable[[float], None] | None DEFAULT: None
bounds_override	Optional per-parameter bound overrides. TYPE: dict[str, tuple[float, float]] | None DEFAULT: None
fit_delay	If True, adds an arterial delay parameter to the model and fits it jointly with the other parameters. Default False. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
DCEFitResult	Fitting result with parameter maps, quality mask, and statistics.

RAISES	DESCRIPTION
FittingError	If fitting fails or data is invalid.
DataValidationError	If model name or fitter name is not recognized.

Examples:

>>> import numpy as np
>>> from osipy.dce.fitting import fit_model
>>> from osipy.common.aif import ParkerAIF
>>>
>>> t = np.linspace(0, 300, 60)
>>> aif = ParkerAIF()(t)
>>> concentration = np.random.rand(64, 64, 20, 60)
>>>
>>> result = fit_model("extended_tofts", concentration, aif, t)
>>> ktrans_map = result.parameter_maps["Ktrans"]