pyfli.analysis.precision.fit_free_lifetime#

Fit-free mono-exponential lifetimes from the photon histogram: mean arrival time and phasor lifetime.

Functions

_mean_time_lookup(irf, laser_period, tau_grid)

_shared_irf(irf)

_signal(decay, background_per_bin)

Background-subtracted counts, deliberately not clipped at zero: clipping would discard the negative noise excursions and bias the moments at low counts.

fit_free_lifetime_maps(decay, irf, laser_period)

All fit-free lifetime maps for an image cube, ready for CVPlot / FactorAnalysis: {"tau_mean_arrival", "tau_mean_arrival_naive", "tau_phasor", "tau_phasor_bin_corrected"}, each (H, W) with NaN outside mask.

gate_times(n_gates, laser_period)

Gate start times k * laser_period / n_gates in ns (endpoint excluded).

mean_arrival_lifetime(decay, irf, laser_period)

Lifetime whose exact gated-model first moment equals the measured mean arrival time (method of moments with the wrap-around / gate / IRF model).

mean_arrival_time_naive(decay, irf, laser_period)

<t>_decay - <t>_IRF per decay (ns) -- the textbook first-moment lifetime, exact only for an unlimited window without wrap-around or gating.

phasor_lifetime(decay, irf, laser_period[, ...])

First-harmonic phasor lifetime at the laser repetition frequency, calibrated with the IRF, via PhasorAnalyzer.
gate_times(n_gates, laser_period)[source]#

Gate start times k * laser_period / n_gates in ns (endpoint excluded).

Parameters:
Return type:

ndarray

mean_arrival_time_naive(decay, irf, laser_period, background_per_bin=0.0)[source]#

<t>_decay - <t>_IRF per decay (ns) – the textbook first-moment lifetime, exact only for an unlimited window without wrap-around or gating.

Parameters:
Return type:

ndarray

mean_arrival_lifetime(decay, irf, laser_period, background_per_bin=0.0, tau_grid=None)[source]#

Lifetime whose exact gated-model first moment equals the measured mean arrival time (method of moments with the wrap-around / gate / IRF model).

Parameters:

  • decay (np.ndarray) – Photon histograms, time axis last.

  • irf (np.ndarray) – Shared IRF (T,).

  • laser_period (float) – Laser repetition period in ns.

  • background_per_bin (float) – Expected background counts per gate, subtracted before the moment.

  • tau_grid (np.ndarray | None) – Lifetimes (ns) of the lookup table; defaults to 2000 log-spaced values in [0.01, 5 * laser_period].

Returns:

Lifetime per decay (ns); NaN for empty decays or means outside the table.

Return type:

np.ndarray

phasor_lifetime(decay, irf, laser_period, background_per_bin=0.0, bin_corrected=False, device='cpu')[source]#

First-harmonic phasor lifetime at the laser repetition frequency, calibrated with the IRF, via PhasorAnalyzer.

Parameters:

  • decay (np.ndarray) – Photon histograms, time axis last.

  • irf (np.ndarray) – Shared IRF (T,).

  • laser_period (float) – Laser repetition period in ns (the phasor frequency is 1 / laser_period).

  • background_per_bin (float) – Expected background counts per gate, subtracted before the phasor.

  • bin_corrected (bool) – False (default): the standard phase lifetime S / (omega * G) from PhasorAnalyzer.compute_lifetime. True: invert the calibrated phasor z = (1 - q) / (1 - q * exp(i*omega*dt)) of the exact wrapped, gated exponential for q = exp(-dt / tau), which removes the gate-width bias.

  • device (Any | None) – Torch device for PhasorAnalyzer (calibration runs in torch).

Returns:

Lifetime per decay (ns), shape decay.shape[:-1].

Return type:

np.ndarray

fit_free_lifetime_maps(decay, irf, laser_period, mask=None, background_per_bin=0.0)[source]#

All fit-free lifetime maps for an image cube, ready for CVPlot / FactorAnalysis: {"tau_mean_arrival", "tau_mean_arrival_naive", "tau_phasor", "tau_phasor_bin_corrected"}, each (H, W) with NaN outside mask.

irf may be a shared (T,) IRF or the (H, W, T) cube, in which case the mean IRF over mask is used.

Parameters:
Return type:

dict[str, ndarray]