pyfli.simulator.calibration.coverage

Check that the experimental data lies within what the calibrated simulator produces.

Functions

_lifetime_side(exp_stats, sim_stats)	Which side of the lifetime range is uncovered, as fractions (short, long) of experimental pixels beyond the simulated range.
_tails(exp_stats, sim_stats, key[, q])	Fractions of experimental values below / above the simulated [q, 1 - q] range.
cover_photon_range(state, exp_counts, ...[, ...])	Discrete: stretch n_cycles so that the signal photons of every experimental pixel are reachable, given that only active_fraction of them land in active bins.
coverage_fractions(exp_stats, sim_stats[, q])	Fraction of experimental pixels inside the region populated by the simulation, per statistic.
covered_pixels(exp_stats, sim_stats[, q])	Per experimental pixel and statistic: is it inside the region holding 1 - q of the simulated pixels? Raw phasors use the 2D highest-density region (hdr_covered()); photons, edge and background use the central [q, 1 - q] quantile range.
ensure_coverage(state, ctx, exp_stats, ...)	Widen state until every statistic in COVERAGE_STATS covers at least target of the experimental pixels (or max_iter widening steps were made).
flatten_beta(p, factor)	Move a Beta toward Beta(1, 1) on the same support: shape -> 1 + factor * (shape - 1).
flatten_lifetime_priors(priors, factor)
hdr_covered(e, s[, q, bins])	2D points e inside the highest-density region that holds 1 - q of the simulated points s.
refit_photon_prior(state, ctx, exp_counts)	Photon prior re-derived from the observed photon counts (or peaks) of the experiment.
resupport_beta(p, lo, hi)	The same mean and SD expressed as a Beta on the new support [lo, hi].
step_factor(coverage, target[, slowest, fastest])	Flattening factor for one step: large steps far below the target, small steps near it.
stretch_tau2_support(state, below, above[, step])	Extend tau2_beta_range on the side(s) where experimental phasors are uncovered.
widen(state, failing, exp_stats, sim_stats, ...)	One widening step for every failing statistic; returns the new state and what was changed.

hdr_covered(e, s, q=1e-3, bins=120)

2D points e inside the highest-density region that holds 1 - q of the simulated points s. The simulated density is a binned Gaussian kernel estimate with Scott’s bandwidth (sd * n ** (-1/6) per axis), so the region converges as the number of simulated pixels grows instead of depending on it, unlike a raw cell-count rule, which marks sparse but supported regions as uncovered.

Parameters:

• e (ndarray)

• s (ndarray)

• q (float)

• bins (int)

Return type:

ndarray

covered_pixels(exp_stats, sim_stats, q=1e-3)

Per experimental pixel and statistic: is it inside the region holding 1 - q of the simulated pixels? Raw phasors use the 2D highest-density region (hdr_covered()); photons, edge and background use the central [q, 1 - q] quantile range.

Parameters:

• exp_stats (dict)

• sim_stats (dict)

• q (float)

Return type:

dict[str, ndarray]

coverage_fractions(exp_stats, sim_stats, q=1e-3)

Fraction of experimental pixels inside the region populated by the simulation, per statistic.

Parameters:

• exp_stats (dict)

• sim_stats (dict)

• q (float)

Return type:

dict[str, float]

flatten_beta(p, factor)

Move a Beta toward Beta(1, 1) on the same support: shape -> 1 + factor * (shape - 1).

Parameters:

• p (BetaPrior)

• factor (float)

Return type:

BetaPrior

flatten_lifetime_priors(priors, factor)

Parameters:

factor (float)

resupport_beta(p, lo, hi)

The same mean and SD expressed as a Beta on the new support [lo, hi].

Parameters:

• p (BetaPrior)

• lo (float)

• hi (float)

Return type:

BetaPrior

cover_photon_range(state, exp_counts, n_active_bins, margin=0.2, active_fraction=1.0)

Discrete: stretch n_cycles so that the signal photons of every experimental pixel are reachable, given that only active_fraction of them land in active bins.

Parameters:

• state (CalibrationState)

• exp_counts (ndarray)

• n_active_bins (int)

• margin (float)

• active_fraction (float)

Return type:

CalibrationState

stretch_tau2_support(state, below, above, step=0.15)

Extend tau2_beta_range on the side(s) where experimental phasors are uncovered.

Parameters:

• state (CalibrationState)

• below (float)

• above (float)

• step (float)

Return type:

CalibrationState

step_factor(coverage, target, slowest=0.9, fastest=0.4)

Flattening factor for one step: large steps far below the target, small steps near it.

Parameters:

• coverage (float)

• target (float)

• slowest (float)

• fastest (float)

Return type:

float

refit_photon_prior(state, ctx, exp_counts)

Photon prior re-derived from the observed photon counts (or peaks) of the experiment.

Parameters:

• state (CalibrationState)

• ctx (ObjectiveContext)

• exp_counts (ndarray)

Return type:

CalibrationState

widen(state, failing, exp_stats, sim_stats, ctx, exp_counts, cov, target, photon_refitted)

One widening step for every failing statistic; returns the new state and what was changed.

Parameters:

• state (CalibrationState)

• failing (list[str])

• exp_stats (dict)

• sim_stats (dict)

• ctx (ObjectiveContext)

• exp_counts (ndarray)

• cov (dict)

• target (float)

• photon_refitted (bool)

Return type:

tuple[CalibrationState, list[str]]

ensure_coverage(state, ctx, exp_stats, exp_counts, target=0.99, n_sim=20000, max_iter=10, seed=0)

Widen state until every statistic in COVERAGE_STATS covers at least target of the experimental pixels (or max_iter widening steps were made).

Returns (state, trace, coverage, sim, sim_stats); trace has one row per iteration with the coverage of each statistic, the distance to the experiment and the widening applied.

Parameters:

• state (CalibrationState)

• ctx (ObjectiveContext)

• exp_stats (dict)

• exp_counts (ndarray)

• target (float)

• n_sim (int)

• max_iter (int)

• seed (int)

Return type:

tuple[CalibrationState, list[dict], dict, dict, dict]