facett_plotters/

boxplot.rs

//! **Box plot** — quartiles + whiskers + outliers, one box per named group.
//! The data→geometry math ([`Quartiles::from_sorted`] / [`Quartiles::compute`])
//! is a pure function with its own tests; [`BoxPlotView`] is the themeable
//! [`Facet`] that paints it and emits the underlying data as CSV/JSON.

use egui::{Align2, Color32, FontId, Pos2, Rect, Sense, Stroke, Ui, vec2};
use facett_core::clip::{ClipKind, ClipPayload, CopySource};
use facett_core::{Elm, FacetCaps, Semantics, a11y_node, theme};
use serde::{Deserialize, Serialize};

/// Five-number summary + the 1.5·IQR whisker fences and the points beyond them.
#[derive(Clone, Debug, PartialEq)]
pub struct Quartiles {
    pub min: f64,
    pub q1: f64,
    pub median: f64,
    pub q3: f64,
    pub max: f64,
    /// Lower whisker end: smallest datum ≥ `q1 - 1.5·IQR`.
    pub lower_fence: f64,
    /// Upper whisker end: largest datum ≤ `q3 + 1.5·IQR`.
    pub upper_fence: f64,
    /// Points outside the fences.
    pub outliers: Vec<f64>,
}

impl Quartiles {
    /// Compute from an arbitrary (unsorted) sample. Empty input → `None`.
    pub fn compute(values: &[f64]) -> Option<Self> {
        if values.is_empty() {
            return None;
        }
        let mut v: Vec<f64> = values.iter().copied().filter(|x| x.is_finite()).collect();
        if v.is_empty() {
            return None;
        }
        v.sort_by(|a, b| a.partial_cmp(b).unwrap());
        Some(Self::from_sorted(&v))
    }

    /// Compute from an already-sorted, finite, non-empty slice. Uses linear
    /// interpolation between order statistics (the "type-7"/`numpy` default), so
    /// it matches what analysts expect from Plotly/pandas.
    pub fn from_sorted(v: &[f64]) -> Self {
        debug_assert!(!v.is_empty());
        let pct = |p: f64| percentile_sorted(v, p);
        let q1 = pct(0.25);
        let median = pct(0.5);
        let q3 = pct(0.75);
        let iqr = q3 - q1;
        let lo = q1 - 1.5 * iqr;
        let hi = q3 + 1.5 * iqr;
        // Whisker ends snap to the most extreme data points still inside the fence.
        let lower_fence = *v.iter().find(|&&x| x >= lo).unwrap_or(&v[0]);
        let upper_fence = *v.iter().rev().find(|&&x| x <= hi).unwrap_or(v.last().unwrap());
        let outliers: Vec<f64> = v.iter().copied().filter(|&x| x < lo || x > hi).collect();
        Self {
            min: v[0],
            q1,
            median,
            q3,
            max: *v.last().unwrap(),
            lower_fence,
            upper_fence,
            outliers,
        }
    }
}

/// Linear-interpolated percentile of a sorted slice. `p ∈ 0..=1`.
pub fn percentile_sorted(sorted: &[f64], p: f64) -> f64 {
    let n = sorted.len();
    if n == 1 {
        return sorted[0];
    }
    let rank = p.clamp(0.0, 1.0) * (n as f64 - 1.0);
    let lo = rank.floor() as usize;
    let hi = rank.ceil() as usize;
    let frac = rank - lo as f64;
    sorted[lo] + (sorted[hi] - sorted[lo]) * frac
}

/// Persistent, observable interaction state (FC-3). The box plot's only mutable
/// state is which group box the pointer last hovered — an index into
/// [`BoxPlotView::summaries`]. Serialized so it round-trips headlessly.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct BoxPlotState {
    /// Index of the hovered box (into `summaries()`), or `None`.
    pub hover: Option<usize>,
}

