pyfli.laguerre.laguerre_method#
Implement Laguerre-basis deconvolution for FLI decay reconstruction.
This module belongs to pyfli.laguerre and is part of PyFLI’s Laguerre-basis
deconvolution and fitting method. Public API includes classes LaguerreFLI.
Classes
|
Run the laguerre FLI routine. |
- class LaguerreFLI(n_components=2, n_laguerre=None, alpha=0.85, dt=1.0, auto_alpha=False, taus_init=None, laser_period_ns=None, reg_strength=0.0, reg_power=2.0, nonneg=True, verbose=True, shift_method='zero_pad', fit_background=False, weighting='irls', variance_floor=1.0, irls_max_rounds=20, irls_tol=1e-6, excitation='bin_start', gate_width=None)[source]#
Bases:
objectRun the laguerre FLI routine. Laguerre basis, projects decays into coefficient space, reconstructs denoised decays, and supports lifetime estimation from the reconstructed signal.
- Parameters:
n_components (
int) – Number of exponential lifetime components to fit.n_laguerre (
Optional[int]) – Number of Laguerre basis functions used for reconstruction.alpha (
float) – Regularization strength or statistical threshold value, depending on context.dt (
float) – Sampling interval between adjacent decay bins.auto_alpha (
bool) – IfTrue, estimate the Laguerre alpha parameter from the data.taus_init (
Optional[np.ndarray]) – Initial lifetime estimates used to seed exponential fitting.laser_period_ns (
Optional[float]) – Laser repetition period in nanoseconds.reg_strength (
float) – Regularization weight applied to higher-order Laguerre coefficients.reg_power (
float) – Exponent controlling how regularization increases across coefficient order.nonneg (
bool) – IfTrue, constrain fitted coefficients or amplitudes to be non-negative.verbose (
bool) – IfTrue, report progress and diagnostic messages during processing.shift_method (
str) – IRF convolution, as inpyfli.cm_funcs.forward_model.model_numpy():"zero_pad"(linear) or"circular"(periodic steady state; the windowT * dtmust be one laser period).fit_background (
bool) – IfTrue, fit a constant per-gate background (the solver’sv_shift). Withshift_method="zero_pad"it is an extra linear term next to the Laguerre coefficients; with"circular"the circularly convolved Laguerre functions span a constant, so it is fitted in the exponential stage instead (a constantbin the deconvolved kernel is the samebin the data, the IRF summing to 1).weighting (
str) – Weights of the coefficient least squares, as the solver’s NLSF (residual_variance()):"irls"(Poisson, iteratively reweighted;irls()),"none"or"neyman".variance_floor (
float,int,float) – IRLS variance floor (counts), maximum rounds and per-pixel relative tolerance.irls_max_rounds (
float,int,float) – IRLS variance floor (counts), maximum rounds and per-pixel relative tolerance.irls_tol (
float,int,float) – IRLS variance floor (counts), maximum rounds and per-pixel relative tolerance.excitation (
str) – Excitation within each IRF gate,"bin_start"(default) or"uniform", as inpyfli.cm_funcs.forward_model.model_numpy().gate_width (
float | None) – Detection-gate width in ns (None: dt); only for an IRF not recorded through the same gate.
Notes
Each pixel’s exponential model is the solver’s gate-integrated kernel (
pyfli.cm_funcs.forward_model.gate_integrated_kernel(), periodic for"circular"),h[n] = sum_i (S a_i) g_n(tau_i, onset), so the amplitudes are photons andphoton_count_map, thealphamaps (photon fractions) andtau_mean_map(photon-weighted) follow the solver’s definitions; the onset is the fractional part ofirf_shift(seefit()).chi2_map,reduced_chi2_map,R2_mapandfit_mapdescribe that exponential model convolved with the IRF (n_params = 2N, plus 1 with fit_background);laguerre_*maps describe the Laguerre expansion fit (n_params= the number of basis functions, plus 1 with fit_background for"zero_pad"); both add 1 for a per-pixelirf_shiftmap (seefit()).- fit(decay, irf, mask=None, irf_shift=None, h_shift=None)[source]#
Fit the model to decay and IRF data.
- Parameters:
decay (
np.ndarray) – Time-resolved decay signal or decay cube.irf (
np.ndarray) – Instrument response function aligned with the decay signal.mask (
Optional[np.ndarray]) – Boolean or labeled mask selecting pixels for the operation.irf_shift (
float | np.ndarray | None) – IRF delay in gates, scalar or(X, Y), e.g. frompyfli.data_cc.irfAligner.IRFAligner.estimate_shift_debiased()orestimate_shift_rmse()(positive when the decay starts later). The IRF is delayed by it by its whole gates (floor) and the remaining fractionfin[0, 1)is the onset of the exponential kernel, which together are exactly the solver’s onseth_shift = irf_shift * dt, reported ash_shift_map. Withf > 0the kernel is geometric from gate 1 and differs only in gate 0, so a unit spike at gate 0 is added to the Laguerre basis (one more expansion coefficient) to represent it exactly. A per-pixel map counts as one fitted parameter.h_shift (
float | np.ndarray | None) – The same offset in the solver’s convention, in ns (scalar or(X, Y)):HarmonicOffset.estimate()["h_shift_map"](pyfli.phasor.harmonic_offset), a solver fit’sh_shift_map, or any other estimate; used asirf_shift = h_shift / dt. Give at most one of irf_shift and h_shift.
- Returns:
Object produced by fit.
- Return type:
'LaguerreFLI'