Skip to main content

​
BoxPlot

Builder for creating box plots (box-and-whisker plots). Displays the five-number summary for one or more groups of values. Whiskers use the Tukey 1.5×IQR rule; values outside the whiskers are not drawn automatically (use an overlay to show individual points). Groups are rendered side-by-side in the order they are added.

​
Constructor

​
BoxPlot::new()
Self
Create a box plot with default settings.Defaults:
  • Color: "black"
  • Box width: 0.8 (as a fraction of category slot)
  • Overlay color: "rgba(0,0,0,0.45)"
  • Overlay point size: 3.0 pixels
  • No overlay

​
Data Methods

​
with_group
Self
pub fn with_group<T, U, I>(self, label: T, values: I) -> Self
where
    T: Into<String>,
    I: IntoIterator<Item = U>,
    U: Into<f64>
Add a group (one box) with a label and raw values. Groups are rendered left-to-right in the order they are added. The renderer computes Q1, median, Q3, and Tukey 1.5×IQR whiskers from the supplied values.Example:
let plot = BoxPlot::new()
    .with_group("A", vec![1.0, 2.5, 3.0, 3.5, 4.0, 5.0])
    .with_group("B", vec![2.0, 3.0, 3.8, 4.2, 4.8, 6.0]);

​
Styling Methods

​
with_color
Self
pub fn with_color<S: Into<String>>(self, color: S) -> Self
Set the box fill color. Accepts CSS color strings (e.g. "steelblue"). This color is applied to all boxes. Use the same color for all groups and distinguish them by position, or layer multiple BoxPlot instances in a Vec<Plot> with different colors.
​
with_width
Self
pub fn with_width(self, width: f64) -> Self
Set the box width as a fraction of the category slot (default 0.8).

​
Overlay Methods

​
with_strip
Self
pub fn with_strip(self, jitter: f64) -> Self
Overlay individual data points as a jittered strip. jitter controls the horizontal spread of the points (in data units). A value of 0.2 is a reasonable default. Points are placed on top of the box — use a semi-transparent with_overlay_color so the box remains visible underneath.
​
with_swarm_overlay
Self
pub fn with_swarm_overlay(self) -> Self
Overlay individual data points as a beeswarm. Points are spread horizontally to avoid overlap, giving a clearer view of the data density than a jittered strip. Useful for smaller datasets (N < ~200 per group) where individual points are meaningful.
​
with_overlay_color
Self
pub fn with_overlay_color<S: Into<String>>(self, color: S) -> Self
Set the fill color for overlay points (default "rgba(0,0,0,0.45)"). A semi-transparent color is recommended so the box underneath remains visible.
​
with_overlay_size
Self
pub fn with_overlay_size(self, size: f64) -> Self
Set the radius of overlay points in pixels (default 3.0).

​
Legend Methods

​
with_legend
Self
pub fn with_legend<S: Into<String>>(self, label: S) -> Self
Attach a legend label to this box plot.

​
Types

​
BoxGroup

A single group (one box) with a category label and raw values. Fields:
  • label: String - Category label
  • values: Vec<f64> - Raw data values

​
Complete Example

​
Simple Box Plot

use kuva::plot::BoxPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = BoxPlot::new()
    .with_group("Control",   vec![4.1, 5.0, 5.3, 5.8, 6.2, 7.0])
    .with_group("Treated",   vec![5.5, 6.1, 6.4, 7.2, 7.8, 8.5])
    .with_color("steelblue");

let plots = vec![Plot::Box(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Control vs. Treated")
    .with_x_label("Group")
    .with_y_label("Value");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
std::fs::write("boxplot.svg", svg).unwrap();

​
Box Plot with Strip Overlay

use kuva::plot::BoxPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = BoxPlot::new()
    .with_group("Control",   vec![4.1, 5.0, 5.3, 5.8, 6.2, 7.0, 5.5, 4.8])
    .with_group("Treated",   vec![5.5, 6.1, 6.4, 7.2, 7.8, 8.5, 6.9, 7.0])
    .with_color("steelblue")
    .with_strip(0.2)
    .with_overlay_color("rgba(0,0,0,0.3)")
    .with_overlay_size(2.5);

let plots = vec![Plot::Box(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Control vs. Treated (with points)")
    .with_x_label("Group")
    .with_y_label("Value");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
std::fs::write("boxplot_strip.svg", svg).unwrap();

​
Box Plot with Beeswarm Overlay

use kuva::plot::BoxPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = BoxPlot::new()
    .with_group("Control",   vec![4.1, 5.0, 5.3, 5.8, 6.2, 7.0, 5.5, 4.8])
    .with_group("Treated",   vec![5.5, 6.1, 6.4, 7.2, 7.8, 8.5, 6.9, 7.0])
    .with_color("steelblue")
    .with_swarm_overlay()
    .with_overlay_color("rgba(0,0,0,0.5)");

let plots = vec![Plot::Box(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Control vs. Treated (beeswarm)")
    .with_x_label("Group")
    .with_y_label("Value");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
std::fs::write("boxplot_swarm.svg", svg).unwrap();

Build docs developers (and LLMs) love

Get started for freeTalk to us