/// FC-2 input surface. The box plot accepts one kind of input: the hovered box
/// changing (hit-tested *purely* in [`BoxPlotView::render`], applied in
/// [`BoxPlotView::update`]).
#[derive(Clone, Debug, PartialEq)]
pub enum BoxPlotMsg {
    /// Set (or clear, with `None`) the hovered box index.
    Hover(Option<usize>),
}

/// FC-8: the box plot does no I/O — an uninhabited effect.
#[derive(Clone, Debug)]
pub enum BoxPlotEffect {}

/// A box plot: named groups of raw samples.
pub struct BoxPlotView {
    pub title: String,
    /// `(group label, raw values)`.
    pub groups: Vec<(String, Vec<f64>)>,
    /// Observable interaction state (FC-3).
    pub state: BoxPlotState,
}

impl BoxPlotView {
    pub fn new(title: impl Into<String>, groups: Vec<(String, Vec<f64>)>) -> Self {
        Self { title: title.into(), groups, state: BoxPlotState::default() }
    }

    /// FC-3: read the complete observable interaction state.
    pub fn state(&self) -> &BoxPlotState {
        &self.state
    }

    /// FC-2/FC-8: the single mutation path. Apply one [`BoxPlotMsg`]; no effects.
    pub fn update(&mut self, msg: BoxPlotMsg) -> Vec<BoxPlotEffect> {
        match msg {
            BoxPlotMsg::Hover(h) => self.state.hover = h,
        }
        Vec::new()
    }

    /// Per-group quartiles (skipping empty groups), paired with the label.
    pub fn summaries(&self) -> Vec<(String, Quartiles)> {
        self.groups
            .iter()
            .filter_map(|(name, vals)| Quartiles::compute(vals).map(|q| (name.clone(), q)))
            .collect()
    }

    /// Global value range across every group (for the shared y-axis).
    fn value_range(&self) -> Option<(f64, f64)> {
        let mut r: Option<(f64, f64)> = None;
        for (_, vals) in &self.groups {
            for &x in vals {
                if x.is_finite() {
                    r = Some(match r {
                        None => (x, x),
                        Some((lo, hi)) => (lo.min(x), hi.max(x)),
                    });
                }
            }
        }
        r
    }

    /// CSV of the five-number summary per group (the `copy()` payload).
    fn to_csv(&self) -> String {
        let mut s = String::from("group,min,q1,median,q3,max,outliers\n");
        for (name, q) in self.summaries() {
            s.push_str(&format!(
                "{},{},{},{},{},{},{}\n",
                name, q.min, q.q1, q.median, q.q3, q.max, q.outliers.len()
            ));
        }
        s
    }
}

// ── typed copy (§16) — the chart dataset as CSV Text ──────────────────
impl CopySource for BoxPlotView {
    fn copy_kinds(&self) -> &[ClipKind] {
        &[ClipKind::Text]
    }
    fn copy_payload(&self) -> Option<ClipPayload> {
        let csv = self.to_csv();
        (!csv.is_empty()).then_some(ClipPayload::Text(csv))
    }
}

