charton 0.5.2

A high-performance, layered charting system for Rust, featuring a flexible data core and multi-backend rendering.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270

use crate::chart::Chart;
use crate::core::context::PanelContext;
use crate::core::layer::{CircleConfig, LineConfig, MarkRenderer, RectConfig, RenderBackend};
use crate::core::utils::IntoParallelizable;
use crate::error::ChartonError;
use crate::mark::boxplot::MarkBoxplot;
use crate::visual::color::SingleColor;
use crate::{Precision, TEMP_SUFFIX};

#[cfg(feature = "parallel")]
use rayon::prelude::*;

impl MarkRenderer for Chart<MarkBoxplot> {
    /// Renders Boxplots using high-performance parallel geometry generation.
    fn render_marks(
        &self,
        backend: &mut dyn RenderBackend,
        context: &PanelContext,
    ) -> Result<(), ChartonError> {
        let df_source = &self.data;
        let row_count = df_source.height();
        if row_count == 0 {
            return Ok(());
        }

        // --- STEP 1: INITIALIZATION & VALIDATION ---
        let mark_config = self
            .mark
            .as_ref()
            .ok_or_else(|| ChartonError::Mark("Boxplot config missing".into()))?;
        let x_enc = self
            .encoding
            .x
            .as_ref()
            .ok_or_else(|| ChartonError::Encoding("X encoding missing".into()))?;

        let x_scale = context.coord.get_x_scale();
        let y_scale = context.coord.get_y_scale();

        // --- STEP 2: DATA NORMALIZATION ---
        // Normalize primary axes and all statistical summary columns
        let x_norms = x_scale
            .scale_type()
            .normalize_column(x_scale, df_source.column(&x_enc.field)?);
        let q1_n = y_scale
            .scale_type()
            .normalize_column(y_scale, df_source.column(&format!("{}_q1", TEMP_SUFFIX))?);
        let q3_n = y_scale
            .scale_type()
            .normalize_column(y_scale, df_source.column(&format!("{}_q3", TEMP_SUFFIX))?);
        let med_n = y_scale.scale_type().normalize_column(
            y_scale,
            df_source.column(&format!("{}_median", TEMP_SUFFIX))?,
        );
        let min_n = y_scale
            .scale_type()
            .normalize_column(y_scale, df_source.column(&format!("{}_min", TEMP_SUFFIX))?);
        let max_n = y_scale
            .scale_type()
            .normalize_column(y_scale, df_source.column(&format!("{}_max", TEMP_SUFFIX))?);

        // Normalize color aesthetic if a mapping exists
        let color_norms = context.spec.aesthetics.color.as_ref().map(|m| {
            let s = m.scale_impl.as_ref();
            s.scale_type()
                .normalize_column(s, df_source.column(&m.field).unwrap())
        });

        // Retrieve helper columns for positioning and outliers
        let groups_count_col = df_source.column(&format!("{}_groups_count", TEMP_SUFFIX))?;
        let sub_idx_col = df_source.column(&format!("{}_sub_idx", TEMP_SUFFIX))?;
        let outliers_col = df_source.column(&format!("{}_outliers", TEMP_SUFFIX))?;

        // Constant used for calculating horizontal pixel widths relative to the X-axis scale
        let unit_step_norm = (x_scale.normalize(1.0) - x_scale.normalize(0.0)).abs();

        // --- STEP 3: PARALLEL GEOMETRY COMPUTATION ---
        let x_col = df_source.column(&x_enc.field)?;
        let boundary_tag = format!("{}_boundary", TEMP_SUFFIX);

        let box_elements: Vec<BoxElement> = (0..row_count)
            .maybe_into_par_iter()
            .filter_map(|i| {
                // 1. Ghost/Boundary Check
                let x_val = x_col.get_str(i)?;
                if x_val == boundary_tag {
                    return None;
                }

                // 2. Comprehensive Data Validation (Filter out Gaps)
                // Use the '?' operator to skip rows where any essential stat is NaN/None
                let q1_val = q1_n[i]?;
                let q3_val = q3_n[i]?;
                let med_val = med_n[i]?;
                let min_val = min_n[i]?;
                let max_val = max_n[i]?;

                let total_groups = groups_count_col.get_f64(i).unwrap_or(1.0);
                let sub_idx = sub_idx_col.get_f64(i).unwrap_or(0.0);

                // --- DODGE LOGIC ---
                let box_width_data = mark_config.width.min(
                    mark_config.span / (total_groups + (total_groups - 1.0) * mark_config.spacing),
                );
                let box_width_norm = box_width_data * unit_step_norm;
                let spacing_norm = box_width_norm * mark_config.spacing;
                let offset_norm =
                    (sub_idx - (total_groups - 1.0) / 2.0) * (box_width_norm + spacing_norm);

                let x_center_n = x_norms[i]? + offset_norm;

                // --- RESOLVE COLOR ---
                let fill = if let Some(ref norms) = color_norms {
                    self.resolve_color_from_value(norms[i], context, &mark_config.color)
                } else {
                    mark_config.color
                };

                // --- COORDINATE PROJECTION ---
                // Reuse the local validated variables (q1_val, med_val, etc.)
                // to avoid redundant indexing and Option unwrapping.
                let (bx1, by1) = context.coord.transform(
                    x_center_n - box_width_norm / 2.0,
                    q1_val,
                    &context.panel,
                );
                let (bx2, by2) = context.coord.transform(
                    x_center_n + box_width_norm / 2.0,
                    q3_val,
                    &context.panel,
                );

                let (p_min_x, p_min_y) =
                    context.coord.transform(x_center_n, min_val, &context.panel);
                let (p_max_x, p_max_y) =
                    context.coord.transform(x_center_n, max_val, &context.panel);

                let (p_q1_x, p_q1_y) = context.coord.transform(x_center_n, q1_val, &context.panel);
                let (p_q3_x, p_q3_y) = context.coord.transform(x_center_n, q3_val, &context.panel);

                let (m1x, m1y) = context.coord.transform(
                    x_center_n - box_width_norm / 2.0,
                    med_val,
                    &context.panel,
                );
                let (m2x, m2y) = context.coord.transform(
                    x_center_n + box_width_norm / 2.0,
                    med_val,
                    &context.panel,
                );

                // --- OUTLIER PARSING ---
                let mut outlier_circles = Vec::new();
                if let Some(raw_outliers) = outliers_col.get_str(i) {
                    let clean = raw_outliers.trim_matches(|c| c == '[' || c == ']');
                    for val_str in clean.split(',').filter(|s| !s.trim().is_empty()) {
                        if let Ok(val) = val_str.trim().parse::<f64>() {
                            let n_o = y_scale.normalize(val);
                            let (ox, oy) = context.coord.transform(x_center_n, n_o, &context.panel);
                            outlier_circles.push(CircleConfig {
                                x: ox as Precision,
                                y: oy as Precision,
                                radius: mark_config.outlier_size as Precision,
                                fill: mark_config.outlier_color,
                                stroke: SingleColor::new("none"),
                                stroke_width: 0.0,
                                opacity: mark_config.opacity as Precision,
                            });
                        }
                    }
                }

                Some(BoxElement {
                    rect: RectConfig {
                        x: bx1.min(bx2) as Precision,
                        y: by1.min(by2) as Precision,
                        width: (bx1 - bx2).abs() as Precision,
                        height: (by1 - by2).abs() as Precision,
                        fill,
                        stroke: mark_config.stroke,
                        stroke_width: mark_config.stroke_width as Precision,
                        opacity: mark_config.opacity as Precision,
                    },
                    whisker_low: [p_min_x, p_min_y, p_q1_x, p_q1_y],
                    whisker_high: [p_max_x, p_max_y, p_q3_x, p_q3_y],
                    median_line: [m1x, m1y, m2x, m2y],
                    outliers: outlier_circles,
                })
            })
            .collect();

        // --- STEP 4: SEQUENTIAL RENDERING ---
        // Backend draw calls are executed on the main thread.
        for el in box_elements {
            // Draw main box
            backend.draw_rect(el.rect);

            // Draw whiskers
            backend.draw_line(LineConfig {
                x1: el.whisker_low[0] as Precision,
                y1: el.whisker_low[1] as Precision,
                x2: el.whisker_low[2] as Precision,
                y2: el.whisker_low[3] as Precision,
                color: mark_config.stroke,
                width: mark_config.stroke_width as Precision,
                opacity: mark_config.opacity as Precision,
                dash: vec![],
            });
            backend.draw_line(LineConfig {
                x1: el.whisker_high[0] as Precision,
                y1: el.whisker_high[1] as Precision,
                x2: el.whisker_high[2] as Precision,
                y2: el.whisker_high[3] as Precision,
                color: mark_config.stroke,
                width: mark_config.stroke_width as Precision,
                opacity: mark_config.opacity as Precision,
                dash: vec![],
            });

            // Draw median line (bold)
            backend.draw_line(LineConfig {
                x1: el.median_line[0] as Precision,
                y1: el.median_line[1] as Precision,
                x2: el.median_line[2] as Precision,
                y2: el.median_line[3] as Precision,
                color: mark_config.stroke,
                width: (mark_config.stroke_width * 2.0) as Precision,
                opacity: mark_config.opacity as Precision,
                dash: vec![],
            });

            // Draw outliers
            for outlier in el.outliers {
                backend.draw_circle(outlier);
            }
        }

        Ok(())
    }
}

/// Stores pre-calculated screen coordinates for a single boxplot group.
struct BoxElement {
    rect: RectConfig,
    whisker_low: [f64; 4],
    whisker_high: [f64; 4],
    median_line: [f64; 4],
    outliers: Vec<CircleConfig>,
}

impl Chart<MarkBoxplot> {
    /// Resolves aesthetic color based on normalized values and scale mapping.
    fn resolve_color_from_value(
        &self,
        val: Option<f64>,
        context: &PanelContext,
        fallback: &SingleColor,
    ) -> SingleColor {
        if let (Some(v), Some(mapping)) = (val, &context.spec.aesthetics.color) {
            let s_trait = mapping.scale_impl.as_ref();
            s_trait
                .mapper()
                .as_ref()
                .map(|m| m.map_to_color(v, s_trait.logical_max()))
                .unwrap_or(*fallback)
        } else {
            *fallback
        }
    }
}