sightloom_analysis/
far_calibrate.rs1#![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#[derive(Clone, Copy, Debug, PartialEq)]
22pub struct AnomalyScoreSample {
23 pub score: f32,
25 pub is_anomaly: bool,
27}
28
29#[derive(Clone, Copy, Debug, PartialEq)]
31pub struct FarCalibrationReport {
32 pub target_far: f32,
34 pub threshold: f32,
36 pub empirical_far: f32,
38 pub n_normal: usize,
40 pub n_anomaly: usize,
42 pub empirical_miss_rate: Option<f32>,
44}
45
46#[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 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#[must_use]
106pub fn apply_far_to_stat_config(
107 mut config: StatAnomalyConfig,
108 report: &FarCalibrationReport,
109) -> StatAnomalyConfig {
110 config.z_threshold = report.threshold.clamp(1.0, 12.0);
112 config
113}
114
115#[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#[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 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}