"""
Centralize tau ordering, lifetime summaries, FRET efficiency, and fit-quality metrics.
This module belongs to :mod:`pyfli.cm_stats` and is shared by the PyFLI solver,
reconstruction, Laguerre, and simulator-calibration packages. Public API includes
functions :func:`enforce_tau_ordering`, :func:`poisson_deviance`,
:func:`expected_poisson_deviance`, :func:`reduced_poisson_deviance`,
:func:`pearson_chi_square`, :func:`compute_fli_stats`, :func:`compute_pearson_stats`,
:func:`compute_average_lifetime`, and :func:`compute_fret_efficiency`. The deviance,
Pearson and residual statistics themselves are defined in :mod:`.deviance`,
:mod:`.chi_square` and :mod:`.goodness_of_fit` and re-exported here.
Goodness of fit is reported as the Poisson deviance ``D`` (the likelihood-ratio
statistic for photon counts). At low counts the expected deviance of a gate is not 1
(about 0.47 at 0.1 expected counts, 1.15 at 1), so the reduced value divides ``D`` by
its expectation under the fitted model, ``sum_k E[D_k](mu_k) - p`` (Kaastra 2017,
A&A 605, A51), instead of ``n - p``; it averages 1 for a correct model at any count
level. The former Pearson statistic, whose variance is floored at 1 count and which
therefore reads below 1 whenever many gates hold less than one expected count, is
still available as :func:`pearson_chi_square` / :func:`compute_pearson_stats`.
"""
from typing import Any
import numpy as np
from .chi_square import degrees_of_freedom, pearson_chi_square
from .deviance import (
expected_poisson_deviance,
poisson_deviance,
reduced_poisson_deviance,
)
from .goodness_of_fit import r_squared, rmse, sum_squared_residuals
__all__ = [
"compute_average_lifetime",
"compute_fli_stats",
"compute_fret_efficiency",
"compute_pearson_stats",
"enforce_tau_ordering",
"expected_poisson_deviance",
"pearson_chi_square",
"poisson_deviance",
"reduced_poisson_deviance",
]
_FIXED_BOUND_TOL = 1e-5
[docs]
def enforce_tau_ordering(
popt: np.ndarray,
perr: Any | None = None,
pcov: np.ndarray | None = None,
bounds: tuple[np.ndarray, np.ndarray] | None = None,
) -> tuple[Any, ...]:
"""
Enforce tau ordering.
Parameters
----------
popt : np.ndarray
Optimized model parameter vector.
perr : Any | None
One-standard-deviation parameter uncertainty estimates.
pcov : np.ndarray | None
Parameter covariance matrix.
bounds : tuple[np.ndarray, np.ndarray] | None
Optional (low, high) bound vectors used for the fit. When either tau1 or tau2
was pinned by the caller (low == high), that parameter's slot is left alone.
Returns
-------
tuple[Any, ...]
Tuple containing the reordered parameter vector and any reordered uncertainty or covariance data.
"""
popt = np.asarray(popt, dtype=float)
if bounds is not None:
low, high = bounds
tau1_fixed = abs(float(high[2]) - float(low[2])) < _FIXED_BOUND_TOL
tau2_fixed = abs(float(high[3]) - float(low[3])) < _FIXED_BOUND_TOL
if tau1_fixed or tau2_fixed:
return popt, perr, pcov
if popt[1] > 0.999:
popt[1], popt[3] = 1.0, popt[2]
elif popt[1] < 0.001:
popt[1], popt[2] = 0.0, popt[3]
if popt[2] > popt[3]:
popt[2], popt[3] = popt[3], popt[2]
popt[1] = 1.0 - popt[1]
if perr is not None:
perr = np.asarray(perr, dtype=float)
perr[2], perr[3] = perr[3], perr[2]
if pcov is not None:
pcov[[2, 3], :] = pcov[[3, 2], :]
pcov[:, [2, 3]] = pcov[:, [3, 2]]
return popt, perr, pcov
[docs]
def compute_fli_stats(
final_model: np.ndarray, d_fit: np.ndarray, n_params: int
) -> tuple[Any, ...]:
"""
Compute FLI fit statistics.
Parameters
----------
final_model : np.ndarray
Model decay evaluated at the fitted parameters.
d_fit : np.ndarray
Measured decay samples over the fitted range.
n_params : int
Number of fitted model parameters.
Returns
-------
tuple[Any, ...]
``(ssr, chi_sq, red_chi_sq, r_sq, rmse)``: sum of squared residuals, the
Poisson deviance (:func:`poisson_deviance`), the reduced deviance
(:func:`reduced_poisson_deviance`), R-squared and RMSE.
"""
residuals = final_model - d_fit
ssr = float(sum_squared_residuals(residuals, axis=None))
chi_sq, red_chi_sq = reduced_poisson_deviance(final_model, d_fit, n_params)
chi_sq, red_chi_sq = float(chi_sq), float(red_chi_sq)
r_sq = float(r_squared(residuals, d_fit, axis=None))
return ssr, chi_sq, red_chi_sq, r_sq, float(rmse(residuals, axis=None))
[docs]
def compute_pearson_stats(
final_model: np.ndarray, d_fit: np.ndarray, n_params: int
) -> tuple[float, float]:
"""
``(pearson_chi2, pearson_reduced_chi2)`` with the former definition (variance
floored at 1 count, dof = n - p), for comparison with earlier results.
"""
chi = float(pearson_chi_square(final_model, d_fit))
return chi, chi / degrees_of_freedom(len(d_fit), n_params)
[docs]
def compute_average_lifetime(popt: np.ndarray) -> float:
"""
Compute average lifetime.
Parameters
----------
popt : np.ndarray
Optimized model parameter vector.
Returns
-------
float
Amplitude-weighted average lifetime for bi-exponential fits or the mono-exponential lifetime.
"""
if len(popt) == 6:
return float(popt[1] * popt[2] + (1.0 - popt[1]) * popt[3])
return float(popt[1])
[docs]
def compute_fret_efficiency(popt: np.ndarray) -> float:
"""
Compute FRET efficiency.
Parameters
----------
popt : np.ndarray
Optimized model parameter vector.
Returns
-------
float
FRET efficiency estimated from the fitted short and long lifetimes.
"""
if len(popt) == 6:
tau1, tau2 = popt[2], popt[3]
if tau2 > 0:
return float(1.0 - tau1 / tau2)
return 0.0