Struct ViolinPlot 

pub struct ViolinPlot {
    pub groups: Vec<ViolinGroup>,
    pub color: String,
    pub width: f64,
    pub legend_label: Option<String>,
    pub bandwidth: Option<f64>,
    pub kde_samples: usize,
    pub group_colors: Option<Vec<String>>,
    pub overlay: Option<StripStyle>,
    pub overlay_color: String,
    pub overlay_size: f64,
    pub overlay_seed: u64,
    pub horizontal: bool,
}

Builder for a violin plot.

Estimates the probability density of each group using kernel density estimation (KDE) and renders the result as a symmetric shape — wider where data is dense, narrower where it is sparse. Unlike box plots, violins reveal multi-modal and skewed distributions.

Bandwidth defaults to Silverman’s rule-of-thumb. Individual data points can be overlaid as a jittered strip or beeswarm.

Example

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

let plot = ViolinPlot::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_width(0.8);

let plots = vec![Plot::Violin(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("violin.svg", svg).unwrap();

Fields

groups: Vec<ViolinGroup>

color: String

width: f64

Width as a fraction of the category slot width (default 0.8). A value of 1.0 fills the slot edge-to-edge; 0.8 leaves a 10 % gap on each side. Equivalent to 1.0 - gap.

legend_label: Option<String>

bandwidth: Option<f64>

KDE bandwidth. None uses Silverman’s rule-of-thumb.

kde_samples: usize

Number of KDE evaluation points (default 200).

group_colors: Option<Vec<String>>

overlay: Option<StripStyle>

overlay_color: String

overlay_size: f64

overlay_seed: u64

horizontal: bool

Implementations

impl ViolinPlot

pub fn new() -> Self

Create a violin plot with default settings.

Defaults: color "black", width 0.8 (slot fraction), Silverman bandwidth, 200 KDE evaluation points, no overlay.

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 violin) with a label and raw values.

Groups are rendered left-to-right in the order they are added. More data points produce a smoother, more accurate density estimate.

let plot = ViolinPlot::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]);

pub fn with_color<S: Into<String>>(self, color: S) -> Self

Set the violin fill color (CSS color string, e.g. "steelblue").

pub fn with_group_colors<S, I>(self, colors: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Set per-group fill colors.

Colors are matched to groups by position. If the list is shorter than the number of groups, the uniform color from with_color is used as a fallback.

pub fn with_width(self, width: f64) -> Self

Set the violin width as a fraction of the category slot (default 0.8).

1.0 fills the slot edge-to-edge; 0.8 leaves a 10 % gap on each side. Equivalent to with_gap(1.0 - width).

pub fn with_gap(self, gap: f64) -> Self

Set the gap between adjacent violins as a fraction of the slot width (default 0.2). Equivalent to with_width(1.0 - gap).

pub fn with_legend<S: Into<String>>(self, label: S) -> Self

Attach a legend label to this violin plot.

pub fn with_bandwidth(self, h: f64) -> Self

Set the KDE bandwidth manually.

Bandwidth controls the smoothness of the density estimate. Smaller values reveal finer structure (but may be noisy); larger values produce a smoother shape (but may hide modes). When not set, Silverman’s rule-of-thumb is applied automatically — a good starting point for unimodal, roughly normal data.

let plot = ViolinPlot::new()
    .with_group("A", vec![1.0, 2.0, 3.0, 4.0, 5.0])
    .with_bandwidth(0.5);  // tighter than the default

pub fn with_kde_samples(self, n: usize) -> Self

Set the number of points at which the KDE is evaluated (default 200).

Higher values produce a smoother curve at the cost of slightly more computation. The default is adequate for most use cases.

pub fn with_strip(self, jitter: f64) -> Self

Overlay individual data points as a jittered strip.

jitter controls the horizontal spread (in data-axis units). A value of 0.15–0.2 is typical. Use a semi-transparent with_overlay_color so the violin shape remains visible underneath.

pub fn with_swarm_overlay(self) -> Self

Overlay individual data points as a beeswarm.

Points are spread horizontally to avoid overlap, giving a clearer picture of density than a jittered strip. Works best with smaller datasets (roughly N < 200 per group).

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 strongly recommended so the KDE shape behind the points remains legible.

pub fn with_overlay_size(self, size: f64) -> Self

Set the radius of overlay points in pixels (default 3.0).

pub fn with_horizontal(self, h: bool) -> Self

Render groups along the Y-axis and data values along the X-axis (default false).

Trait Implementations

impl Default for ViolinPlot

fn default() -> Self

Returns the “default value” for a type.

impl From<ViolinPlot> for Plot

fn from(p: ViolinPlot) -> Self

Converts to this type from the input type.