Skip to main content

ggplot_rs/
summary.rs

1//! What a built plot draws, as numbers: per layer (and facet panel) and per
2//! series, how many marks, the x range, the y minimum / maximum and where,
3//! the first and last y, a band's extent, the series' shape (its largest
4//! move against the trend, its peaks) and which series leads at each x. A
5//! caller that writes about a chart (a title, an answer) can quote these
6//! instead of guessing them.
7//!
8//! ```
9//! use ggplot_rs::prelude::*;
10//! let df = vec![
11//!     ("x".to_string(), vec![Value::Str("a".into()), Value::Str("b".into())]),
12//!     ("y".to_string(), vec![Value::Float(3.0), Value::Float(5.0)]),
13//! ];
14//! let built = GGPlot::new(df).aes(Aes::new().x("x").y("y")).geom_col().build();
15//! assert_eq!(built.summary_text(), "col: 2 marks, x a … b; y first 3, last 5, min 3 at a, max 5 at b");
16//! ```
17
18use crate::build::BuiltPlot;
19use crate::data::{format_epoch_secs, DataFrame, Value};
20
21/// Columns that name a layer's series, in order of preference.
22const SERIES_COLS: &[&str] = &["colour", "color", "fill", "group"];
23/// At most this many series per layer are listed; the rest are counted.
24pub const MAX_SERIES: usize = 12;
25
26/// One layer of one panel.
27#[derive(Debug, Clone, PartialEq)]
28pub struct LayerSummary {
29    /// The geom's name (`line`, `col`, `smooth`, …).
30    pub geom: String,
31    /// The facet panel's label, when the plot is faceted.
32    pub panel: Option<String>,
33    pub series: Vec<SeriesSummary>,
34    /// Two or more series over the same x values: which one is highest at
35    /// each shared x — `(series, how many x)`, most first — and how many x
36    /// they share. "A is always the highest" holds only when A has them all.
37    pub leaders: Option<Leaders>,
38}
39
40/// Who is highest at each shared x: `(series, how many x)` most first, and
41/// how many x the series share.
42pub type Leaders = (Vec<(String, usize)>, usize);
43
44/// A move of a series between two of its marks: `(y, x)` at each end.
45#[derive(Debug, Clone, PartialEq)]
46pub struct Move {
47    pub from: (f64, String),
48    pub to: (f64, String),
49}
50
51/// One series of a layer (all its rows when the layer has no series column).
52#[derive(Debug, Clone, PartialEq)]
53pub struct SeriesSummary {
54    /// The series' value (its colour / fill / group), `None` for a single one.
55    pub key: Option<String>,
56    /// Rows with a finite y.
57    pub n: usize,
58    /// The x extent: the smallest and largest of a numeric or date x, the
59    /// first and last (in the order drawn) of a discrete one.
60    pub x_from: String,
61    pub x_to: String,
62    pub y_first: f64,
63    pub y_last: f64,
64    /// `(y, x)` of the smallest and largest y (the first, on a tie).
65    pub y_min: (f64, String),
66    pub y_max: (f64, String),
67    /// `(lowest ymin, highest ymax)` of a band (ribbon, smooth, interval).
68    pub band: Option<(f64, f64)>,
69    /// The band's width (ymax − ymin) at `x_from` and at `x_to`: whether
70    /// the uncertainty widens or narrows along x.
71    pub band_width: Option<(f64, f64)>,
72    /// Every mark's `(x label, y)`, in the order drawn.
73    pub points: Vec<(String, f64)>,
74    /// How y goes with a numeric x on a point layer (a scatter, a bubble
75    /// chart) of at least [`MIN_COR_POINTS`] marks.
76    pub cor: Option<Correlation>,
77    /// Along an ordered x (at least [`MIN_SHAPE_POINTS`] marks): the
78    /// largest move against the series' net direction — the deepest fall of
79    /// a series that ends higher than it starts, the biggest rise of one
80    /// that ends lower — when it is at least a tenth of the y range. A
81    /// series that "rises steadily" has none worth naming.
82    pub counter_move: Option<Move>,
83    /// Along an ordered x: the local maxima that stand out by at least a
84    /// quarter of the y range (their prominence), highest first. Two or
85    /// more: the series peaks more than once.
86    pub peaks: Vec<(f64, String)>,
87}
88
89/// A series needs this many marks for its shape (counter move, peaks).
90pub const MIN_SHAPE_POINTS: usize = 4;
91
92/// A point layer needs this many marks for a correlation.
93pub const MIN_COR_POINTS: usize = 5;
94
95/// How two things go together in a scatter: y with x, and a bubble's size
96/// with x and with y.
97#[derive(Debug, Clone, PartialEq)]
98pub struct Correlation {
99    /// Pearson's r of x and y.
100    pub r: f64,
101    /// Spearman's ρ of x and y (ranks: any monotone trend).
102    pub rho: f64,
103    /// Spearman's ρ of the size with x and with y, for a bubble chart.
104    pub size_rho: Option<(f64, f64)>,
105}
106
107/// The summaries of every layer, panel by panel.
108#[derive(Debug, Clone, PartialEq, Default)]
109pub struct PlotSummary {
110    pub layers: Vec<LayerSummary>,
111    /// Two series over the same x values: their difference per x.
112    pub compare: Option<Comparison>,
113    /// A faceted plot whose panels each draw one series of the same layer
114    /// over the same x: which panel is highest at each shared x, as
115    /// [`LayerSummary::leaders`], with the layer's geom.
116    pub panel_leaders: Option<(String, Leaders)>,
117}
118
119/// `b − a` per shared x, for a plot of exactly two series (2025 against
120/// 2024, actual against plan): where the gap is largest and smallest.
121#[derive(Debug, Clone, PartialEq)]
122pub struct Comparison {
123    pub a: String,
124    pub b: String,
125    /// `(b − a, (b − a) / |a| in %, x)` of the largest and smallest difference.
126    pub largest: (f64, Option<f64>, String),
127    pub smallest: (f64, Option<f64>, String),
128    /// The same by the % change, when that ranks the x values differently.
129    pub largest_pct: Option<(f64, Option<f64>, String)>,
130    pub smallest_pct: Option<(f64, Option<f64>, String)>,
131}
132
133impl BuiltPlot {
134    /// What the plot draws, as numbers (see the [module docs](crate::summary)).
135    pub fn summary(&self) -> PlotSummary {
136        // a date x stays a date in the stat output too (a smooth's grid is
137        // plain numbers): format those as dates as well
138        let date_x = self.layers.iter().any(|l| {
139            l.data
140                .column("x")
141                .is_some_and(|c| c.iter().any(|v| v.is_datetime()))
142        });
143        let mut layers = Vec::new();
144        let faceted = self.panels.len() > 1 && !self.panels_data.is_empty();
145        if faceted {
146            for (p, data) in self.panels.iter().zip(&self.panels_data) {
147                for (l, d) in self.layers.iter().zip(data) {
148                    if let Some(s) = layer_summary(l.geom.name(), d, date_x) {
149                        layers.push(LayerSummary {
150                            panel: Some(p.label.clone()),
151                            ..s
152                        });
153                    }
154                }
155            }
156        } else {
157            for l in &self.layers {
158                layers.extend(layer_summary(l.geom.name(), &l.data, date_x));
159            }
160        }
161        // a layer repeating the one before it (a line's point markers) is
162        // one entry: `line+point`
163        let mut merged: Vec<LayerSummary> = Vec::new();
164        for l in layers {
165            match merged.last_mut() {
166                Some(m) if m.panel == l.panel && m.series == l.series => {
167                    m.geom = format!("{}+{}", m.geom, l.geom);
168                }
169                _ => merged.push(l),
170            }
171        }
172        let compare = compare(&merged);
173        let panel_leaders = faceted.then(|| panel_leaders(&merged)).flatten();
174        PlotSummary {
175            layers: merged,
176            compare,
177            panel_leaders,
178        }
179    }
180
181    /// [`summary`](Self::summary) as text, one line per layer and panel.
182    pub fn summary_text(&self) -> String {
183        self.summary().to_string()
184    }
185}
186
187impl std::fmt::Display for PlotSummary {
188    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
189        for (i, l) in self.layers.iter().enumerate() {
190            if i > 0 {
191                writeln!(f)?;
192            }
193            match &l.panel {
194                Some(p) => write!(f, "{} [{p}]:", l.geom)?,
195                None => write!(f, "{}:", l.geom)?,
196            }
197            let shown = l.series.len().min(MAX_SERIES);
198            for (j, s) in l.series[..shown].iter().enumerate() {
199                if j > 0 {
200                    write!(f, ";")?;
201                }
202                if let Some(k) = &s.key {
203                    write!(f, " {k} —")?;
204                }
205                // a ribbon is its band: its y is only the lower edge
206                if let (true, Some((lo, hi))) = (l.geom == "ribbon", s.band) {
207                    write!(
208                        f,
209                        " {} mark{}, x {} … {}, band {} … {}",
210                        s.n,
211                        if s.n == 1 { "" } else { "s" },
212                        s.x_from,
213                        s.x_to,
214                        num(lo),
215                        num(hi)
216                    )?;
217                    write_width(f, s)?;
218                    continue;
219                }
220                write!(
221                    f,
222                    " {} mark{}, x {} … {}; y first {}, last {}, min {} at {}, max {} at {}",
223                    s.n,
224                    if s.n == 1 { "" } else { "s" },
225                    s.x_from,
226                    s.x_to,
227                    num(s.y_first),
228                    num(s.y_last),
229                    num(s.y_min.0),
230                    s.y_min.1,
231                    num(s.y_max.0),
232                    s.y_max.1
233                )?;
234                if let Some((lo, hi)) = s.band {
235                    write!(f, ", band {} … {}", num(lo), num(hi))?;
236                    write_width(f, s)?;
237                }
238                if let Some(m) = &s.counter_move {
239                    let word = if m.to.0 < m.from.0 { "fall" } else { "rise" };
240                    write!(
241                        f,
242                        "; against the trend: largest {word} {} at {} → {} at {}",
243                        num(m.from.0),
244                        m.from.1,
245                        num(m.to.0),
246                        m.to.1
247                    )?;
248                }
249                if s.peaks.len() > 1 {
250                    let list: Vec<String> = s.peaks[..s.peaks.len().min(3)]
251                        .iter()
252                        .map(|(y, x)| format!("{} at {x}", num(*y)))
253                        .collect();
254                    let more = if s.peaks.len() > 3 { ", …" } else { "" };
255                    write!(f, "; {} peaks: {}{more}", s.peaks.len(), list.join(", "))?;
256                }
257                if let Some(c) = &s.cor {
258                    write!(
259                        f,
260                        "; y {} with x (r {}, ρ {})",
261                        trend(c.rho),
262                        num(round2(c.r)),
263                        num(round2(c.rho))
264                    )?;
265                    if let Some((sx, sy)) = c.size_rho {
266                        write!(
267                            f,
268                            "; size {} with x (ρ {}), {} with y (ρ {})",
269                            trend(sx),
270                            num(round2(sx)),
271                            trend(sy),
272                            num(round2(sy))
273                        )?;
274                    }
275                }
276            }
277            if l.series.len() > shown {
278                write!(f, "; +{} more series", l.series.len() - shown)?;
279            }
280            if let Some((top, shared)) = &l.leaders {
281                let list: Vec<String> = top.iter().map(|(k, c)| format!("{k} {c}")).collect();
282                write!(
283                    f,
284                    "; highest at each of {shared} shared x: {}",
285                    list.join(", ")
286                )?;
287            }
288        }
289        if let Some((geom, (top, shared))) = &self.panel_leaders {
290            let list: Vec<String> = top.iter().map(|(k, c)| format!("{k} {c}")).collect();
291            write!(
292                f,
293                "\n{geom} across panels: highest at each of {shared} shared x: {}",
294                list.join(", ")
295            )?;
296        }
297        if let Some(c) = &self.compare {
298            let one = |(d, p, x): &(f64, Option<f64>, String)| {
299                let sign = if *d >= 0.0 { "+" } else { "" };
300                match p {
301                    Some(p) => format!("{sign}{} ({sign}{} %) at {x}", num(*d), num(*p)),
302                    None => format!("{sign}{} at {x}", num(*d)),
303                }
304            };
305            write!(
306                f,
307                "\n{} − {}: largest {}, smallest {}",
308                c.b,
309                c.a,
310                one(&c.largest),
311                one(&c.smallest)
312            )?;
313            if let (Some(l), Some(s)) = (&c.largest_pct, &c.smallest_pct) {
314                write!(f, "; by %: largest {}, smallest {}", one(l), one(s))?;
315            }
316        }
317        Ok(())
318    }
319}
320
321/// The plot's series outside bands and ribbons; exactly two named ones over
322/// the same (at least two) x values are compared.
323fn compare(layers: &[LayerSummary]) -> Option<Comparison> {
324    let series: Vec<&SeriesSummary> = layers
325        .iter()
326        .filter(|l| l.panel.is_none() && l.geom != "ribbon" && l.geom != "smooth")
327        .flat_map(|l| &l.series)
328        .collect();
329    let [a, b] = series.as_slice() else {
330        return None;
331    };
332    let (ka, kb) = (a.key.clone()?, b.key.clone()?);
333    if ka == kb || a.points.len() < 2 || a.points.len() != b.points.len() {
334        return None;
335    }
336    let diffs: Vec<(f64, Option<f64>, String)> = a
337        .points
338        .iter()
339        .map(|(x, ya)| {
340            let yb = b.points.iter().find(|(xb, _)| xb == x)?.1;
341            let d = yb - ya;
342            Some((d, (*ya != 0.0).then(|| 100.0 * d / ya.abs()), x.clone()))
343        })
344        .collect::<Option<_>>()?;
345    let pick = |better: fn(f64, f64) -> bool| {
346        diffs
347            .iter()
348            .fold(None::<&(f64, Option<f64>, String)>, |m, d| match m {
349                Some(m) if !better(d.0, m.0) => Some(m),
350                _ => Some(d),
351            })
352            .cloned()
353    };
354    let largest = pick(|x, y| x > y)?;
355    let smallest = pick(|x, y| x < y)?;
356    let by_pct = |better: fn(f64, f64) -> bool| {
357        diffs
358            .iter()
359            .filter_map(|d| d.1.map(|p| (p, d)))
360            .fold(
361                None::<(f64, &(f64, Option<f64>, String))>,
362                |m, (p, d)| match m {
363                    Some(m) if !better(p, m.0) => Some(m),
364                    _ => Some((p, d)),
365                },
366            )
367            .map(|(_, d)| d.clone())
368    };
369    let (lp, sp) = (by_pct(|x, y| x > y), by_pct(|x, y| x < y));
370    // only when % ranks them differently (else it repeats the line above)
371    let differs = lp.as_ref().map(|l| &l.2) != Some(&largest.2)
372        || sp.as_ref().map(|s| &s.2) != Some(&smallest.2);
373    Some(Comparison {
374        a: ka,
375        b: kb,
376        largest,
377        smallest,
378        largest_pct: lp.filter(|_| differs),
379        smallest_pct: sp.filter(|_| differs),
380    })
381}
382
383/// A correlation in words: how strongly, and which way.
384fn trend(rho: f64) -> &'static str {
385    match (rho.abs(), rho > 0.0) {
386        (a, _) if a < 0.2 => "shows no clear trend",
387        (a, true) if a < 0.4 => "rises weakly",
388        (a, false) if a < 0.4 => "falls weakly",
389        (a, true) if a < 0.7 => "rises moderately",
390        (a, false) if a < 0.7 => "falls moderately",
391        (_, true) => "rises strongly",
392        (_, false) => "falls strongly",
393    }
394}
395
396fn round2(v: f64) -> f64 {
397    (v * 100.0).round() / 100.0
398}
399
400/// Pearson's r, `None` when either side doesn't vary.
401fn pearson(a: &[f64], b: &[f64]) -> Option<f64> {
402    let n = a.len() as f64;
403    let (ma, mb) = (a.iter().sum::<f64>() / n, b.iter().sum::<f64>() / n);
404    let (mut sab, mut saa, mut sbb) = (0.0, 0.0, 0.0);
405    for (x, y) in a.iter().zip(b) {
406        sab += (x - ma) * (y - mb);
407        saa += (x - ma) * (x - ma);
408        sbb += (y - mb) * (y - mb);
409    }
410    (saa > 0.0 && sbb > 0.0).then(|| (sab / (saa * sbb).sqrt()).clamp(-1.0, 1.0))
411}
412
413/// Average ranks (ties share their mean rank).
414fn ranks(v: &[f64]) -> Vec<f64> {
415    let mut ix: Vec<usize> = (0..v.len()).collect();
416    ix.sort_by(|&i, &j| v[i].total_cmp(&v[j]));
417    let mut r = vec![0.0; v.len()];
418    let mut k = 0;
419    while k < ix.len() {
420        let mut e = k;
421        while e + 1 < ix.len() && v[ix[e + 1]] == v[ix[k]] {
422            e += 1;
423        }
424        let avg = (k + e) as f64 / 2.0 + 1.0;
425        for &i in &ix[k..=e] {
426            r[i] = avg;
427        }
428        k = e + 1;
429    }
430    r
431}
432
433fn spearman(a: &[f64], b: &[f64]) -> Option<f64> {
434    pearson(&ranks(a), &ranks(b))
435}
436
437/// `, width 16 at a → 25.3 at b (widens)` for a band.
438fn write_width(f: &mut std::fmt::Formatter<'_>, s: &SeriesSummary) -> std::fmt::Result {
439    let Some((a, b)) = s.band_width else {
440        return Ok(());
441    };
442    let trend = if (b - a).abs() <= 0.02 * a.abs().max(b.abs()) {
443        "about even"
444    } else if b > a {
445        "widens"
446    } else {
447        "narrows"
448    };
449    write!(
450        f,
451        ", width {} at {} → {} at {} ({trend})",
452        num(a),
453        s.x_from,
454        num(b),
455        s.x_to
456    )
457}
458
459fn layer_summary(geom: &str, d: &DataFrame, date_x: bool) -> Option<LayerSummary> {
460    let x = d.column("x")?;
461    // a stacked layer keeps each mark's own value in `.y_raw`
462    let y = d.column(".y_raw").or_else(|| d.column("y"))?;
463    let key = SERIES_COLS.iter().find_map(|c| d.column(c));
464    let (ymin, ymax) = (d.column("ymin"), d.column("ymax"));
465    // a band is drawn only by a layer whose ymin/ymax differ from its y
466    // (a bar's ymin = 0 is its base, not a band)
467    let banded = matches!(
468        geom,
469        "ribbon" | "smooth" | "errorbar" | "linerange" | "pointrange" | "crossbar"
470    );
471    let mut order: Vec<String> = Vec::new();
472    let mut rows: Vec<Vec<usize>> = Vec::new();
473    for i in 0..d.nrows() {
474        let k = key.map(|k| label(&k[i], false)).unwrap_or_default();
475        let at = match order.iter().position(|o| *o == k) {
476            Some(at) => at,
477            None => {
478                order.push(k);
479                rows.push(Vec::new());
480                order.len() - 1
481            }
482        };
483        rows[at].push(i);
484    }
485    let series: Vec<SeriesSummary> = order
486        .into_iter()
487        .zip(rows)
488        .filter_map(|(k, ix)| {
489            let pts: Vec<(usize, f64)> = ix
490                .into_iter()
491                .filter_map(|i| y[i].as_f64().filter(|v| v.is_finite()).map(|v| (i, v)))
492                .collect();
493            let (&(i0, y0), &(i1, y1)) = (pts.first()?, pts.last()?);
494            let lo = pts
495                .iter()
496                .fold(pts[0], |a, b| if b.1 < a.1 { *b } else { a });
497            let hi = pts
498                .iter()
499                .fold(pts[0], |a, b| if b.1 > a.1 { *b } else { a });
500            let xl = |i: usize| label(&x[i], date_x);
501            let band = banded.then(|| {
502                let f = |c: Option<&[Value]>, pick: fn(f64, f64) -> f64| {
503                    c.and_then(|c| {
504                        pts.iter()
505                            .filter_map(|(i, _)| c[*i].as_f64().filter(|v| v.is_finite()))
506                            .reduce(pick)
507                    })
508                };
509                f(ymin, f64::min).zip(f(ymax, f64::max))
510            });
511            // a numeric / date x: its extent, not the row order (a scatter's
512            // rows are in no x order)
513            let xs: Vec<(usize, f64)> = pts
514                .iter()
515                .filter(|(i, _)| !matches!(x[*i], Value::Str(_)))
516                .filter_map(|(i, _)| x[*i].as_f64().map(|v| (*i, v)))
517                .collect();
518            let (ia, ib) = if xs.len() == pts.len() {
519                let a = xs.iter().fold(xs[0], |a, b| if b.1 < a.1 { *b } else { a });
520                let b = xs.iter().fold(xs[0], |a, b| if b.1 > a.1 { *b } else { a });
521                (a.0, b.0)
522            } else {
523                (i0, i1)
524            };
525            let (x_from, x_to) = (xl(ia), xl(ib));
526            let width = |i: usize| {
527                let lo = ymin?.get(i)?.as_f64()?;
528                let hi = ymax?.get(i)?.as_f64()?;
529                (lo.is_finite() && hi.is_finite()).then_some(hi - lo)
530            };
531            let band_width = band
532                .as_ref()
533                .and_then(|b| b.as_ref())
534                .and_then(|_| width(ia).zip(width(ib)))
535                .filter(|_| ia != ib);
536            // a scatter or bubble chart: how y (and the size) go with x
537            let cor =
538                (geom.starts_with("point") && xs.len() == pts.len() && pts.len() >= MIN_COR_POINTS)
539                    .then(|| {
540                        let xv: Vec<f64> = xs.iter().map(|p| p.1).collect();
541                        let yv: Vec<f64> = pts.iter().map(|p| p.1).collect();
542                        let size_rho = d.column("size").and_then(|sc| {
543                            let sv: Vec<f64> = pts
544                                .iter()
545                                .map(|(i, _)| sc[*i].as_f64().filter(|v| v.is_finite()))
546                                .collect::<Option<_>>()?;
547                            Some((spearman(&sv, &xv)?, spearman(&sv, &yv)?))
548                        });
549                        Some(Correlation {
550                            r: pearson(&xv, &yv)?,
551                            rho: spearman(&xv, &yv)?,
552                            size_rho,
553                        })
554                    })
555                    .flatten();
556            // the shape along x: a numeric / date x in x order, a discrete
557            // one as drawn; a scatter (point layer) has no line to follow
558            let ordered: Vec<(f64, String)> = if geom.starts_with("point") {
559                Vec::new()
560            } else if xs.len() == pts.len() {
561                let mut v: Vec<(f64, f64, usize)> = xs
562                    .iter()
563                    .zip(&pts)
564                    .map(|(xv, p)| (xv.1, p.1, p.0))
565                    .collect();
566                v.sort_by(|a, b| a.0.total_cmp(&b.0));
567                v.into_iter().map(|(_, yv, i)| (yv, xl(i))).collect()
568            } else {
569                pts.iter().map(|(i, v)| (*v, xl(*i))).collect()
570            };
571            let (counter_move, peaks) = shape(&ordered);
572            Some(SeriesSummary {
573                counter_move,
574                peaks,
575                key: key.map(|_| k),
576                n: pts.len(),
577                x_from,
578                x_to,
579                y_first: y0,
580                y_last: y1,
581                y_min: (lo.1, xl(lo.0)),
582                y_max: (hi.1, xl(hi.0)),
583                band: band.flatten(),
584                band_width,
585                points: pts.iter().map(|(i, v)| (xl(*i), *v)).collect(),
586                cor,
587            })
588        })
589        .collect();
590    let leaders = leaders(&series);
591    (!series.is_empty()).then(|| LayerSummary {
592        geom: geom.to_string(),
593        panel: None,
594        series,
595        leaders,
596    })
597}
598
599/// The largest move against the net direction and the prominent peaks of
600/// `ys` (in x order), see [`SeriesSummary::counter_move`] / [`SeriesSummary::peaks`].
601fn shape(ys: &[(f64, String)]) -> (Option<Move>, Vec<(f64, String)>) {
602    let n = ys.len();
603    if n < MIN_SHAPE_POINTS {
604        return (None, Vec::new());
605    }
606    let (lo, hi) = ys
607        .iter()
608        .fold((f64::INFINITY, f64::NEG_INFINITY), |(a, b), (y, _)| {
609            (a.min(*y), b.max(*y))
610        });
611    let range = hi - lo;
612    if range <= 0.0 {
613        return (None, Vec::new());
614    }
615    // against the net direction: a fall when it ends higher (or level), a rise when lower
616    let up = ys[n - 1].0 >= ys[0].0;
617    let (mut best, mut ext, mut at) = (0.0, ys[0].0, 0);
618    let mut mv = None;
619    for (j, (y, _)) in ys.iter().enumerate() {
620        let d = if up { ext - y } else { y - ext };
621        if d > best {
622            best = d;
623            mv = Some((at, j));
624        }
625        if (up && *y > ext) || (!up && *y < ext) {
626            ext = *y;
627            at = j;
628        }
629    }
630    let counter_move = mv.filter(|_| best >= 0.1 * range).map(|(a, b)| Move {
631        from: ys[a].clone(),
632        to: ys[b].clone(),
633    });
634    // peaks by prominence: how far it stands above the higher of the two
635    // lowest points between it and the next higher mark on either side
636    let mut peaks = Vec::new();
637    if n <= 5000 {
638        for i in 0..n {
639            let y = ys[i].0;
640            let left_ok = i == 0 || ys[i - 1].0 < y;
641            let right_ok = i + 1 == n || ys[i + 1].0 <= y;
642            if !(left_ok && right_ok) || (i == 0 && n > 1 && ys[1].0 == y) {
643                continue;
644            }
645            let side = |it: &mut dyn Iterator<Item = usize>| {
646                let mut m = y;
647                for k in it {
648                    if ys[k].0 > y {
649                        return m;
650                    }
651                    m = m.min(ys[k].0);
652                }
653                m
654            };
655            let l = side(&mut (0..i).rev());
656            let r = side(&mut (i + 1..n));
657            // an end of the series counts only by its inner side
658            let base = if i == 0 {
659                r
660            } else if i + 1 == n {
661                l
662            } else {
663                l.max(r)
664            };
665            if y - base >= 0.25 * range {
666                peaks.push(ys[i].clone());
667            }
668        }
669        peaks.sort_by(|a, b| b.0.total_cmp(&a.0));
670    }
671    (counter_move, peaks)
672}
673
674/// The first layer of each panel, when every panel draws it as one series:
675/// those series, keyed by panel, compared like the series of one layer.
676fn panel_leaders(layers: &[LayerSummary]) -> Option<(String, Leaders)> {
677    let geom = &layers.first()?.geom;
678    let mut seen = Vec::new();
679    let mut series = Vec::new();
680    for l in layers.iter().filter(|l| &l.geom == geom) {
681        let p = l.panel.clone()?;
682        if seen.contains(&p) || l.series.len() != 1 {
683            return None;
684        }
685        seen.push(p.clone());
686        series.push(SeriesSummary {
687            key: Some(p),
688            ..l.series[0].clone()
689        });
690    }
691    Some((geom.clone(), leaders(&series)?))
692}
693
694/// Which series is highest at each x two or more series share.
695fn leaders(series: &[SeriesSummary]) -> Option<Leaders> {
696    if series.len() < 2 || series.iter().any(|s| s.key.is_none()) {
697        return None;
698    }
699    let maps: Vec<std::collections::HashMap<&str, f64>> = series
700        .iter()
701        .map(|s| s.points.iter().map(|(x, y)| (x.as_str(), *y)).collect())
702        .collect();
703    let mut count: Vec<usize> = vec![0; series.len()];
704    let mut shared = 0;
705    for (x, _) in &series[0].points {
706        let ys: Option<Vec<f64>> = maps.iter().map(|m| m.get(x.as_str()).copied()).collect();
707        let Some(ys) = ys else { continue };
708        shared += 1;
709        let top = ys.iter().cloned().fold(f64::NEG_INFINITY, f64::max);
710        for (k, y) in ys.iter().enumerate() {
711            if *y == top {
712                count[k] += 1;
713            }
714        }
715    }
716    if shared < 3 {
717        return None;
718    }
719    let mut out: Vec<(String, usize)> = series
720        .iter()
721        .zip(count)
722        .filter(|(_, c)| *c > 0)
723        .map(|(s, c)| (s.key.clone().unwrap_or_default(), c))
724        .collect();
725    out.sort_by_key(|o| std::cmp::Reverse(o.1));
726    Some((out, shared))
727}
728
729/// A value as the summary shows it: a date as `YYYY-MM-DD` (with the time
730/// when it has one), a number trimmed, text as is.
731fn label(v: &Value, date_x: bool) -> String {
732    let date = |secs: f64| {
733        let s = format_epoch_secs(secs.round() as i64);
734        s.strip_suffix(" 00:00:00").map(str::to_string).unwrap_or(s)
735    };
736    match v {
737        Value::DateTime(_) => date(v.as_f64().unwrap_or(0.0)),
738        Value::Str(s) => s.clone(),
739        Value::Na => "NA".into(),
740        _ => match v.as_f64() {
741            Some(n) if date_x => date(n),
742            Some(n) => num(n),
743            None => v.key_str().into_owned(),
744        },
745    }
746}
747
748/// A number with at most 4 significant decimals, no trailing zeros.
749fn num(n: f64) -> String {
750    if n == n.trunc() && n.abs() < 1e15 {
751        return format!("{}", n as i64);
752    }
753    let digits = (4 - n.abs().log10().floor() as i32).clamp(0, 6) as usize;
754    let s = format!("{n:.digits$}");
755    let s = s.trim_end_matches('0').trim_end_matches('.');
756    s.to_string()
757}
758
759#[cfg(test)]
760mod tests {
761    use crate::prelude::*;
762
763    fn strs(v: &[&str]) -> Vec<Value> {
764        v.iter().map(|s| Value::Str(s.to_string())).collect()
765    }
766
767    #[test]
768    fn a_scatter_says_how_y_and_the_size_go_with_x() {
769        let f = |v: &[f64]| v.iter().map(|x| Value::Float(*x)).collect::<Vec<_>>();
770        let x = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
771        let y = [2.0, 3.0, 5.0, 4.0, 7.0, 8.0];
772        // the size falls as y rises (big districts sit low)
773        let size = [90.0, 80.0, 50.0, 60.0, 20.0, 10.0];
774        let df = vec![
775            ("x".to_string(), f(&x)),
776            ("y".to_string(), f(&y)),
777            ("s".to_string(), f(&size)),
778        ];
779        let built = GGPlot::new(df)
780            .aes(Aes::new().x("x").y("y").size("s"))
781            .geom_point()
782            .build();
783        let c = built.summary().layers[0].series[0].cor.clone().unwrap();
784        assert!(c.r > 0.9 && c.rho > 0.9, "{c:?}");
785        let (sx, sy) = c.size_rho.unwrap();
786        assert!(sx < -0.9 && sy < -0.9, "{c:?}");
787        let text = built.summary_text();
788        assert!(
789            text.contains("; y rises strongly with x (r 0.95, ρ 0.94)"),
790            "{text}"
791        );
792        assert!(
793            text.contains("size falls strongly with x (ρ -0.94), falls strongly with y (ρ -1)"),
794            "{text}"
795        );
796
797        // too few marks, or a line: no correlation
798        let df = vec![("x".to_string(), f(&x[..4])), ("y".to_string(), f(&y[..4]))];
799        let few = GGPlot::new(df)
800            .aes(Aes::new().x("x").y("y"))
801            .geom_point()
802            .build();
803        assert!(few.summary().layers[0].series[0].cor.is_none());
804        let df = vec![("x".to_string(), f(&x)), ("y".to_string(), f(&y))];
805        let line = GGPlot::new(df)
806            .aes(Aes::new().x("x").y("y"))
807            .geom_line()
808            .build();
809        assert!(line.summary().layers[0].series[0].cor.is_none());
810        assert!(!line.summary_text().contains(" with x"));
811    }
812
813    #[test]
814    fn series_dates_and_a_smooth_band() {
815        let day = |d: i64| Value::from_timestamp(1_700_006_400 + d * 86_400);
816        let df = vec![
817            (
818                "x".to_string(),
819                vec![day(0), day(1), day(2), day(0), day(1), day(2)],
820            ),
821            (
822                "y".to_string(),
823                [3.0, 5.0, 1.0, 2.0, 2.5, 4.0].map(Value::Float).to_vec(),
824            ),
825            ("g".to_string(), strs(&["A", "A", "A", "B", "B", "B"])),
826        ];
827        let s = GGPlot::new(df)
828            .aes(Aes::new().x("x").y("y").color("g"))
829            .geom_line()
830            .geom_smooth()
831            .build()
832            .summary();
833        let line = &s.layers[0];
834        assert_eq!(line.geom, "line");
835        assert_eq!(line.series.len(), 2);
836        let a = &line.series[0];
837        assert_eq!(a.key.as_deref(), Some("A"));
838        assert_eq!(
839            (a.n, a.x_from.as_str(), a.x_to.as_str()),
840            (3, "2023-11-15", "2023-11-17")
841        );
842        assert_eq!(a.y_max, (5.0, "2023-11-16".to_string()));
843        assert_eq!(a.y_min, (1.0, "2023-11-17".to_string()));
844        let smooth = &s.layers[1];
845        assert_eq!(smooth.geom, "smooth");
846        // the fitted grid's x is a date too, and its band is reported
847        assert!(
848            smooth.series[0].x_from.starts_with("2023-11-15"),
849            "{smooth:?}"
850        );
851        assert!(smooth.series[0].band.is_some());
852    }
853
854    #[test]
855    fn stacked_bars_report_their_own_values_and_facets_their_panel() {
856        let df = vec![
857            ("x".to_string(), strs(&["W1", "W1", "W2", "W2"])),
858            (
859                "y".to_string(),
860                [3.0, 5.0, 7.0, 2.0].map(Value::Float).to_vec(),
861            ),
862            ("c".to_string(), strs(&["a", "b", "a", "b"])),
863        ];
864        let s = GGPlot::new(df.clone())
865            .aes(Aes::new().x("x").y("y").fill("c"))
866            .geom_col()
867            .position(PositionStack)
868            .build()
869            .summary();
870        let b = &s.layers[0].series[1];
871        assert_eq!(b.key.as_deref(), Some("b"));
872        assert_eq!(
873            (b.y_first, b.y_last),
874            (5.0, 2.0),
875            "own values, not the stack tops"
876        );
877        assert_eq!(b.band, None, "a bar's base is not a band");
878
879        let s = GGPlot::new(df)
880            .aes(Aes::new().x("x").y("y"))
881            .geom_col()
882            .facet_wrap("c", None)
883            .build()
884            .summary();
885        let panels: Vec<_> = s.layers.iter().map(|l| l.panel.clone().unwrap()).collect();
886        assert_eq!(panels, ["a", "b"]);
887        assert_eq!(s.layers[1].series[0].y_max, (5.0, "W1".to_string()));
888    }
889
890    #[test]
891    fn scatter_x_extent_ribbon_band_and_markers_merged() {
892        let df = vec![
893            ("x".to_string(), [5.0, 1.0, 9.0].map(Value::Float).to_vec()),
894            ("y".to_string(), [2.0, 4.0, 3.0].map(Value::Float).to_vec()),
895            ("lo".to_string(), [1.0, 3.0, 2.0].map(Value::Float).to_vec()),
896            ("hi".to_string(), [3.0, 6.0, 4.0].map(Value::Float).to_vec()),
897        ];
898        let t = GGPlot::new(df)
899            .aes(Aes::new().x("x").y("y").ymin("lo").ymax("hi"))
900            .geom_ribbon()
901            .geom_line()
902            .geom_point()
903            .build()
904            .summary_text();
905        let lines: Vec<&str> = t.lines().collect();
906        // widths: x=1 → 6−3 = 3, x=9 → 4−2 = 2
907        assert_eq!(
908            lines[0], "ribbon: 3 marks, x 1 … 9, band 1 … 6, width 3 at 1 → 2 at 9 (narrows)",
909            "{t}"
910        );
911        assert!(
912            lines[1].starts_with("line+point: 3 marks, x 1 … 9; y first"),
913            "{t}"
914        );
915        assert_eq!(lines.len(), 2, "{t}");
916    }
917
918    #[test]
919    fn two_series_over_the_same_x_are_compared() {
920        let m: Vec<Value> = (1..=3).map(|i| Value::Float(i as f64)).collect();
921        let df = vec![
922            ("x".to_string(), [m.clone(), m].concat()),
923            (
924                "y".to_string(),
925                [100.0, 200.0, 50.0, 130.0, 220.0, 51.0]
926                    .map(Value::Float)
927                    .to_vec(),
928            ),
929            (
930                "g".to_string(),
931                strs(&["2024", "2024", "2024", "2025", "2025", "2025"]),
932            ),
933        ];
934        let t = GGPlot::new(df)
935            .aes(Aes::new().x("x").y("y").color("g"))
936            .geom_line()
937            .build()
938            .summary_text();
939        assert!(
940            t.ends_with("2025 − 2024: largest +30 (+30 %) at 1, smallest +1 (+2 %) at 3"),
941            "{t}"
942        );
943    }
944
945    #[test]
946    fn a_comparison_by_percent_when_it_ranks_differently() {
947        let df = vec![
948            (
949                "x".to_string(),
950                [1.0, 2.0, 1.0, 2.0].map(Value::Float).to_vec(),
951            ),
952            (
953                "y".to_string(),
954                [10.0, 200.0, 15.0, 260.0].map(Value::Float).to_vec(),
955            ),
956            ("g".to_string(), strs(&["a", "a", "b", "b"])),
957        ];
958        let t = GGPlot::new(df)
959            .aes(Aes::new().x("x").y("y").color("g"))
960            .geom_line()
961            .build()
962            .summary_text();
963        assert!(
964            t.ends_with("by %: largest +5 (+50 %) at 1, smallest +60 (+30 %) at 2"),
965            "{t}"
966        );
967    }
968
969    #[test]
970    fn many_series_are_counted() {
971        let n = 15;
972        let df = vec![
973            (
974                "x".to_string(),
975                (0..n).map(|i| Value::Float(i as f64)).collect(),
976            ),
977            (
978                "y".to_string(),
979                (0..n).map(|i| Value::Float(i as f64 * 1.5)).collect(),
980            ),
981            (
982                "g".to_string(),
983                (0..n).map(|i| Value::Str(format!("s{i}"))).collect(),
984            ),
985        ];
986        let t = GGPlot::new(df)
987            .aes(Aes::new().x("x").y("y").color("g"))
988            .geom_point()
989            .build()
990            .summary_text();
991        assert!(t.ends_with("; +3 more series"), "{t}");
992        assert!(t.contains("s1 — 1 mark, x 1 … 1; y first 1.5"), "{t}");
993    }
994
995    fn line(ys: &[f64]) -> String {
996        let df = vec![
997            (
998                "x".to_string(),
999                (1..=ys.len()).map(|i| Value::Float(i as f64)).collect(),
1000            ),
1001            (
1002                "y".to_string(),
1003                ys.iter().map(|v| Value::Float(*v)).collect(),
1004            ),
1005        ];
1006        GGPlot::new(df)
1007            .aes(Aes::new().x("x").y("y"))
1008            .geom_line()
1009            .build()
1010            .summary_text()
1011    }
1012
1013    #[test]
1014    fn a_rise_with_a_dip_names_the_dip() {
1015        let t = line(&[1.0, 2.0, 5.0, 3.0, 4.0, 6.0]);
1016        assert!(
1017            t.contains("; against the trend: largest fall 5 at 3 → 3 at 4"),
1018            "{t}"
1019        );
1020        let t = line(&[9.0, 8.0, 4.0, 7.0, 3.0, 1.0]);
1021        assert!(t.contains("largest rise 4 at 3 → 7 at 4"), "{t}");
1022    }
1023
1024    #[test]
1025    fn a_steady_or_nearly_steady_series_has_no_counter_move() {
1026        assert!(!line(&[1.0, 2.0, 3.0, 4.0, 5.0]).contains("against the trend"));
1027        // a wobble under a tenth of the range is not named
1028        assert!(!line(&[0.0, 50.0, 49.0, 100.0]).contains("against the trend"));
1029    }
1030
1031    #[test]
1032    fn two_peaks_are_named_highest_first() {
1033        let t = line(&[0.0, 10.0, 0.0, 0.0, 6.0, 0.0, 0.0]);
1034        assert!(t.contains("; 2 peaks: 10 at 2, 6 at 5"), "{t}");
1035        // a small bump is not a peak
1036        assert!(!line(&[0.0, 10.0, 0.0, 1.0, 0.0]).contains("peaks"));
1037    }
1038
1039    #[test]
1040    fn a_scatter_has_no_shape() {
1041        let df = vec![
1042            (
1043                "x".to_string(),
1044                vec![3.0, 1.0, 2.0, 5.0, 4.0]
1045                    .into_iter()
1046                    .map(Value::Float)
1047                    .collect(),
1048            ),
1049            (
1050                "y".to_string(),
1051                vec![1.0, 5.0, 2.0, 4.0, 3.0]
1052                    .into_iter()
1053                    .map(Value::Float)
1054                    .collect(),
1055            ),
1056        ];
1057        let s = GGPlot::new(df)
1058            .aes(Aes::new().x("x").y("y"))
1059            .geom_point()
1060            .build()
1061            .summary();
1062        assert!(s.layers[0].series[0].counter_move.is_none());
1063        assert!(s.layers[0].series[0].peaks.is_empty());
1064    }
1065
1066    #[test]
1067    fn the_highest_series_per_x_is_counted() {
1068        let df = vec![
1069            (
1070                "x".to_string(),
1071                strs(&["a", "b", "c", "d", "a", "b", "c", "d"]),
1072            ),
1073            (
1074                "y".to_string(),
1075                vec![5.0, 6.0, 7.0, 1.0, 4.0, 5.0, 6.0, 2.0]
1076                    .into_iter()
1077                    .map(Value::Float)
1078                    .collect(),
1079            ),
1080            (
1081                "g".to_string(),
1082                strs(&["WI", "WI", "WI", "WI", "CA", "CA", "CA", "CA"]),
1083            ),
1084        ];
1085        let t = GGPlot::new(df)
1086            .aes(Aes::new().x("x").y("y").color("g"))
1087            .geom_line()
1088            .build()
1089            .summary_text();
1090        assert!(
1091            t.contains("; highest at each of 4 shared x: WI 3, CA 1"),
1092            "{t}"
1093        );
1094    }
1095
1096    #[test]
1097    fn facet_panels_are_compared_per_x() {
1098        let df = vec![
1099            (
1100                "x".to_string(),
1101                vec![1.0, 2.0, 3.0, 1.0, 2.0, 3.0]
1102                    .into_iter()
1103                    .map(Value::Float)
1104                    .collect(),
1105            ),
1106            (
1107                "y".to_string(),
1108                vec![5.0, 1.0, 7.0, 4.0, 6.0, 2.0]
1109                    .into_iter()
1110                    .map(Value::Float)
1111                    .collect(),
1112            ),
1113            (
1114                "store".to_string(),
1115                strs(&["WI", "WI", "WI", "CA", "CA", "CA"]),
1116            ),
1117        ];
1118        let t = GGPlot::new(df)
1119            .aes(Aes::new().x("x").y("y"))
1120            .geom_line()
1121            .facet_wrap("store", None)
1122            .build()
1123            .summary_text();
1124        assert!(
1125            t.contains("\nline across panels: highest at each of 3 shared x: WI 2, CA 1"),
1126            "{t}"
1127        );
1128    }
1129
1130    #[test]
1131    fn at_most_three_peaks_are_listed() {
1132        let t = line(&[0.0, 9.0, 0.0, 8.0, 0.0, 7.0, 0.0, 10.0, 0.0]);
1133        assert!(t.contains("; 4 peaks: 10 at 8, 9 at 2, 8 at 4, …"), "{t}");
1134    }
1135}