Skip to main content

qualia_core_db/solvers/learning/metrics/
classification.rs

1//! Classification metrics — accuracy, the binary confusion matrix and its derived
2//! rates, ROC AUC (rank form, reusing the statistics ranker), and log-loss.
3
4use crate::solvers::statistics::correlation::rank_into;
5
6/// Fraction of exact matches between predicted and true class labels. `None` if
7/// lengths differ or are empty.
8pub fn accuracy(y_true: &[usize], y_pred: &[usize]) -> Option<f64> {
9    let n = y_true.len();
10    if n == 0 || n != y_pred.len() {
11        return None;
12    }
13    let correct = y_true.iter().zip(y_pred).filter(|(a, b)| a == b).count();
14    Some(correct as f64 / n as f64)
15}
16
17/// Binary confusion matrix (positive class = `true`).
18#[derive(Debug, Clone, Copy, PartialEq, Eq)]
19pub struct ConfusionBinary {
20    pub tp: u64,
21    pub fp: u64,
22    pub tn: u64,
23    pub fn_: u64,
24}
25
26impl ConfusionBinary {
27    /// Running total.
28    pub fn total(&self) -> u64 {
29        self.tp + self.fp + self.tn + self.fn_
30    }
31    /// `ConfusionBinary::accuracy`.
32    pub fn accuracy(&self) -> f64 {
33        let t = self.total();
34        if t == 0 {
35            return 0.0;
36        }
37        (self.tp + self.tn) as f64 / t as f64
38    }
39    /// TP/(TP+FP); 0 when no positives are predicted.
40    pub fn precision(&self) -> f64 {
41        let d = self.tp + self.fp;
42        if d == 0 {
43            0.0
44        } else {
45            self.tp as f64 / d as f64
46        }
47    }
48    /// TP/(TP+FN) (sensitivity / true-positive rate).
49    pub fn recall(&self) -> f64 {
50        let d = self.tp + self.fn_;
51        if d == 0 {
52            0.0
53        } else {
54            self.tp as f64 / d as f64
55        }
56    }
57    /// TN/(TN+FP) (specificity).
58    pub fn specificity(&self) -> f64 {
59        let d = self.tn + self.fp;
60        if d == 0 {
61            0.0
62        } else {
63            self.tn as f64 / d as f64
64        }
65    }
66    /// Harmonic mean of precision and recall.
67    pub fn f1(&self) -> f64 {
68        let (p, r) = (self.precision(), self.recall());
69        if p + r == 0.0 {
70            0.0
71        } else {
72            2.0 * p * r / (p + r)
73        }
74    }
75}
76
77/// Build the binary confusion matrix from predicted/true boolean labels.
78pub fn confusion_binary(y_true: &[bool], y_pred: &[bool]) -> Option<ConfusionBinary> {
79    let n = y_true.len();
80    if n == 0 || n != y_pred.len() {
81        return None;
82    }
83    let mut c = ConfusionBinary {
84        tp: 0,
85        fp: 0,
86        tn: 0,
87        fn_: 0,
88    };
89    for (&t, &p) in y_true.iter().zip(y_pred) {
90        match (t, p) {
91            (true, true) => c.tp += 1,
92            (false, true) => c.fp += 1,
93            (false, false) => c.tn += 1,
94            (true, false) => c.fn_ += 1,
95        }
96    }
97    Some(c)
98}
99
100/// ROC AUC via the Mann–Whitney rank statistic:
101/// `AUC = (R₊ − n₊(n₊+1)/2) / (n₊·n₋)`, where `R₊` is the sum of the (tie-averaged)
102/// ranks of the positive-class scores. Reuses the statistics ranker. `None` if the
103/// inputs mismatch or a class is empty.
104pub fn roc_auc(scores: &[f64], labels: &[bool]) -> Option<f64> {
105    let n = scores.len();
106    if n == 0 || n != labels.len() {
107        return None;
108    }
109    let n_pos = labels.iter().filter(|&&l| l).count();
110    let n_neg = n - n_pos;
111    if n_pos == 0 || n_neg == 0 {
112        return None; // AUC undefined with only one class present
113    }
114    let mut idx = vec![0usize; n];
115    let mut ranks = vec![0.0f64; n];
116    rank_into(scores, &mut idx, &mut ranks)?;
117    let sum_pos_ranks: f64 = labels
118        .iter()
119        .zip(ranks.iter())
120        .filter(|(&l, _)| l)
121        .map(|(_, &r)| r)
122        .sum();
123    let n_pos_f = n_pos as f64;
124    Some((sum_pos_ranks - n_pos_f * (n_pos_f + 1.0) / 2.0) / (n_pos_f * n_neg as f64))
125}
126
127/// Binary cross-entropy (log-loss): `−(1/n)Σ[yᵢln pᵢ + (1−yᵢ)ln(1−pᵢ)]`, with `p`
128/// clamped away from 0/1 for numerical safety. `None` on a length mismatch.
129pub fn log_loss(probs: &[f64], labels: &[bool]) -> Option<f64> {
130    let n = probs.len();
131    if n == 0 || n != labels.len() {
132        return None;
133    }
134    const EPS: f64 = 1e-15;
135    let mut s = 0.0;
136    for (&p, &y) in probs.iter().zip(labels) {
137        let p = p.clamp(EPS, 1.0 - EPS);
138        s += if y { -p.ln() } else { -(1.0 - p).ln() };
139    }
140    Some(s / n as f64)
141}
142
143#[cfg(test)]
144mod tests {
145    use super::*;
146
147    #[test]
148    fn accuracy_basic() {
149        assert!((accuracy(&[0, 1, 2, 1], &[0, 1, 1, 1]).unwrap() - 0.75).abs() < 1e-12);
150        assert_eq!(accuracy(&[], &[]), None);
151    }
152
153    #[test]
154    fn confusion_rates() {
155        // 2 TP, 1 FP, 2 TN, 1 FN.
156        let t = [true, true, false, false, false, true];
157        let p = [true, true, true, false, false, false];
158        let c = confusion_binary(&t, &p).unwrap();
159        assert_eq!((c.tp, c.fp, c.tn, c.fn_), (2, 1, 2, 1));
160        assert!((c.precision() - 2.0 / 3.0).abs() < 1e-12);
161        assert!((c.recall() - 2.0 / 3.0).abs() < 1e-12);
162        assert!((c.f1() - 2.0 / 3.0).abs() < 1e-12);
163        assert!((c.accuracy() - 4.0 / 6.0).abs() < 1e-12);
164    }
165
166    #[test]
167    fn auc_perfect_and_random() {
168        // Perfectly separable: all positives score above all negatives → AUC 1.
169        let scores = [0.1, 0.2, 0.3, 0.8, 0.9, 1.0];
170        let labels = [false, false, false, true, true, true];
171        assert!((roc_auc(&scores, &labels).unwrap() - 1.0).abs() < 1e-12);
172        // Reversed → AUC 0.
173        let rev = [true, true, true, false, false, false];
174        assert!(roc_auc(&scores, &rev).unwrap().abs() < 1e-12);
175        // Single class → undefined.
176        assert_eq!(roc_auc(&scores, &[true; 6]), None);
177    }
178
179    #[test]
180    fn auc_known_value() {
181        // scores/labels with a known AUC of 0.75.
182        let scores = [0.2, 0.4, 0.6, 0.8];
183        let labels = [false, true, false, true];
184        assert!((roc_auc(&scores, &labels).unwrap() - 0.75).abs() < 1e-12);
185    }
186
187    #[test]
188    fn log_loss_rewards_confident_correct() {
189        let confident = log_loss(&[0.99, 0.01], &[true, false]).unwrap();
190        let unsure = log_loss(&[0.5, 0.5], &[true, false]).unwrap();
191        assert!(confident < unsure);
192    }
193}