hpr_flightdata/readings/interval.rs
1//! The readings' 90% intervals ([ADR-257][adr-257] §1, [ADR-308][adr-308]).
2//!
3//! A reading's bound is the most its error can be, held on the tuning set; a 90% interval is
4//! narrower, and says how far off the reading usually is. Each comes from the reading's own
5//! bound: the interval runs from the reading less [`Shares::high`] of its bound to the reading
6//! less [`Shares::low`] of it. The two shares are the 5% and 95% points of the reading's error
7//! as a share of its bound, `(reading − truth)/bound`, measured on the synthetic flights' own
8//! calibration set (2,000 flights on a seed of their own, each flight's own logger's log) and
9//! written here to three significant figures. The point from each end is the `⌊0.05 (n + 1)⌋`-th
10//! of the `n` sorted shares, the split-conformal rank (V. Vovk, A. Gammerman and G. Shafer,
11//! *Algorithmic Learning in a Random World*, Springer, 2005, ch. 2; J. Lei et al.,
12//! "Distribution-free predictive inference for regression", *JASA* 113(523), 1094–1111, 2018).
13//! `cargo xtask synthetic` fits them again and fails if they differ from the values here, then
14//! holds the intervals to the coverage test of [ADR-257][adr-257], calibrated intervals, on the
15//! two test sets.
16//!
17//! **How far to trust it.** Over flights drawn as the synthetic ones are, a reading's interval
18//! holds the truth about 90% of the time and misses about 5% on each side. The 90% is over their
19//! days, spread evenly within 15 K of the standard atmosphere, and the misses aren't: most of the
20//! height's error is the day's air, so no height missed on a day within 10 K of standard, while a
21//! third of the days warmer than that read low enough to leave the truth above the interval, the
22//! flattering side for a waiver (#1055). The top speed and the mean descent rate, taken from the
23//! same height, miss the same way, the flattering side for a fin's margin and for how gentle the
24//! descent was (#1061); for flights at or past the top speed's transonic mark, only its low
25//! readings are given. The times lean by logger: on the AltOS logs, the apogee time's interval
26//! misses late about one time in six or seven (#1056), and liftoff, landing and the flight time
27//! lean on others (#1062). The top acceleration's interval leans by logger too: on the AltOS logs
28//! the truth misses about one time in five, and on the 500 Hz IMU's it never did (#1070). The
29//! canopies' rates miss as the height does, by the day's air. The top speed is tested only where
30//! it is given, below [`super::TRANSONIC_SPEED_M_S`]. A real flight can lie outside what the sets draw, as a day more
31//! than 15 K from standard does; its interval then says less than 90%. No real flight has yet
32//! checked one (evidence row G34).
33//!
34//! **A floor** ([ADR-308][adr-308]) states only a lower end, the reading less its 95% share
35//! of its bound ([`FloorShares`]), as its truth may lie any amount above it. A burnout from the
36//! top speed's peak fits its share on its own floors. How far past a clip a top acceleration goes
37//! is the design's, and no log says: a first fit on tops as flown put the lower end above the
38//! reading, and one design whose tops only just passed the clip left 21 of 22 truths below it. So
39//! its share is fitted on every top the reader can call clipped and the part may not have clipped:
40//! from where a gain `s` high and the part's bias carry a top up to the reader's threshold, a
41//! quarter g under the range, to `1/(1 − s)`, past which every part clips. A truth lies below the
42//! lower end only on a top under the clip that the gain carried up to it; a top truly past the clip
43//! lies above the reading. An apogee floor states none, nor a top whose burn
44//! the log ends in: no synthetic set reads one (#1071).
45//!
46//! [adr-257]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/decisions/0257-the-2026-10-13-review-calibrated-intervals-and-the-post-flight-comparison.md
47//! [adr-308]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/decisions/0308-m7-2e-in-four-the-intervals-by-reading-then-the-surfaces.md
48
49use serde::{Deserialize, Serialize};
50
51/// A 90% interval on a reading: on the synthetic flights, the truth lay below [`Interval::low`]
52/// about 5% of the time and above [`Interval::high`] about 5%.
53#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
54pub struct Interval {
55 /// Its lower end, in the reading's unit.
56 pub low: f64,
57 /// Its upper end, in the reading's unit.
58 pub high: f64,
59}
60
61/// A reading's error, `(reading − truth)/bound`, at its 5% and 95% points on the calibration set.
62#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
63pub struct Shares {
64 /// The 5% point: an error lower than this is the truth above the interval.
65 pub low: f64,
66 /// The 95% point: an error higher than this is the truth below the interval.
67 pub high: f64,
68}
69
70impl Shares {
71 /// The 90% interval on `reading` with its `bound`: from `reading − high · bound` to
72 /// `reading − low · bound`. `None` when either isn't finite, or the bound isn't positive.
73 pub fn interval(self, reading: f64, bound: f64) -> Option<Interval> {
74 let (low, high) = (reading - self.high * bound, reading - self.low * bound);
75 (reading.is_finite() && bound.is_finite() && bound > 0.0 && low.is_finite())
76 .then_some(Interval { low, high })
77 .filter(|i| i.high.is_finite() && i.low <= i.high)
78 }
79}
80
81/// A floor's error, `(reading − truth)/bound`, on the calibration set. A floor's truth may lie any
82/// amount above it, so only its lower side is stated.
83#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
84pub struct FloorShares {
85 /// The 95% point: an error higher than this is the truth below the lower end.
86 pub high: f64,
87 /// The median: the lower end's standard error is measured to it.
88 pub median: f64,
89}
90
91impl FloorShares {
92 /// The lower end on `reading` with its `bound`, `reading − high · bound`. `None` when either
93 /// isn't finite, or the bound isn't positive.
94 pub fn lower_end(self, reading: f64, bound: f64) -> Option<f64> {
95 let low = reading - self.high * bound;
96 (reading.is_finite() && bound.is_finite() && bound > 0.0 && low.is_finite()).then_some(low)
97 }
98
99 /// The lower end's standard error with `bound`, the same unit: `(high − median) · bound` over
100 /// the standard normal's 95% point, as an interval's width over `2 × 1.645` is.
101 pub fn standard_error(self, bound: f64) -> f64 {
102 (self.high - self.median) * bound / Z_90
103 }
104}
105
106/// The standard normal's 95% point: a 90% interval's half-width over its standard error.
107pub const Z_90: f64 = 1.644_853_626_951_472_2;
108
109/// The apogee height's shares of its bound (`Apogee::bound_m`), fitted on the calibration set.
110pub const APOGEE_HEIGHT_SHARES: Shares = Shares {
111 low: -0.631,
112 high: 0.637,
113};
114
115/// The apogee time's shares of its bound (`Apogee::time_bound_s`), fitted on the calibration set.
116pub const APOGEE_TIME_SHARES: Shares = Shares {
117 low: -0.331,
118 high: 0.227,
119};
120
121/// Liftoff's shares of its bound (`Liftoff::bound_s`), fitted on the calibration set.
122pub const LIFTOFF_SHARES: Shares = Shares {
123 low: 0.203,
124 high: 0.482,
125};
126
127/// The top speed's shares of its bound (`MaxSpeed::bound_m_s`), fitted on the calibration set.
128pub const TOP_SPEED_SHARES: Shares = Shares {
129 low: -0.218,
130 high: 0.265,
131};
132
133/// Landing's shares of its bound (`Landing::bound_s`), fitted on the calibration set.
134pub const LANDING_SHARES: Shares = Shares {
135 low: -0.335,
136 high: 0.156,
137};
138
139/// The flight time's shares of its bound (`FlightTime::bound_s`), fitted on the calibration set.
140pub const FLIGHT_TIME_SHARES: Shares = Shares {
141 low: -0.379,
142 high: -0.132,
143};
144
145/// The mean descent rate's shares of its bound (`Landing::mean_descent_rate_bound_m_s`), fitted
146/// on the calibration set.
147pub const DESCENT_RATE_SHARES: Shares = Shares {
148 low: -0.475,
149 high: 0.495,
150};
151
152/// The top acceleration's shares of its bound (`MaxAcceleration::bound_m_s2`), where it isn't a
153/// floor, fitted on the calibration set.
154pub const TOP_ACCELERATION_SHARES: Shares = Shares {
155 low: -0.495,
156 high: 0.568,
157};
158
159/// Burnout's shares of its bound (`Burnout::bound_s`), where it isn't a floor, fitted on the
160/// calibration set.
161pub const BURNOUT_SHARES: Shares = Shares {
162 low: -0.065,
163 high: 0.0689,
164};
165
166/// The drogue's rate's shares of its bound (`Descent::bound_m_s`), fitted on the calibration set.
167pub const DROGUE_RATE_SHARES: Shares = Shares {
168 low: -0.622,
169 high: 0.612,
170};
171
172/// The main's opening's shares of its bound (`Opening::bound_s`), fitted on the calibration set.
173pub const MAIN_OPENING_SHARES: Shares = Shares {
174 low: 0.138,
175 high: 0.567,
176};
177
178/// The main's rate's shares of its bound (`Descent::bound_m_s`), fitted on the calibration set.
179pub const MAIN_RATE_SHARES: Shares = Shares {
180 low: -0.574,
181 high: 0.586,
182};
183
184/// A burnout floor's shares of its bound (`Burnout::bound_s`), fitted on the calibration set.
185pub const BURNOUT_FLOOR_SHARES: FloorShares = FloorShares {
186 high: -0.0335,
187 median: -0.194,
188};
189
190/// A top acceleration floor's shares of its bound (`MaxAcceleration::bound_m_s2`), fitted on the
191/// calibration set's flights with their accelerometers clipping at 8 g and their tops scaled to
192/// anywhere the reader can call them clipped and the part may not have clipped: how far past a
193/// clip a top goes depends on the design, and no log says.
194pub const TOP_ACCELERATION_FLOOR_SHARES: FloorShares = FloorShares {
195 high: 0.259,
196 median: -0.124,
197};
198
199/// The rank from each end of `n` sorted shares that is the 5% or 95% point, `⌊0.05 (n + 1)⌋`,
200/// counted from 1; at least 1.
201pub fn tail_rank(n: usize) -> usize {
202 ((n + 1) / 20).max(1)
203}
204
205/// The 5% and 95% points of `shares`, each the [`tail_rank`]-th from its end. `None` when there
206/// are fewer than 20 shares or any isn't finite.
207pub fn fit(shares: &[f64]) -> Option<Shares> {
208 if shares.len() < 20 || shares.iter().any(|s| !s.is_finite()) {
209 return None;
210 }
211 let mut sorted = shares.to_vec();
212 sorted.sort_by(f64::total_cmp);
213 let k = tail_rank(sorted.len());
214 Some(Shares {
215 low: sorted[k - 1],
216 high: sorted[sorted.len() - k],
217 })
218}
219
220/// A floor's 95% point, the [`tail_rank`]-th from the top, and its median. `None` when there are
221/// fewer than 20 shares or any isn't finite.
222pub fn fit_floor(shares: &[f64]) -> Option<FloorShares> {
223 if shares.len() < 20 || shares.iter().any(|s| !s.is_finite()) {
224 return None;
225 }
226 let mut sorted = shares.to_vec();
227 sorted.sort_by(f64::total_cmp);
228 let n = sorted.len();
229 Some(FloorShares {
230 high: sorted[n - tail_rank(n)],
231 median: 0.5 * (sorted[(n - 1) / 2] + sorted[n / 2]),
232 })
233}
234
235#[cfg(test)]
236mod tests {
237 use super::*;
238
239 #[test]
240 fn the_interval_runs_from_the_high_share_to_the_low_one() {
241 let shares = Shares {
242 low: -0.2,
243 high: 0.5,
244 };
245 // An error of +0.5 bound means the truth sits 0.5 bound below the reading: the low end.
246 let i = shares.interval(100.0, 10.0).unwrap();
247 assert_eq!((i.low, i.high), (95.0, 102.0));
248 assert!(shares.interval(100.0, 0.0).is_none());
249 assert!(shares.interval(100.0, -1.0).is_none());
250 assert!(shares.interval(f64::NAN, 1.0).is_none());
251 assert!(shares.interval(100.0, f64::INFINITY).is_none());
252 // Shares that cross give no interval.
253 let crossed = Shares {
254 low: 0.5,
255 high: -0.2,
256 };
257 assert!(crossed.interval(100.0, 10.0).is_none());
258 }
259
260 #[test]
261 fn a_floors_lower_end_and_standard_error_come_from_its_shares() {
262 let shares = FloorShares {
263 high: -0.05,
264 median: -0.2,
265 };
266 // An error of −0.05 bound leaves the truth above the reading: the lower end lies above it.
267 assert_eq!(shares.lower_end(100.0, 10.0), Some(100.5));
268 let se = shares.standard_error(10.0);
269 assert!((se - 1.5 / Z_90).abs() < 1e-12, "{se}");
270 assert!(shares.lower_end(100.0, 0.0).is_none());
271 assert!(shares.lower_end(100.0, -1.0).is_none());
272 assert!(shares.lower_end(f64::NAN, 1.0).is_none());
273 assert!(shares.lower_end(100.0, f64::INFINITY).is_none());
274 }
275
276 #[test]
277 fn the_floor_fit_takes_the_top_rank_and_the_median() {
278 let shares: Vec<f64> = (0..2000).map(|k| ((k * 7919) % 2000) as f64).collect();
279 let fitted = fit_floor(&shares).unwrap();
280 assert_eq!((fitted.high, fitted.median), (1900.0, 999.5));
281 assert!(fit_floor(&shares[..19]).is_none());
282 let mut bad = shares.clone();
283 bad[7] = f64::NAN;
284 assert!(fit_floor(&bad).is_none());
285 }
286
287 #[test]
288 fn the_fit_takes_the_conformal_rank_from_each_end() {
289 // 0, 1, …, 1999 shuffled: n = 2000, ⌊0.05 · 2001⌋ = 100, so the 100th from each end.
290 let shares: Vec<f64> = (0..2000).map(|k| ((k * 7919) % 2000) as f64).collect();
291 assert_eq!(tail_rank(2000), 100);
292 let fitted = fit(&shares).unwrap();
293 assert_eq!((fitted.low, fitted.high), (99.0, 1900.0));
294 assert_eq!(tail_rank(19), 1);
295 assert_eq!(tail_rank(39), 2);
296 assert!(fit(&shares[..19]).is_none());
297 let mut bad = shares.clone();
298 bad[7] = f64::NAN;
299 assert!(fit(&bad).is_none());
300 }
301}