pyfli.bayes_utils.fit_aware_tolerance#

Fit-aware tolerance probability T_GOF = T_delta * A_chi * A_R * A_M_tilde for Bayesian FLI posteriors (trustworthiness note, Sections 3 and 7).

Functions

_dof(w, n_params)

_expanded_delta(delta, center, axis, relative)

_window_weights(shape, mask)

acceptance_band(nu[, z0, eps])

Return (lower, upper) = (1 - z0 sqrt(2/nu), 1 + max(z0 sqrt(2/nu), eps)) (eq.

combine_fit_aware_factors(T_delta, chi2_nu, ...)

Gate the fit statistics and return the factors and T_gof (eq.

dispersion_adjusted_tolerance(samples, ...)

T_adj: tolerance probability of draws inflated by sqrt(max(1, phi)) (eq.

early_window_mask(t, lam, tau1[, n_tau, mask])

Boolean early window t_k <= t_peak + n_tau * tau1, t_peak = argmax of lam.

gate(x, lower, upper[, s])

Tolerant Gaussian gate: 1 inside [lower, upper], half-Gaussian of width s outside (eq.

gaussian_tolerance_probability(delta, sigma)

Gaussian limit 2 Phi(delta / (sigma sqrt(phi))) - 1.

joint_tolerance_probability(samples, deltas)

Joint T_delta: probability all parameters in deltas are within tolerance.

mean_lifetime_draws(alpha1, tau1, tau2)

Per-draw mean lifetime tau_m = alpha1 tau1 + (1 - alpha1) tau2.

median_representativeness(chi2_draws, ...[, ...])

A_M: fraction of draws with chi2 >= chi2 of the median curve (eq.

reduced_chi2(y, lam, n_params[, mask, statistic])

Return (chi2_nu, nu): Pearson chi2 / nu (eq.

representativeness_penalty(a_m)

A_M_tilde = min(1, 2 A_M) (eq.

residual_noise_ratio(y, lam, n_params[, mask])

Unweighted R2, its Poisson ceiling R2_ceil and rho_R = RSS / E[RSS] (eqs.

tolerance_probability(samples, delta[, ...])

T_delta = P(|theta - center| < delta | y); center defaults to the median (eq.

tolerance_standard_error(T, n_eff)

Monte-Carlo standard error sqrt(T (1 - T) / n_eff).

weighted_r2(y, lam, n_params[, mask])

Return (R2_w, R2_w_ceil) with weights 1/lam (eq.

Classes

FitAwareTolerance(forward, delta[, ...])

Per-pixel T_GOF = T_delta * A_chi * A_R * A_M_tilde from posterior draws and the measured decay.

PosteriorDecayForward(model_type, freq[, ...])

Forward model lambda(theta) via ParamToDecay, amplitude pinned to the measured total.

tolerance_probability(samples, delta, center=None, relative=False, axis=-1)[source]#

T_delta = P(|theta - center| < delta | y); center defaults to the median (eq. 5).

joint_tolerance_probability(samples, deltas, centers=None, relative=False, axis=-1)[source]#

Joint T_delta: probability all parameters in deltas are within tolerance.

tolerance_standard_error(T, n_eff)[source]#

Monte-Carlo standard error sqrt(T (1 - T) / n_eff).

gaussian_tolerance_probability(delta, sigma, phi=1.0)[source]#

Gaussian limit 2 Phi(delta / (sigma sqrt(phi))) - 1.

dispersion_adjusted_tolerance(samples, delta, phi, center=None, relative=False, axis=-1)[source]#

T_adj: tolerance probability of draws inflated by sqrt(max(1, phi)) (eq. 32).

mean_lifetime_draws(alpha1, tau1, tau2)[source]#

Per-draw mean lifetime tau_m = alpha1 tau1 + (1 - alpha1) tau2.

reduced_chi2(y, lam, n_params, mask=None, statistic='pearson')[source]#

Return (chi2_nu, nu): Pearson chi2 / nu (eq. 20), or deviance D / (sum E[D_k] - p), the solver’s reduced deviance (eq. 20’s nu would bias it at low counts).

residual_noise_ratio(y, lam, n_params, mask=None)[source]#

Unweighted R2, its Poisson ceiling R2_ceil and rho_R = RSS / E[RSS] (eqs. 22-24).

weighted_r2(y, lam, n_params, mask=None)[source]#

Return (R2_w, R2_w_ceil) with weights 1/lam (eq. 25).

acceptance_band(nu, z0=2.0, eps=0.2)[source]#

Return (lower, upper) = (1 - z0 sqrt(2/nu), 1 + max(z0 sqrt(2/nu), eps)) (eq. 29).

gate(x, lower, upper, s=0.2)[source]#

Tolerant Gaussian gate: 1 inside [lower, upper], half-Gaussian of width s outside (eq. 28).

median_representativeness(chi2_draws, chi2_median, axis=-1)[source]#

A_M: fraction of draws with chi2 >= chi2 of the median curve (eq. 26).

representativeness_penalty(a_m)[source]#

A_M_tilde = min(1, 2 A_M) (eq. 27).

early_window_mask(t, lam, tau1, n_tau=3.0, mask=None)[source]#

Boolean early window t_k <= t_peak + n_tau * tau1, t_peak = argmax of lam.

combine_fit_aware_factors(T_delta, chi2_nu, rho_R, a_m, nu, z0=2.0, eps=0.2, s=0.2, chi2_nu_early=None, rho_R_early=None, nu_early=None)[source]#

Gate the fit statistics and return the factors and T_gof (eq. 31).

class PosteriorDecayForward(model_type, freq, irf=None, num_gates=None, shift_method='zero_pad', background_key=None, amplitude_mask=None, background=None, background_bins=None, onset_fraction=0.01, h_shift=None, h_shift_key=None, excitation='bin_start', gate_width=None)[source]#

Bases: object

Forward model lambda(theta) via ParamToDecay, amplitude pinned to the measured total.

background (v_shift) is None, a value, a map or "auto" (Poisson MLE, seeded from pre-onset bins); background_key takes it from the posterior instead. h_shift (onset, ns) is None, a value or a map; h_shift_key takes it from the posterior; excitation/gate_width are the forward-model options of ParamToDecay. Called as forward(params, y).

PARAM_KEYS: ClassVar[dict[str, tuple[str, ...]]] = {'bi-exponential': ('alpha1', 'tau1', 'tau2'), 'mono-exponential': ('tau',)}#
pre_onset_bins()[source]#

Bins before the IRF first reaches onset_fraction of its maximum.

property param_keys#

Posterior keys used by the forward model.

property n_params#

lifetime keys + amplitude (+ posterior or auto background).

Type:

Free parameters

auto_background(shape, y, lead, max_iter=100, tol=1e-9)[source]#

Poisson MLE of b in lambda = b + A shape (profile Newton on [0, Y/N]), seeded from pre-onset bins.

background_map(params, y, lead, shape=None)[source]#

Background b broadcast to lead: posterior key, fixed value/map, auto or zero.

shape(params, lead)[source]#

Unit-amplitude IRF-convolved decay of shape (*lead, K).

class FitAwareTolerance(forward, delta, n_params=None, t=None, statistic='pearson', z0=2.0, eps=0.2, s=0.2, early_params=('tau1', 'alpha1'), early_tau_key='tau1', n_tau_early=3.0, relative=False, draw_batch=None, max_draws=None, seed=None)[source]#

Bases: object

Per-pixel T_GOF = T_delta * A_chi * A_R * A_M_tilde from posterior draws and the measured decay.

delta maps parameter name to tolerance; forward(params, y) returns the model decay.

GROUPS = ('T_delta', 'T_delta_se', 'A_chi', 'A_R', 'T_gof', 'T_adj', 'T_adj_gof')#
median_representativeness(samples, y, chi2_median, mask=None)[source]#

A_M from draws streamed through the forward model in batches.