Skip to main content

sightloom_analysis/
far_calibrate.rs

1//! False-alarm-rate (FAR) calibration for anomaly score thresholds.
2//!
3//! Hosts score a **normal** (no-attack) history window, then pick a threshold
4//! so that the fraction of scores exceeding it ≈ target FAR.
5
6#![allow(
7    clippy::cast_precision_loss,
8    clippy::cast_possible_truncation,
9    clippy::cast_sign_loss
10)]
11
12extern crate alloc;
13
14use alloc::vec::Vec;
15
16use crate::input::AnalysisSeries;
17use crate::stat_anomaly::{BaselineStats, StatAnomalyConfig};
18use crate::stats::{hour_of_day_ns, robust_z_score, z_score};
19
20/// One score used for FAR calibration (higher = more anomalous).
21#[derive(Clone, Copy, Debug, PartialEq)]
22pub struct AnomalyScoreSample {
23    /// Anomaly score (e.g. absolute z-score).
24    pub score: f32,
25    /// When true, this sample is a known anomaly (for empirical FAR/FRR eval).
26    pub is_anomaly: bool,
27}
28
29/// Result of calibrating a score threshold to a target false-alarm rate.
30#[derive(Clone, Copy, Debug, PartialEq)]
31pub struct FarCalibrationReport {
32    /// Requested FAR in `(0, 1]` (e.g. `0.01` = 1%).
33    pub target_far: f32,
34    /// Score threshold: flag when `score >= threshold`.
35    pub threshold: f32,
36    /// Empirical FAR on the calibration scores at `threshold`.
37    pub empirical_far: f32,
38    /// Number of **normal** scores used.
39    pub n_normal: usize,
40    /// Number of labeled anomaly scores (may be 0 for threshold-only calib).
41    pub n_anomaly: usize,
42    /// Empirical miss rate on labeled anomalies when provided (`None` if none).
43    pub empirical_miss_rate: Option<f32>,
44}
45
46/// Calibrates a threshold so ≈ `target_far` of **normal** scores fire.
47///
48/// Uses the quantile of normal scores: threshold = percentile
49/// `(1 - target_far)` of normal scores (higher scores more anomalous).
50///
51/// # Errors
52///
53/// Returns `None` when there are no finite normal scores or `target_far` invalid.
54#[must_use]
55pub fn calibrate_far_threshold(
56    samples: &[AnomalyScoreSample],
57    target_far: f32,
58) -> Option<FarCalibrationReport> {
59    if !(target_far > 0.0 && target_far <= 1.0) {
60        return None;
61    }
62    let mut normals: Vec<f32> = samples
63        .iter()
64        .filter(|s| !s.is_anomaly && s.score.is_finite())
65        .map(|s| s.score)
66        .collect();
67    if normals.is_empty() {
68        return None;
69    }
70    normals.sort_by(|a, b| a.partial_cmp(b).unwrap_or(core::cmp::Ordering::Equal));
71    // Threshold at (1 - FAR) quantile so fraction above ≈ FAR.
72    let q = (1.0 - target_far).clamp(0.0, 1.0);
73    let idx = ((q * (normals.len().saturating_sub(1) as f32)) + 0.5) as usize;
74    let idx = idx.min(normals.len().saturating_sub(1));
75    let threshold = normals[idx];
76
77    let n_normal = normals.len();
78    let false_alarms = normals.iter().filter(|s| **s >= threshold).count();
79    let empirical_far = false_alarms as f32 / n_normal as f32;
80
81    let anomalies: Vec<f32> = samples
82        .iter()
83        .filter(|s| s.is_anomaly && s.score.is_finite())
84        .map(|s| s.score)
85        .collect();
86    let n_anomaly = anomalies.len();
87    let empirical_miss_rate = if n_anomaly == 0 {
88        None
89    } else {
90        let misses = anomalies.iter().filter(|s| **s < threshold).count();
91        Some(misses as f32 / n_anomaly as f32)
92    };
93
94    Some(FarCalibrationReport {
95        target_far,
96        threshold,
97        empirical_far,
98        n_normal,
99        n_anomaly,
100        empirical_miss_rate,
101    })
102}
103
104/// Maps a FAR calibration result into a statistical z-threshold config.
105#[must_use]
106pub fn apply_far_to_stat_config(
107    mut config: StatAnomalyConfig,
108    report: &FarCalibrationReport,
109) -> StatAnomalyConfig {
110    // z_threshold is absolute z; clamp to a sensible band.
111    config.z_threshold = report.threshold.clamp(1.0, 12.0);
112    config
113}
114
115/// Scores dwell/gap/hour absolute z-values on `series` vs `baseline` (for FAR).
116///
117/// All returned samples are marked `is_anomaly: false` (normal-window assumption).
118#[must_use]
119pub fn score_series_vs_baseline(
120    series: &AnalysisSeries,
121    baseline: &BaselineStats,
122    config: StatAnomalyConfig,
123) -> Vec<AnomalyScoreSample> {
124    let mut out = Vec::new();
125
126    if let (Some(mu), Some(sd)) = (baseline.dwell_mean, baseline.dwell_std) {
127        for d in &series.durations {
128            let v = d.duration_ns as f32;
129            if let Some(z) = z_score(v, mu, sd) {
130                out.push(AnomalyScoreSample {
131                    score: z,
132                    is_anomaly: false,
133                });
134            }
135        }
136    }
137    if config.use_robust
138        && let (Some(med), Some(mad_v)) = (baseline.dwell_median, baseline.dwell_mad)
139    {
140        for d in &series.durations {
141            let v = d.duration_ns as f32;
142            if let Some(z) = robust_z_score(v, med, mad_v) {
143                out.push(AnomalyScoreSample {
144                    score: z,
145                    is_anomaly: false,
146                });
147            }
148        }
149    }
150    if let (Some(mu), Some(sd)) = (baseline.gap_mean, baseline.gap_std) {
151        let mut by_subj: Vec<(Option<sightloom_core::SubjectId>, Vec<i64>)> = Vec::new();
152        for e in &series.timed {
153            if let Some((_, t)) = by_subj.iter_mut().find(|(s, _)| *s == e.subject_id) {
154                t.push(e.at_ns);
155            } else {
156                by_subj.push((e.subject_id, alloc::vec![e.at_ns]));
157            }
158        }
159        for (_, mut times) in by_subj {
160            times.sort_unstable();
161            for w in times.windows(2) {
162                let gap = (w[1] - w[0]) as f32;
163                if let Some(z) = z_score(gap, mu, sd) {
164                    out.push(AnomalyScoreSample {
165                        score: z,
166                        is_anomaly: false,
167                    });
168                }
169            }
170        }
171    }
172    if let (Some(mu), Some(sd)) = (baseline.hour_mean, baseline.hour_std) {
173        for e in &series.timed {
174            let hour = f32::from(hour_of_day_ns(e.at_ns));
175            let d = (hour - mu).abs();
176            let delta = d.min(24.0 - d);
177            if let Some(z) = z_score(mu + delta, mu, sd.max(0.5)) {
178                out.push(AnomalyScoreSample {
179                    score: z,
180                    is_anomaly: false,
181                });
182            }
183        }
184    }
185    out
186}
187
188/// End-to-end: baseline fit on history → score history → FAR threshold.
189#[must_use]
190pub fn calibrate_far_from_series(
191    history: &AnalysisSeries,
192    config: StatAnomalyConfig,
193    target_far: f32,
194) -> Option<FarCalibrationReport> {
195    let baseline = crate::stat_anomaly::build_baseline(history, config);
196    let scores = score_series_vs_baseline(history, &baseline, config);
197    calibrate_far_threshold(&scores, target_far)
198}
199
200#[cfg(test)]
201mod tests {
202    use super::*;
203    use crate::input::DurationSample;
204    use sightloom_core::SubjectId;
205
206    #[test]
207    fn far_threshold_orders_normals() {
208        let mut samples = Vec::new();
209        for i in 0..100 {
210            samples.push(AnomalyScoreSample {
211                score: i as f32 * 0.05,
212                is_anomaly: false,
213            });
214        }
215        // High scores are anomalies in this test set.
216        for i in 0..10 {
217            samples.push(AnomalyScoreSample {
218                score: 10.0 + i as f32,
219                is_anomaly: true,
220            });
221        }
222        let report = calibrate_far_threshold(&samples, 0.05).unwrap();
223        assert!(report.threshold > 0.0);
224        assert!(report.empirical_far <= 0.15);
225        assert!(report.empirical_miss_rate.is_some());
226    }
227
228    #[test]
229    fn series_far_smoke() {
230        let mut hist = AnalysisSeries::default();
231        for i in 0..30 {
232            hist.durations.push(DurationSample {
233                subject_id: Some(SubjectId(1)),
234                source_id: None,
235                zone_id: None,
236                duration_ns: 1_000_000_000 + i * 10_000,
237                at_ns: i * 86_400_000_000_000,
238                event_id: None,
239            });
240        }
241        let report = calibrate_far_from_series(&hist, StatAnomalyConfig::default(), 0.1);
242        assert!(report.is_some());
243    }
244}