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

LaguerreFLI([n_components, n_laguerre, ...])

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: object

Run 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) – If True, 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) – If True, constrain fitted coefficients or amplitudes to be non-negative.

  • verbose (bool) – If True, report progress and diagnostic messages during processing.

  • shift_method (str) – IRF convolution, as in pyfli.cm_funcs.forward_model.model_numpy(): "zero_pad" (linear) or "circular" (periodic steady state; the window T * dt must be one laser period).

  • fit_background (bool) – If True, fit a constant per-gate background (the solver’s v_shift). With shift_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 constant b in the deconvolved kernel is the same b in 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 in pyfli.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 and photon_count_map, the alpha maps (photon fractions) and tau_mean_map (photon-weighted) follow the solver’s definitions; the onset is the fractional part of irf_shift (see fit()). chi2_map, reduced_chi2_map, R2_map and fit_map describe 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-pixel irf_shift map (see fit()).

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. from pyfli.data_cc.irfAligner.IRFAligner.estimate_shift_debiased() or estimate_shift_rmse() (positive when the decay starts later). The IRF is delayed by it by its whole gates (floor) and the remaining fraction f in [0, 1) is the onset of the exponential kernel, which together are exactly the solver’s onset h_shift = irf_shift * dt, reported as h_shift_map. With f > 0 the 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’s h_shift_map, or any other estimate; used as irf_shift = h_shift / dt. Give at most one of irf_shift and h_shift.

Returns:

Object produced by fit.

Return type:

'LaguerreFLI'

get_parameters(data_name='LaguerreFLI_Dataset')[source]#

Return parameters.

Parameters:

data_name (str) – Label assigned to the fitted or processed dataset.

Returns:

Dictionary containing the data produced by get parameters.

Return type:

dict

save_results(dataset, folder='results')[source]#

Save results.

Parameters:
  • dataset (dict) – Dataset dictionary or fit result collection to save.

  • folder (str) – Output directory used when saving results.

Returns:

No object is returned; the function save results.

Return type:

None

load_map(h5_path, map_name='tau1_map')[source]#

Load a map from a .h5 file.

Parameters:
  • h5_path (str) – Filesystem path used by the routine.

  • map_name (str) – Name of the saved parameter map to load.

Returns:

Map array loaded from disk.

Return type:

Optional[np.ndarray]

predict()[source]#

Return reconstructed value.

Returns:

Reconstructed decay array predicted from the fitted Laguerre model.

Return type:

np.ndarray