pyfli.solver.shared_metrics#

Centralize tau ordering, lifetime summaries, FRET efficiency, and fit-quality metrics.

This module belongs to pyfli.solver and is part of PyFLI least-squares, maximum- likelihood, CPU, GPU, binned, and global FLI fitting routines. Public API includes functions enforce_tau_ordering(), poisson_deviance(), expected_poisson_deviance(), reduced_poisson_deviance(), pearson_chi_square(), compute_fli_stats(), compute_pearson_stats(), compute_average_lifetime(), and compute_fret_efficiency().

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 pearson_chi_square() / compute_pearson_stats().

Functions

`_exact_expected_deviance`(mu)
`compute_average_lifetime`(popt)	Compute average lifetime.
`compute_fli_stats`(final_model, d_fit, n_params)	Compute FLI fit statistics.
`compute_fret_efficiency`(popt)	Compute FRET efficiency.
`compute_pearson_stats`(final_model, d_fit, ...)	`(pearson_chi2, pearson_reduced_chi2)` with the former definition (variance floored at 1 count, dof = n - p), for comparison with earlier results.
`enforce_tau_ordering`(popt[, perr, pcov, bounds])	Enforce tau ordering.
`expected_poisson_deviance`(model)	Expected Poisson deviance `E[2 * (mu - d + d * ln(d / mu))]` of a gate with expected count mu (element-wise), for `d ~ Poisson(mu)`: about `2 mu ln(1/mu)` for `mu -> 0`, peaks near 1.15 at `mu ~ 1` and tends to `1 + 1/(6 mu)` for large `mu`.
`pearson_chi_square`(model, data[, axis])	Pearson chi-square `sum((d - mu)^2 / max(mu, 1))` along axis -- the fit statistic reported before the switch to the Poisson deviance.
`poisson_deviance`(model, data[, axis])	Poisson deviance `2 * sum(mu - d + d * ln(d / mu))` along axis (gates with `d <= 0` contribute `2 * (mu - d)`).
`reduced_poisson_deviance`(model, data, n_params)	`(D, D_reduced)`: the Poisson deviance along axis and the deviance divided by its expectation under the model minus the number of fitted parameters, `D / max(sum E[D_k] - n_params, 1)`, which averages 1 for a correct model.

enforce_tau_ordering(popt, perr=None, pcov=None, bounds=None)[source]#

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 containing the reordered parameter vector and any reordered uncertainty or covariance data.

Return type:

tuple[Any, ]

poisson_deviance(model, data, axis=-1)[source]#

Poisson deviance 2 * sum(mu - d + d * ln(d / mu)) along axis (gates with d <= 0 contribute 2 * (mu - d)). For counts drawn from the model, deviance / (sum E[D_k] - p) averages 1 (see reduced_poisson_deviance()).

Parameters:

model (Any)
data (Any)
axis (int)

Return type:

Any

expected_poisson_deviance(model)[source]#

Expected Poisson deviance E[2 * (mu - d + d * ln(d / mu))] of a gate with expected count mu (element-wise), for d ~ Poisson(mu): about 2 mu ln(1/mu) for mu -> 0, peaks near 1.15 at mu ~ 1 and tends to 1 + 1/(6 mu) for large mu. Tabulated exactly below mu = 10.

Parameters:: model (Any)
Return type:: Any

reduced_poisson_deviance(model, data, n_params, axis=-1)[source]#

(D, D_reduced): the Poisson deviance along axis and the deviance divided by its expectation under the model minus the number of fitted parameters, D / max(sum E[D_k] - n_params, 1), which averages 1 for a correct model.

Parameters:

model (Any)
data (Any)
n_params (int)
axis (int)

Return type:

tuple[Any, Any]

pearson_chi_square(model, data, axis=-1)[source]#

Pearson chi-square sum((d - mu)^2 / max(mu, 1)) along axis – the fit statistic reported before the switch to the Poisson deviance. The variance floor of 1 count makes it read below n - p when many gates hold less than one expected count.

Parameters:

model (Any)
data (Any)
axis (int)

Return type:

Any

compute_fli_stats(final_model, d_fit, n_params)[source]#

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:

(ssr, chi_sq, red_chi_sq, r_sq, rmse): sum of squared residuals, the Poisson deviance (poisson_deviance()), the reduced deviance (reduced_poisson_deviance()), R-squared and RMSE.

Return type:

tuple[Any, ]

compute_pearson_stats(final_model, d_fit, n_params)[source]#

(pearson_chi2, pearson_reduced_chi2) with the former definition (variance floored at 1 count, dof = n - p), for comparison with earlier results.

Parameters:

final_model (ndarray)
d_fit (ndarray)
n_params (int)

Return type:

tuple[float, float]

compute_average_lifetime(popt)[source]#

Compute average lifetime.

Parameters:: popt (np.ndarray) – Optimized model parameter vector.
Returns:: Amplitude-weighted average lifetime for bi-exponential fits or the mono-exponential lifetime.
Return type:: float

compute_fret_efficiency(popt)[source]#

Compute FRET efficiency.

Parameters:: popt (np.ndarray) – Optimized model parameter vector.
Returns:: FRET efficiency estimated from the fitted short and long lifetimes.
Return type:: float