Methods

How each interval is built

Every evidence receipt names the method that built its interval. This page states each method as a formula, says where in the serving path it is used, and quotes the caveats from the code that produces it. A test fails if a quoted comment changes in the code.

1. Fixed ±25 % placeholder band

   heuristic_fixed_fraction

   Where it is used · Emitted by every analytical predictor (lab tiles show it as is). On /api/ml/predict it is never served as an interval: the per-class path treats it as no interval and takes the benchmark or withheld path below.

   $$\left[\hat y\,(1 - s),\ \hat y\,(1 + s)\right], \qquad s = 0.25$$

   Symbol	Meaning	Unit
   $\hat y$	served point estimate	display unit
   $s$	fixed spread (COD removal: s/2)	1

   Caveats, quoted from the code

   • this is a RAW PHYSICS ENVELOPE, not a calibrated prediction interval. Scored on bes-benchmark-v1 (3,320 paper-disjoint rows) it covered 0% of held-out power density and 19% of COD removal — it states lab-to-lab reproducibility of one measurement, not cross-paper predictive uncertainty.

     libs/shared/electrochemistry/src/predict.ts

   • The per-class analytical predictors' bounds are a fixed ±25% placeholder (`uncertaintyBasis: 'heuristic_fixed_fraction'`), not an uncertainty.

     libs/shared/ml/src/run-full-prediction.ts

2. Benchmark out-of-fold residual quantiles

   empirical-oof-residual-quantiles · also named benchmark-oof-residual-quantiles

   Where it is used · Served by /api/ml/predict when the predictor carries no usable σ (every per-class analytical path, or a degenerate σ) and the benchmark artifact has a cell for the target with n ≥ n_min. Cell lookup backs off class|domain → class → pooled.

   $$\left[\frac{T^{-1}\!\left(T(f\hat y) + q_{lo}\right)}{f},\ \frac{T^{-1}\!\left(T(f\hat y) + q_{hi}\right)}{f}\right], \qquad T \in \left\{\log_{10},\ \operatorname{logit}\right\}$$

   Symbol	Meaning	Unit
   $\hat y$	served point estimate	display unit
   $f$	display-to-SI factor of the served field	1
   $T$	the target’s transform: log₁₀ for densities, logit for fractions	1
   $q_{lo}, q_{hi}$	out-of-fold residual quantiles of the matched cell at the nominal level	transformed

   Caveats, quoted from the code

   • No fabricated width. A stratum below `n_min` is absent from the artifact and this module returns `null` — the caller must then report the interval as unavailable, never fall back to a guess.

     libs/shared/ml/src/predictions/benchmark-interval.ts

   • Width cannot fix centre. The quantiles are measured around the class×domain median. Serving them around a DIFFERENT point only covers at nominal if that point is comparably centred;

     libs/shared/ml/src/predictions/benchmark-interval.ts

3. Split-conformal (Track 5)

   split-conformal · also named split-conformal-track5

   Where it is used · Served when the predictor ships its own interval, so σ = (ci_high − ci_low) / (2 × 1.96), and the conformal artifact has a cell for (slug, unit, class[, domain]). Log-scale cells build the band around log ŷ.

   $$\left[\hat y\, e^{-\hat q\,\sigma/\hat y},\ \hat y\, e^{\hat q\,\sigma/\hat y}\right], \qquad \sigma = \frac{ci_{high} - ci_{low}}{2 \times 1.96}$$

   Symbol	Meaning	Unit
   $\hat y$	served point estimate	display unit
   $\hat q$	calibrated nonconformity quantile of the matched cell	1
   $\sigma$	σ recovered from the predictor’s own interval; σ/ŷ is the delta-method log-scale σ	display unit

   Caveats, quoted from the code

   • the current `conformal-constants.json` was calibrated against the fit-cohort PRIOR MEAN (holdout-priors-2026-05-21.json), NOT the model that `run-full-prediction.ts` actually serves (per-class analytical / SmartPredictionRouter).

     libs/shared/ml/src/conformal-apply.ts

   • the marginal-coverage guarantee is provisional — the log-space + clamp fixes here make the interval MATH honest, but the q̂ still carries the predictor-mismatch caveat.

     libs/shared/ml/src/conformal-apply.ts

4. Parametric ±1.96 σ fallback

   parametric

   Where it is used · Served when the predictor ships a σ but no conformal cell covers the target. Built in the field’s scale so a strictly positive quantity keeps a positive lower bound.

   $$\hat y \pm 1.96\,\sigma$$

   Symbol	Meaning	Unit
   $\hat y$	served point estimate	display unit
   $\sigma$	σ recovered from the predictor’s own interval	display unit

   Caveats, quoted from the code

   • parametric fallback: ±1.96·σ in the field's scale (nominal 95%)

     libs/shared/ml/src/conformal-apply.ts

5. Withheld

   none

   Where it is used · No calibration cell reaches n_min for the target, or the bound would rest only on the placeholder band (voltage on the per-class path). The receipt then says "no interval served".

   $$\mathrm{ci}_{low} = \mathrm{ci}_{high} = \varnothing$$

   Symbol	Meaning	Unit
   $\varnothing$	no interval is served	—

   Caveats, quoted from the code

   • Reporting no interval rather than a fabricated one.

     libs/shared/ml/src/run-full-prediction.ts

   • Voltage is the one bound still built from the placeholder (V = P / I on the ±25% bands) and has no calibration target, so it is withheld rather than left unlabelled.

     libs/shared/ml/src/run-full-prediction.ts