# solver/mle_fitter.py
"""
Extend the base fitter with Poisson and chi-square maximum-likelihood estimators.
This module belongs to :mod:`pyfli.solver` and is part of PyFLI least-squares, maximum-
likelihood, CPU, GPU, binned, and global FLI fitting routines. Public API includes
classes :class:`MLEFLIFitter`.
"""
from typing import Any
import numpy as np
from scipy.optimize import minimize
from scipy.stats import chi2
from ..cm_funcs.forward_model import validate_model_type
from ..cm_stats import chi_square as _chi_square
from ..cm_stats.deviance import poisson_deviance
from ..cm_stats.goodness_of_fit import sum_squared_residuals
from ..cm_stats.model_comparison import nested_f_test
from ..cm_stats.shared_metrics import (
_FIXED_BOUND_TOL,
compute_fli_stats,
enforce_tau_ordering,
)
from .base_fitter import BaseFLIFitter
from .base_static import resolve_params_and_bounds
MLE_WEIGHTINGS = ("poisson", "pearson", "neyman", "none")
"""Objectives of :meth:`MLEFLIFitter.fit_with_estimator` (``"poisson"`` is the default)."""
[docs]
class MLEFLIFitter(BaseFLIFitter):
"""
Extend the base FLI fitter with Poisson, Pearson, and Neyman objective functions.
It supports MLE-style fitting, Fisher-information (Poisson) and robust sandwich
(chi-square) parameter uncertainties, and likelihood-based model comparison.
"""
[docs]
def poisson_log_likelihood(self, params: Any, model_type: str) -> Any:
"""Standard Poisson MLE (Deviance/C-Statistic)."""
model = self.model_fit(self.t, params, model_type=model_type)[self.fit_indices]
if not np.all(np.isfinite(model)):
return np.inf
data = self.decay[self.fit_indices]
val = poisson_deviance(
model, data, axis=None, floor=1e-9, nonpositive="floor", data_floor=1e-9
)
return val if np.isfinite(val) else np.inf
[docs]
def pearson_chi_square(self, params: Any, model_type: str) -> np.ndarray:
"""Pearson's Chi-square: Weighted by the MODEL [1/y_model]."""
model = self.model_fit(self.t, params, model_type=model_type)[self.fit_indices]
data = self.decay[self.fit_indices]
model = np.clip(model, 1e-9, None)
return _chi_square.pearson_chi_square(model, data, axis=None, floor=1e-9)
[docs]
def neyman_chi_square(self, params: Any, model_type: str) -> np.ndarray:
"""Neyman's Chi-square: Weighted by the DATA [1/y_data]."""
model = self.model_fit(self.t, params, model_type=model_type)[self.fit_indices]
data = self.decay[self.fit_indices]
return _chi_square.neyman_chi_square(model, data, axis=None)
[docs]
def unweighted_sum_of_squares(self, params: Any, model_type: str) -> np.ndarray:
"""Unweighted sum of squared residuals (every gate counts equally)."""
model = self.model_fit(self.t, params, model_type=model_type)[self.fit_indices]
data = self.decay[self.fit_indices]
return sum_squared_residuals(data - model, axis=None)
[docs]
def fit_with_estimator(
self,
estimator_type: str = "poisson",
model_type: str = "bi-exponential",
p0: Any | None = None,
bounds: np.ndarray | None = None,
weighting: str | None = None,
**kwargs: Any,
) -> Any:
"""
Main interface for MLE/Chi-square fitting, with the same argument order as
:meth:`pyfli.solver.base_fitter.BaseFLIFitter.fit_with_estimator`:
``(estimator_type, model_type, p0, bounds, ...)``.
Parameters
----------
estimator_type : str
Objective name (``"poisson"``, ``"pearson"`` or ``"neyman"``); used when
`weighting` is not given. Unknown names fall back to ``"poisson"``.
model_type : str
``"mono-exponential"`` or ``"bi-exponential"``.
p0, bounds : Any
Initial parameters and bounds (see :func:`resolve_params_and_bounds`).
weighting : str | None
Objective to minimize (see :data:`MLE_WEIGHTINGS`); overrides
`estimator_type`:
- ``"poisson"`` (default): Poisson deviance -- the maximum-likelihood
estimator for photon counts; the consistent, least-biased choice.
- ``"pearson"``: ``sum (d - mu)^2 / mu`` minimized directly. Because the
weights move with the model, it is biased towards larger model values
(for decays, longer lifetimes) at low counts.
- ``"neyman"``: ``sum (d - mu)^2 / max(d, 1)``; biased towards low
counts (shorter lifetimes) at low counts.
- ``"none"``: unweighted sum of squares.
**kwargs : Any
``max_iter`` (or ``maxiter``, default 2000) optimizer iterations,
``maxfun`` (default 50000), ``ftol`` and ``gtol``.
"""
validate_model_type(model_type)
if weighting is None:
weighting = (
estimator_type if estimator_type in MLE_WEIGHTINGS else "poisson"
)
elif weighting not in MLE_WEIGHTINGS:
raise ValueError(
f"weighting must be one of {MLE_WEIGHTINGS}, got {weighting!r}"
)
# Call the external static logic to merge guesses and bounds
p0_safe, (l_vec, h_vec) = resolve_params_and_bounds(
p0,
bounds,
model_type,
self.t,
self.decay,
self.T_laser,
self.guess_plugin,
self.T_acq,
)
bnds = list(zip(l_vec, h_vec))
funcs = {
"poisson": self.poisson_log_likelihood,
"pearson": self.pearson_chi_square,
"neyman": self.neyman_chi_square,
"none": self.unweighted_sum_of_squares,
}
obj_func = funcs[weighting]
scale = np.maximum(np.abs(p0_safe), 1.0)
res = minimize(
lambda z, mt: obj_func(z * scale, mt),
x0=p0_safe / scale,
args=(model_type,),
bounds=[(lo / s, hi / s) for (lo, hi), s in zip(bnds, scale)],
method="L-BFGS-B",
options={
"ftol": kwargs.get("ftol", 1e-12),
"gtol": kwargs.get("gtol", 1e-9),
"maxfun": kwargs.get("maxfun", 50000),
"maxiter": kwargs.get("max_iter", kwargs.get("maxiter", 2000)),
},
)
popt = res.x * scale
converged = 1 if res.success else 0
try:
perr = self.parameter_errors(
popt, model_type, weighting=weighting, bounds=(l_vec, h_vec)
)
except Exception:
perr = np.full(len(popt), np.nan)
return self._post_process(
popt, None, converged, model_type, manual_perr=perr, bounds=(l_vec, h_vec)
)
[docs]
def parameter_errors(
self,
popt: np.ndarray,
model_type: str,
weighting: str = "poisson",
bounds: tuple[np.ndarray, np.ndarray] | None = None,
) -> np.ndarray:
"""
One-standard-deviation uncertainties of parameters fitted with `weighting`.
``"poisson"`` uses the inverse Fisher information ``(J^T diag(1/mu) J)^-1`` of
the Poisson likelihood at `popt`, i.e. the asymptotic covariance (and
Cramer-Rao bound) of the MLE. ``"pearson"``, ``"neyman"`` and ``"none"`` use
the heteroscedasticity-robust sandwich of :meth:`calculate_uncertainties` on
the weighted Jacobian and residuals.
Parameters
----------
popt : np.ndarray
Fitted parameter vector (before tau ordering).
model_type : str
``"mono-exponential"`` or ``"bi-exponential"``.
weighting : str
Objective the parameters were fitted with (see :data:`MLE_WEIGHTINGS`).
bounds : tuple[np.ndarray, np.ndarray] | None
``(low, high)`` bounds of the fit. Parameters pinned by them
(low == high) get 0; parameters sitting on an active bound get NaN,
because the asymptotic normal approximation does not hold there. The
remaining uncertainties are computed with those parameters held fixed.
Returns
-------
np.ndarray
Standard error of each parameter.
"""
popt = np.asarray(popt, dtype=float)
n_params = len(popt)
if bounds is None:
low = np.full(n_params, -np.inf)
high = np.full(n_params, np.inf)
else:
low = np.asarray(bounds[0], dtype=float)
high = np.asarray(bounds[1], dtype=float)
width = np.maximum(np.abs(popt), 1.0)
pinned = np.abs(high - low) < _FIXED_BOUND_TOL
on_bound = ~pinned & (
(popt - low <= 1e-8 * width) | (high - popt <= 1e-8 * width)
)
perr = np.full(n_params, np.nan)
perr[pinned] = 0.0
free = np.flatnonzero(~pinned & ~on_bound)
if free.size == 0:
return perr
data = self.decay[self.fit_indices]
mu = self.model_fit(self.t, popt, model_type=model_type)[self.fit_indices]
jac = np.empty((len(data), free.size))
for j, k in enumerate(free):
step = 1e-6 * width[k]
up, down = popt.copy(), popt.copy()
up[k] = min(popt[k] + step, high[k])
down[k] = max(popt[k] - step, low[k])
jac[:, j] = (
self.model_fit(self.t, up, model_type=model_type)[self.fit_indices]
- self.model_fit(self.t, down, model_type=model_type)[self.fit_indices]
) / (up[k] - down[k])
if weighting == "poisson":
info = jac.T @ (jac / np.clip(mu, 1e-9, None)[:, None])
diag = np.diag(info)
norm = np.sqrt(np.where(diag > 0, diag, 1.0))
cov = np.linalg.pinv(info / np.outer(norm, norm)) / np.outer(norm, norm)
perr[free] = np.where(
diag > 0, np.sqrt(np.maximum(np.diag(cov), 0.0)), np.nan
)
return perr
if weighting == "pearson":
weights = 1.0 / np.clip(mu, 1e-9, None)
elif weighting == "neyman":
weights = 1.0 / np.clip(data, 1.0, None)
else:
weights = np.ones_like(data, dtype=float)
root_w = np.sqrt(weights)
residuals = (data - mu) * root_w
perr[free] = self.calculate_uncertainties(
jac * root_w[:, None],
float(np.sum(residuals**2)),
len(data),
free.size,
residuals=residuals,
)
return perr
def _post_process(
self,
popt: np.ndarray,
jac: Any,
status: np.ndarray,
model_type: str,
pcov: np.ndarray | None = None,
manual_stat: np.ndarray | None = None,
manual_perr: np.ndarray | None = None,
bounds: np.ndarray | None = None,
) -> tuple[Any, ...]:
"""
Compatible post-processor that enforces tau1 <= tau2 and handles MLE-specific statistics.
"""
if model_type == "bi-exponential":
popt, manual_perr, _ = enforce_tau_ordering(
popt, perr=manual_perr, bounds=bounds
)
data = self.decay[self.fit_indices]
final_model = self.model_fit(self.t, popt, model_type=model_type)[
self.fit_indices
]
ssr, chi_sq, red_chi_sq, r_sq, rmse = compute_fli_stats(
final_model, data, len(popt)
)
perr = manual_perr if manual_perr is not None else np.full(len(popt), np.nan)
return popt, perr, r_sq, chi_sq, red_chi_sq, ssr, (1 if status > 0 else 0), rmse
[docs]
def compare_models(
self, alpha: float = 0.05, estimator: str = "poisson"
) -> tuple[Any, ...]:
"""
Statistical model selection.
- Poisson: Uses Likelihood Ratio Test (LRT) on Deviance.
- Chi-square/LS: Uses F-test on the reported chi-square (res[3], the Poisson
deviance from compute_fli_stats).
"""
res_m = self.fit_with_estimator(estimator, model_type="mono-exponential")
res_b = self.fit_with_estimator(estimator, model_type="bi-exponential")
if estimator == "poisson":
# LRT: Difference in Deviance follows a Chi-square distribution
dev_m = self.poisson_log_likelihood(res_m[0], "mono-exponential")
dev_b = self.poisson_log_likelihood(res_b[0], "bi-exponential")
LRT_stat = max(dev_m - dev_b, 0.0)
p_val = 1.0 - chi2.cdf(LRT_stat, df=2)
else:
n, p_m, p_b = len(self.fit_indices), 4, 6
_, p_val = nested_f_test(
res_m[3], res_b[3], p_b - p_m, n - p_b, p_value="cdf"
)
winner = res_b if p_val < alpha else res_m
return (
"bi-exponential" if p_val < alpha else "mono-exponential",
winner[0],
winner[1],
winner[2],
winner[4],
p_val,
)