Skip to main content

Module uncertainty_ece

Module uncertainty_ece 

Source
Expand description

Uncertainty calibration, Gaussian coverage factor, covariance rotation, Mahalanobis NEES, and Expected Calibration Error (ECE) verifiers (C02-C03, C02-C04, C02-C05, Modes 6 & 7).

All reference calculations are evaluated in independent f64 arithmetic:

  • Target quantity, unit, and uncertainty kind admission (StandardAbsolute, ExpandedAbsolute, Relative).
  • One-shot affine calibration $\text{physical} = \text{scale}\cdot\text{raw} + \text{offset}$ with idempotence guard against double-scaling already calibrated streams.
  • Half-open calibration validity interval $[t_{\text{from}}, t_{\text{until}})$ with exact boundary rejection.
  • Exact positive-term Kummer-confluent series $\operatorname{erf}(k/\sqrt{2})$ verifying Gaussian coverage factor $k \leftrightarrow p$ consistency ($k=1 \leftrightarrow 68.268949%$, $k=1.959964 \leftrightarrow 95%$, $k=2 \leftrightarrow 95.449974%$, $k=3 \leftrightarrow 99.730020%$).
  • $3\times 3$ covariance symmetry, positive-definiteness, frame rotation $\boldsymbol{\Sigma}’ = \mathbf{R}\boldsymbol{\Sigma}\mathbf{R}^T$, Mahalanobis distance / NEES, ECE, Brier score, and Gaussian NLL.

Structs§

CalibrationMetricsReport
Summary of probabilistic calibration metrics (ECE, MCE, Brier score).
UncertaintyDescriptor
Uncertainty descriptor bound to a specific quantity and unit (C02-C05).

Enums§

CalibrationStage
Calibration stage of a sample stream (C02-C05 & QAC Schema 210).
UncertaintyKind
Uncertainty representation kind required by C02-C05 and Modes 6/7.
UncertaintyValidationError
Structured rejection reasons for calibration, uncertainty, and statistical consistency checks.

Functions§

apply_or_verify_affine_calibration
Apply one-shot affine calibration $\text{physical} = \text{scale} \cdot \text{raw} + \text{offset}$ to a raw-count sample, or verify that an already calibrated physical stream has units_per_sample == 1.0 and offset == 0.0 without re-scaling (C02-C05).
erf_f64
Evaluate $\operatorname{erf}(x)$ in independent f64 arithmetic with zero-cancellation positive-term Kummer series for $|x| \le 5.5$ and Laplace continued fraction for $|x| > 5.5$.
evaluate_ece_and_brier
Compute Expected Calibration Error (ECE), Maximum Calibration Error (MCE), and Brier score over equal-width probability bins in $[0, 1]$.
evaluate_gaussian_nll
Compute univariate Gaussian Negative Log-Likelihood (NLL): $\text{NLL} = \frac{1}{N} \sum_{i=1}^N \left[\frac{1}{2}\ln(2\pi \sigma_i^2) + \frac{(y_i - \mu_i)^2}{2\sigma_i^2}\right]$.
gaussian_coverage_probability
Compute two-sided Gaussian coverage probability $p(k) = \operatorname{erf}(k / \sqrt{2})$ for $k > 0$.
mahalanobis_nees_3d
Compute squared Mahalanobis distance (Normalized Estimation Error Squared, NEES) $d_M^2 = (\mathbf{x} - \boldsymbol{\mu})^T \boldsymbol{\Sigma}^{-1} (\mathbf{x} - \boldsymbol{\mu})$ in $\mathbb{R}^3$.
rotate_covariance_3x3
Rotate a $3\times 3$ covariance or Cauchy stress tensor by a proper rotation matrix $\mathbf{R}$: $\boldsymbol{\Sigma}’ = \mathbf{R}\boldsymbol{\Sigma}\mathbf{R}^T$ (C02-C04 & C02-C05), verifying trace and determinant invariance.
verify_covariance_3x3_spd
Verify that a $3\times 3$ covariance matrix $\boldsymbol{\Sigma}$ is finite, symmetric, and strictly positive definite (Sylvester’s criterion on all leading principal minors).
verify_gaussian_coverage_factor
Verify consistency between a Gaussian coverage factor $k > 0$ and claimed confidence probability $p \in (0, 1)$.
verify_half_open_calibration_window
Verify half-open calibration validity window $[t_{\text{from}}, t_{\text{until}})$ (C02-C03 & C02-C05). Exact boundary rule: $t_{\text{from}} < t_{\text{until}}$ and $t_{\text{from}} \le t < t_{\text{until}}$.
verify_uncertainty_descriptor
Validate a C02-C05 / Mode 6 / Mode 7 uncertainty descriptor.