result

result

FittingResult dataclass for model fitting results.

This module provides the data container for storing results from pharmacokinetic model fitting, including parameters, goodness-of-fit metrics, and convergence information.

FittingResult dataclass

FittingResult(
    parameters,
    uncertainties=None,
    residuals=(lambda: array([]))(),
    r_squared=0.0,
    chi_squared=None,
    aic=None,
    converged=False,
    n_iterations=0,
    termination_reason="",
    model_name="",
    initial_guess=dict(),
    bounds=dict(),
)

Results from pharmacokinetic model fitting.

This dataclass contains the fitted parameters, goodness-of-fit metrics, and convergence information for a single voxel or ROI fit.

ATTRIBUTE	DESCRIPTION
parameters	Fitted parameter values. Keys are OSIPI-standard parameter names. TYPE: dict[str, float]
uncertainties	Standard errors for each parameter, if computed. TYPE: dict[str, float] | None
residuals	Fit residuals (observed - predicted). TYPE: NDArray[floating]
r_squared	Coefficient of determination (R²). TYPE: float
chi_squared	Chi-squared statistic, if weights were provided. TYPE: float | None
aic	Akaike Information Criterion. TYPE: float | None
converged	Whether the fit converged successfully. TYPE: bool
n_iterations	Number of iterations performed. TYPE: int
termination_reason	Reason for termination ('converged', 'max_iter', 'tolerance'). TYPE: str
model_name	Name of the model that was fitted. TYPE: str
initial_guess	Initial parameter values used. TYPE: dict[str, float]
bounds	Parameter bounds that were applied. TYPE: dict[str, tuple[float, float]]

Examples:

>>> import numpy as np
>>> from osipy.common.fitting.result import FittingResult
>>> result = FittingResult(
...     parameters={"Ktrans": 0.15, "ve": 0.3, "vp": 0.02},
...     residuals=np.random.randn(60) * 0.01,
...     r_squared=0.95,
...     converged=True,
...     n_iterations=15,
...     termination_reason="converged",
...     model_name="ExtendedTofts",
...     initial_guess={"Ktrans": 0.1, "ve": 0.2, "vp": 0.01},
...     bounds={"Ktrans": (0, 5), "ve": (0, 1), "vp": (0, 0.2)},
... )

is_valid property

is_valid

Return True if fit converged with reasonable R².

rmse property

rmse

Return root mean squared error of residuals.

n_parameters property

n_parameters

Return number of fitted parameters.

get_parameter

get_parameter(name, default=nan)

Get a parameter value by name.

PARAMETER	DESCRIPTION
name	Parameter name. TYPE: str
default	Default value if parameter not found. TYPE: float DEFAULT: nan

RETURNS	DESCRIPTION
float	Parameter value.

get_uncertainty

get_uncertainty(name, default=nan)

Get uncertainty for a parameter by name.

PARAMETER	DESCRIPTION
name	Parameter name. TYPE: str
default	Default value if uncertainty not available. TYPE: float DEFAULT: nan

RETURNS	DESCRIPTION
float	Uncertainty value.