pyfli.solver.base_fitter#
Implement the shared least-squares FLI fitter used by CPU, GPU, and model-comparison workflows.
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
classes BaseFLIFitter.
Module Attributes
Residual weightings of |
Classes
|
Run the base flifitter routine. |
- NLSF_WEIGHTINGS = ('irls', 'none', 'neyman')#
Residual weightings of
BaseFLIFitter.least_squares_fit().
- class BaseFLIFitter(freq, decay_px, irf_px, white_noise=0.1, guess_plugin=moment_based_guess, custom_funcs=None, shift_method='zero_pad', fit_indices=None)[source]#
Bases:
objectRun the base flifitter routine. base class handles model construction, fit ranges, parameter guesses, bounds, post- processing, and model comparison support.
- Parameters:
freq (
float) – Acquisition frequency information used to derive timing constants.decay_px (
np.ndarray) – Per-pixel fluorescence decay trace supplied to the fitter.irf_px (
np.ndarray) – Per-pixel instrument response function supplied to the fitter.white_noise (
float) – White-noise estimate used to weight residuals.guess_plugin (
np.ndarray) – Optional callable that supplies initial parameter guesses.custom_funcs (
np.ndarray | None) – Optional custom model functions used by the fitter.shift_method (
str) – Method used to align the IRF and decay traces.fit_indices (
tuple[int,int] | None) – Optional (gate_num_start, gate_num_end) gate range to fit over, e.g. to focus on the tail of the decay.Nonefits the full trace.
- fit_with_estimator(estimator_type='least_squares', model_type='bi-exponential', p0=None, bounds=None, **kwargs)[source]#
Unified entry point for all NLSF estimators.
- least_squares_fit(p0, bounds, model_type, weighting='irls', use_weights=None, **kwargs)[source]#
Weighted non-linear least-squares fit,
min sum_k w_k (mu_k - d_k)^2.- Parameters:
p0 (
Any) – Initial parameter vector supplied to the optimizer.bounds (
np.ndarray) – Lower and upper parameter bounds supplied to the optimizer.model_type (
str) – FLI model family, such as mono- or bi-exponential.weighting (
str) –How the residual weights
w_kare chosen (seeNLSF_WEIGHTINGS):"irls"(default): iteratively reweighted least squares. Each round solves with the weights frozen at1 / max(mu_k, variance_floor)from the previous round’s model, until the parameters stop changing. At convergencesum_k (d_k - mu_k) / mu_k * dmu_k/dtheta = 0, the Poisson likelihood equations, so photon-count data gets MLE-equivalent (unbiased) estimates."none": unweighted; nearly unbiased but less precise for Poisson data, since every gate counts equally."neyman": weights1 / max(d_k, 1)from the measured data (Neyman chi-square). Biased towards low counts – for decays, towards short lifetimes, increasingly so at low photon counts. Kept only to reproduce results of earlier PyFLI versions.
use_weights (
bool | None) – Deprecated:Truemeansweighting="neyman"(the former default) andFalsemeansweighting="none".**kwargs (
Any) –max_iter/maxiter(function evaluations per solve),ftol,xtol, and for IRLSirls_max_rounds(default 20),irls_tol(relative parameter change for convergence, default 1e-6) andvariance_floor(default 1.0 counts).
- Returns:
Object produced by least squares fit.
- Return type:
Any
- trust_region(p0, bounds, model_type, **kwargs)[source]#
Run the trust region routine.
- Parameters:
p0 (
Any) – Initial parameter vector supplied to the optimizer.bounds (
np.ndarray) – Lower and upper parameter bounds supplied to the optimizer.model_type (
str) – FLI model family, such as mono- or bi-exponential.**kwargs (
Any) – Additional keyword options forwarded to the underlying implementation.
- Returns:
Object produced by trust region.
- Return type:
Any
- unconstrained(p0, bounds, model_type, **kwargs)[source]#
Run the unconstrained routine.
- Parameters:
p0 (
Any) – Initial parameter vector supplied to the optimizer.bounds (
np.ndarray) – Lower and upper parameter bounds supplied to the optimizer.model_type (
str) – FLI model family, such as mono- or bi-exponential.**kwargs (
Any) – Additional keyword options forwarded to the underlying implementation.
- Returns:
Object produced by unconstrained.
- Return type:
Any
- model_fit(t, params, model_type='mono-exponential')[source]#
Run the model fit routine.
- Parameters:
t (
np.ndarray) – Time axis or acquisition period used by the calculation.params (
Any) – Model, detector, or plotting parameters used by the routine.model_type (
str) – FLI model family, such as mono- or bi-exponential.
- Returns:
Object produced by model fit.
- Return type:
Any
- calculate_uncertainties(jacobian, chi_sq, n_data, n_params, residuals=None)[source]#
Calculate uncertainties.
- Parameters:
jacobian (
Any) – Jacobian matrix used to estimate parameter uncertainty.chi_sq (
np.ndarray) – Chi-square statistic used to scale uncertainty estimates.n_data (
int) – Number of samples, components, gates, or iterations used by the routine.n_params (
int) – Number of fitted model parameters.residuals (
np.ndarray | None) – Residuals of an unweighted fit. When given, the covariance is the heteroscedasticity-robust sandwich(J^T J)^-1 J^T diag(r^2) J (J^T J)^-1 * n / (n - p), since unweighted residuals of photon counts do not share one variance; otherwise it is(J^T J)^-1 * chi_sq / (n - p)for residuals already weighted by their inverse standard deviation.
- Returns:
One-standard-deviation uncertainty of each parameter.
- Return type:
Any
- compare_models(alpha=0.05)[source]#
Compare models.
- Parameters:
alpha (
float) – Regularization strength, fraction value, or significance threshold used by the routine.- Returns:
Tuple containing model-comparison statistics and selected fit results.
- Return type:
tuple[Any,]
- get_average_lifetime(popt)[source]#
Return average lifetime.
- Parameters:
popt (
np.ndarray) – Optimized model parameter vector.- Returns:
Object produced by get average lifetime.
- Return type:
Any