pyfli.bayes_utils.unc_trustworthiness#

Per-pixel posterior uncertainty (MAD), credible-interval and goodness-of-fit trustworthiness maps.

Functions

_deviance_moment_table([mu_min, mu_max, n_grid])

trustworthiness_CrI(samples[, median_map, ...])

Trustworthiness from the relative credible-interval width: 1 / (1 + (q_high - q_low) / |median|), in (0, 1].

unc(samples[, axis, scale])

Median absolute deviation (MAD) of posterior samples.

Classes

trustworthiness_gof(n_params[, mode, ...])

Goodness-of-fit score G in (0, 1] for FLIM / TCSPC decay fits.
unc(samples, axis=-1, scale=1.0)[source]#

Median absolute deviation (MAD) of posterior samples.

Parameters:

  • samples (np.ndarray) – Posterior draws, e.g. (H, W, NUM_SAMPLES) from BiPipeline.output_samples[key].

  • axis (int) – Sample axis.

  • scale (float or str) – Passed to scipy.stats.median_abs_deviation(). 1.0 gives the raw MAD (same as BiPipeline uncertainties); "normal" gives a standard-deviation-comparable value.

Returns:

MAD map with the sample axis removed.

Return type:

np.ndarray

trustworthiness_CrI(samples, median_map=None, ci=90.0, axis=-1)[source]#

Trustworthiness from the relative credible-interval width: 1 / (1 + (q_high - q_low) / |median|), in (0, 1].

Parameters:

  • samples (np.ndarray) – Posterior draws, e.g. (H, W, NUM_SAMPLES).

  • median_map (np.ndarray | None) – Posterior median map; computed from samples when None.

  • ci (float) – Central credible interval in percent (90 uses the 5th and 95th percentiles).

  • axis (int) – Sample axis.

Returns:

Trustworthiness map. NaN where the median is ~0 (relative width undefined, including all-zero masked-out pixels).

Return type:

np.ndarray

class trustworthiness_gof(n_params, mode='one-sided', z_plus=3.0, z_minus=5.0, expectation='exact', axis=-1)[source]#

Bases: object

Goodness-of-fit score G in (0, 1] for FLIM / TCSPC decay fits.

The fit’s Poisson deviance D is standardized against its exact expected mean and variance under Poisson noise (so dim pixels are not rewarded for chi2_nu < 1), giving z, which is mapped to a score:

  • mode="one-sided": G = exp(-max(0, z)^2 / (2 z_plus^2)) penalizes only underfitting.

  • mode="two-sided": additionally multiplies by exp(-max(0, -z)^2 / (2 z_minus^2)) to penalize implausibly good fits.

The time-bin axis is axis (last by default), so y and mu can be (K,), (n_pixels, K) or (H, W, K).

Parameters:

  • n_params (int) – Number of fitted parameters, subtracted from the expected deviance.

  • mode (str) – "one-sided" or "two-sided".

  • z_plus (float) – Width of the penalty for z > 0 (underfitting).

  • z_minus (float) – Width of the penalty for z < 0 (overfitting), two-sided mode only.

  • expectation (str) – "exact": z = (D - (sum E_k - n_params)) / sqrt(sum V_k). "asymptotic": z = (D - nu) / sqrt(2 nu).

  • axis (int) – Time-bin axis.

MODES = ('one-sided', 'two-sided')#
EXPECTATIONS = ('exact', 'asymptotic')#
static deviance_terms(y, mu)[source]#

Per-bin Poisson deviance 2 [y ln(y/mu) - (y - mu)] (2 mu when y = 0).

static expected_moments(mu)[source]#

Exact per-bin (E[d], Var[d]) for y ~ Poisson(mu), same shape as mu.

zscore(y, mu, mask=None)[source]#

Standardized deviance per pixel.

Parameters:

  • y (np.ndarray) – Measured counts.

  • mu (np.ndarray) – Fitted model counts, same shape as y.

  • mask (np.ndarray | None) – Boolean array broadcastable to y selecting the fit window.

Returns:

(z, D, nu) with the time-bin axis removed.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray]

score(z)[source]#

Map standardized deviance z to the fit score G in (0, 1].