impl BoxPlotView {
    /// FC-9 pure view: paints the boxes + hover tooltip (from the *stored* hover)
    /// and **returns** the hovered-box change as a `Msg` — it never mutates `self`.
    fn render(&self, ui: &mut Ui) -> Vec<BoxPlotMsg> {
        let th = theme(ui);
        let summaries = self.summaries();
        let (rect, resp) = ui.allocate_exact_size(ui.available_size(), Sense::hover());
        let painter = ui.painter_at(rect);
        painter.rect_filled(rect, egui::CornerRadius::ZERO, th.bg);
        let Some((vmin, vmax)) = self.value_range() else {
            // ── render-lane emit: this Facet::ui path RAN ─────────────────────────
            #[cfg(feature = "testmatrix")]
            facett_core::testmatrix::emit(
                "facett-plotters::BoxPlotView::ui",
                "ui_render",
                summaries.is_empty(),
                &format!("drew=empty_hint groups={} summaries={}", self.groups.len(), summaries.len()),
            );
            painter.text(rect.center(), Align2::CENTER_CENTER, "no data", FontId::proportional(13.0), th.text_dim);
            return hover_msg(self.state.hover, None);
        };
        if summaries.is_empty() {
            // ── render-lane emit: this Facet::ui path RAN ─────────────────────────
            #[cfg(feature = "testmatrix")]
            facett_core::testmatrix::emit(
                "facett-plotters::BoxPlotView::ui",
                "ui_render",
                summaries.is_empty(),
                &format!("drew=empty_hint groups={} summaries={}", self.groups.len(), summaries.len()),
            );
            painter.text(rect.center(), Align2::CENTER_CENTER, "no data", FontId::proportional(13.0), th.text_dim);
            return hover_msg(self.state.hover, None);
        }
        let plot = rect.shrink2(vec2(28.0, 24.0));
        let span = (vmax - vmin).max(1e-9);
        let y_of = |v: f64| plot.bottom() - ((v - vmin) / span) as f32 * plot.height();

        let n = summaries.len();
        let slot = plot.width() / n as f32;
        let box_w = (slot * 0.5).min(60.0);
        let hover = resp.hover_pos();
        let mut new_hover: Option<usize> = None;
        let base = ui.id().with("boxplot");

        for (i, (name, q)) in summaries.iter().enumerate() {
            let cx = plot.left() + slot * (i as f32 + 0.5);
            let color = facett_core::hash_color(name);
            let stroke = Stroke::new(1.5_f32, th.accent);

            // Whiskers.
            painter.line_segment([Pos2::new(cx, y_of(q.lower_fence)), Pos2::new(cx, y_of(q.q1))], Stroke::new(1.0_f32, th.text_dim));
            painter.line_segment([Pos2::new(cx, y_of(q.q3)), Pos2::new(cx, y_of(q.upper_fence))], Stroke::new(1.0_f32, th.text_dim));
            // Whisker caps.
            let cap = box_w * 0.3;
            for &v in &[q.lower_fence, q.upper_fence] {
                painter.line_segment([Pos2::new(cx - cap, y_of(v)), Pos2::new(cx + cap, y_of(v))], Stroke::new(1.0_f32, th.text_dim));
            }
            // The box (q1..q3).
            let box_rect = Rect::from_min_max(Pos2::new(cx - box_w * 0.5, y_of(q.q3)), Pos2::new(cx + box_w * 0.5, y_of(q.q1)));
            painter.rect_filled(box_rect, egui::CornerRadius::same(2), color.gamma_multiply(0.55));
            painter.rect_stroke(box_rect, egui::CornerRadius::same(2), stroke, egui::StrokeKind::Middle);
            // AccessKit node over the box body (FC-4): role=Image, label = the
            // group name, numeric_value = the median (the box's headline stat).
            // Keyed on the group name (stable across reorder, FC-5).
            a11y_node(
                ui,
                base,
                name,
                Sense::hover(),
                box_rect,
                Semantics::image(name.clone()).value(q.median),
            );
            // Median line.
            painter.line_segment(
                [Pos2::new(box_rect.left(), y_of(q.median)), Pos2::new(box_rect.right(), y_of(q.median))],
                Stroke::new(2.0_f32, th.glow),
            );
            // Outliers.
            for &o in &q.outliers {
                painter.circle_stroke(Pos2::new(cx, y_of(o)), 2.5, Stroke::new(1.0_f32, th.point));
            }
            // Group label.
            painter.text(Pos2::new(cx, plot.bottom() + 12.0), Align2::CENTER_CENTER, name, FontId::proportional(11.0), th.text);

            // Pure hit-test: which slot is the cursor over this frame.
            if let Some(hp) = hover
                && hp.x >= cx - slot * 0.5 && hp.x < cx + slot * 0.5 && plot.y_range().contains(hp.y)
            {
                new_hover = Some(i);
            }
        }

        // Tooltip is painted from the *persisted* hover (set by `update` last frame),
        // keeping `render` a pure function of `&self`.
        if let Some(hp) = hover && let Some((name, q)) = self.state.hover.and_then(|i| summaries.get(i)) {
            paint_tooltip(
                &painter,
                &th,
                hp,
                &format!(
                    "{name}\nmax {:.3}\nq3  {:.3}\nmed {:.3}\nq1  {:.3}\nmin {:.3}\noutliers {}",
                    q.max, q.q3, q.median, q.q1, q.min, q.outliers.len()
                ),
            );
        }
        // ── render-lane emit: this Facet::ui path RAN ─────────────────────────
        #[cfg(feature = "testmatrix")]
        facett_core::testmatrix::emit(
            "facett-plotters::BoxPlotView::ui",
            "ui_render",
            !summaries.is_empty() && summaries.len() <= self.groups.len(),
            &format!("groups={} boxes={}", self.groups.len(), summaries.len()),
        );
        hover_msg(self.state.hover, new_hover)
    }
}

