pyfli.analysis.precision.monte_carlo_precision#

Monte Carlo lifetime precision: repeated simulation of one pixel across photon counts.

Module Attributes

MU_PER_CYCLE

Expected photons per laser cycle used by PhotonCountSimulator.

Functions

estimate_lifetimes(decays, irf, ...[, freq, ...])

Lifetime of every decay with one method: "NLSF", "MLE" (fits), "mean_arrival", "phasor" or "phasor_bin_corrected" (fit-free, background-subtracted).

fit_lifetimes(decays, irf, freq, method[, ...])

Fit every decay of decays (M, T) with a mono-exponential model using FLICPUProcessor and the fitter/estimator of method ("NLSF" or "MLE").

plot_monte_carlo(df[, figsize])

Plot a run_monte_carlo() table: CV vs. photon count (log-log) with the Cramér-Rao bound, and the F-value vs. photon count with the bound and the ideal F = 1.

run_monte_carlo(irf, tau, photon_counts[, ...])

Monte Carlo precision of each method against photon count, for one fixed lifetime.

simulate_fixed_lifetime_decays(irf, tau, ...)

Simulate n_repeats independent photon histograms of one pixel with lifetime tau and on average n_photons detected signal photons, using PhotonCountSimulator.
MU_PER_CYCLE = 0.01#

Expected photons per laser cycle used by PhotonCountSimulator.

simulate_fixed_lifetime_decays(irf, tau, n_photons, n_repeats, laser_feq=80.0, dcr=0.0, seed=None)[source]#

Simulate n_repeats independent photon histograms of one pixel with lifetime tau and on average n_photons detected signal photons, using PhotonCountSimulator.

Parameters:

  • irf (np.ndarray) – IRF trace (T,) (or a cube, from which the simulator picks one pixel).

  • tau (float) – Fixed lifetime in ns.

  • n_photons (float) – Expected signal photons per decay; must be >= 10 (the simulator needs at least 1000 laser cycles).

  • n_repeats (int) – Number of independent copies.

  • laser_feq (float) – Laser repetition rate in MHz (period 1000 / laser_feq ns).

  • dcr (float) – Dark counts per gate added by the simulator (0 disables them).

  • seed (int | None) – Seeds the simulator engine and NumPy’s global RNG (used for dark counts).

Returns:

(decays, irf_used): decays (n_repeats, T) and the normalized IRF the simulator convolved with (T,).

Return type:

tuple[np.ndarray, np.ndarray]

fit_lifetimes(decays, irf, freq, method, max_iter=1000, n_jobs=-1)[source]#

Fit every decay of decays (M, T) with a mono-exponential model using FLICPUProcessor and the fitter/estimator of method ("NLSF" or "MLE"). Returns the fitted lifetimes (M,); failed fits are NaN.

Parameters:
Return type:

ndarray

estimate_lifetimes(decays, irf, laser_period, method, freq=None, background_per_bin=0.0, max_iter=1000, n_jobs=-1)[source]#

Lifetime of every decay with one method: "NLSF", "MLE" (fits), "mean_arrival", "phasor" or "phasor_bin_corrected" (fit-free, background-subtracted).

Parameters:
Return type:

ndarray

run_monte_carlo(irf, tau, photon_counts, n_repeats=200, methods=('NLSF', 'MLE', 'mean_arrival', 'phasor'), laser_feq=80.0, dcr=0.0, max_iter=1000, n_jobs=-1, seed=None, crb_fit_background=None)[source]#

Monte Carlo precision of each method against photon count, for one fixed lifetime.

For every photon count N in photon_counts, n_repeats decays are simulated, every method estimates the lifetime of every decay, and the spread of the estimates is summarized. The Cramér-Rao bound for the same tau, N, IRF, window and background is added for reference.

Parameters:

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

  • tau (float) – True lifetime (ns) shared by all copies.

  • photon_counts (iterable of float) – Expected signal photons per decay (each >= 10).

  • n_repeats (int) – Copies per photon count.

  • methods (iterable of str) – Any of "NLSF", "MLE", "mean_arrival", "phasor", "phasor_bin_corrected".

  • laser_feq (float) – Laser repetition rate in MHz.

  • dcr (float) – Dark counts per gate (0 disables them).

  • max_iter (int) – Optimizer iteration budget for the fits.

  • n_jobs (int) – Parallel fitting jobs.

  • seed (int | None) – Base seed; photon count i uses seed + i.

  • crb_fit_background (bool | None) – Whether the bound treats the background as unknown (as fits with a free offset do). Defaults to dcr > 0.

Returns:

One row per (method, N): method, n_photons, n_detected (mean total counts), n_valid, tau_true, tau_mean, tau_std, bias, rel_bias, cv (std / mean), F (cv * sqrt(N)), cv_crb, F_crb and efficiency ((cv_crb / cv) ** 2, see fisher_crlb.estimator_efficiency(); 1 means the method reaches the bound).

Return type:

pd.DataFrame

plot_monte_carlo(df, figsize=(13, 4.5))[source]#

Plot a run_monte_carlo() table: CV vs. photon count (log-log) with the Cramér-Rao bound, and the F-value vs. photon count with the bound and the ideal F = 1.

Parameters:
Return type:

tuple[Any, Any]