Skip to main content

hyprstream_calibration/
bins.rs

1//! Binning for calibration curves and error metrics.
2//!
3//! The gate protocol pins **15 equal-mass bins** ([`crate::protocol::GATE_BIN_COUNT`]) for
4//! ECE and reliability curves. Equal-mass (equal-count) binning is used rather than the
5//! classic equal-width ECE binning because real decision distributions are peaked: under
6//! equal-width binning nearly all mass lands in one or two top bins and the curve says
7//! nothing about the rest of the confidence range. Equal-width binning is retained for
8//! the class-wise SCE, whose published definition is static (Nixon et al. 2019); ACE is
9//! its equal-mass counterpart.
10
11use serde::{Deserialize, Serialize};
12
13use crate::error::MetricError;
14
15/// A monotone set of bin edges over a confidence axis (`edges.len() == n_bins + 1`).
16///
17/// Construct via [`Binning::equal_mass`] (protocol default) or [`Binning::equal_width`]
18/// (SCE's published static form). Degenerate duplicate edges are collapsed, so the
19/// realized bin count may be smaller than requested when confidences tie heavily.
20#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
21pub struct Binning {
22    edges: Vec<f64>,
23}
24
25/// One populated bin of a reliability diagram.
26#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
27pub struct Bin {
28    /// Bin index in the parent [`Binning`].
29    pub index: usize,
30    /// Inclusive lower edge.
31    pub lower: f64,
32    /// Inclusive upper edge.
33    pub upper: f64,
34    /// Number of observations in the bin.
35    pub count: usize,
36    /// Mean confidence within the bin.
37    pub mean_confidence: f64,
38    /// Mean outcome within the bin (empirical accuracy / event frequency).
39    pub mean_outcome: f64,
40}
41
42impl Binning {
43    /// Equal-mass binning: edges chosen so each bin holds (approximately) `n / n_bins`
44    /// confidences. This is the protocol binning.
45    ///
46    /// # Errors
47    /// [`MetricError::InvalidBinCount`] if `n_bins` is zero or exceeds the number of
48    /// confidences; [`MetricError::EmptyInput`] on an empty slice.
49    pub fn equal_mass(confidences: &[f64], n_bins: usize) -> Result<Self, MetricError> {
50        if confidences.is_empty() {
51            return Err(MetricError::EmptyInput("equal_mass binning"));
52        }
53        if n_bins == 0 || n_bins > confidences.len() {
54            return Err(MetricError::InvalidBinCount {
55                bins: n_bins,
56                n: confidences.len(),
57            });
58        }
59        let mut sorted: Vec<f64> = confidences.to_vec();
60        sorted.sort_by(f64::total_cmp);
61        let n = sorted.len();
62        let mut edges = Vec::with_capacity(n_bins + 1);
63        for b in 0..=n_bins {
64            // Rank-quantile edge: the (b / n_bins)-quantile of the sorted confidences.
65            let pos = b * n / n_bins;
66            let idx = pos.min(n - 1);
67            edges.push(sorted[idx]);
68        }
69        edges[0] = 0.0_f64.min(edges[0]);
70        edges[n_bins] = 1.0_f64.max(edges[n_bins]);
71        edges.dedup();
72        Ok(Self { edges })
73    }
74
75    /// Equal-width binning over `[0, 1]` — the published static form used by SCE.
76    #[must_use]
77    pub fn equal_width(n_bins: usize) -> Self {
78        let n_bins = n_bins.max(1);
79        #[allow(clippy::cast_precision_loss)]
80        let width = 1.0 / n_bins as f64;
81        let edges = (0..=n_bins).map(|b| b as f64 * width).collect();
82        Self { edges }
83    }
84
85    /// Number of bins.
86    #[must_use]
87    pub fn n_bins(&self) -> usize {
88        self.edges.len() - 1
89    }
90
91    /// Bin index for a confidence value (last bin is closed on both sides).
92    #[must_use]
93    pub fn assign(&self, confidence: f64) -> usize {
94        let n_bins = self.n_bins();
95        for (i, w) in self.edges.windows(2).enumerate() {
96            if confidence >= w[0] && (confidence < w[1] || (i == n_bins - 1 && confidence <= w[1]))
97            {
98                return i;
99            }
100        }
101        // Out-of-range confidences clamp to the nearest end bin.
102        if confidence < self.edges[0] {
103            0
104        } else {
105            n_bins - 1
106        }
107    }
108
109    /// Populate the bins: mean confidence and mean outcome per non-empty bin.
110    ///
111    /// # Errors
112    /// [`MetricError::LengthMismatch`] if the slices differ in length;
113    /// [`MetricError::EmptyInput`] if both are empty.
114    pub fn summarize(
115        &self,
116        confidences: &[f64],
117        outcomes: &[bool],
118    ) -> Result<Vec<Bin>, MetricError> {
119        if confidences.len() != outcomes.len() {
120            return Err(MetricError::LengthMismatch {
121                left_name: "confidences",
122                left: confidences.len(),
123                right_name: "outcomes",
124                right: outcomes.len(),
125            });
126        }
127        if confidences.is_empty() {
128            return Err(MetricError::EmptyInput("bin summarization"));
129        }
130        let n_bins = self.n_bins();
131        let mut counts = vec![0usize; n_bins];
132        let mut conf_sums = vec![0.0f64; n_bins];
133        let mut out_sums = vec![0.0f64; n_bins];
134        for (&c, &o) in confidences.iter().zip(outcomes) {
135            let b = self.assign(c);
136            counts[b] += 1;
137            conf_sums[b] += c;
138            out_sums[b] += f64::from(o);
139        }
140        let mut bins = Vec::with_capacity(n_bins);
141        for (i, (&count, (&cs, &os))) in counts
142            .iter()
143            .zip(conf_sums.iter().zip(out_sums.iter()))
144            .enumerate()
145        {
146            if count == 0 {
147                continue;
148            }
149            #[allow(clippy::cast_precision_loss)]
150            let n = count as f64;
151            bins.push(Bin {
152                index: i,
153                lower: self.edges[i],
154                upper: self.edges[i + 1],
155                count,
156                mean_confidence: cs / n,
157                mean_outcome: os / n,
158            });
159        }
160        Ok(bins)
161    }
162}