/// Emit a `Hover` message only when the hovered box actually changed (keeps the
/// FC-9 loop from re-applying an identical hover every frame).
fn hover_msg(current: Option<usize>, next: Option<usize>) -> Vec<BoxPlotMsg> {
    if current != next { vec![BoxPlotMsg::Hover(next)] } else { Vec::new() }
}

impl Elm for BoxPlotView {
    type Model = BoxPlotState;
    type Msg = BoxPlotMsg;
    type Effect = BoxPlotEffect;

    fn title(&self) -> &str {
        &self.title
    }
    fn state(&self) -> &BoxPlotState {
        &self.state
    }
    fn update(&mut self, msg: BoxPlotMsg) -> Vec<BoxPlotEffect> {
        BoxPlotView::update(self, msg)
    }
    fn view(&self, ui: &mut Ui) -> Vec<BoxPlotMsg> {
        facett_core::navgraph::declare_own_draw_order(ui); // atoms follow the data order (navgraph §9)
        self.render(ui)
    }
}

// Form 3 (`custom_state_json`): this view publishes a **richer** `state_json`
// (the derived five-number summary per group) than a plain `serde(state())`, so
// the macro's default is suppressed and the exact existing JSON is preserved.
facett_core::impl_facet_via_elm!(BoxPlotView, custom_state_json, {
    fn caps(&self) -> FacetCaps {
        FacetCaps::NONE.themeable().copyable().resizable()
    }
    fn copy(&mut self) -> Option<String> {
        Some(self.to_csv())
    }
    fn state_json(&self) -> serde_json::Value {
        serde_json::json!({
            "kind": "boxplot",
            "groups": self.summaries().iter().map(|(n, q)| serde_json::json!({
                "name": n, "min": q.min, "q1": q.q1, "median": q.median,
                "q3": q.q3, "max": q.max, "outliers": q.outliers.len(),
            })).collect::<Vec<_>>(),
        })
    }
});

