Skip to main content

dima_core/
summary.rs

1//! Run-level summaries (D11, D32, D42, D43, D88).
2//!
3//! * The **eligible summary** (top-level keys) covers positions with support above the
4//!   threshold only, whose entropy the paper's correction applies to: mean, lowest and highest
5//!   (first position plus the number of tied positions), and position counts.
6//! * The **all-positions summary** reproduces DiMA v5.0.9's averaging rule (every position, NS
7//!   counted as 0 bits, LS/ELS with their reported entropy: the observed entropy with the
8//!   `dima` and `raw` estimators) for comparison with earlier results.
9//! * The **coverage summary** describes the estimated sample coverage (Chao & Jost 2012).
10
11use crate::model::{
12    AllPositionsSummary, CoverageSummary, Extremum, PositionResult, SupportLabel,
13    SupportLabelCounts,
14};
15use crate::numeric::Neumaier;
16
17/// Text of the all-positions averaging rule, recorded in the output.
18pub const ALL_POSITIONS_RULE: &str = "mean over all positions with positions without support \
19    counted as 0 bits and low-support positions with their reported entropy (DiMA v5.0.9's \
20    rule; v5.0.9 reported the last maximum with a 0-based position, here the first, 1-based)";
21
22/// Counts of positions per support class.
23#[must_use]
24pub fn label_counts(positions: &[PositionResult]) -> SupportLabelCounts {
25    let mut c = SupportLabelCounts::default();
26    for p in positions {
27        match p.low_support {
28            Some(SupportLabel::NoSupport) => c.no_support += 1,
29            Some(SupportLabel::Low) => c.low += 1,
30            Some(SupportLabel::EqualToThreshold) => c.equal_to_threshold += 1,
31            None => c.eligible += 1,
32        }
33    }
34    c
35}
36
37/// Mean (compensated sum) and extrema (first position, tie count) of `(position, value)` pairs
38/// in position order; all `None` when empty.
39#[must_use]
40pub fn describe(values: &[(u64, f64)]) -> (Option<f64>, Option<Extremum>, Option<Extremum>) {
41    let Some(&(first_pos, first_val)) = values.first() else {
42        return (None, None, None);
43    };
44    let mut sum = Neumaier::new();
45    let mut low = Extremum {
46        position: first_pos,
47        entropy: first_val,
48        tied_position_count: 0,
49    };
50    let mut high = low;
51    for &(pos, v) in values {
52        sum.add(v);
53        if v < low.entropy {
54            low = Extremum {
55                position: pos,
56                entropy: v,
57                tied_position_count: 0,
58            };
59        }
60        if v > high.entropy {
61            high = Extremum {
62                position: pos,
63                entropy: v,
64                tied_position_count: 0,
65            };
66        }
67    }
68    low.tied_position_count = values.iter().filter(|&&(_, v)| v == low.entropy).count() as u64;
69    high.tied_position_count = values.iter().filter(|&&(_, v)| v == high.entropy).count() as u64;
70    let mean = sum.total() / values.len() as f64;
71    (Some(mean), Some(low), Some(high))
72}
73
74/// The eligible summary: mean, lowest and highest entropy over positions with support > T.
75#[must_use]
76pub fn eligible(positions: &[PositionResult]) -> (Option<f64>, Option<Extremum>, Option<Extremum>) {
77    let values: Vec<(u64, f64)> = positions
78        .iter()
79        .filter(|p| p.low_support.is_none())
80        .filter_map(|p| p.entropy.map(|e| (p.position, e)))
81        .collect();
82    describe(&values)
83}
84
85/// The all-positions summary (DiMA v5.0.9's rule).
86#[must_use]
87pub fn all_positions(positions: &[PositionResult]) -> AllPositionsSummary {
88    let values: Vec<(u64, f64)> = positions
89        .iter()
90        .map(|p| (p.position, p.entropy.unwrap_or(0.0)))
91        .collect();
92    let (average_entropy, lowest_entropy, highest_entropy) = describe(&values);
93    AllPositionsSummary {
94        rule: ALL_POSITIONS_RULE.to_owned(),
95        position_count: values.len() as u64,
96        average_entropy,
97        lowest_entropy,
98        highest_entropy,
99    }
100}
101
102/// The sample-coverage summary.
103#[must_use]
104pub fn coverage(positions: &[PositionResult], min_coverage: Option<f64>) -> CoverageSummary {
105    let values: Vec<f64> = positions.iter().filter_map(|p| p.sample_coverage).collect();
106    let mut sum = Neumaier::new();
107    values.iter().for_each(|&v| sum.add(v));
108    CoverageSummary {
109        evaluated: values.len() as u64,
110        min: values.iter().copied().reduce(f64::min),
111        mean: (!values.is_empty()).then(|| sum.total() / values.len() as f64),
112        min_coverage,
113        below_min_count: min_coverage.map(|m| values.iter().filter(|&&v| v < m).count() as u64),
114    }
115}
116
117#[cfg(test)]
118mod tests {
119    use super::*;
120    use crate::model::EntropyMethod;
121
122    fn pos(
123        position: u64,
124        label: Option<SupportLabel>,
125        entropy: Option<f64>,
126        coverage: Option<f64>,
127    ) -> PositionResult {
128        PositionResult {
129            position,
130            low_support: label,
131            support: 0,
132            distinct_variants_count: 0,
133            entropy,
134            observed_entropy: entropy,
135            entropy_method: EntropyMethod::PlugIn,
136            entropy_fallback: None,
137            distinct_variants_incidence: None,
138            total_variants_incidence: None,
139            sample_coverage: coverage,
140            below_min_coverage: None,
141            diversity_motifs: Vec::new(),
142        }
143    }
144
145    #[test]
146    fn eligible_summary_uses_first_position_and_ties() {
147        let ps = vec![
148            pos(1, None, Some(1.0), Some(0.9)),
149            pos(2, Some(SupportLabel::NoSupport), None, None),
150            pos(3, None, Some(2.0), Some(0.8)),
151            pos(4, Some(SupportLabel::Low), Some(5.0), Some(0.5)),
152            pos(5, None, Some(2.0), Some(1.0)),
153            pos(6, None, Some(1.0), None),
154        ];
155        let (mean, low, high) = eligible(&ps);
156        assert_eq!(mean, Some(1.5));
157        assert_eq!(
158            low,
159            Some(Extremum {
160                position: 1,
161                entropy: 1.0,
162                tied_position_count: 2
163            })
164        );
165        assert_eq!(
166            high,
167            Some(Extremum {
168                position: 3,
169                entropy: 2.0,
170                tied_position_count: 2
171            })
172        );
173        let all = all_positions(&ps);
174        assert_eq!(all.position_count, 6);
175        assert_eq!(all.average_entropy, Some(11.0 / 6.0));
176        assert_eq!(
177            all.lowest_entropy.unwrap().position,
178            2,
179            "NS counts as 0 bits"
180        );
181        assert_eq!(all.highest_entropy.unwrap().position, 4);
182        let c = label_counts(&ps);
183        assert_eq!(
184            (c.no_support, c.low, c.equal_to_threshold, c.eligible),
185            (1, 1, 0, 4)
186        );
187        let cov = coverage(&ps, Some(0.85));
188        assert_eq!(cov.evaluated, 4);
189        assert_eq!(cov.min, Some(0.5));
190        assert_eq!(cov.below_min_count, Some(2));
191        assert!((cov.mean.unwrap() - 0.8).abs() < 1e-15);
192        assert_eq!(coverage(&ps, None).below_min_count, None);
193    }
194
195    #[test]
196    fn empty_summaries_are_null() {
197        assert_eq!(describe(&[]), (None, None, None));
198        let ps = vec![pos(1, Some(SupportLabel::NoSupport), None, None)];
199        assert_eq!(eligible(&ps), (None, None, None));
200        let cov = coverage(&ps, None);
201        assert_eq!((cov.evaluated, cov.min, cov.mean), (0, None, None));
202        assert_eq!(all_positions(&[]).average_entropy, None);
203    }
204}