/// Shared themed tooltip box used by the chart facets.
pub(crate) fn paint_tooltip(painter: &egui::Painter, th: &facett_core::Theme, at: Pos2, text: &str) {
    let font = FontId::proportional(11.0);
    let galley = painter.layout(text.to_string(), font, th.text, 240.0);
    let pad = vec2(6.0, 4.0);
    let pos = at + vec2(12.0, 12.0);
    let bg = Rect::from_min_size(pos, galley.size() + pad * 2.0);
    painter.rect_filled(bg, egui::CornerRadius::same(3), th.panel_bg);
    painter.rect_stroke(bg, egui::CornerRadius::same(3), Stroke::new(1.0_f32, th.panel_stroke), egui::StrokeKind::Middle);
    painter.galley(pos + pad, galley, Color32::WHITE);
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn typed_copy_is_the_dataset_csv() {
        use facett_core::clip::{ClipKind, CopySource};
        let v = BoxPlotView::new("t", vec![("a".into(), vec![1.0, 2.0, 3.0])]);
        let p = v.copy_payload().expect("groups copy");
        assert_eq!(p.kind(), ClipKind::Text);
        assert_eq!(p.as_text(), v.to_csv());
    }

    #[test]
    fn percentile_matches_numpy_type7() {
        // numpy.percentile([1..=10], [25,50,75]) = 3.25, 5.5, 7.75
        let v: Vec<f64> = (1..=10).map(|x| x as f64).collect();
        assert!((percentile_sorted(&v, 0.25) - 3.25).abs() < 1e-9);
        assert!((percentile_sorted(&v, 0.50) - 5.5).abs() < 1e-9);
        assert!((percentile_sorted(&v, 0.75) - 7.75).abs() < 1e-9);
    }

    #[test]
    fn quartiles_basic_no_outliers() {
        let q = Quartiles::compute(&[1.0, 2.0, 3.0, 4.0, 5.0]).unwrap();
        assert_eq!(q.min, 1.0);
        assert_eq!(q.max, 5.0);
        assert_eq!(q.median, 3.0);
        assert_eq!(q.q1, 2.0);
        assert_eq!(q.q3, 4.0);
        assert!(q.outliers.is_empty());
        // fences cover the whole range when there are no outliers
        assert_eq!(q.lower_fence, 1.0);
        assert_eq!(q.upper_fence, 5.0);
    }

    #[test]
    fn quartiles_detects_high_outlier() {
        let mut data: Vec<f64> = (1..=10).map(|x| x as f64).collect();
        data.push(100.0); // far above q3 + 1.5 IQR
        let q = Quartiles::compute(&data).unwrap();
        assert!(q.outliers.contains(&100.0), "100 must be flagged as an outlier");
        assert!(q.upper_fence <= 10.0, "upper whisker snaps to in-fence data");
    }

    #[test]
    fn quartiles_empty_and_nonfinite() {
        assert!(Quartiles::compute(&[]).is_none());
        assert!(Quartiles::compute(&[f64::NAN, f64::INFINITY]).is_none());
    }

    #[test]
    fn single_value() {
        let q = Quartiles::compute(&[7.0]).unwrap();
        assert_eq!(q.median, 7.0);
        assert_eq!(q.q1, 7.0);
        assert_eq!(q.q3, 7.0);
        assert!(q.outliers.is_empty());
    }

    #[test]
    fn csv_has_header_and_row_per_group() {
        let v = BoxPlotView::new("t", vec![("a".into(), vec![1.0, 2.0, 3.0]), ("b".into(), vec![4.0, 5.0, 6.0])]);
        let csv = v.to_csv();
        assert!(csv.starts_with("group,min,q1,median,q3,max,outliers\n"));
        assert_eq!(csv.lines().count(), 3); // header + 2 groups
    }

    // ── Elm (FC-2/FC-3) harness properties ────────────────────────────────
    #[test]
    fn hover_transitions_are_observable() {
        let mut v = BoxPlotView::new(
            "t",
            vec![("a".into(), vec![1.0, 2.0, 3.0]), ("b".into(), vec![4.0, 5.0, 6.0])],
        );
        assert_eq!(v.state().hover, None);
        let snap = facett_core::harness::snapshot(&mut v, [BoxPlotMsg::Hover(Some(1))]);
        assert_eq!(snap.hover, Some(1), "hovering a box is observable in the snapshot");
        let snap = facett_core::harness::snapshot(&mut v, [BoxPlotMsg::Hover(None)]);
        assert_eq!(snap.hover, None, "leaving clears the hover");
    }

    #[test]
    fn drive_produces_no_effects() {
        let mut v = BoxPlotView::new("t", vec![("a".into(), vec![1.0, 2.0, 3.0])]);
        let effects = facett_core::harness::drive(&mut v, [BoxPlotMsg::Hover(Some(0)), BoxPlotMsg::Hover(None)]);
        assert!(effects.is_empty(), "the box plot does no I/O");
    }

    #[test]
    fn state_serde_round_trips() {
        let st = BoxPlotState { hover: Some(2) };
        let back: BoxPlotState = serde_json::from_value(serde_json::to_value(&st).unwrap()).unwrap();
        assert_eq!(st, back);
    }
}