kuva

kuva is a scientific plotting library for Rust that renders plots to SVG. It targets bioinformatics use cases and ships with 60 plot types — from standard scatter and bar charts to Manhattan plots, UpSet plots, phylogenetic trees, and synteny diagrams. A kuva CLI binary lets you render plots directly from the shell without writing any Rust.

Design

The API follows a builder pattern. Every plot type is constructed with ::new(), configured with method chaining, and rendered through a single pipeline:

plot struct  →  Plot enum  →  Layout  →  SVG / PNG / PDF

Quick start

#![allow(unused)]
fn main() {
use kuva::prelude::*;

let data = vec![(1.0_f64, 2.0_f64), (3.0, 5.0), (5.0, 4.0)];

let plot = ScatterPlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_size(5.0);

let plots: Vec<Plot> = vec![plot.into()];
let layout = Layout::auto_from_plots(&plots)
    .with_title("My Plot")
    .with_x_label("X")
    .with_y_label("Y");

let svg = render_to_svg(plots, layout);
std::fs::write("my_plot.svg", svg).unwrap();
}

Prelude

use kuva::prelude::* brings all 60 plot structs, Plot, Layout, Figure, Theme, Palette, render_to_svg, and everything else you typically need into scope in one line.

Every plot struct implements Into<Plot>, so you can write plot.into() instead of Plot::Scatter(plot).

For PNG or PDF output, use render_to_png and render_to_pdf (require feature flags png and pdf respectively):

#![allow(unused)]
fn main() {
use kuva::prelude::*;

let plots: Vec<Plot> = vec![/* ... */];
let layout = Layout::auto_from_plots(&plots);

// SVG — always available
let svg: String = render_to_svg(plots, layout);

// PNG — feature = "png"
let png: Vec<u8> = render_to_png(plots, layout, 2.0).unwrap();

// PDF — feature = "pdf"
let pdf: Vec<u8> = render_to_pdf(plots, layout).unwrap();
}

Regenerating documentation assets

The SVG images embedded in these docs are generated by standalone example programs in the examples/ directory. Regenerate all assets at once with:

bash scripts/gen_docs.sh

Or regenerate a single plot type:

cargo run --example scatter
cargo run --example histogram
# etc. — one example per plot type in examples/

Building the book

Install mdBook, then:

mdbook build docs    # produce docs/book/
mdbook serve docs    # live-reload preview at http://localhost:3000

Gallery

All plot types at a glance

60 plot types, one figure — generated by running cargo run --example all_plots_simple and cargo run --example all_plots_complex.

Simple overview (compact, minimal data):

Full-featured (larger datasets, titles, axis labels, legends):

Individual plot types

Click any image to go to the full documentation page.

Scatter Plot

x/y points with optional trend line, error bars, and variable size.

Line Plot

Connected series with solid, dashed, dotted, and dash-dot styles.

Bar Chart

Categorical bars — grouped, stacked, and single-series.

Histogram

Distribution of a numeric column with configurable bins and normalisation.

Density Plot

KDE-smoothed probability density curve — single or multi-group with optional fill.

Ridgeline Plot

Stacked KDE density curves per group — the classic joyplot for comparing distributions.

2D Histogram

Joint density of two numeric columns with colourmap and optional correlation.

Box Plot

Median, IQR, and whiskers per group — with optional strip or swarm overlay.

Violin Plot

KDE density mirrored per group, with configurable bandwidth and swarm overlay.

Strip Plot

Individual points jittered or swarmed by group; composes with box/violin.

Pie Chart

Pie or donut chart with inside, outside, or legend-only labels.

Heatmap

Matrix of values with colourmap, optional cell labels, and row/col clustering.

Dot Plot

Size and colour encoding on a categorical grid — common in single-cell analysis.

Dice Plot

Die-face dot layout per grid cell — multivariate categorical and continuous data (port of ggdiceplot).

Contour Plot

Filled or line contours from gridded or scattered x/y/z data via IDW interpolation.

Stacked Area Plot

Stacked time-series with absolute or 100%-normalised mode.

Waterfall Chart

Running total with positive/negative deltas, connectors, and value labels.

Candlestick Chart

OHLC bars with optional volume panel and datetime axis.

Volcano Plot

log₂FC vs −log₁₀(p) with threshold lines and top-N gene labels.

Manhattan Plot

GWAS p-values across chromosomes with genome-wide threshold and gene labels.

UpSet Plot

Set intersection sizes as a bar chart with a membership matrix below.

Chord Diagram

Pairwise flows between N groups as arc segments and Bézier ribbons.

Network Plot

Node-edge graph with force-directed or circular layout, directed arrows, and weighted edges.

Sankey Diagram

Multi-stage flow with tapered Bézier links and source/gradient colouring.

Phylogenetic Tree

Newick, edge-list, distance-matrix, or linkage input; rectangular, slanted, or circular layout.

Synteny Plot

Genome synteny ribbons between sequences with forward and inverted blocks.

Forest Plot

Point estimates with confidence intervals for meta-analysis studies.

Band Plot

Shaded confidence or credible interval bands, standalone or attached to a line/scatter.

Series Plot

Multiple named data series on one canvas with per-series line and marker styles.

Brick Plot

Read-level alignment bricks with per-base colouring and STRIGAR string support.

Polar Plot

Polar coordinate scatter/line with configurable radial and angular grid.

Ternary Plot

Simplex scatter with barycentric coordinates and equilateral triangle geometry.

3D Scatter Plot

Orthographic 3D scatter with depth sorting, z-colormap, and open-box wireframe.

3D Surface Plot

Depth-sorted quadrilateral mesh with z-colormap, wireframe edges, and alpha transparency.

ECDF Plot

Empirical cumulative distribution function with optional confidence bands.

Q-Q Plot

Quantile-quantile plot for normality assessment and genomic inflation checks.

Hexbin Plot

Hexagonal bin density for large scatter datasets with colormap and colorbar support.

Treemap

Squarified treemap for hierarchical data — flat or two-level with grouped headers.

Sunburst Chart

Radial hierarchical chart with concentric rings; optional donut cut-out.

Bump Chart

Rank change over time with smooth sigmoid curves and end-of-line series labels.

Funnel Chart

Stage-by-stage attrition with trapezoidal connectors; mirror mode for side-by-side comparison.

Nightingale Rose

Polar bar chart where sector area encodes value; stacked, grouped, and wind-rose modes.

Calendar Heatmap

GitHub-style contribution graph for daily data across one or more years.

Gantt Chart

Task bars with group phases, progress fills, milestone diamonds, and a now line.

ROC Curve

Receiver operating characteristic with AUC annotation and diagonal reference line.

Precision-Recall Curve

Precision-recall with AUC annotation and no-skill baseline.

Kaplan-Meier Curve

Step-function survival curves with optional confidence intervals and censoring marks.

Slope Chart

Before-after comparisons with labeled endpoints; also functions as a dumbbell plot.

Lollipop Chart

Dot-on-a-stick for ranked categorical values; horizontal or vertical orientation.

Venn Diagram

2-, 3-, and 4-set Venn diagrams with overlap labels and proportional sizing.

Mosaic Plot

Proportional area tiles for two-way categorical contingency tables.

Parallel Coordinates

Multi-dimensional lines across parallel axes; colored by group or continuous value.

Population Pyramid

Back-to-back horizontal bars for demographic comparison; single or multi-series.

Waffle Chart

Grid of unit squares for part-to-whole proportions with optional per-cell icons.

Horizon Chart

Folded area chart for dense time-series comparison across many series.

Radar / Spider Chart

Multivariate polygon chart with configurable spoke count and optional fill.

Twin-Y Plot

Two independent y-axes sharing one x-axis for dual-scale comparisons.

Streamgraph

Flowing stacked area centered at zero for showing compositional change over time.

Clustermap

Hierarchically clustered heatmap with row and column dendrograms.

Joint Plot

Scatter with marginal histograms or KDE density panels on the top and right.

Raincloud Plot

KDE half-violin, box, and jittered strip combined for full distributional detail.

Origins

Before kuva had axes, themes, or 25 plot types, it had three blue circles. (It was also called visus back then)

The first output: three hardcoded circles, no background, no axes.

The very first proof-of-concept was just three blue dots on a transparent 500×500 canvas. No coordinate system, no margins, no layout. Just enough to confirm that the SVG pipeline worked end-to-end.

The next milestone was getting the library to automatically compute a layout from data:

• margins
• tick marks
• grid lines
• axis labels

all derived from the data bounds with no manual positioning.

The first auto-sized plot: real ticks and labels computed from data.

scatter_autosized.svg was the moment the coordinate mapping started making sense. Data values mapped to pixel positions, axes drawn automatically, tick intervals chosen from the data range. The red x-axis and green y-axis are relics of the earliest rendering code, colour-coded for debugging. That was the first plot that felt like a real plot. The rush I felt when this plot first rendered...wow.

Everything since has been built on that foundation.

Before LLM assistance

The first Claude Code session was opened on 20 February 2026, just to run /init and generate a CLAUDE.md file. At that point the library already had 11 plot types, all written from scratch:

ScatterPlot, LinePlot, BarPlot, Histogram, Histogram2D, BoxPlot, ViolinPlot, PiePlot, SeriesPlot, Heatmap, BrickPlot

(Technically 10 compiled. BrickPlot had a syntax error on day one, because I was still figuring out STRIGAR processing from bladerunner, an STR calling tool I wrote)

The 14 plot types added with AI assistance: BandPlot, WaterfallPlot, StripPlot, VolcanoPlot, ManhattanPlot, DotPlot, UpSetPlot, StackedAreaPlot, CandlestickPlot, ContourPlot, ChordPlot, SankeyPlot, PhyloTree, SyntenyPlot

The architecture, the rendering pipeline, the builder pattern API, and the core plotting logic were all designed and written before any LLM was involved.

On using LLM assistance

I want to be honest about this, because I think the discourse around AI and software is often dishonest in one direction or the other.

I am perfectly capable of writing everything in this library myself. I've been doing bioinformatics software development for years. The architecture here (the pipeline, the builder pattern, the primitive-based renderer) is all mine. I designed it, and I would have made the same design choices with or without an LLM. The deep domain knowledge of what a bioinformatician actually needs from a plotting library, the aesthetics, the decisions about which plot types to include and how their APIs should feel. None of that came from an LLM.

What LLM assistance changed was pace. Going from 11 plot types to 25, adding a full CLI, a terminal backend, a documentation book, smoke tests, and integration tests, all in roughly a week, that would have taken me much longer alone. Not because I couldn't do it, but because translating a clear mental model into working, tested code takes time, and that's where the acceleration is real.

It isn't a one-way process either. The LLM gets things wrong, proposes approaches that don't fit the existing code, or misses the intent entirely. Every feature required my involvement at every step: reviewing, redirecting, and often rejecting what was produced. A good example is the x-axis label positioning in the terminal backend. Getting tick labels to sit correctly in braille character cells, snapping to the right row, spacing correctly across different terminal heights, went through several wrong approaches before landing on the solution that actually works. That kind of problem requires someone who understands both what the output should look like and why a given implementation is producing the wrong result. The LLMs can generate absolute shit sometimes, and it's up to us to decide what is correct, and take responsibility for any of the output.

The honest summary: this is my library, reflecting my vision and expertise. The LLM is a fast, capable collaborator that I direct. I would not be publishing this so soon without that acceleration, but the work is mine. Your opinion of this may differ, and that's fine. But I really don't care and kuva exists, rather than not. That's all the validation I need.

Scatter Plot

A scatter plot renders individual (x, y) data points as markers. It supports trend lines, error bars, variable point sizes, per-point colors, and six marker shapes.

Import path: kuva::plot::scatter::ScatterPlot

Basic usage

#![allow(unused)]
fn main() {
use kuva::plot::scatter::ScatterPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data = vec![
    (0.5_f64, 1.2_f64),
    (1.4, 3.1),
    (2.1, 2.4),
    (3.3, 5.0),
    (4.0, 4.3),
    (5.2, 6.8),
    (6.1, 6.0),
    (7.0, 8.5),
    (8.4, 7.9),
    (9.1, 9.8),
];

let plot = ScatterPlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_size(5.0);

let plots = vec![Plot::Scatter(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Scatter Plot")
    .with_x_label("X")
    .with_y_label("Y");

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

Layout options

Layout::auto_from_plots() automatically computes axis ranges from the data. You can also set ranges manually with Layout::new((x_min, x_max), (y_min, y_max)).

Trend line

Add a linear trend line with .with_trend(TrendLine::Linear). Optionally overlay the regression equation and the Pearson R² value.

#![allow(unused)]
fn main() {
use kuva::plot::scatter::{ScatterPlot, TrendLine};
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data = vec![
    (1.0_f64, 2.1_f64), (2.0, 3.9), (3.0, 6.2),
    (4.0, 7.8), (5.0, 10.1), (6.0, 12.3),
    (7.0, 13.9), (8.0, 16.2), (9.0, 17.8), (10.0, 19.7),
];

let plot = ScatterPlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_size(5.0)
    .with_trend(TrendLine::Linear)
    .with_trend_color("crimson")   // defaults to "black"
    .with_equation()               // show y = mx + b
    .with_correlation();           // show R²

let plots = vec![Plot::Scatter(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Linear Trend Line")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Tip: .with_equation() and .with_correlation() render the fit statistics as floating text in the data area. For a cleaner presentation — particularly with dense point clouds — consider using Layout::with_stats_box() to display fit statistics in a bordered inset box instead. See Stats Box.

Confidence band

Attach a shaded uncertainty region with .with_band(y_lower, y_upper). Both slices must align with the x positions of the scatter data. The band color matches the point color.

#![allow(unused)]
fn main() {
use kuva::plot::scatter::ScatterPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let xs: Vec<f64> = (1..=10).map(|i| i as f64).collect();
let ys: Vec<f64> = xs.iter().map(|&x| x * 1.8 + 0.5).collect();
let lower: Vec<f64> = ys.iter().map(|&y| y - 1.2).collect();
let upper: Vec<f64> = ys.iter().map(|&y| y + 1.2).collect();

let data: Vec<(f64, f64)> = xs.into_iter().zip(ys).collect();

let plot = ScatterPlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_size(5.0)
    .with_band(lower, upper);

let plots = vec![Plot::Scatter(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Confidence Band")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Error bars

Use .with_x_err() and .with_y_err() for symmetric error bars. Asymmetric variants accept (negative, positive) tuples.

#![allow(unused)]
fn main() {
use kuva::plot::scatter::ScatterPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data = vec![
    (1.0_f64, 2.0_f64), (2.0, 4.5), (3.0, 5.8),
    (4.0, 8.2), (5.0, 10.1),
];
let x_err = vec![0.2_f64, 0.15, 0.3, 0.1, 0.25];  // symmetric
let y_err = vec![0.6_f64, 0.8, 0.4, 0.9, 0.5];     // symmetric

let plot = ScatterPlot::new()
    .with_data(data)
    .with_x_err(x_err)
    .with_y_err(y_err)
    .with_color("steelblue")
    .with_size(5.0);

let plots = vec![Plot::Scatter(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Error Bars")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Asymmetric errors

Pass (neg, pos) tuples instead of scalar values:

#![allow(unused)]
fn main() {
use kuva::plot::scatter::ScatterPlot;
let data = vec![(1.0_f64, 5.0_f64), (2.0, 6.0)];
let y_err = vec![(0.3_f64, 0.8_f64), (0.5, 1.2)];  // (neg, pos)

let plot = ScatterPlot::new()
    .with_data(data)
    .with_y_err_asymmetric(y_err);
}

Marker shapes

Six marker shapes are available via MarkerShape. They are particularly useful when overlaying multiple series on the same axes.

#![allow(unused)]
fn main() {
use kuva::plot::scatter::{ScatterPlot, MarkerShape};
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plots = vec![
    Plot::Scatter(ScatterPlot::new()
        .with_data(vec![(1.0_f64, 1.0_f64), (2.0, 1.0), (3.0, 1.0)])
        .with_color("steelblue").with_size(7.0)
        .with_marker(MarkerShape::Circle).with_legend("Circle")),

    Plot::Scatter(ScatterPlot::new()
        .with_data(vec![(1.0_f64, 2.0_f64), (2.0, 2.0), (3.0, 2.0)])
        .with_color("crimson").with_size(7.0)
        .with_marker(MarkerShape::Square).with_legend("Square")),

    Plot::Scatter(ScatterPlot::new()
        .with_data(vec![(1.0_f64, 3.0_f64), (2.0, 3.0), (3.0, 3.0)])
        .with_color("seagreen").with_size(7.0)
        .with_marker(MarkerShape::Triangle).with_legend("Triangle")),
];

let layout = Layout::auto_from_plots(&plots)
    .with_title("Marker Shapes")
    .with_x_label("X")
    .with_y_label("");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Available variants: Circle (default), Square, Triangle, Diamond, Cross, Plus.

Bubble plot

Encode a third dimension through point area using .with_sizes(). Values are point radii in pixels.

#![allow(unused)]
fn main() {
use kuva::plot::scatter::ScatterPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data = vec![
    (1.0_f64, 3.0_f64), (2.5, 6.5), (4.0, 4.0),
    (5.5, 8.0), (7.0, 5.5), (8.5, 9.0),
];
let sizes = vec![5.0_f64, 14.0, 9.0, 18.0, 11.0, 7.0];

let plot = ScatterPlot::new()
    .with_data(data)
    .with_sizes(sizes)
    .with_color("steelblue");

let plots = vec![Plot::Scatter(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Bubble Plot")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Per-point colors

Encode a categorical grouping through color using .with_colors(). Colors are matched to points by index and fall back to the uniform .with_color() value for any point without an entry.

This is useful when your data already carries a group label and you want to avoid splitting into multiple ScatterPlot instances. The legend is not updated automatically — add .with_legend() on separate ScatterPlot instances when you need a labeled legend.

#![allow(unused)]
fn main() {
use kuva::plot::scatter::ScatterPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

// Three clusters, colors assigned per point
let data = vec![
    (1.0_f64, 1.5_f64), (1.5, 2.0), (2.0, 1.8),  // cluster A
    (4.0, 4.5),         (4.5, 5.0), (5.0, 4.8),  // cluster B
    (7.0, 2.0),         (7.5, 2.5), (8.0, 2.2),  // cluster C
];
let colors = vec![
    "steelblue", "steelblue", "steelblue",
    "crimson",   "crimson",   "crimson",
    "seagreen",  "seagreen",  "seagreen",
];

let plot = ScatterPlot::new()
    .with_data(data)
    .with_colors(colors)
    .with_size(6.0);

let plots = vec![Plot::Scatter(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Per-Point Colors")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Marker opacity and stroke

Two builders control the visual style of markers, enabling three distinct modes useful for dense datasets:

Semi-transparent markers — overlapping clusters

Three Gaussian clusters of 200 points each share a region in the centre. Solid markers at this density merge into a single opaque mass. Reducing opacity to 0.25 lets the darker overlap region show where clusters share space, while the 0.7 px stroke keeps each marker individually legible.

#![allow(unused)]
fn main() {
use kuva::plot::scatter::ScatterPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

// Three clusters, 200 points each — defined as (center_x, center_y, color, label)
let series = [
    (3.0_f64, 4.0_f64, "steelblue", "Cluster A"),
    (5.0,     5.5,     "tomato",    "Cluster B"),
    (4.0,     3.0,     "seagreen",  "Cluster C"),
];

// (populate `data` from your source — each entry is 200 (x, y) points)

let data: Vec<(f64,f64)> = vec![];
let plot = ScatterPlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_size(5.0)
    .with_marker_opacity(0.25)
    .with_marker_stroke_width(0.7)
    .with_legend("Cluster A");

let plots = vec![Plot::Scatter(plot) /* , ... */];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Overlapping Clusters — semi-transparent markers")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Hollow open circles — dense annular data

800 points sampled uniformly along a noisy ring. With solid fill the ring becomes a uniform band; hollow circles (opacity = 0.0) make the denser arc sections visible through the accumulation of overlapping outlines.

#![allow(unused)]
fn main() {
use kuva::plot::scatter::ScatterPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

// 800 points sampled along a noisy annulus of radius ≈ 3
let data: Vec<(f64,f64)> = vec![];
let plot = ScatterPlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_size(4.0)
    .with_marker_opacity(0.0)       // fully hollow
    .with_marker_stroke_width(1.0); // only the outline is drawn

let plots = vec![Plot::Scatter(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Hollow open circles — 800 pts in a noisy annulus")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Multiple series

Wrap multiple ScatterPlot structs in a Vec<Plot> and pass them to render_multiple(). Legends are shown when any series has a label attached via .with_legend().

#![allow(unused)]
fn main() {
use kuva::plot::scatter::ScatterPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let series_a = ScatterPlot::new()
    .with_data(vec![(1.0_f64, 2.0_f64), (3.0, 4.0), (5.0, 3.5)])
    .with_color("steelblue")
    .with_legend("Series A");

let series_b = ScatterPlot::new()
    .with_data(vec![(1.0_f64, 5.0_f64), (3.0, 6.5), (5.0, 7.0)])
    .with_color("crimson")
    .with_legend("Series B");

let plots = vec![Plot::Scatter(series_a), Plot::Scatter(series_b)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Two Series")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

API reference

MarkerShape variants

Circle · Square · Triangle · Diamond · Cross · Plus

TrendLine variants

Linear — fits y = mx + b by ordinary least squares.

Line Plot

A line plot connects (x, y) data points with a continuous path. It supports four built-in stroke styles, area fills, step interpolation, confidence bands, and error bars.

Import path: kuva::plot::LinePlot

Basic usage

#![allow(unused)]
fn main() {
use kuva::plot::LinePlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data: Vec<(f64, f64)> = (0..=100)
    .map(|i| { let x = i as f64 * 0.1; (x, x.sin()) })
    .collect();

let plot = LinePlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_stroke_width(2.0);

let plots = vec![Plot::Line(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Line Plot")
    .with_x_label("X")
    .with_y_label("Y");

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

Line styles

Four built-in stroke styles are available. Use the shorthand methods or pass a LineStyle variant directly.

#![allow(unused)]
fn main() {
use kuva::plot::{LinePlot, LineStyle};
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let xs: Vec<f64> = (0..=80).map(|i| i as f64 * 0.125).collect();

let plots = vec![
    Plot::Line(LinePlot::new()
        .with_data(xs.iter().map(|&x| (x, x.sin())))
        .with_color("steelblue").with_stroke_width(2.0)
        .with_line_style(LineStyle::Solid).with_legend("Solid")),

    Plot::Line(LinePlot::new()
        .with_data(xs.iter().map(|&x| (x, x.cos())))
        .with_color("crimson").with_stroke_width(2.0)
        .with_dashed().with_legend("Dashed")),

    Plot::Line(LinePlot::new()
        .with_data(xs.iter().map(|&x| (x, (x * 0.7).sin())))
        .with_color("seagreen").with_stroke_width(2.0)
        .with_dotted().with_legend("Dotted")),

    Plot::Line(LinePlot::new()
        .with_data(xs.iter().map(|&x| (x, (x * 0.7).cos())))
        .with_color("darkorange").with_stroke_width(2.0)
        .with_dashdot().with_legend("Dash-dot")),
];

let layout = Layout::auto_from_plots(&plots)
    .with_title("Line Styles")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Custom dasharray

For patterns not covered by the built-in variants, use LineStyle::Custom with an SVG stroke-dasharray string:

#![allow(unused)]
fn main() {
use kuva::plot::{LinePlot, LineStyle};
let plot = LinePlot::new()
    .with_data(vec![(0.0_f64, 0.0_f64), (1.0, 1.0), (2.0, 0.5)])
    .with_line_style(LineStyle::Custom("12 3 3 3".into()));
}

Area plot

Call .with_fill() to shade the region between the line and the x-axis. The fill uses the line color at 0.3 opacity by default.

#![allow(unused)]
fn main() {
use kuva::plot::LinePlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data: Vec<(f64, f64)> = (0..=100)
    .map(|i| { let x = i as f64 * 0.1; (x, x.sin()) })
    .collect();

let plot = LinePlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_stroke_width(2.0)
    .with_fill()
    .with_fill_opacity(0.3);   // optional, 0.3 is the default

let plots = vec![Plot::Line(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Area Plot")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Step plot

.with_step() draws horizontal-then-vertical transitions between consecutive points rather than diagonal segments. This is the standard rendering for histograms and discrete time-series data.

#![allow(unused)]
fn main() {
use kuva::plot::LinePlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data = vec![
    (0.0_f64, 2.0_f64), (1.0, 5.0), (2.0, 3.0), (3.0, 7.0),
    (4.0, 4.0), (5.0, 8.0), (6.0, 5.0), (7.0, 9.0),
];

let plot = LinePlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_stroke_width(2.0)
    .with_step();

let plots = vec![Plot::Line(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Step Plot")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Step and fill can be combined: .with_step().with_fill() produces a filled step area.

Confidence band

.with_band(y_lower, y_upper) draws a shaded region between two boundary series aligned to the line's x positions. The band color inherits from the line color.

#![allow(unused)]
fn main() {
use kuva::plot::LinePlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let xs: Vec<f64> = (0..=80).map(|i| i as f64 * 0.125).collect();
let ys: Vec<f64> = xs.iter().map(|&x| x.sin()).collect();
let lower: Vec<f64> = ys.iter().map(|&y| y - 0.3).collect();
let upper: Vec<f64> = ys.iter().map(|&y| y + 0.3).collect();

let data: Vec<(f64, f64)> = xs.into_iter().zip(ys).collect();

let plot = LinePlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_stroke_width(2.0)
    .with_band(lower, upper);

let plots = vec![Plot::Line(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Confidence Band")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Error bars

.with_y_err() and .with_x_err() attach symmetric error bars. Asymmetric variants take (negative, positive) tuples.

#![allow(unused)]
fn main() {
use kuva::plot::LinePlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data: Vec<(f64, f64)> = (0..=8)
    .map(|i| (i as f64, (i as f64 * 0.8).sin()))
    .collect();
let y_err = vec![0.15, 0.20, 0.12, 0.18, 0.22, 0.14, 0.19, 0.16, 0.21_f64];

let plot = LinePlot::new()
    .with_data(data)
    .with_y_err(y_err)
    .with_color("steelblue")
    .with_stroke_width(2.0);

let plots = vec![Plot::Line(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Error Bars")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Asymmetric errors

Pass (neg, pos) tuples instead of scalar values:

#![allow(unused)]
fn main() {
use kuva::plot::LinePlot;
let data: Vec<(f64, f64)> = (0..=4).map(|i| (i as f64, i as f64)).collect();
let y_err = vec![(0.1_f64, 0.3_f64), (0.2, 0.5), (0.1, 0.4), (0.3, 0.2), (0.2, 0.6)];

let plot = LinePlot::new()
    .with_data(data)
    .with_y_err_asymmetric(y_err);
}

Multiple series

Pass multiple LinePlot structs in a Vec<Plot>. Legends appear automatically when any series has a label.

#![allow(unused)]
fn main() {
use kuva::plot::LinePlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let xs: Vec<f64> = (0..=60).map(|i| i as f64 * 0.1).collect();

let plots = vec![
    Plot::Line(LinePlot::new()
        .with_data(xs.iter().map(|&x| (x, x.sin())))
        .with_color("steelblue").with_legend("sin(x)")),
    Plot::Line(LinePlot::new()
        .with_data(xs.iter().map(|&x| (x, x.cos())))
        .with_color("crimson").with_legend("cos(x)")),
];

let layout = Layout::auto_from_plots(&plots)
    .with_title("Multiple Series")
    .with_x_label("X")
    .with_y_label("Y");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

API reference

LineStyle variants

Solid (default) · Dashed (8 4) · Dotted (2 4) · DashDot (8 4 2 4) · Custom(String)

Bar Chart

A bar chart renders categorical data as vertical bars. It has three modes — simple, grouped, and stacked — all built from the same BarPlot struct.

Import path: kuva::plot::BarPlot

Simple bar chart

Use .with_bar() or .with_bars() to add one bar per category, then .with_color() to set a uniform fill.

#![allow(unused)]
fn main() {
use kuva::plot::BarPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = BarPlot::new()
    .with_bars(vec![
        ("Apples",     42.0),
        ("Bananas",    58.0),
        ("Cherries",   31.0),
        ("Dates",      47.0),
        ("Elderberry", 25.0),
    ])
    .with_color("steelblue");

let plots = vec![Plot::Bar(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Bar Chart")
    .with_y_label("Count");

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

Adding bars individually

.with_bar(label, value) adds one bar at a time, which is useful when constructing data programmatically:

#![allow(unused)]
fn main() {
use kuva::plot::BarPlot;
let plot = BarPlot::new()
    .with_bar("A", 3.2)
    .with_bar("B", 4.7)
    .with_bar("C", 2.8)
    .with_color("steelblue");
}

Per-bar colors

Use .with_colored_bar() or .with_colored_bars() to give each bar its own color — useful when bars represent distinct categories such as nucleotide variants or mutation types.

#![allow(unused)]
fn main() {
use kuva::plot::BarPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = BarPlot::new()
    .with_colored_bar("A2C", 42.0, "steelblue")
    .with_colored_bar("A2G", 58.0, "seagreen")
    .with_colored_bar("A2T", 31.0, "tomato")
    .with_colored_bar("C2A", 25.0, "gold");

let plots = vec![Plot::Bar(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Mutation Counts")
    .with_y_label("Count");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

To add many colored bars at once, pass an iterator of (label, value, color) triples to .with_colored_bars():

#![allow(unused)]
fn main() {
use kuva::plot::BarPlot;
let variants = vec![
    ("A2C", 42.0, "steelblue"),
    ("A2G", 58.0, "seagreen"),
    ("A2T", 31.0, "tomato"),
    ("C2A", 25.0, "gold"),
    ("C2G", 18.0, "orchid"),
    ("C2T", 63.0, "darkorange"),
];
let plot = BarPlot::new().with_colored_bars(variants);
}

Grouped bar chart

Use .with_group(label, values) to add a category with multiple side-by-side bars. Each item in values is a (value, color) pair — one per series. Call .with_legend() to label each series.

#![allow(unused)]
fn main() {
use kuva::plot::BarPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = BarPlot::new()
    .with_group("Q1", vec![(18.0, "steelblue"), (12.0, "crimson"), (9.0,  "seagreen")])
    .with_group("Q2", vec![(22.0, "steelblue"), (17.0, "crimson"), (14.0, "seagreen")])
    .with_group("Q3", vec![(19.0, "steelblue"), (21.0, "crimson"), (11.0, "seagreen")])
    .with_group("Q4", vec![(25.0, "steelblue"), (15.0, "crimson"), (18.0, "seagreen")])
    .with_legend(vec!["Product A", "Product B", "Product C"]);

let plots = vec![Plot::Bar(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Grouped Bar Chart")
    .with_y_label("Sales (units)");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Stacked bar chart

Add .with_stacked() to the same grouped structure to stack segments vertically instead of placing them side-by-side.

#![allow(unused)]
fn main() {
use kuva::plot::BarPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = BarPlot::new()
    .with_group("Q1", vec![(18.0, "steelblue"), (12.0, "crimson"), (9.0,  "seagreen")])
    .with_group("Q2", vec![(22.0, "steelblue"), (17.0, "crimson"), (14.0, "seagreen")])
    .with_group("Q3", vec![(19.0, "steelblue"), (21.0, "crimson"), (11.0, "seagreen")])
    .with_group("Q4", vec![(25.0, "steelblue"), (15.0, "crimson"), (18.0, "seagreen")])
    .with_legend(vec!["Product A", "Product B", "Product C"])
    .with_stacked();

let plots = vec![Plot::Bar(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Stacked Bar Chart")
    .with_y_label("Sales (units)");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Bar width

.with_width() controls how much of each category slot the bar fills. The default is 0.8; 1.0 means bars touch.

#![allow(unused)]
fn main() {
use kuva::plot::BarPlot;
let plot = BarPlot::new()
    .with_bars(vec![("A", 3.0), ("B", 5.0), ("C", 4.0)])
    .with_color("steelblue")
    .with_width(0.5);   // narrower bars with more whitespace
}

API reference

Choosing a mode

Histogram

A histogram bins a 1-D dataset into equal-width intervals and renders each bin as a vertical bar. It supports explicit ranges, normalization, and overlapping distributions.

Import path: kuva::plot::Histogram

Basic usage

.with_range((min, max)) is required — without it Layout::auto_from_plots cannot determine the axis extent and will produce an empty chart. Compute the range from your data before building the histogram:

#![allow(unused)]
fn main() {
use kuva::plot::Histogram;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data: Vec<f64> = vec![/* your samples */];

// Compute range from data first.
let min = data.iter().cloned().fold(f64::INFINITY, f64::min);
let max = data.iter().cloned().fold(f64::NEG_INFINITY, f64::max);

let hist = Histogram::new()
    .with_data(data)
    .with_bins(20)
    .with_range((min, max))   // required for auto_from_plots
    .with_color("steelblue");

let plots = vec![Plot::Histogram(hist)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Histogram")
    .with_x_label("Value")
    .with_y_label("Count");

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

Bin count

.with_bins(n) sets the number of equal-width bins (default 10). Fewer bins smooth out noise; more bins reveal finer structure at the cost of per-bin counts. The same range is used in both cases so the x-axis stays comparable.

#![allow(unused)]
fn main() {
use kuva::plot::Histogram;
// Coarse — few bins, clear shape
let hist = Histogram::new().with_data(data.clone()).with_bins(5).with_range(range);

// Fine — many bins, more detail
let hist = Histogram::new().with_data(data).with_bins(40).with_range(range);
}

Fixed range

Pass an explicit (min, max) to .with_range() to fix the bin edges regardless of the data. Values outside the range are silently ignored. This is useful when you want to focus on a sub-range, exclude outliers, or ensure two independent histograms cover the same x-axis scale.

#![allow(unused)]
fn main() {
use kuva::plot::Histogram;
let hist = Histogram::new()
    .with_data(data)
    .with_bins(20)
    .with_range((-3.0, 3.0))   // bins fixed to [-3, 3]; outliers ignored
    .with_color("steelblue");
}

Normalized histogram

.with_normalize() rescales bar heights so the tallest bar equals 1.0. This is peak-normalization — useful for comparing the shape of distributions with different sample sizes. The y-axis shows relative frequency, not counts or probability density.

#![allow(unused)]
fn main() {
use kuva::plot::Histogram;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let min = data.iter().cloned().fold(f64::INFINITY, f64::min);
let max = data.iter().cloned().fold(f64::NEG_INFINITY, f64::max);

let hist = Histogram::new()
    .with_data(data)
    .with_bins(20)
    .with_range((min, max))
    .with_color("steelblue")
    .with_normalize();

let plots = vec![Plot::Histogram(hist)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Normalized Histogram")
    .with_x_label("Value")
    .with_y_label("Relative frequency");
}

Overlapping distributions

Place multiple Histogram structs in the same Vec<Plot>. Since bars have no built-in opacity setting, use 8-digit hex colors (#RRGGBBAA) to make each series semi-transparent so the overlap is visible.

When overlapping, compute a shared range from the combined data so both histograms use the same bin edges and x-axis scale:

#![allow(unused)]
fn main() {
use kuva::plot::Histogram;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

// Shared range across both groups so x-axes align.
let combined_min = group_a.iter().chain(group_b.iter())
    .cloned().fold(f64::INFINITY, f64::min);
let combined_max = group_a.iter().chain(group_b.iter())
    .cloned().fold(f64::NEG_INFINITY, f64::max);
let range = (combined_min, combined_max);

// #4682b480 = steelblue at ~50% opacity
// #dc143c80 = crimson  at ~50% opacity
let hist_a = Histogram::new()
    .with_data(group_a)
    .with_bins(20)
    .with_range(range)
    .with_color("#4682b480")
    .with_legend("Group A");

let hist_b = Histogram::new()
    .with_data(group_b)
    .with_bins(20)
    .with_range(range)
    .with_color("#dc143c80")
    .with_legend("Group B");

let plots = vec![Plot::Histogram(hist_a), Plot::Histogram(hist_b)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Overlapping Distributions")
    .with_x_label("Value")
    .with_y_label("Count");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

The AA byte in the hex color controls opacity: ff = fully opaque, 80 ≈ 50%, 40 ≈ 25%.

API reference

Density Plot

A density plot estimates the probability density of a numeric dataset via Gaussian kernel density estimation (KDE) and renders it as a smooth continuous curve. It is the continuous alternative to a histogram — it shows the same shape without the arbitrary bin boundaries, and curves from multiple groups can be overlaid naturally.

Import path: kuva::plot::DensityPlot

Basic usage

Pass raw data values with .with_data(iter). The bandwidth is chosen automatically using Silverman's rule-of-thumb.

#![allow(unused)]
fn main() {
use kuva::plot::DensityPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data = vec![2.1, 3.4, 3.7, 2.8, 4.2, 3.9, 3.1, 2.5, 4.0, 3.3,
                2.9, 3.6, 2.7, 3.8, 3.2, 4.1, 2.6, 3.5, 3.0, 4.3];

let density = DensityPlot::new()
    .with_data(data)
    .with_color("steelblue");

let plots = vec![Plot::Density(density)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Expression Distribution")
    .with_x_label("Expression")
    .with_y_label("Density");

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

The y-axis is a proper probability density: each curve integrates to approximately 1 over the displayed range.

Tail behaviour. By default, the KDE is evaluated from data_min − 3×bandwidth to data_max + 3×bandwidth so the Gaussian tails taper smoothly to zero beyond the data. The x-axis auto-scales to include those tails. This matches ggplot2's default cut = 3 behaviour and is statistically correct — the tails reflect that a distribution does not hard-stop at the outermost data point. If your data is physically bounded (see below) you should set explicit bounds to prevent the curve from extending into impossible values.

Filled area

.with_filled(true) shades the area under the curve. The fill uses the same color as the stroke at a low opacity (default 0.2).

#![allow(unused)]
fn main() {
use kuva::plot::DensityPlot;
let density = DensityPlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_filled(true)
    .with_opacity(0.25);
}

Multiple groups

Use one DensityPlot per group and collect them into a single Vec<Plot>. Set .with_palette() on the layout to auto-assign colors, or assign colors and legend labels manually.

#![allow(unused)]
fn main() {
use kuva::plot::DensityPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;
use kuva::render::palette::Palette;

let pal = Palette::category10();

let plots = vec![
    Plot::Density(
        DensityPlot::new()
            .with_data(group_a)
            .with_color(pal[0])
            .with_filled(true)
            .with_legend("Control"),
    ),
    Plot::Density(
        DensityPlot::new()
            .with_data(group_b)
            .with_color(pal[1])
            .with_filled(true)
            .with_legend("Treatment A"),
    ),
    Plot::Density(
        DensityPlot::new()
            .with_data(group_c)
            .with_color(pal[2])
            .with_filled(true)
            .with_legend("Treatment B"),
    ),
];

let layout = Layout::auto_from_plots(&plots)
    .with_title("Expression by Group")
    .with_x_label("Expression")
    .with_y_label("Density");

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

Overlapping filled curves distinguish naturally by color. Increase .with_opacity() toward 0.4 if groups are well separated, or keep it low (0.15–0.2) when they overlap heavily.

Bounded data — identity scores, β-values, frequencies

For data that is physically constrained to a fixed interval — identity scores [0, 1], methylation β-values [0, 1], allele frequencies [0, 1], percentages [0, 100] — the default KDE will extend past those limits, producing a curve that bleeds into impossible negative values or past the upper ceiling.

Default — tails bleed past 0 and 1	with_x_range(0, 1) — smooth taper at boundaries

Use .with_x_range(lo, hi) to enforce both limits simultaneously:

#![allow(unused)]
fn main() {
use kuva::plot::DensityPlot;
let data = vec![0.1_f64; 10];
// Identity scores: scores cannot be negative or exceed 1.0
let density = DensityPlot::new()
    .with_data(data)
    .with_x_range(0.0, 1.0);
}

Boundary reflection. Simply truncating the evaluation range would cause the curve to cut off abruptly mid-peak wherever data is dense near a boundary. kuva instead uses the reflection method (the same approach as ggplot2 geom_density(bounds = ...) since 3.4.0): for each data point within 3×bandwidth of an active boundary a ghost point is mirrored across that boundary. The KDE is then evaluated only within [lo, hi] using the augmented dataset. The result tapers smoothly to zero at the boundary even when data is concentrated right at the edge.

One-sided bounds. If only one side is physically constrained, set just that bound:

#![allow(unused)]
fn main() {
use kuva::plot::DensityPlot;
let data = vec![0.1_f64; 10];
// Scores cannot be negative but have no known upper cap
let density = DensityPlot::new()
    .with_data(data)
    .with_x_lo(0.0); // left boundary reflected; right tail still free

// Percentages cannot exceed 100 but have no known lower cap
let density = DensityPlot::new()
    .with_data(data)
    .with_x_hi(100.0); // right boundary reflected; left tail still free
}

When only one bound is set the other tail extends 3×bandwidth past the data extreme as normal. This means a curve with only x_lo = 0 set can still extend past 1.0 on the right if the data range allows — use with_x_range(0.0, 1.0) when both sides are constrained.

In the CLI, pass --x-min and --x-max independently — either flag alone is sufficient:

# Both sides bounded — identity scores
kuva density scores.tsv --value score --x-min 0 --x-max 1

# Left side only — counts that cannot be negative
kuva density counts.tsv --value count --x-min 0

KDE bandwidth

Bandwidth controls smoothing. Silverman's rule works well for roughly normal unimodal data. Set it manually with .with_bandwidth(h) when the automatic choice is too smooth (blends modes) or too rough (noisy).

#![allow(unused)]
fn main() {
use kuva::plot::DensityPlot;
// Over-smoothed — modes blend together
let d = DensityPlot::new().with_data(data.clone()).with_bandwidth(2.0);

// Automatic — Silverman's rule (default, no call needed)
let d = DensityPlot::new().with_data(data.clone());

// Under-smoothed — noisy, jagged
let d = DensityPlot::new().with_data(data.clone()).with_bandwidth(0.1);
}

h = 0.1 (too narrow)	Auto — Silverman	h = 2.0 (too wide)

.with_kde_samples(n) controls how many points the curve is evaluated at (default 200). The default is smooth enough for most screen resolutions.

Dashed lines

.with_line_dash("4 2") applies an SVG stroke-dasharray. Useful when distinguishing groups in print or greyscale output.

#![allow(unused)]
fn main() {
use kuva::plot::DensityPlot;
let d = DensityPlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_stroke_width(2.0)
    .with_line_dash("6 3");
}

Pre-computed curves

DensityPlot::from_curve(x, y) accepts a pre-smoothed curve directly — useful when the density was already computed in Python or R:

#![allow(unused)]
fn main() {
use kuva::plot::DensityPlot;

// x and y computed externally (e.g. scipy.stats.gaussian_kde)
let x = vec![0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0];
let y = vec![0.05, 0.15, 0.40, 0.55, 0.40, 0.15, 0.05];

let density = DensityPlot::from_curve(x, y)
    .with_color("coral")
    .with_filled(true);
}

API reference

Ridgeline Plot

A ridgeline plot (also called a joyplot) stacks multiple KDE density curves vertically — one per group. Groups are labelled on the y-axis; the x-axis is the continuous data range. Curves can overlap for the classic "mountain range" look.

Basic usage

#![allow(unused)]
fn main() {
use kuva::plot::ridgeline::RidgelinePlot;
use kuva::render::plots::Plot;
use kuva::render::layout::Layout;
use kuva::render::render::render_multiple;
use kuva::backend::svg::SvgBackend;

let plot = RidgelinePlot::new()
    .with_group("Control",     vec![1.2, 1.5, 1.8, 2.0, 2.2, 1.9, 1.6, 1.3])
    .with_group("Treatment A", vec![2.5, 3.0, 3.5, 4.0, 3.8, 3.2, 2.8, 3.6])
    .with_group("Treatment B", vec![4.5, 5.0, 5.5, 6.0, 5.8, 5.2, 4.8, 5.3]);

let plots = vec![Plot::Ridgeline(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Expression by Treatment")
    .with_x_label("Expression Level")
    .with_y_label("Group");
let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Per-group colors — seasonal temperature example

.with_group_color(label, data, color) lets you assign an explicit color to each group. A cold-to-warm gradient across months gives the plot an intuitive thermal feel.

#![allow(unused)]
fn main() {
use kuva::plot::ridgeline::RidgelinePlot;
use kuva::render::plots::Plot;
use kuva::render::layout::Layout;
use kuva::render::render::render_multiple;
use kuva::backend::svg::SvgBackend;

// (month, mean °C, std-dev) for a temperate-climate city
let months = [
    ("January",   -3.0_f64, 5.0_f64),
    ("February",  -1.5,     5.5),
    ("March",      4.0,     5.0),
    ("April",     10.0,     4.0),
    ("May",       15.5,     3.5),
    ("June",      20.0,     3.0),
    ("July",      23.0,     2.5),
    ("August",    22.5,     2.5),
    ("September", 17.0,     3.0),
    ("October",   10.5,     4.0),
    ("November",   3.5,     5.0),
    ("December",  -1.0,     5.5),
];

// Blue → red gradient (cold → hot)
let colors = [
    "#3a7abf", "#4589c4", "#6ba3d4", "#a0bfdc",
    "#d4b8a0", "#e8c97a", "#f0a830", "#e86820",
    "#d44a10", "#c06030", "#9070a0", "#5060b0",
];

let mut plot = RidgelinePlot::new()
    .with_overlap(0.6)
    .with_opacity(0.75);

for (i, &(month, mean, std)) in months.iter().enumerate() {
    let data: Vec<f64> = vec![/* 200 samples from N(mean, std) */];
    plot = plot.with_group_color(month, data, colors[i]);
}

let plots = vec![Plot::Ridgeline(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Daily Temperature Distributions by Month")
    .with_x_label("Temperature (°C)")
    .with_y_label("Month");
let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

CLI

kuva ridgeline samples.tsv --group-by group --value expression \
    --title "Ridgeline" --x-label "Expression"

Builder reference

ECDF Plot

An Empirical Cumulative Distribution Function plot shows F(x) = P(X ≤ x) as a right-continuous step function. It is one of the most informative single-distribution diagnostics — no binning, no bandwidth choice, and the full distribution is visible. Multiple groups can be overlaid for direct comparison.

Import path: kuva::plot::EcdfPlot

Basic usage

#![allow(unused)]
fn main() {
use kuva::plot::EcdfPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data: Vec<f64> = vec![1.2, 3.4, 2.1, 5.6, 4.0, 0.8, 3.3, 2.7, 4.5, 1.9];

let plot = EcdfPlot::new()
    .with_data("Sample", data)
    .with_color("steelblue");

let plots = vec![Plot::Ecdf(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("ECDF")
    .with_x_label("Value")
    .with_y_label("F(x)");

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

Multi-group comparison

Add multiple groups to overlay ECDFs on the same axes. Call .with_legend("") to enable the legend — an empty string shows group labels without a separate title.

#![allow(unused)]
fn main() {
use kuva::plot::EcdfPlot;
use kuva::render::plots::Plot;
use kuva::render::layout::Layout;
use kuva::render::render::render_multiple;
use kuva::backend::svg::SvgBackend;
let plot = EcdfPlot::new()
    .with_data("Control", vec![1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0])
    .with_data("Treated", vec![2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0])
    .with_legend("");

let plots = vec![Plot::Ecdf(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Treatment vs Control");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Complementary CDF (CCDF)

.with_complementary() flips the y-axis to 1 - F(x), which is the survival function / exceedance probability. This is the standard view for:

• Sequencing read length distributions (what fraction of reads are ≥ N bp?)
• Coverage distributions (what fraction of positions have ≥ N× depth?)
• Heavy-tailed data where you care about the tail rather than the bulk

#![allow(unused)]
fn main() {
use kuva::plot::EcdfPlot;
use kuva::render::plots::Plot;
let plot = EcdfPlot::new()
    .with_data("Nanopore run", vec![500.0, 1200.0, 3500.0, 8000.0, 15000.0])
    .with_color("steelblue")
    .with_complementary();
}

Combine with a log x-axis via Layout::with_log_x() for read-length distributions:

#![allow(unused)]
fn main() {
use kuva::plot::EcdfPlot;
use kuva::render::plots::Plot;
use kuva::render::layout::Layout;
let plot = EcdfPlot::new().with_data("", vec![1.0]);
let plots = vec![Plot::Ecdf(plot)];
let layout = Layout::auto_from_plots(&plots).with_log_x();
}

DKW confidence bands

.with_confidence_band() adds a shaded DKW 95% confidence band around each curve. The band width is ε = √(ln(40) / (2n)) — wider for small n, tight for large n. This is the key diagnostic for whether two curves are statistically distinguishable:

#![allow(unused)]
fn main() {
use kuva::plot::EcdfPlot;
let plot = EcdfPlot::new()
    .with_data("n=20", (0..20).map(|i| i as f64))
    .with_data("n=100", (0..100).map(|i| i as f64))
    .with_confidence_band()
    .with_legend("");
}

Adjust the band opacity with .with_band_alpha(f) (default 0.15).

Rug plot

.with_rug() draws small tick marks at the bottom of the plot area at each data point's location. This shows the density and distribution of raw observations — useful for spotting clusters, gaps, and outliers that the step function alone can obscure.

#![allow(unused)]
fn main() {
use kuva::plot::EcdfPlot;
let plot = EcdfPlot::new()
    .with_data("Sample", vec![1.0, 1.1, 1.2, 3.0, 5.0, 5.1, 7.5])
    .with_color("steelblue")
    .with_rug();
}

For multi-group plots, each group's rug is offset vertically so they don't fully overlap.

Percentile reference lines

.with_percentile_lines(vec![0.25, 0.5, 0.75]) draws horizontal dashed reference lines at Q1, median, and Q3 (or any levels you specify). Labels are placed at the right edge.

#![allow(unused)]
fn main() {
use kuva::plot::EcdfPlot;
let plot = EcdfPlot::new()
    .with_data("", (1..=100).map(|i| i as f64))
    .with_color("steelblue")
    .with_percentile_lines(vec![0.25, 0.5, 0.75]);
}

Step markers

.with_markers() places a circle at each step endpoint, making the discrete nature of the ECDF explicit. Most useful for small samples (n < ~30):

#![allow(unused)]
fn main() {
use kuva::plot::EcdfPlot;
let plot = EcdfPlot::new()
    .with_data("n=8", vec![1.2, 2.4, 2.9, 3.5, 4.1, 5.0, 5.8, 7.2])
    .with_color("steelblue")
    .with_markers()
    .with_marker_size(4.0);
}

Smooth CDF

.with_smooth() replaces the step function with a KDE-integrated smooth CDF (bandwidth chosen by Silverman's rule):

#![allow(unused)]
fn main() {
use kuva::plot::EcdfPlot;
let plot = EcdfPlot::new()
    .with_data("Sample", (0..200).map(|i| (i as f64) * 0.05))
    .with_color("steelblue")
    .with_smooth();
}

Builder reference

CLI

# Basic ECDF
kuva ecdf data.tsv --value score --x-label "Score" --y-label "F(x)" --title "ECDF"

# Multi-group comparison
kuva ecdf data.tsv --value expression --color-by group --confidence-band

# Complementary CDF with log x-axis (read lengths)
kuva ecdf reads.tsv --value length --complementary --rug --log-x \
    --x-label "Read length (bp)" --y-label "Fraction ≥ length"

# Percentile markers + rug
kuva ecdf data.tsv --value score --percentile-lines 0.25,0.5,0.75 --markers --rug

# Smooth CDF
kuva ecdf data.tsv --value score --color-by group --smooth

CLI flags

Q-Q Plot

A Q-Q (quantile-quantile) plot compares the quantile structure of a sample against a theoretical distribution — or against another sample. It is a complete distributional diagnostic: every departure from the reference line carries information about skew, heavy tails, bimodality, or systematic bias.

Import path: kuva::plot::QQPlot

Two modes are available:

Normal Q-Q

Compare a sample against the standard normal. Points on the dashed reference line indicate normally distributed data. Deviations reveal:

• S-shaped curve — skew (right or left)
• Banana / fan shape — heavy or light tails
• Parallel shift — same distribution shape, different location

#![allow(unused)]
fn main() {
use kuva::plot::QQPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data: Vec<f64> = vec![/* your values */];

let plot = QQPlot::new()
    .with_data("Sample", data)
    .with_color("steelblue");

let plots = vec![Plot::QQ(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Normal Q-Q")
    .with_x_label("Theoretical Quantiles")
    .with_y_label("Sample Quantiles");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

When data is right-skewed (e.g. log-normal), the upper tail curves above the reference line:

Multi-group normal Q-Q

Overlay multiple groups on the same axes to compare their distributional shapes. The reference line is drawn independently for each group (each uses its own Q1–Q3 anchored robust line):

#![allow(unused)]
fn main() {
use kuva::plot::QQPlot;
use kuva::render::plots::Plot;
use kuva::render::layout::Layout;
use kuva::render::render::render_multiple;
use kuva::backend::svg::SvgBackend;
use kuva::render::palette::Palette;
let pal = Palette::category10();

let plot = QQPlot::new()
    .with_data_colored("Control", vec![/* ... */], pal[0].to_string())
    .with_data_colored("Treated",  vec![/* ... */], pal[1].to_string())
    .with_legend("");
}

Genomic Q-Q (GWAS)

.with_pvalues() switches to genomic mode. Input values must be raw p-values in (0, 1]. The plot shows −log₁₀(observed p) vs −log₁₀(expected p) under the null hypothesis. Points on the y = x diagonal indicate well-calibrated test statistics:

#![allow(unused)]
fn main() {
use kuva::plot::QQPlot;
use kuva::render::plots::Plot;
let plot = QQPlot::new()
    .with_pvalues("GWAS study", pvalues)
    .with_lambda();   // annotate genomic inflation factor λ
}

CI band and genomic inflation factor λ

.with_ci_band() draws a shaded 95 % pointwise confidence band around the y = x diagonal. Points falling outside the band indicate more deviation from the null than expected by chance.

.with_lambda() annotates λ, the genomic inflation factor:

λ = median(χ²₁ observed) / 0.4549

A value near 1.0 means test statistics are well-calibrated. λ > 1 indicates inflation — often caused by population stratification, cryptic relatedness, or systematic batch effects:

#![allow(unused)]
fn main() {
use kuva::plot::QQPlot;
use kuva::render::plots::Plot;
let plot = QQPlot::new()
    .with_pvalues("GWAS study", pvalues)
    .with_ci_band()
    .with_lambda();
}

Multi-study genomic Q-Q

Overlay multiple GWAS datasets to compare calibration between studies or cohorts:

#![allow(unused)]
fn main() {
use kuva::plot::QQPlot;
use kuva::render::plots::Plot;
use kuva::render::palette::Palette;
let pal = Palette::category10();

let plot = QQPlot::new()
    .with_pvalues_colored("Study A", pvals_a, pal[0].to_string())
    .with_pvalues_colored("Study B", pvals_b, pal[1].to_string())
    .with_ci_band()
    .with_legend("")
    .with_lambda();
}

Builder reference

CLI

# Normal Q-Q
kuva qq data.tsv --value score --title "Normal Q-Q"

# Multi-group normal Q-Q
kuva qq data.tsv --value score --color-by group

# Genomic Q-Q from GWAS p-values
kuva qq gwas.tsv --value pvalue --genomic \
    --title "GWAS Q-Q" \
    --x-label "Expected -log10(p)" --y-label "Observed -log10(p)"

# Genomic Q-Q with CI band and lambda annotation
kuva qq gwas.tsv --value pvalue --genomic --ci-band --lambda

# Multi-study comparison
kuva qq gwas.tsv --value pvalue --color-by study --genomic --ci-band --lambda

CLI flags

2D Histogram

A 2D histogram (density map) bins scatter points (x, y) into a rectangular grid and colors each cell by its count. The colorbar labeled "Count" is added to the right margin automatically. Use it to visualize the joint distribution of two continuous variables.

Import path: kuva::plot::Histogram2D, kuva::plot::histogram2d::ColorMap

Basic usage

Pass (x, y) scatter points along with explicit axis ranges and bin counts to .with_data(). Points outside the specified ranges are silently discarded.

#![allow(unused)]
fn main() {
use kuva::plot::Histogram2D;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

// (x, y) scatter points — e.g. from a 2D measurement
let data: Vec<(f64, f64)> = vec![];  // ...your data here

let hist = Histogram2D::new()
    .with_data(data, (0.0, 30.0), (0.0, 30.0), 30, 30);

let plots = vec![Plot::Histogram2d(hist)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("2D Histogram — Viridis")
    .with_x_label("X")
    .with_y_label("Y");

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

A single bivariate Gaussian cluster binned into a 30×30 grid. The Viridis colorbar on the right shows the count scale from zero (dark blue) to the maximum (yellow).

Correlation annotation

.with_correlation() computes the Pearson r coefficient from the raw scatter points and prints it in the top-right corner.

#![allow(unused)]
fn main() {
use kuva::plot::Histogram2D;
use kuva::render::plots::Plot;
let hist = Histogram2D::new()
    .with_data(data, (0.0, 20.0), (0.0, 20.0), 25, 25)
    .with_correlation();
}

The diagonal density ridge reflects a strong positive correlation (r ≈ 0.85). The coefficient is computed from all input points, including those clipped outside the plot range.

Bimodal data — Inferno colormap

ColorMap::Inferno maps low counts to near-black and high counts to bright yellow. It is effective for high-contrast visualization of structured or multi-modal data.

#![allow(unused)]
fn main() {
use kuva::plot::Histogram2D;
use kuva::plot::histogram2d::ColorMap;
use kuva::render::plots::Plot;

let hist = Histogram2D::new()
    .with_data(data, (0.0, 30.0), (0.0, 30.0), 30, 30)
    .with_color_map(ColorMap::Inferno);
}

Two Gaussian clusters in opposite corners of the grid, visible as bright islands against the dark background. Empty bins are not drawn, preserving the black background of Inferno.

Bin resolution

Bin count controls the trade-off between noise and detail.

ColorMap::Grayscale maps zero to white and the maximum to black — useful for printing or publication figures.

10×10 bins smooth the distribution and make the Gaussian shape immediately obvious, but lose fine-grained density structure.

ColorMap::Viridis (the default) uses a perceptually uniform blue → green → yellow scale, making density gradients easy to read at high resolution.

50×50 bins reveal the internal shape of the distribution, though individual cells become noisier at lower sample counts.

Range convention

The axis is calibrated directly to the physical x_range / y_range values you supply, so tick labels always show real data units regardless of bin count. Any (min, max) pair works.

Log color scale

When a small number of bins dominate the count (a dense core surrounded by sparse tails), the linear color scale washes out low-density structure. .with_log_count() compresses the dynamic range via ln(count + 1), keeping both the core and the halo visible. The colorbar label updates to "log(Count)" automatically.

#![allow(unused)]
fn main() {
use kuva::plot::Histogram2D;
use kuva::plot::histogram2d::ColorMap;
use kuva::render::plots::Plot;
let hist = Histogram2D::new()
    .with_data(data, (0.0, 30.0), (0.0, 30.0), 30, 30)
    .with_color_map(ColorMap::Inferno)
    .with_log_count();
}

Linear — the dense core saturates the colormap; the surrounding halo is invisible.

Log — the same data with with_log_count(). The halo structure is now visible alongside the core.

Colorbar tick format

By default (TickFormat::Auto) colorbar tick labels render as plain integers and switch to scientific notation automatically when counts reach 10 000 or more. You can override this with Layout::with_colorbar_tick_format().

#![allow(unused)]
fn main() {
use kuva::plot::Histogram2D;
use kuva::render::plots::Plot;
use kuva::render::layout::{Layout, TickFormat};

let plots = vec![Plot::Histogram2d(hist)];
let layout = Layout::auto_from_plots(&plots)
    .with_colorbar_tick_format(TickFormat::Sci);   // always scientific notation
}

Auto — on a 50 000-point dataset the max bin count exceeds 10 000, so Auto switches to scientific notation automatically.

Sci — forces scientific notation at all magnitudes.

Colormaps

API reference

Hexbin Plot

A hexbin plot bins scatter points (x, y) into a regular hexagonal grid and colors each cell by its point count — or by an aggregated third variable z. Hexagonal bins tile the plane without gaps and are equidistant from all six neighbors, giving a more visually uniform density estimate than rectangular bins. A colorbar labeled "Count" (or the chosen aggregation) is added to the right margin automatically.

Import path: kuva::plot::hexbin::HexbinPlot, kuva::plot::hexbin::ZReduce, kuva::plot::ColorMap

Basic usage

Pass (x, y) scatter points to .with_data(). The plot divides the pixel canvas into hexagonal bins, counts the points in each, and applies the Viridis colormap.

#![allow(unused)]
fn main() {
use kuva::plot::hexbin::HexbinPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let x: Vec<f64> = /* your data */ vec![];
let y: Vec<f64> = /* your data */ vec![];

let plot = HexbinPlot::new().with_data(x, y);

let plots = vec![Plot::Hexbin(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Hexbin Density")
    .with_x_label("X")
    .with_y_label("Y");

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

Three Gaussian clusters binned at the default resolution (20 bins across). The Viridis colorbar on the right maps bin counts from dark purple (sparse) to yellow (dense).

Bin resolution

.with_n_bins(n) sets the number of hex columns across the x-axis. More bins reveal finer density structure at the cost of noisier estimates in sparse regions.

#![allow(unused)]
fn main() {
use kuva::plot::hexbin::HexbinPlot;
use kuva::render::plots::Plot;
// Coarse — large hexes, smooth shape
let plot = HexbinPlot::new().with_data(x.clone(), y.clone()).with_n_bins(10);

// Fine — small hexes, more detail
let plot = HexbinPlot::new().with_data(x, y).with_n_bins(40);
}

10 bins — the cluster shapes are obvious but internal density structure is lost.

40 bins — peaks within each cluster become visible; individual bins in the periphery are noisier.

Log color scale

When a few bins dominate the count (dense core, sparse halo), the linear color scale saturates the colormap at the peak and hides structure elsewhere. .with_log_color(true) applies log₁₀(count + 1) before color mapping so both dense and sparse regions remain readable.

#![allow(unused)]
fn main() {
use kuva::plot::hexbin::HexbinPlot;
use kuva::render::plots::Plot;
let plot = HexbinPlot::new()
    .with_data(x, y)
    .with_log_color(true);
}

The colorbar tick marks show actual count values (1, 10, 100, …) while the color scale compresses high counts to reveal the low-density fringe.

Third variable — Z aggregation

.with_z(z, reduce) replaces count-based coloring with an aggregated third variable. Each bin collects the z values of the points it contains and applies the chosen ZReduce function. The colorbar label updates automatically.

#![allow(unused)]
fn main() {
use kuva::plot::hexbin::{HexbinPlot, ZReduce};
use kuva::render::plots::Plot;

// Color bins by the mean of a per-point measurement
let z: Vec<f64> = x.iter().zip(y.iter()).map(|(xi, yi)| xi + yi).collect();

let plot = HexbinPlot::new()
    .with_data(x, y)
    .with_z(z, ZReduce::Mean);
}

Bins colored by the mean of z = x + y. The gradient follows the diagonal, reflecting the additive structure of the z variable.

When z values are absent, all ZReduce variants fall back to point count.

Normalized density

.with_normalize(true) divides each bin's count by the total number of input points, expressing density as a fraction in [0, 1]. The colorbar label changes to "Density".

#![allow(unused)]
fn main() {
use kuva::plot::hexbin::HexbinPlot;
use kuva::render::plots::Plot;
let plot = HexbinPlot::new()
    .with_data(x, y)
    .with_normalize(true)
    .with_colorbar_label("Density");  // optional: keep the default or override
}

Normalized density makes plots with different sample sizes comparable on the same scale.

Min count filter

.with_min_count(n) suppresses bins that contain fewer than n points. This trims noise from the periphery of a distribution, leaving only regions with meaningful density.

#![allow(unused)]
fn main() {
use kuva::plot::hexbin::HexbinPlot;
use kuva::render::plots::Plot;
// Only render bins with at least 8 points
let plot = HexbinPlot::new()
    .with_data(x, y)
    .with_n_bins(10)
    .with_min_count(8);
}

min_count = 1 — all bins are shown; peripheral singletons are visible.

min_count = 8 — only the dense cluster cores remain.

Flat-top orientation

By default hexes are pointy-top (a vertex at the top). .with_flat_top(true) rotates to flat-top orientation (a flat edge at the top), which can align better with certain data layouts or visual preferences.

#![allow(unused)]
fn main() {
use kuva::plot::hexbin::HexbinPlot;
use kuva::render::plots::Plot;
let plot = HexbinPlot::new()
    .with_data(x, y)
    .with_flat_top(true);
}

Hex outline (stroke)

.with_stroke(color) draws a CSS-colored border around each hexagon. This distinguishes individual bins in dense regions and is useful for publication figures.

#![allow(unused)]
fn main() {
use kuva::plot::hexbin::HexbinPlot;
use kuva::render::plots::Plot;
let plot = HexbinPlot::new()
    .with_data(x, y)
    .with_stroke("#333333")
    .with_stroke_width(0.8);
}

A dark outline clearly separates adjacent bins at the cost of slightly more visual noise.

Color range clamping

.with_color_range(lo, hi) pins the colormap to a fixed value interval, ignoring bins outside the range. Values below lo receive the lowest colormap color; values above hi receive the highest. Use this to compare multiple plots on the same scale or to highlight a specific density range.

#![allow(unused)]
fn main() {
use kuva::plot::hexbin::HexbinPlot;
use kuva::render::plots::Plot;
let plot = HexbinPlot::new()
    .with_data(x, y)
    .with_color_range(2.0, 8.0);
}

Axis range clipping

.with_x_range(lo, hi) and .with_y_range(lo, hi) restrict binning to a sub-region of the data and fix the corresponding axis limits. Points outside the specified window are silently discarded.

#![allow(unused)]
fn main() {
use kuva::plot::hexbin::HexbinPlot;
use kuva::render::plots::Plot;
let plot = HexbinPlot::new()
    .with_data(x, y)
    .with_x_range(-0.5, 3.0)
    .with_y_range(-2.0, 4.0);
}

Colormaps

.with_color_map(map) selects the colormap. The same ColorMap variants used by Heatmap and Histogram2D apply.

#![allow(unused)]
fn main() {
use kuva::plot::{hexbin::HexbinPlot, ColorMap};
use kuva::render::plots::Plot;
let plot = HexbinPlot::new()
    .with_data(x, y)
    .with_color_map(ColorMap::Inferno);
}

Hiding the colorbar

.with_colorbar(false) suppresses the colorbar and reclaims the right margin.

#![allow(unused)]
fn main() {
use kuva::plot::hexbin::HexbinPlot;
use kuva::render::plots::Plot;
let plot = HexbinPlot::new()
    .with_data(x, y)
    .with_colorbar(false);
}

API reference

Treemap Plot

A treemap tiles a rectangle with nested rectangles proportional to node values. Squarified layout (default) minimises worst-case aspect ratios. Supports arbitrary depth hierarchies, second-dimension coloring, and SVG hover tooltips.

Import path: kuva::plot::treemap::TreemapPlot, kuva::plot::treemap::TreemapNode, kuva::plot::treemap::TreemapColorMode, kuva::plot::treemap::TreemapLayout, kuva::plot::ColorMap

Basic usage

Pass leaf nodes to .with_node(). The plot tiles the canvas area proportionally to each node's value.

#![allow(unused)]
fn main() {
use kuva::plot::treemap::{TreemapPlot, TreemapNode};
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = TreemapPlot::new()
    .with_node(TreemapNode::leaf("Rust",   40.0))
    .with_node(TreemapNode::leaf("Python", 35.0))
    .with_node(TreemapNode::leaf("Go",     25.0));

let plots = vec![Plot::Treemap(plot)];
let layout = Layout::auto_from_plots(&plots).with_title("Language usage");
let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
std::fs::write("treemap.svg", svg).unwrap();
}

Hierarchical data

Use TreemapNode::new(label, children) for inner nodes. Values auto-sum from children when value = 0.0.

#![allow(unused)]
fn main() {
use kuva::plot::treemap::{TreemapPlot, TreemapNode};
use kuva::render::plots::Plot;
let plot = TreemapPlot::new()
    .with_node(TreemapNode::new("Languages", vec![
        TreemapNode::leaf("Rust",   40.0),
        TreemapNode::leaf("Python", 35.0),
        TreemapNode::leaf("Go",     25.0),
    ]))
    .with_node(TreemapNode::new("Databases", vec![
        TreemapNode::leaf("Postgres", 60.0),
        TreemapNode::leaf("SQLite",   30.0),
    ]));
}

Parent cells show a group label at top-left. Children are tiled inside with padding and a label-reserve row.

Forest (multiple roots)

Pass multiple .with_node() calls — each root gets a distinct category10 color and its descendants inherit it.

#![allow(unused)]
fn main() {
use kuva::plot::treemap::{TreemapPlot, TreemapNode};
use kuva::render::plots::Plot;
let plot = TreemapPlot::new()
    .with_node(TreemapNode::new("Alpha", vec![
        TreemapNode::leaf("a1", 10.0),
        TreemapNode::leaf("a2", 20.0),
    ]))
    .with_node(TreemapNode::new("Beta", vec![
        TreemapNode::leaf("b1", 30.0),
        TreemapNode::leaf("b2", 15.0),
    ]))
    .with_node(TreemapNode::leaf("Gamma", 25.0));
}

Color modes

ByParent (default)

Each root group inherits a distinct category10 color. All descendants use the same hue.

ByValue

Color leaves by their value (or a parallel color_values vector) using a colormap.

#![allow(unused)]
fn main() {
use kuva::plot::treemap::{TreemapPlot, TreemapNode, TreemapColorMode, ColorMap};
use kuva::render::plots::Plot;

let plot = TreemapPlot::new()
    .with_node(TreemapNode::leaf("A", 10.0))
    .with_node(TreemapNode::leaf("B", 50.0))
    .with_node(TreemapNode::leaf("C", 25.0))
    .with_color_mode(TreemapColorMode::ByValue(ColorMap::Viridis));
// show_colorbar is automatically enabled when ByValue is set
}

Explicit

Use the color field on each node (CSS string). Call .with_color_mode(TreemapColorMode::Explicit).

#![allow(unused)]
fn main() {
use kuva::plot::treemap::{TreemapPlot, TreemapNode, TreemapColorMode};
use kuva::render::plots::Plot;

let plot = TreemapPlot::new()
    .with_node(TreemapNode::leaf_colored("Red",  30.0, "#e74c3c"))
    .with_node(TreemapNode::leaf_colored("Blue", 20.0, "#3498db"))
    .with_color_mode(TreemapColorMode::Explicit);
}

Second-dimension coloring (GO enrichment pattern)

Use color_values to color leaves by a variable independent of size. A common bioinformatics pattern: size = gene count, color = p-value.

#![allow(unused)]
fn main() {
use kuva::plot::treemap::{TreemapPlot, TreemapNode, TreemapColorMode, ColorMap};
use kuva::render::plots::Plot;

let gene_counts = vec![120_f64, 80.0, 55.0, 40.0];
let p_values    = vec![0.001, 0.023, 0.045, 0.0001];

let plot = TreemapPlot::new()
    .with_node(TreemapNode::leaf("GO:0008150 — biological process", gene_counts[0]))
    .with_node(TreemapNode::leaf("GO:0005575 — cellular component",  gene_counts[1]))
    .with_node(TreemapNode::leaf("GO:0003674 — molecular function",  gene_counts[2]))
    .with_node(TreemapNode::leaf("GO:0006950 — response to stress",  gene_counts[3]))
    .with_color_values(p_values)
    .with_color_mode(TreemapColorMode::ByValue(ColorMap::Viridis))
    .with_colorbar_label("p-value");
}

Or use the convenience builder:

#![allow(unused)]
fn main() {
use kuva::plot::treemap::TreemapPlot;
use kuva::render::plots::Plot;

let plot = TreemapPlot::new()
    .with_go_terms(vec![
        ("GO:0008150", "biological process", 120, 0.001),
        ("GO:0005575", "cellular component",  80, 0.023),
        ("GO:0003674", "molecular function",  55, 0.045),
    ])
    .with_colorbar_label("p-value");
}

Layout algorithms

.with_layout(algo) selects the tiling strategy.

#![allow(unused)]
fn main() {
use kuva::plot::treemap::{TreemapPlot, TreemapNode, TreemapLayout};
use kuva::render::plots::Plot;

// Squarify (default): minimises worst aspect ratio
let plot = TreemapPlot::new()
    .with_layout(TreemapLayout::Squarify);

// SliceDice: alternating H/V cuts per level — fast, may produce slivers
let plot = TreemapPlot::new()
    .with_layout(TreemapLayout::SliceDice);

// Binary: balanced binary splits — good for uniform distributions
let plot = TreemapPlot::new()
    .with_layout(TreemapLayout::Binary);
}

Padding and borders

.with_padding(px) sets the gap between a parent's border and its children. Padding halves at each depth level.

#![allow(unused)]
fn main() {
use kuva::plot::treemap::{TreemapPlot, TreemapNode};
use kuva::render::plots::Plot;
let plot = TreemapPlot::new()
    .with_padding(6.0)
    .with_border_width(0.5)
    .with_root_border_width(2.5);
}

Depth limiting

.with_max_depth(n) renders at most n levels deep (root = depth 0). Nodes at the limit are treated as leaves even if they have children.

#![allow(unused)]
fn main() {
use kuva::plot::treemap::{TreemapPlot, TreemapNode};
use kuva::render::plots::Plot;
let plot = TreemapPlot::new()
    .with_max_depth(2);  // root + 2 child levels
}

Tooltips

By default each cell emits an SVG <title> tooltip showing the breadcrumb path and value on hover. Disable with .with_tooltips(false).

#![allow(unused)]
fn main() {
use kuva::plot::treemap::{TreemapPlot, TreemapNode};
use kuva::render::plots::Plot;
// Tooltips off — smaller SVG
let plot = TreemapPlot::new()
    .with_tooltips(false);
}

API reference

TreemapNode constructors

See also: Shared flags — output, appearance, axes, log scale.

Sunburst Chart

A sunburst chart displays hierarchical data as concentric rings. Each ring represents one depth level; arc widths within a ring are proportional to node values. Uses the same TreemapNode data model as the TreemapPlot.

Import path: kuva::plot::sunburst::SunburstPlot, kuva::plot::sunburst::SunburstColorMode, kuva::plot::treemap::TreemapNode, kuva::plot::ColorMap

Basic usage

#![allow(unused)]
fn main() {
use kuva::plot::sunburst::SunburstPlot;
use kuva::plot::treemap::TreemapNode;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = SunburstPlot::new()
    .with_node(TreemapNode::new("Root", vec![
        TreemapNode::leaf("A", 30.0),
        TreemapNode::leaf("B", 45.0),
        TreemapNode::leaf("C", 25.0),
    ]));

let plots = vec![Plot::Sunburst(plot)];
let layout = Layout::auto_from_plots(&plots).with_title("Sunburst");
let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
std::fs::write("sunburst.svg", svg).unwrap();
}

Hierarchical data (multiple levels)

Use TreemapNode::new(label, children) for inner nodes. Values auto-sum from children when value = 0.0.

#![allow(unused)]
fn main() {
use kuva::plot::sunburst::SunburstPlot;
use kuva::plot::treemap::TreemapNode;
use kuva::render::{plots::Plot, layout::Layout, render::render_multiple};
use kuva::backend::svg::SvgBackend;
let plot = SunburstPlot::new()
    .with_node(TreemapNode::new("Animals", vec![
        TreemapNode::new("Mammals", vec![
            TreemapNode::leaf("Dog",  40.0),
            TreemapNode::leaf("Cat",  35.0),
            TreemapNode::leaf("Bear", 25.0),
        ]),
        TreemapNode::new("Birds", vec![
            TreemapNode::leaf("Eagle",  60.0),
            TreemapNode::leaf("Parrot", 40.0),
        ]),
    ]));
}

Multiple roots (forest)

Multiple root nodes share the innermost ring, each receiving a distinct category color.

#![allow(unused)]
fn main() {
use kuva::plot::sunburst::SunburstPlot;
use kuva::plot::treemap::TreemapNode;
let plot = SunburstPlot::new()
    .with_children("Frontend", vec![
        TreemapNode::leaf("React", 50.0),
        TreemapNode::leaf("Vue",   30.0),
        TreemapNode::leaf("Svelte", 20.0),
    ])
    .with_children("Backend", vec![
        TreemapNode::leaf("Rust",   40.0),
        TreemapNode::leaf("Go",     35.0),
        TreemapNode::leaf("Python", 25.0),
    ]);
}

Donut style

Set .with_inner_radius(frac) where frac is the fractional inner hole size (0.0 = solid disc, 0.3 = 30% hole).

#![allow(unused)]
fn main() {
use kuva::plot::sunburst::SunburstPlot;
use kuva::plot::treemap::TreemapNode;
let plot = SunburstPlot::new()
    .with_node(TreemapNode::new("Root", vec![
        TreemapNode::leaf("A", 40.0),
        TreemapNode::leaf("B", 35.0),
        TreemapNode::leaf("C", 25.0),
    ]))
    .with_inner_radius(0.35);   // 35% inner hole
}

Color modes

By parent (default)

Each root node gets a distinct category10 color; descendants inherit it.

#![allow(unused)]
fn main() {
use kuva::plot::sunburst::{SunburstPlot, SunburstColorMode};
use kuva::plot::treemap::TreemapNode;
let plot = SunburstPlot::new()
    .with_children("Group A", vec![
        TreemapNode::leaf("X", 40.0),
        TreemapNode::leaf("Y", 60.0),
    ])
    .with_color_mode(SunburstColorMode::ByParent);
}

By value

Color arcs by a continuous colormap. Parent arcs appear as neutral #e0e0e0.

#![allow(unused)]
fn main() {
use kuva::plot::sunburst::{SunburstPlot, SunburstColorMode};
use kuva::plot::treemap::TreemapNode;
use kuva::plot::ColorMap;
let plot = SunburstPlot::new()
    .with_node(TreemapNode::new("Root", vec![
        TreemapNode::leaf("A", 30.0),
        TreemapNode::leaf("B", 45.0),
        TreemapNode::leaf("C", 25.0),
    ]))
    .with_color_mode(SunburstColorMode::ByValue(ColorMap::Viridis))
    .with_colorbar(true)
    .with_colorbar_label("Score");
}

Explicit

Use TreemapNode::leaf_colored(label, value, css_color) for per-node CSS colors.

#![allow(unused)]
fn main() {
use kuva::plot::sunburst::{SunburstPlot, SunburstColorMode};
use kuva::plot::treemap::TreemapNode;
let plot = SunburstPlot::new()
    .with_node(TreemapNode::new("Root", vec![
        TreemapNode::leaf_colored("Red slice",  40.0, "#e74c3c"),
        TreemapNode::leaf_colored("Blue slice", 35.0, "#3498db"),
        TreemapNode::leaf_colored("Green slice",25.0, "#2ecc71"),
    ]))
    .with_color_mode(SunburstColorMode::Explicit);
}

Second-dimension coloring (color_values)

For GO enrichment-style charts: size = gene count, color = p-value (independent of arc size).

#![allow(unused)]
fn main() {
use kuva::plot::sunburst::{SunburstPlot, SunburstColorMode};
use kuva::plot::treemap::TreemapNode;
use kuva::plot::ColorMap;
let terms = vec![
    ("GO:0006955 immune response",      120_usize, 1e-10_f64),
    ("GO:0007049 cell cycle",            85,        2e-7),
    ("GO:0016310 phosphorylation",       60,        5e-5),
];

let mut plot = SunburstPlot::new();
let mut pvalues = Vec::new();
for (label, count, pval) in &terms {
    plot = plot.with_node(TreemapNode::leaf(label.to_string(), *count as f64));
    pvalues.push(-pval.log10());   // –log₁₀(p) so high = significant
}
let plot = plot
    .with_color_values(pvalues)
    .with_color_mode(SunburstColorMode::ByValue(ColorMap::Viridis))
    .with_colorbar(true)
    .with_colorbar_label("−log₁₀(p)");
}

Start angle and depth limit

#![allow(unused)]
fn main() {
use kuva::plot::sunburst::SunburstPlot;
use kuva::plot::treemap::TreemapNode;
let plot = SunburstPlot::new()
    .with_node(TreemapNode::new("Root", vec![
        TreemapNode::leaf("A", 30.0),
        TreemapNode::leaf("B", 70.0),
    ]))
    .with_start_angle(90.0)   // start from east instead of north
    .with_max_depth(2)        // limit to 2 rings
    .with_ring_gap(2.0);      // wider gap between rings
}

Builder reference

Bump Chart

A bump chart shows how the rank of each series changes across discrete time points or conditions. Lines connect consecutive ranks; the best rank (1) appears at the top.

Basic usage (pre-ranked)

#![allow(unused)]
fn main() {
use kuva::plot::bump::BumpPlot;
use kuva::render::{plots::Plot, layout::Layout, render::render_multiple};
use kuva::backend::svg::SvgBackend;

let plot = BumpPlot::new()
    .with_series("Alpha", vec![1, 3, 2, 1])
    .with_series("Beta",  vec![2, 1, 1, 3])
    .with_series("Gamma", vec![3, 2, 3, 2])
    .with_x_labels(["2021", "2022", "2023", "2024"]);

let plots = vec![Plot::Bump(plot)];
let layout = Layout::auto_from_plots(&plots).with_title("Rank over time");
let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
std::fs::write("bump.svg", svg).unwrap();
}

Auto-ranking from raw values

Instead of supplying pre-computed ranks you can provide raw values; kuva ranks them per time point automatically.

#![allow(unused)]
fn main() {
use kuva::plot::bump::BumpPlot;

let plot = BumpPlot::new()
    .with_raw_series("A", vec![95.0, 80.0, 88.0])
    .with_raw_series("B", vec![80.0, 95.0, 72.0])
    .with_raw_series("C", vec![70.0, 85.0, 95.0])
    .with_x_labels(["Q1", "Q2", "Q3"]);
}

By default, higher value = rank 1 (better). Pass .with_rank_ascending(true) to flip this so lower value = rank 1.

Builder reference

Highlight mode

Highlighting one series draws it with a thicker stroke and bolder endpoint labels; all others are rendered at reduced opacity and with muted grey labels.

#![allow(unused)]
fn main() {
let plot = BumpPlot::new()
    .with_series("Alpha", vec![1, 3, 2, 1])
    .with_series("Beta",  vec![2, 1, 1, 3])
    .with_series("Gamma", vec![3, 2, 3, 2])
    .with_highlight("Alpha");
}

Missing time points

Supply None entries via .with_ranked_series or .with_raw_series_opt to produce line breaks at absent time points:

#![allow(unused)]
fn main() {
let plot = BumpPlot::new()
    .with_ranked_series("Alpha", vec![Some(1.0), None, Some(2.0), Some(1.0)])
    .with_x_labels(["A", "B", "C", "D"]);
}

Tie-breaking modes

Series Plot

A series plot displays an ordered sequence of y-values against their sequential index on the x-axis. It is the simplest way to visualise a time series, signal trace, or any 1D ordered measurement. Three rendering styles are available: line, point, or both.

Import path: kuva::plot::SeriesPlot

Basic usage

Pass an iterable of numeric values to .with_data(). The x-axis is assigned automatically as 0, 1, 2, ….

#![allow(unused)]
fn main() {
use kuva::plot::SeriesPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data: Vec<f64> = (0..80)
    .map(|i| (i as f64 * std::f64::consts::TAU / 80.0).sin())
    .collect();

let series = SeriesPlot::new()
    .with_data(data)
    .with_color("steelblue")
    .with_line_style();

let plots = vec![Plot::Series(series)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Series Plot — Line Style")
    .with_x_label("Sample")
    .with_y_label("Amplitude");

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

Display styles

Three styles control how values are rendered. Call the corresponding method instead of setting a field directly.

Multiple series

Place multiple SeriesPlot instances in the same plots vector to overlay them on one canvas. All series share the same axes; they align automatically when they have the same number of values.

#![allow(unused)]
fn main() {
use kuva::plot::SeriesPlot;
use kuva::render::plots::Plot;
let s1 = SeriesPlot::new()
    .with_data(sin_data)
    .with_color("steelblue")
    .with_line_style()
    .with_legend("sin(t)");

let s2 = SeriesPlot::new()
    .with_data(cos_data)
    .with_color("firebrick")
    .with_line_style()
    .with_legend("cos(t)");

let s3 = SeriesPlot::new()
    .with_data(damped)
    .with_color("seagreen")
    .with_line_style()
    .with_stroke_width(1.5)
    .with_legend("e^(−t/2)·sin(t)");

let plots = vec![Plot::Series(s1), Plot::Series(s2), Plot::Series(s3)];
}

Each series has its own color and legend entry. The legend is drawn automatically when any series has a legend_label.

Custom stroke and point size

.with_stroke_width(f) sets the line thickness; .with_point_radius(f) sets the circle size. These only affect the relevant style — stroke_width applies to Line and Both; point_radius applies to Point and Both.

#![allow(unused)]
fn main() {
use kuva::plot::SeriesPlot;
use kuva::render::plots::Plot;
let series = SeriesPlot::new()
    .with_data(data)
    .with_color("darkorchid")
    .with_line_point_style()
    .with_stroke_width(1.5)
    .with_point_radius(4.0)
    .with_legend("signal");
}

API reference

Band Plot

A band plot fills the region between two y-curves over a shared x-axis. It is used to display confidence intervals, prediction bands, IQR envelopes, or any shaded range around a central estimate.

Import path: kuva::plot::BandPlot

Standalone band

BandPlot::new(x, y_lower, y_upper) creates a filled area independently. Pair it with a LinePlot or ScatterPlot by placing both in the same plots vector — the band is drawn behind the line.

#![allow(unused)]
fn main() {
use kuva::plot::{BandPlot, LinePlot};
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let x: Vec<f64> = (0..60).map(|i| i as f64 * 0.2).collect();
let y: Vec<f64> = x.iter().map(|&v| v.sin()).collect();
let lower: Vec<f64> = y.iter().map(|&v| v - 0.35).collect();
let upper: Vec<f64> = y.iter().map(|&v| v + 0.35).collect();

let band = BandPlot::new(x.clone(), lower, upper)
    .with_color("steelblue")
    .with_opacity(0.25);

let line = LinePlot::new()
    .with_data(x.iter().copied().zip(y.iter().copied()))
    .with_color("steelblue");

// Band must come before the line so it renders behind it
let plots = vec![Plot::Band(band), Plot::Line(line)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Band Plot — Standalone")
    .with_x_label("x")
    .with_y_label("y");

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

The band fills between y_lower and y_upper. Placing Plot::Band before Plot::Line in the vector ensures it is drawn first and appears behind the line.

Band attached to a line

LinePlot::with_band(y_lower, y_upper) is a one-call shorthand. It creates the BandPlot internally, using the line's x positions and inheriting its color automatically.

#![allow(unused)]
fn main() {
use kuva::plot::LinePlot;
use kuva::render::plots::Plot;

let line = LinePlot::new()
    .with_data(x.iter().copied().zip(y.iter().copied()))
    .with_color("firebrick")
    .with_band(lower, upper);  // band color = "firebrick", opacity = 0.2

let plots = vec![Plot::Line(line)];
}

The band is always rendered behind the line. No ordering in the plots vector is needed.

Band attached to a scatter plot

ScatterPlot::with_band(y_lower, y_upper) works identically: the band inherits the scatter color and renders behind the points.

#![allow(unused)]
fn main() {
use kuva::plot::ScatterPlot;
use kuva::render::plots::Plot;

let scatter = ScatterPlot::new()
    .with_data(x.iter().copied().zip(y.iter().copied()))
    .with_color("seagreen")
    .with_band(lower, upper);

let plots = vec![Plot::Scatter(scatter)];
}

Multiple series with bands

Each LinePlot carries its own independent band. Combine all series in one plots vector — they share the same axes automatically.

#![allow(unused)]
fn main() {
use kuva::plot::LinePlot;
use kuva::render::plots::Plot;

let line1 = LinePlot::new()
    .with_data(x.iter().copied().zip(y1.iter().copied()))
    .with_color("steelblue")
    .with_band(y1.iter().map(|&v| v - 0.25), y1.iter().map(|&v| v + 0.25))
    .with_legend("sin(x)");

let line2 = LinePlot::new()
    .with_data(x.iter().copied().zip(y2.iter().copied()))
    .with_color("darkorange")
    .with_band(y2.iter().map(|&v| v - 0.25), y2.iter().map(|&v| v + 0.25))
    .with_legend("0.8 · cos(0.5x)");

let plots = vec![Plot::Line(line1), Plot::Line(line2)];
}

Opacity

.with_opacity(f) sets the fill transparency. The default 0.2 is deliberately light so that overlapping bands and the underlying line remain readable.

API reference

Brick Plot

A brick plot displays sequences as rows of colored rectangles — one brick per character. It is designed for bioinformatics workflows involving DNA/RNA sequence visualization and tandem-repeat structure analysis. Each character maps to a color defined by a template; rows are labeled on the y-axis.

Import paths: kuva::plot::BrickPlot, kuva::plot::brick::BrickTemplate

DNA sequences

BrickTemplate::dna() provides a standard A / C / G / T color scheme. Pass the .template field to BrickPlot::with_template(). Use with_x_offset(n) to skip a common flanking region so the region of interest starts at x = 0.

#![allow(unused)]
fn main() {
use std::collections::HashMap;
use kuva::plot::BrickPlot;
use kuva::plot::brick::BrickTemplate;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let tmpl = BrickTemplate::new().dna();

let plot = BrickPlot::new()
    .with_sequences(vec![
        "CGGCGATCAGGCCGCACTCATCATCATCATCATCATCAT",
        "CGGCGATCAGGCCGCACTCATCATCATCATCATCATCATCAT",
    ])
    .with_names(vec!["read_1", "read_2"])
    .with_template(tmpl.template)
    .with_x_offset(18.0);  // skip 18-base common prefix

let plots = vec![Plot::Brick(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("DNA Repeat Region");

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

The 18-character flanking prefix is hidden by with_x_offset(18.0). All rows start at the same x = 0, aligning the CAT repeat region across reads.

Per-row offsets

When reads begin at different positions, with_x_offsets accepts one offset per row. Pass None for any row that should fall back to the global x_offset.

#![allow(unused)]
fn main() {
use kuva::plot::BrickPlot;
use kuva::plot::brick::BrickTemplate;
use kuva::render::plots::Plot;
let plot = BrickPlot::new()
    .with_sequences(sequences)
    .with_names(names)
    .with_template(BrickTemplate::new().dna().template)
    .with_x_offset(12.0)                       // global fallback
    .with_x_offsets(vec![
        Some(18.0_f64),  // read 1: skip 18
        Some(10.0),      // read 2: skip 10
        Some(16.0),      // read 3: skip 16
        Some(5.0),       // read 4: skip 5
        None,            // read 5: use global (12)
    ]);
}

Each row is shifted independently, aligning the repeat boundary across reads with different flanking lengths.

Custom template with value overlay

with_template accepts any HashMap<char, String>. Here a protein secondary-structure alphabet (H, E, C, T) gets custom colors. with_values() prints the character label inside each brick.

#![allow(unused)]
fn main() {
use std::collections::HashMap;
use kuva::plot::BrickPlot;
use kuva::render::plots::Plot;

let mut tmpl: HashMap<char, String> = HashMap::new();
tmpl.insert('H', "steelblue".into());   // α-helix
tmpl.insert('E', "firebrick".into());   // β-strand
tmpl.insert('C', "#aaaaaa".into());     // coil
tmpl.insert('T', "seagreen".into());    // turn

let plot = BrickPlot::new()
    .with_sequences(vec!["CCCHHHHHHHHHHCCCCEEEEEECCC"])
    .with_names(vec!["prot_1"])
    .with_template(tmpl)
    .with_values();  // show letter labels inside bricks
}

Any single-character alphabet can be used — amino acids, repeat unit categories, chromatin states, etc.

Strigar mode (tandem-repeat motifs)

with_strigars switches to strigar mode for structured tandem-repeat data produced by BLADERUNNER. Each read is described by two strings:

• motif string — maps local letters to k-mers: "CAT:A,C:B,T:C"
• strigar string — run-length encoding of those letters: "10A1B4A1C1A"

with_strigars normalises k-mers across all reads by canonical rotation, assigns global letters (A, B, C, …) by frequency, auto-generates colors, and renders variable-width bricks proportional to each motif's nucleotide length.

#![allow(unused)]
fn main() {
use kuva::plot::BrickPlot;
use kuva::render::plots::Plot;
let strigars: Vec<(String, String)> = vec![
    ("CAT:A,C:B,T:C".to_string(),   "10A1B4A1C1A".to_string()),
    ("CAT:A,T:B".to_string(),        "14A1B1A".to_string()),
    ("CAT:A,C:B,GGT:C".to_string(), "10A1B8A1C5A".to_string()),
    // ...
];

let plot = BrickPlot::new()
    .with_names(names)
    .with_strigars(strigars);  // sequences not needed — derived from strigars
}

Bricks are proportional to motif length (CAT = 3 bp wide; single-nucleotide interruptions are narrower). The dominant repeat unit (CAT) is assigned letter A and the first color; rarer motifs receive subsequent letters and colors.

Bladerunner stitched format

Bladerunner's stitched output joins multiple STR candidates with | separators. Each |-delimited section is its own candidate with its own local letter assignments; with_strigars handles this automatically.

Inter-candidate gaps

Gaps between candidates appear as N@ in the strigar (where N is the gap width in nucleotides) and render as light grey bricks:

#![allow(unused)]
fn main() {
use kuva::plot::BrickPlot;
use kuva::render::plots::Plot;
// Three stitched candidates; two large gaps between them.
// ACCCTA, TAACCC, CCCTAA are all rotations of the same unit —
// with_strigars assigns them the same global letter and colour.
let strigars: Vec<(String, String)> = vec![
    (
        "ACCCTA:A | ACCCTA:A | TAACCC:A,T:B | CCCTAA:A,ACCTAACCCTTAA:B".to_string(),
        "2A | 36@ | 2A | 213@ | 2A1B3A | 31@ | 2A1B2A".to_string(),
    ),
];

let plot = BrickPlot::new()
    .with_names(vec!["read_1"])
    .with_strigars(strigars);
}

Aligning reads by genomic position

Use with_start_positions to pass the reference coordinate where each read begins. Reads are shifted on the shared x-axis so repeat regions line up visually. Combine with with_x_origin to anchor a biologically meaningful position (e.g. the repeat start) to x = 0.

#![allow(unused)]
fn main() {
use kuva::plot::BrickPlot;
use kuva::render::plots::Plot;
// read_1: A-repeat (16 nt) + small gap GAA (3 nt) + AGA-repeat.
//         AGA region starts at reference position 19.
// read_2: AGA-repeat only, starting at reference position 19.
//
// with_start_positions aligns both reads on the shared reference axis.
// with_x_origin(19) places x=0 at the repeat start; the pre-repeat
// flanking region of read_1 appears at negative x values.
let strigars: Vec<(String, String)> = vec![
    ("A:A | @:GAA | AGA:B".to_string(), "16A | 1@ | 9B".to_string()),
    ("AGA:A".to_string(),               "12A".to_string()),
];

let plot = BrickPlot::new()
    .with_names(vec!["read_1", "read_2"])
    .with_strigars(strigars)
    .with_start_positions(vec![0.0_f64, 19.0])  // genomic start coord per read
    .with_x_origin(19.0);                        // x=0 at the repeat start
}

with_start_positions is equivalent to with_x_offsets with negated values but expresses intent clearly: pass the actual reference start coordinate for each read and kuva handles the shift. with_x_origin is a separate, independent axis shift applied on top — it does not interact with per-row offsets and can be used with or without with_start_positions.

Flanked strigars

with_flanked_strigars is a convenience wrapper for workflows where each read carries DNA flanking sequence on both sides of the STR region. Pass an iterator of (left_flank, motif_string, strigar_string, right_flank) tuples. Flanks are rendered with standard bioinformatics DNA colors (A=green, C=blue, G=orange, T=red) immediately adjacent to the STR bricks.

#![allow(unused)]
fn main() {
use kuva::plot::BrickPlot;
use kuva::render::plots::Plot;
let flanked = vec![
    // (left_flank, motifs, strigar, right_flank)
    ("ACGTACGT", "CAG:A,CAA:B", "6A1B8A", "TGCATGCA"),
    ("ACGTACGT", "CAG:A",       "16A",    "TGCATGCA"),
];

let plot = BrickPlot::new()
    .with_names(vec!["consensus", "read_1"])
    .with_flanked_strigars(flanked);
}

The motif and strigar strings are processed identically to with_strigars. The flank strings are treated as raw DNA sequences — each character becomes one brick with the standard base color.

Right-anchoring

By default all rows are left-aligned (STR start at x = 0 for all reads after offset adjustment). with_anchor(BrickAnchor::Right) instead aligns the trailing edges of all rows, which is useful when reads end at the same reference position but differ in length.

#![allow(unused)]
fn main() {
use kuva::plot::brick::BrickAnchor;
use kuva::plot::BrickPlot;
use kuva::render::plots::Plot;
let plot = BrickPlot::new()
    .with_names(names)
    .with_strigars(strigars)
    .with_anchor(BrickAnchor::Right);
}

BrickAnchor::Left is the default. BrickAnchor::Right shifts shorter rows rightward so all trailing edges line up on the same vertical.

Consensus-anchored rotation

When multiple reads cover the same STR locus, different reads may describe the same repeat unit using different rotations of the same k-mer (e.g. CAG, AGC, GCA). By default the rotation chosen for the legend is the most frequent one across all reads. with_consensus_row(i) locks the rotation to whatever row i uses, so the legend always reflects the reference or assembly read:

#![allow(unused)]
fn main() {
use kuva::plot::BrickPlot;
use kuva::render::plots::Plot;
let strigars = vec![
    ("CAG:A".to_string(), "12A".to_string()),  // consensus — uses CAG
    ("AGC:A".to_string(), "10A".to_string()),  // same unit, different rotation
];

let plot = BrickPlot::new()
    .with_names(vec!["consensus", "read_1"])
    .with_consensus_row(0)          // lock rotation to row 0's k-mers
    .with_strigars(strigars);       // must be called after with_consensus_row
}

with_consensus_row must be set before with_strigars (or with_flanked_strigars), as rotation resolution happens during strigar parsing.

Primary motif marker

with_mark_primary() appends * to the legend label of global letter A (the dominant motif by brick count). This is a visual cue that A is the canonical repeat unit when the plot is shown alongside other data:

#![allow(unused)]
fn main() {
use kuva::plot::BrickPlot;
let plot = BrickPlot::new()
    .with_names(names)
    .with_mark_primary()
    .with_strigars(strigars);
// Legend entry for A reads "CAG*" instead of "CAG"
}

Per-block notation labels

with_notations renders (kmer)count labels above the bricks for each consecutive run of the same motif. Pass one Option<String> per row: Some(_) enables labels for that row, None disables them. The string content is ignored — labels are always auto-generated from the run-length structure of the expanded strigar.

#![allow(unused)]
fn main() {
use kuva::plot::BrickPlot;
use kuva::render::plots::Plot;
let plot = BrickPlot::new()
    .with_names(vec!["consensus", "read_1", "read_2"])
    .with_consensus_row(0)
    .with_flanked_strigars(flanked)
    .with_notations(vec![
        Some("".to_string()),  // enable labels for consensus row
        None,                  // no labels for read_1
        None,                  // no labels for read_2
    ]);
}

For a consensus row with strigar 6A1B2A1C10A and motifs CAG:A, CAA:B, CCG:C, this renders five separate labels above the corresponding brick runs: (CAG)6, (CAA)1, (CAG)2, (CCG)1, (CAG)10. Gap bricks (@) are skipped.

When labels from adjacent runs overlap in pixel space they are staggered vertically across up to four tiers. The plot canvas automatically gains extra top-margin headroom when any row has notations enabled.

Row ordering

Row 0 is always rendered at the top of the plot. The first entry in with_names appears at the top of the y-axis. This matches the natural reading order when row 0 is a reference/consensus sequence.

Bladerunner full-pipeline example

Combining all of the above for a typical bladerunner workflow:

#![allow(unused)]
fn main() {
use kuva::plot::BrickPlot;
use kuva::plot::brick::BrickAnchor;
use kuva::render::plots::Plot;
use kuva::render::layout::Layout;
use kuva::render::render::render_multiple;
use kuva::backend::svg::SvgBackend;

let flanked = vec![
    // consensus row — row 0, shown at the top with notation labels
    ("ACGTACGT", "CAG:A,CAA:B,CCG:C", "6A1B2A1C10A", "TGCATGCA"),
    // supporting reads — no labels
    ("ACGTACGT", "CAG:A,CCG:B",       "8A1B10A",     "TGCATGCA"),
    ("ACGTACGT", "CAG:A",             "20A",          "TGCA"),
];

let plot = BrickPlot::new()
    .with_names(vec!["consensus", "read_1", "read_2"])
    .with_consensus_row(0)
    .with_mark_primary()
    .with_flanked_strigars(flanked)
    .with_notations(vec![Some("".to_string()), None, None]);

let plots = vec![Plot::Brick(plot)];
let layout = Layout::auto_from_plots(&plots).with_title("STR locus");
let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
std::fs::write("brick_locus.svg", svg).unwrap();
}

Built-in templates

Access the populated map via .template and pass it to with_template().

API reference

Box Plot

A box plot (box-and-whisker plot) displays the five-number summary of one or more groups of values. Boxes show the interquartile range (Q1–Q3) with a median line; whiskers extend to the most extreme values within 1.5×IQR of the box edges (Tukey style). Individual data points can optionally be overlaid as a jittered strip or beeswarm.

Import path: kuva::plot::BoxPlot

Basic usage

Add one group per category with .with_group(label, values). Groups are rendered left-to-right in the order they are added.

#![allow(unused)]
fn main() {
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("Treatment A", vec![5.5, 6.1, 6.4, 7.2, 7.8, 8.5, 6.9, 7.0])
    .with_group("Treatment B", vec![3.2, 4.0, 4.5, 4.8, 5.1, 5.9, 4.3, 4.7])
    .with_group("Treatment C", vec![6.0, 7.2, 7.5, 8.1, 8.8, 9.5, 7.9, 8.2])
    .with_color("steelblue");

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

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

What the box shows

Values outside the whisker range are not drawn automatically — use an overlay to show them.

Point overlays

Overlaying the raw data on top of each box makes the sample size and distribution shape immediately visible. Both modes accept an optional color and point size.

Jittered strip

.with_strip(jitter) scatters points randomly within a horizontal band. The jitter argument controls the spread width (in data-axis units; 0.2 is a reasonable starting value).

#![allow(unused)]
fn main() {
use kuva::plot::BoxPlot;
use kuva::render::plots::Plot;

let plot = BoxPlot::new()
    .with_group("Control",     vec![/* values */])
    .with_group("Treatment A", vec![/* values */])
    .with_color("steelblue")
    .with_strip(0.2)
    .with_overlay_color("rgba(0,0,0,0.4)")
    .with_overlay_size(3.0);
}

Beeswarm

.with_swarm_overlay() uses a beeswarm algorithm to spread points horizontally to avoid overlap. This gives a clearer picture of data density and is particularly useful for smaller datasets (roughly N < 200 per group).

#![allow(unused)]
fn main() {
use kuva::plot::BoxPlot;
use kuva::render::plots::Plot;

let plot = BoxPlot::new()
    .with_group("Control",     vec![/* values */])
    .with_group("Treatment A", vec![/* values */])
    .with_color("steelblue")
    .with_swarm_overlay()
    .with_overlay_color("rgba(0,0,0,0.4)")
    .with_overlay_size(3.0);
}

A semi-transparent overlay_color is recommended so the box remains visible beneath the points.

Per-group colors

Color each group independently within a single BoxPlot using .with_group_colors(). Colors are matched to groups by position — the first color applies to the first group added, and so on. The uniform .with_color() value is used as a fallback for any group without an entry. All elements of a group (box, whiskers, caps) share the same color.

#![allow(unused)]
fn main() {
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",     samples(5.0, 1.0, 60, 1))
    .with_group("Treatment A", samples(6.5, 1.2, 60, 2))
    .with_group("Treatment B", samples(4.2, 0.9, 60, 3))
    .with_group("Treatment C", samples(7.1, 1.5, 60, 4))
    .with_group_colors(["steelblue", "tomato", "seagreen", "goldenrod"]);

let plots = vec![Plot::Box(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Box Plot — Per-group Colors")
    .with_y_label("Value");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

A partial list is also valid — groups beyond the list length fall back to the uniform .with_color() value:

#![allow(unused)]
fn main() {
use kuva::plot::BoxPlot;
let plot = BoxPlot::new()
    .with_group("Control",     vec![/* values */])
    .with_group("Treatment A", vec![/* values */])
    .with_group("Treatment B", vec![/* values */])
    .with_color("steelblue")          // fallback for groups 1 and 2
    .with_group_colors(["tomato"]);   // only group 0 gets this color
}

Legend note: the legend entry uses the uniform .with_color() value. For a fully labeled per-group legend, create one BoxPlot per group and attach .with_legend() to each, then use a Layout::with_palette() to auto-assign colors.

API reference

Violin Plot

A violin plot estimates the probability density of each group using kernel density estimation (KDE) and renders it as a symmetric shape — widest where data is most dense. Unlike box plots, violins reveal multi-modal and skewed distributions that a five-number summary would obscure.

Import path: kuva::plot::ViolinPlot

Basic usage

Add one group per category with .with_group(label, values). Groups are rendered left-to-right in the order they are added.

#![allow(unused)]
fn main() {
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("Normal",  normal_data)   // unimodal
    .with_group("Bimodal", bimodal_data)  // two peaks — invisible in a box plot
    .with_group("Skewed",  skewed_data)   // long tail
    .with_color("steelblue")
    .with_width(30.0);

let plots = vec![Plot::Violin(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Violin Plot")
    .with_y_label("Value");

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

The bimodal group shows two distinct bulges — structure that a box plot would represent as a single median and IQR, losing all information about the separation.

Violin width

.with_width(px) sets the maximum half-width of each violin in pixels. The default is 30.0. Unlike bar width, this is an absolute pixel value, not a fraction of the category slot.

#![allow(unused)]
fn main() {
use kuva::plot::ViolinPlot;
let plot = ViolinPlot::new()
    .with_group("A", data)
    .with_width(20.0);   // narrower violins
}

KDE bandwidth

Bandwidth controls how smooth the density estimate is. The default uses Silverman's rule-of-thumb, which works well for unimodal, roughly normal data. Set it manually with .with_bandwidth(h) when the automatic choice is too smooth (hides modes) or too rough (noisy).

#![allow(unused)]
fn main() {
use kuva::plot::ViolinPlot;
use kuva::render::plots::Plot;

// Too narrow — jagged, noisy
let plot = ViolinPlot::new().with_group("", data.clone()).with_bandwidth(0.15);

// Automatic — Silverman's rule (default, no call needed)
let plot = ViolinPlot::new().with_group("", data.clone());

// Too wide — over-smoothed, modes blend together
let plot = ViolinPlot::new().with_group("", data.clone()).with_bandwidth(2.0);
}

h = 0.15 (too narrow)	Auto — Silverman	h = 2.0 (too wide)

.with_kde_samples(n) sets the number of points at which the density is evaluated (default 200). Increase it for a smoother rendered curve; the default is adequate for most datasets.

Point overlays

Adding individual points on top of the violin makes the sample size visible and helps readers judge the reliability of the density estimate.

Beeswarm overlay

.with_swarm_overlay() spreads points horizontally to avoid overlap. Recommended for smaller datasets (roughly N < 200 per group).

#![allow(unused)]
fn main() {
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("Normal",  normal_data)
    .with_group("Bimodal", bimodal_data)
    .with_group("Skewed",  skewed_data)
    .with_color("steelblue")
    .with_width(30.0)
    .with_swarm_overlay()
    .with_overlay_color("rgba(0,0,0,0.35)")
    .with_overlay_size(2.5);

let plots = vec![Plot::Violin(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Violin + Swarm Overlay")
    .with_y_label("Value");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Jittered strip

.with_strip(jitter) places points with random horizontal offsets. More appropriate for large datasets where beeswarm layout becomes slow.

#![allow(unused)]
fn main() {
use kuva::plot::ViolinPlot;
let plot = ViolinPlot::new()
    .with_group("A", data)
    .with_color("steelblue")
    .with_strip(0.15)                       // jitter spread in data units
    .with_overlay_color("rgba(0,0,0,0.4)") // semi-transparent recommended
    .with_overlay_size(3.0);
}

Per-group colors

Color each group independently within a single ViolinPlot using .with_group_colors(). Colors are matched to groups by position — the first color applies to the first group added, and so on. The uniform .with_color() value is used as a fallback for any group without an entry.

#![allow(unused)]
fn main() {
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("Normal",  normal_samples(0.0, 1.0, 300, 1))
    .with_group("Bimodal", bimodal_samples(-2.0, 2.0, 0.6, 300, 2))
    .with_group("Skewed",  skewed_samples(300, 3))
    .with_group_colors(["steelblue", "tomato", "seagreen"])
    .with_width(30.0);

let plots = vec![Plot::Violin(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Violin Plot — Per-group Colors")
    .with_y_label("Value");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

A partial list is also valid — groups beyond the list length fall back to the uniform .with_color() value:

#![allow(unused)]
fn main() {
use kuva::plot::ViolinPlot;
let plot = ViolinPlot::new()
    .with_group("Normal",  vec![/* values */])
    .with_group("Bimodal", vec![/* values */])
    .with_group("Skewed",  vec![/* values */])
    .with_color("steelblue")        // fallback for groups 1 and 2
    .with_group_colors(["tomato"]); // only group 0 gets this color
}

Legend note: the legend entry uses the uniform .with_color() value. For a fully labeled per-group legend, create one ViolinPlot per group and attach .with_legend() to each, then use a Layout::with_palette() to auto-assign colors.

API reference

Pie Chart

A pie chart divides a circle into slices proportional to each category's value. Each slice has its own explicit color. Slice labels can be placed automatically (inside large slices, outside small ones), forced to one side, or replaced with a legend.

Import path: kuva::plot::PiePlot

Basic usage

Add slices with .with_slice(label, value, color). Slices are drawn clockwise from 12 o'clock in the order they are added.

#![allow(unused)]
fn main() {
use kuva::plot::PiePlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_pie;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let pie = PiePlot::new()
    .with_slice("Rust",   40.0, "steelblue")
    .with_slice("Python", 30.0, "tomato")
    .with_slice("R",      20.0, "seagreen")
    .with_slice("Other",  10.0, "gold");

let plots = vec![Plot::Pie(pie.clone())];
let layout = Layout::auto_from_plots(&plots).with_title("Pie Chart");

let scene = render_pie(&pie, &layout);
let svg = SvgBackend.render_scene(&scene);
std::fs::write("pie.svg", svg).unwrap();
}

Only the ratio between slice values matters — absolute magnitudes are irrelevant. .with_slice("A", 1.0, ...) and .with_slice("A", 100.0, ...) produce the same slice if all others scale identically.

Donut chart

.with_inner_radius(r) cuts a hollow centre, converting the pie into a donut. r is the inner radius in pixels; the outer radius is computed from the canvas size. Values in the range 40.0–80.0 work well at the default canvas size.

#![allow(unused)]
fn main() {
use kuva::plot::PiePlot;
let pie = PiePlot::new()
    .with_slice("Rust",   40.0, "steelblue")
    .with_slice("Python", 30.0, "tomato")
    .with_slice("R",      20.0, "seagreen")
    .with_slice("Other",  10.0, "gold")
    .with_inner_radius(60.0);   // donut hole radius in pixels
}

Percentage labels

.with_percent() appends each slice's percentage of the total to its label, formatted to one decimal place (e.g. "Rust 40.0%").

#![allow(unused)]
fn main() {
use kuva::plot::PiePlot;
let pie = PiePlot::new()
    .with_slice("Rust",   40.0, "steelblue")
    .with_slice("Python", 30.0, "tomato")
    .with_slice("R",      20.0, "seagreen")
    .with_slice("Other",  10.0, "gold")
    .with_percent();
}

Label positioning

.with_label_position(PieLabelPosition) controls where labels appear.

Outside labels

Outside is recommended when slices vary widely in size or when many slices are present, since leader lines prevent labels from overlapping.

#![allow(unused)]
fn main() {
use kuva::plot::{PiePlot, PieLabelPosition};
use kuva::render::plots::Plot;

let pie = PiePlot::new()
    .with_slice("Apples",  30.0, "seagreen")
    .with_slice("Oranges", 25.0, "darkorange")
    .with_slice("Bananas", 20.0, "gold")
    .with_slice("Grapes",  12.0, "mediumpurple")
    .with_slice("Mango",    8.0, "coral")
    .with_slice("Kiwi",     5.0, "olivedrab")
    .with_label_position(PieLabelPosition::Outside);
}

Minimum label fraction

By default, slices smaller than 5 % of the total are not labelled (to avoid cramped text). Adjust this with .with_min_label_fraction(f).

#![allow(unused)]
fn main() {
use kuva::plot::PiePlot;
// Label every slice, even slices below 5 %
let pie = PiePlot::new()
    .with_slice("Big",  90.0, "steelblue")
    .with_slice("Tiny",  1.0, "tomato")
    .with_min_label_fraction(0.0);   // default is 0.05
}

Legend

.with_legend("") enables a per-slice legend in the right margin. Each slice gets an entry (colored square + slice label); the slice labels come from .with_slice(), not from the string passed to .with_legend(). Use render_multiple instead of render_pie so the legend is rendered.

Combine with PieLabelPosition::None to use the legend as the sole means of identification.

#![allow(unused)]
fn main() {
use kuva::plot::{PiePlot, PieLabelPosition};
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let pie = PiePlot::new()
    .with_slice("Apples",  40.0, "seagreen")
    .with_slice("Oranges", 35.0, "darkorange")
    .with_slice("Grapes",  25.0, "mediumpurple")
    .with_legend("Fruit")
    .with_percent()
    .with_label_position(PieLabelPosition::None);  // legend replaces labels

let plots = vec![Plot::Pie(pie)];
let layout = Layout::auto_from_plots(&plots).with_title("Pie with Legend");

// render_multiple (not render_pie) so the legend is drawn
let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
std::fs::write("pie_legend.svg", svg).unwrap();
}

API reference

Heatmap

A heatmap renders a two-dimensional grid where each cell's color encodes a numeric value. Values are normalized to the data range and passed through a color map. A colorbar is always shown in the right margin.

Import path: kuva::plot::Heatmap

Basic usage

Pass a 2-D array to .with_data(). The outer dimension is rows (top to bottom) and the inner dimension is columns (left to right).

#![allow(unused)]
fn main() {
use kuva::plot::Heatmap;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data = vec![
    vec![0.8, 0.3, 0.9, 0.2, 0.6],
    vec![0.4, 0.7, 0.1, 0.8, 0.3],
    vec![0.5, 0.9, 0.4, 0.6, 0.1],
    vec![0.2, 0.5, 0.8, 0.3, 0.7],
];

let heatmap = Heatmap::new().with_data(data);

let plots = vec![Plot::Heatmap(heatmap)];
let layout = Layout::auto_from_plots(&plots).with_title("Heatmap");

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

.with_data() accepts any iterable of iterables of numeric values — Vec<Vec<f64>>, slices, or any type implementing Into<f64>.

Axis labels

Axis labels are set on the Layout, not on the Heatmap struct. Pass column labels to .with_x_categories() and row labels to .with_y_categories().

#![allow(unused)]
fn main() {
use kuva::plot::Heatmap;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data = vec![
    vec![2.1, 0.4, 3.2, 1.1, 2.8],
    vec![0.9, 3.5, 0.3, 2.7, 1.2],
    vec![1.8, 2.9, 1.5, 0.6, 3.1],
    vec![3.3, 1.1, 2.0, 3.8, 0.5],
];

let col_labels = vec!["Ctrl", "T1", "T2", "T3", "T4"]
    .into_iter().map(String::from).collect::<Vec<_>>();
let row_labels = vec!["GeneA", "GeneB", "GeneC", "GeneD"]
    .into_iter().map(String::from).collect::<Vec<_>>();

let heatmap = Heatmap::new().with_data(data);
let plots = vec![Plot::Heatmap(heatmap)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Gene Expression Heatmap")
    .with_x_categories(col_labels)   // column labels on x-axis
    .with_y_categories(row_labels);  // row labels on y-axis

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Value overlay

.with_values() prints each cell's raw numeric value (formatted to two decimal places) centered inside the cell. Most useful for small grids where the text remains legible.

#![allow(unused)]
fn main() {
use kuva::plot::Heatmap;
let heatmap = Heatmap::new()
    .with_data(vec![
        vec![10.0, 20.0, 30.0, 15.0],
        vec![45.0, 55.0, 25.0, 60.0],
        vec![70.0, 35.0, 80.0, 40.0],
        vec![50.0, 90.0, 65.0, 20.0],
    ])
    .with_values();
}

Color maps

.with_color_map(ColorMap) selects the color encoding. The default is Viridis.

#![allow(unused)]
fn main() {
use kuva::plot::{Heatmap, ColorMap};
use kuva::render::plots::Plot;

let heatmap = Heatmap::new()
    .with_data(vec![vec![1.0, 2.0], vec![3.0, 4.0]])
    .with_color_map(ColorMap::Inferno);
}

Viridis	Inferno	Grayscale

Custom color map

For diverging scales or other custom encodings, use ColorMap::Custom with a closure that maps a normalized [0.0, 1.0] value to a CSS color string.

#![allow(unused)]
fn main() {
use std::sync::Arc;
use kuva::plot::{Heatmap, ColorMap};

// Blue-to-red diverging scale
let cmap = ColorMap::Custom(Arc::new(|t: f64| {
    let r = (t * 255.0) as u8;
    let b = ((1.0 - t) * 255.0) as u8;
    format!("rgb({r},0,{b})")
}));

let heatmap = Heatmap::new()
    .with_data(vec![vec![1.0, 2.0, 3.0], vec![4.0, 5.0, 6.0]])
    .with_color_map(cmap);
}

Custom axis bounds — scalar fields

By default the heatmap maps columns to [0.5, cols + 0.5] and rows to [0.5, rows + 0.5] so that integer tick values land on cell centres. Use .with_x_range() and .with_y_range() when the grid represents a physical domain and you want real-world coordinates on the axes.

#![allow(unused)]
fn main() {
use kuva::plot::{Heatmap, ColorMap};
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

// 2D Gaussian temperature field over x ∈ [-10, 10], y ∈ [-4, 4]
let data: Vec<Vec<f64>> = (0..16)
    .map(|i| {
        let y = 4.0 - (i as f64 + 0.5) * 8.0 / 16.0;
        (0..40).map(|j| {
            let x = -10.0 + (j as f64 + 0.5) * 20.0 / 40.0;
            let r2 = x * x / 16.0 + y * y / 4.0;
            (-r2 / 2.0).exp()
        }).collect()
    })
    .collect();

let hm = Heatmap::new()
    .with_data(data)
    .with_color_map(ColorMap::Inferno)
    .with_x_range(-10.0, 10.0)
    .with_y_range(-4.0, 4.0);

let plots = vec![Plot::Heatmap(hm)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Temperature Field")
    .with_x_label("x (m)")
    .with_y_label("y (m)");
}

Both methods accept any numeric type via impl Into<f64>. Either range can be set independently — you can fix only the x-axis and leave the y-axis on its default integer scale, or vice versa.

Row reordering — phylogenetic alignment

When composing a heatmap alongside a PhyloTree, use with_labels + with_y_categories to reorder the heatmap rows so they match the tree's leaf order top-to-bottom.

Key points:

• with_y_categories(order) treats order as top-to-bottom — the first label ends up at the top of the rendered heatmap.
• After the call, heatmap.row_labels is stored in bottom-to-top order (matching the y-axis convention). Pass it directly to Layout::with_y_categories.
• Use Figure::new(1, 2) to place the tree and heatmap side by side.

#![allow(unused)]
fn main() {
use kuva::plot::{Heatmap, PhyloTree};
use kuva::render::figure::Figure;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;
use kuva::backend::svg::SvgBackend;

let labels_str = ["Wolf", "Cat", "Whale", "Human"];
let labels: Vec<String> = labels_str.iter().map(|s| s.to_string()).collect();

// Distance matrix — rows correspond to labels_str in order
let dist = vec![
    vec![0.0, 0.5, 0.9, 0.8],  // Wolf
    vec![0.5, 0.0, 0.9, 0.8],  // Cat
    vec![0.9, 0.9, 0.0, 0.7],  // Whale
    vec![0.8, 0.8, 0.7, 0.0],  // Human
];

let tree = PhyloTree::from_distance_matrix(&labels_str, &dist).with_phylogram();

// leaf_labels_top_to_bottom() returns the leaf render order, top-to-bottom
let leaf_order = tree.leaf_labels_top_to_bottom();

let heatmap = Heatmap::new()
    .with_data(dist)
    .with_labels(labels, vec![])     // associate rows with names
    .with_y_categories(leaf_order);  // first leaf → top of heatmap

// row_labels is now stored bottom-to-top — pass directly to Layout
let layout_cats = heatmap.row_labels.clone().unwrap();

let tree_plots = vec![Plot::PhyloTree(tree)];
let heatmap_plots = vec![Plot::Heatmap(heatmap)];

let tree_layout = Layout::auto_from_plots(&tree_plots).with_title("UPGMA Tree");
let heatmap_layout = Layout::auto_from_plots(&heatmap_plots)
    .with_title("Distance Matrix")
    .with_y_categories(layout_cats);

// 1 row × 2 columns: tree on left, heatmap on right
let figure = Figure::new(1, 2)
    .with_plots(vec![tree_plots, heatmap_plots])
    .with_layouts(vec![tree_layout, heatmap_layout]);

let svg = SvgBackend.render_scene(&figure.render());
std::fs::write("phylo_heatmap.svg", svg).unwrap();
}

Note: Layout::with_y_categories() alone only changes the axis tick labels — it does not reorder the data matrix. Always call Heatmap::with_y_categories() first to permute the rows, then pass row_labels to the layout.

Column reordering works the same way via with_x_categories. Unlike with_y_categories, column order is not reversed internally — pass the desired left-to-right order directly to both Heatmap::with_x_categories and Layout::with_x_categories.

API reference

Layout methods used with heatmaps:

Clustermap

A clustermap combines a heatmap with hierarchical clustering dendrograms for both rows and columns. Unlike composing a Heatmap and PhyloTree manually in a Figure, Clustermap computes both in the same renderer and guarantees pixel-perfect alignment between dendrogram leaves and heatmap cell centres.

Rows and columns are clustered automatically via UPGMA (Euclidean distance) unless clustering is disabled or a pre-built PhyloTree is supplied.

Import path: kuva::plot::{Clustermap, ClustermapNorm, AnnotationTrack}

Basic usage

Pass a 2-D grid to .with_data(). The outer dimension is rows (top to bottom) and the inner dimension is columns (left to right). Row and column labels are set directly on the Clustermap, not via Layout.

#![allow(unused)]
fn main() {
use kuva::prelude::*;

let data = vec![
    vec![0.9, 0.1, 0.2, 0.8, 0.1],
    vec![0.8, 0.2, 0.1, 0.9, 0.2],
    vec![0.1, 0.9, 0.8, 0.2, 0.9],
    vec![0.2, 0.8, 0.9, 0.1, 0.8],
    vec![0.1, 0.7, 0.8, 0.3, 0.9],
];

let cm = Clustermap::new()
    .with_data(data)
    .with_row_labels(["A", "B", "C", "D", "E"])
    .with_col_labels(["X1", "X2", "X3", "X4", "X5"])
    .with_legend("Value");

let plots = vec![Plot::Clustermap(cm)];
let layout = Layout::auto_from_plots(&plots).with_title("Clustermap");

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

Both dendrograms are drawn automatically. Rows and columns are reordered so that similar profiles cluster together.

Disabling clustering

Pass false to .with_cluster_rows() or .with_cluster_cols() to suppress a dendrogram and keep the original data order on that axis.

#![allow(unused)]
fn main() {
use kuva::prelude::*;
// Cluster rows only — keep original column order
let cm = Clustermap::new()
    .with_data(data)
    .with_row_labels(["A", "B", "C", "D", "E"])
    .with_col_labels(["X1", "X2", "X3", "X4", "X5"])
    .with_cluster_cols(false);

// Or disable both for a plain labeled heatmap via the Clustermap API
let cm_plain = Clustermap::new()
    .with_data(data)
    .with_row_labels(["A", "B", "C", "D", "E"])
    .with_col_labels(["X1", "X2", "X3", "X4", "X5"])
    .with_cluster_rows(false)
    .with_cluster_cols(false);
}

When clustering is disabled on an axis, no dendrogram panel is drawn for that axis and the data is displayed in its original order.

Normalization

.with_normalization(ClustermapNorm) applies a transform to the data before color mapping. This is useful for comparing expression profiles where absolute magnitudes differ across rows or columns.

#![allow(unused)]
fn main() {
use kuva::prelude::*;
let cm = Clustermap::new()
    .with_data(data)
    .with_row_labels(["GeneA", "GeneB", "GeneC", "GeneD", "GeneE"])
    .with_col_labels(["Ctrl", "T1", "T2", "T3", "T4"])
    .with_normalization(ClustermapNorm::RowZScore)
    .with_legend("Z-score");
}

The colorbar always reflects the post-normalization range. Use RowZScore when you want to compare relative expression patterns across samples; use ColZScore when comparing relative feature activity across samples.

Color maps

The same ColorMap enum used by Heatmap applies here.

#![allow(unused)]
fn main() {
use kuva::prelude::*;
use kuva::plot::ColorMap;
let cm = Clustermap::new()
    .with_data(data)
    .with_color_map(ColorMap::Inferno);
}

Annotation tracks

AnnotationTrack adds a strip of colored cells alongside the heatmap body. Row annotation tracks appear between the row dendrogram and the heatmap. Column annotation tracks appear between the column dendrogram and the heatmap.

Provide one CSS color string per row (or column), in the original data order — the renderer reorders them to match the clustering automatically.

#![allow(unused)]
fn main() {
use kuva::prelude::*;
// Sample-group colors in original column order
let sample_colors = vec!["#ff7f00", "#ff7f00", "#984ea3", "#984ea3", "#984ea3"];

let col_annot = AnnotationTrack::new(sample_colors)
    .with_label("Group");

// Treatment status in original row order
let row_annot = AnnotationTrack::new(vec![
    "#e41a1c", "#e41a1c", "#4daf4a", "#377eb8", "#377eb8",
])
.with_label("Sample");

let cm = Clustermap::new()
    .with_data(data)
    .with_row_labels(["A", "B", "C", "D", "E"])
    .with_col_labels(["X1", "X2", "X3", "X4", "X5"])
    .with_row_annotation(row_annot)
    .with_col_annotation(col_annot);
}

Multiple tracks can be stacked by calling .with_row_annotation() or .with_col_annotation() multiple times. Each track is independent and can have a different width.

Track width

#![allow(unused)]
fn main() {
use kuva::prelude::*;
let track = AnnotationTrack::new(colors)
    .with_label("Treatment")
    .with_width(20.0);   // pixels; default 15.0
}

Pre-supplied trees

Supply a PhyloTree directly with .with_row_tree() or .with_col_tree() to use a custom topology instead of auto-clustering. The tree's leaf labels must match the row (or column) labels set via .with_row_labels() / .with_col_labels().

#![allow(unused)]
fn main() {
use kuva::prelude::*;
let labels = ["A", "B", "C", "D", "E"];
let dist = vec![
    vec![0.0, 0.1, 0.9, 0.9, 0.9],
    vec![0.1, 0.0, 0.9, 0.9, 0.9],
    vec![0.9, 0.9, 0.0, 0.1, 0.2],
    vec![0.9, 0.9, 0.1, 0.0, 0.2],
    vec![0.9, 0.9, 0.2, 0.2, 0.0],
];

// Build a tree externally (UPGMA, Newick parse, etc.)
let row_tree = PhyloTree::from_distance_matrix(&labels, &dist);

let cm = Clustermap::new()
    .with_data(data)
    .with_row_labels(labels)
    .with_row_tree(row_tree)  // use this topology; skip auto-clustering
    .with_cluster_cols(true); // auto-cluster columns as normal
}

This is useful when you want to impose a known phylogeny on the rows while still auto-clustering the columns.

Value overlay

.with_values() prints each cell's raw (post-normalization) value inside the cell, formatted to two decimal places. Most useful for small grids.

#![allow(unused)]
fn main() {
use kuva::prelude::*;
let cm = Clustermap::new()
    .with_data(vec![
        vec![1.0, 4.0, 7.0],
        vec![2.0, 5.0, 8.0],
        vec![3.0, 6.0, 9.0],
    ])
    .with_row_labels(["R1", "R2", "R3"])
    .with_col_labels(["C1", "C2", "C3"])
    .with_values();
}

Dendrogram panel sizing

The row dendrogram panel is 100 px wide by default. The column dendrogram panel is 80 px tall. Adjust these if your labels or canvas size require more or less space.

#![allow(unused)]
fn main() {
use kuva::prelude::*;
let cm = Clustermap::new()
    .with_data(data)
    .with_row_dendrogram_width(60.0)   // narrower row dendrogram
    .with_col_dendrogram_height(50.0); // shorter col dendrogram
}

Comparison with Figure-based PhyloTree + Heatmap

The older approach for pairing a dendrogram with a heatmap uses Figure::new(1, 2) to place a PhyloTree and a Heatmap side by side, then manually aligns them via leaf_labels_top_to_bottom() and with_y_categories(). This works but has a limitation:

The tree leaves and heatmap rows are each spaced independently within their own figure cells. At most canvas sizes the alignment looks correct, but is not guaranteed to be pixel-exact.

Clustermap solves this by computing both the dendrogram and the heatmap body in the same renderer, sharing an identical cell_h = hm_h / n_rows formula. Every leaf centre and every heatmap row centre are placed at hm_y + (k + 0.5) * cell_h — the same expression — so alignment is guaranteed regardless of canvas size or the number of rows.

Use Clustermap when:

• You need reliable dendrogram-to-heatmap alignment.
• You want UPGMA auto-clustering and just need a result.
• You need annotation tracks alongside the heatmap.
• You want row / column z-score normalization in the same call.

Use the Figure + PhyloTree + Heatmap approach when:

• You need full control over the tree (e.g. circular layout, clade coloring, branch lengths, support values).
• You want to show a phylogram (branch-length-accurate tree) alongside the heatmap.
• The tree and heatmap use different data sources and need to be laid out independently.

API reference

Clustermap builder methods

AnnotationTrack builder methods

ClustermapNorm variants

Joint Plot

A joint plot combines a central scatter plot with marginal distribution panels on the top and right edges. Each marginal panel shows the univariate distribution of the corresponding axis — either as a histogram or a kernel density estimate (KDE). This makes it easy to see both the bivariate relationship and each variable's marginal distribution in a single figure.

JointPlot is a standalone composite renderer, not a Plot enum variant. Render it with render_jointplot(jp, layout) instead of render_multiple.

Import path: kuva::prelude::* (re-exports JointPlot, JointGroup, MarginalType, and render_jointplot)

Basic usage

#![allow(unused)]
fn main() {
use kuva::prelude::*;

let x = vec![1.2, 2.4, 3.1, 4.8, 5.0, 2.1, 3.7, 4.2];
let y = vec![2.1, 3.8, 3.2, 5.1, 5.4, 2.8, 4.0, 4.6];

let jp = JointPlot::new()
    .with_xy(x, y)
    .with_x_label("Feature A")
    .with_y_label("Feature B");

let layout = Layout::new((0.0, 6.0), (1.5, 6.5))
    .with_title("Joint Plot");

let svg = SvgBackend.render_scene(&render_jointplot(jp, layout));
std::fs::write("jointplot.svg", svg).unwrap();
}

By default both the top (x-distribution) and right (y-distribution) marginal panels are shown as histograms with 20 bins.

Marginal type

.with_marginal_type(MarginalType) switches between histogram bars and a filled KDE curve.

#![allow(unused)]
fn main() {
use kuva::prelude::*;
let jp = JointPlot::new()
    .with_xy(x, y)
    .with_marginal_type(MarginalType::Density)
    .with_x_label("log2 TPM")
    .with_y_label("log2 FC");
}

KDE bandwidth defaults to Silverman's rule of thumb. Override with .with_bandwidth(f64).

Showing / hiding marginal panels

Each panel can be toggled independently.

#![allow(unused)]
fn main() {
use kuva::prelude::*;
// Top marginal only
let jp_top = JointPlot::new()
    .with_xy(x.clone(), y.clone())
    .with_right_marginal(false);

// Right marginal only
let jp_right = JointPlot::new()
    .with_xy(x.clone(), y.clone())
    .with_top_marginal(false);

// Scatter only — useful as a feature-parity path through the JointPlot API
let jp_scatter = JointPlot::new()
    .with_xy(x, y)
    .with_top_marginal(false)
    .with_right_marginal(false)
    .with_x_label("X")
    .with_y_label("Y");
}

Multiple groups

Use .with_group() to add named, colored data groups. When two or more groups have labels the legend is rendered automatically to the right of the marginal panel.

#![allow(unused)]
fn main() {
use kuva::prelude::*;
let jp = JointPlot::new()
    .with_group("Control", x_ctrl, y_ctrl, "#4e79a7")
    .with_group("Treated", x_trt,  y_trt,  "#f28e2b")
    .with_x_label("X")
    .with_y_label("Y");

let layout = Layout::new((-6.0, 9.0), (-6.0, 9.0))
    .with_title("Two Groups");
}

Each group's marginal bars or density fill use the group's marker color at 60 % opacity (controlled by .with_marginal_alpha(f64)).

Layout note: When a legend is present alongside a right marginal panel, the total SVG width is automatically expanded so the legend appears to the right of the panel, with no white space between the data area and the panel.

Trend lines

Build a JointGroup directly for access to all scatter-plot features, including trend lines and correlation annotations.

#![allow(unused)]
fn main() {
use kuva::prelude::*;
use kuva::plot::scatter::TrendLine;
let group = JointGroup::new(x, y)
    .with_color("#e15759")
    .with_trend(TrendLine::Linear)
    .with_trend_color("#333333")
    .with_correlation();          // adds "r = X.XX" annotation

let jp = JointPlot::new()
    .with_joint_group(group)
    .with_x_label("X")
    .with_y_label("Y");
}

Error bars

#![allow(unused)]
fn main() {
use kuva::prelude::*;
let x_err = vec![0.2; 30];
let y_err = vec![0.3; 30];

let group = JointGroup::new(x, y)
    .with_color("#76b7b2")
    .with_x_err(x_err)
    .with_y_err(y_err);

let jp = JointPlot::new()
    .with_joint_group(group)
    .with_x_label("Measurement")
    .with_y_label("Response");
}

Asymmetric error bars are also supported via .with_x_err_asymmetric() and .with_y_err_asymmetric().

Marker shape and size

#![allow(unused)]
fn main() {
use kuva::prelude::*;
use kuva::plot::scatter::MarkerShape;
let group = JointGroup::new(x, y)
    .with_color("#59a14f")
    .with_marker(MarkerShape::Square)
    .with_marker_size(5.0)
    .with_marker_stroke_width(1.0);

let jp = JointPlot::new()
    .with_joint_group(group)
    .with_marginal_type(MarginalType::Density);
}

Available marker shapes: Circle (default), Square, Triangle, Diamond, Cross, Plus.

Per-point colors

#![allow(unused)]
fn main() {
use kuva::prelude::*;
// Color each point by sign of x
let colors: Vec<String> = x.iter()
    .map(|&v| if v > 0.0 { "#4e79a7".into() } else { "#e15759".into() })
    .collect();

let group = JointGroup::new(x, y)
    .with_colors(colors);

let jp = JointPlot::new().with_joint_group(group);
}

The per-point colors apply only to the scatter markers; marginal bars use the group's uniform color.

Tooltips

#![allow(unused)]
fn main() {
use kuva::prelude::*;
let labels: Vec<String> = (0..40).map(|i| format!("Sample {i}")).collect();

let group = JointGroup::new(x, y)
    .with_color("#b07aa1")
    .with_tooltips()
    .with_tooltip_labels(labels);

let jp = JointPlot::new().with_joint_group(group);
}

Tooltip <title> elements are injected into the SVG and shown on hover in browsers. They are silently ignored by PNG/PDF/terminal backends.

Panel sizing

#![allow(unused)]
fn main() {
use kuva::prelude::*;
let jp = JointPlot::new()
    .with_xy(x, y)
    .with_marginal_size(120.0)   // panel height (top) / width (right), default 80.0
    .with_marginal_gap(8.0)      // gap between panel and scatter, default 4.0
    .with_bins(30)               // histogram bins, default 20
    .with_marginal_alpha(0.5);   // bar/fill opacity, default 0.6
}

Canvas size

JointPlot uses Layout::with_width() and Layout::with_height() for total canvas dimensions (including marginal panels). A square canvas (e.g. 500 × 500) is natural for scatter data. Increase width or height if labels or legend need more room.

#![allow(unused)]
fn main() {
use kuva::prelude::*;
let layout = Layout::new((-8.0, 8.0), (-5.0, 5.0))
    .with_title("Expression vs Fold Change")
    .with_width(520.0)
    .with_height(520.0);
}

API reference

JointPlot builder methods

JointGroup builder methods

JointGroup wraps a ScatterPlot and forwards all scatter features.

Strip Plot

A strip plot (dot plot / univariate scatter) shows every individual data point along a categorical axis. Unlike a box or violin, nothing is summarised — the raw values are shown directly, making sample size and exact distribution shape immediately visible.

Import path: kuva::plot::StripPlot

Basic usage

Add one group per category with .with_group(label, values). Groups are rendered left-to-right in the order they are added.

#![allow(unused)]
fn main() {
use kuva::plot::StripPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let strip = StripPlot::new()
    .with_group("Control",   control_data)
    .with_group("Low dose",  low_data)
    .with_group("High dose", high_data)
    .with_group("Washout",   washout_data)
    .with_color("steelblue")
    .with_point_size(2.5)
    .with_jitter(0.35);

let plots = vec![Plot::Strip(strip)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Jittered Strip Plot")
    .with_y_label("Measurement");

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

300 points per group. The jitter cloud fills out the slot width, making the spread and central tendency of each distribution easy to compare.

Layout modes

Three modes control how points are spread horizontally within each group slot.

Jittered strip

.with_jitter(j) assigns each point a random horizontal offset. j is the half-width as a fraction of the slot — 0.3 spreads points ±30 % of the slot width. This is the default (j = 0.3).

Use a smaller j to tighten the column or a larger j to spread it out. The jitter positions are randomised with a fixed seed (changeable via .with_seed()), so output is reproducible.

#![allow(unused)]
fn main() {
use kuva::plot::StripPlot;
let strip = StripPlot::new()
    .with_group("A", data)
    .with_jitter(0.35)      // ±35 % of slot width
    .with_point_size(2.5);
}

Beeswarm

.with_swarm() uses a deterministic algorithm to place each point as close to the group center as possible without overlapping any already-placed point. The outline of the resulting shape traces the density of the distribution.

Swarm works best for N < ~200 per group. With very large N, points are pushed far from center and the spread becomes impractical.

#![allow(unused)]
fn main() {
use kuva::plot::StripPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let strip = StripPlot::new()
    .with_group("Control",      normal_data)
    .with_group("Bimodal",      bimodal_data)
    .with_group("Right-skewed", skewed_data)
    .with_color("steelblue")
    .with_point_size(3.0)
    .with_swarm();

let plots = vec![Plot::Strip(strip)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Beeswarm")
    .with_y_label("Value");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

150 points per group. The bimodal group shows two distinct lobes; the right-skewed group shows the long tail — structure that jitter reveals less cleanly at this sample size.

Center stack

.with_center() places all points at x = group center with no horizontal spread, creating a vertical column. The density of the distribution is readable directly from where points are most tightly packed.

#![allow(unused)]
fn main() {
use kuva::plot::StripPlot;
let strip = StripPlot::new()
    .with_group("Normal",  normal_data)
    .with_group("Bimodal", bimodal_data)
    .with_group("Skewed",  skewed_data)
    .with_color("steelblue")
    .with_point_size(2.0)
    .with_center();
}

400 points per group. The bimodal group shows a clear gap in the column; the skewed group has a dense cluster at the low end thinning toward the tail.

Composing with a box plot

A StripPlot can be layered on top of a BoxPlot by passing both to render_multiple. Use a semi-transparent rgba color for the strip so the box summary remains legible underneath.

#![allow(unused)]
fn main() {
use kuva::plot::{StripPlot, BoxPlot};
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let boxplot = BoxPlot::new()
    .with_group("Control",     control_data.clone())
    .with_group("Bimodal",     bimodal_data.clone())
    .with_group("High-spread", spread_data.clone())
    .with_color("steelblue");

let strip = StripPlot::new()
    .with_group("Control",     control_data)
    .with_group("Bimodal",     bimodal_data)
    .with_group("High-spread", spread_data)
    .with_color("rgba(0,0,0,0.3)")   // semi-transparent so box shows through
    .with_point_size(2.5)
    .with_jitter(0.2);

let plots = vec![Plot::Box(boxplot), Plot::Strip(strip)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Box + Strip")
    .with_y_label("Value");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

The box summarises Q1/median/Q3; the individual points reveal that the bimodal group has two sub-populations the box conceals entirely.

Multiple strip plots with a palette

Passing multiple StripPlots to render_multiple with a Layout::with_palette() auto-assigns distinct colors. Attach .with_legend() to each plot to identify them.

#![allow(unused)]
fn main() {
use kuva::plot::StripPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;
use kuva::Palette;

let line_a = StripPlot::new()
    .with_group("WT",  wt_a).with_group("HET", het_a).with_group("KO", ko_a)
    .with_jitter(0.3).with_point_size(2.5)
    .with_legend("Line A");

let line_b = StripPlot::new()
    .with_group("WT",  wt_b).with_group("HET", het_b).with_group("KO", ko_b)
    .with_jitter(0.3).with_point_size(2.5)
    .with_legend("Line B");

let plots = vec![Plot::Strip(line_a), Plot::Strip(line_b)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Two Lines – Palette")
    .with_y_label("Expression")
    .with_palette(Palette::wong());

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Per-group colors

Color each group independently within a single StripPlot using .with_group_colors(). Colors are matched to groups by position — the first color applies to the first group added, and so on. The uniform .with_color() value is used as a fallback for any group without an entry.

This is an alternative to creating one StripPlot per group when the data is already grouped. The legend is not updated automatically; use separate StripPlot instances with .with_legend() when you need labeled legend entries.

#![allow(unused)]
fn main() {
use kuva::plot::StripPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let strip = StripPlot::new()
    .with_group("Control",   vec![4.1, 5.0, 5.3, 5.8, 6.2, 4.7])
    .with_group("Treatment", vec![5.5, 6.1, 6.4, 7.2, 7.8, 6.9])
    .with_group("Placebo",   vec![3.9, 4.5, 4.8, 5.1, 5.6, 4.3])
    .with_group_colors(vec!["steelblue", "crimson", "seagreen"])
    .with_point_size(4.0)
    .with_jitter(0.3);

let plots = vec![Plot::Strip(strip)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Per-Group Colors")
    .with_y_label("Measurement");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Per-point colors

.with_colored_group(label, points) adds a group where each point carries its own color. points is any iterator of (value, color) pairs — the value and color travel together. Points beyond the end of the color list fall back to the group/uniform color.

This is useful when each observation belongs to a distinct category within a single sample column — for example, coloring reads by their primary repeat motif in a STR genotyping view.

#![allow(unused)]
fn main() {
use kuva::plot::{StripPlot, LegendEntry, LegendShape, LegendPosition};
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let strip = StripPlot::new()
    .with_colored_group("Sample", vec![
        (6.1, "tomato"),       // ATTC repeat
        (9.3, "seagreen"),     // GCGC repeat
        (4.8, "goldenrod"),    // ATAT repeat
        (11.2, "mediumpurple"), // CGCG repeat
        (7.0, "steelblue"),   // TTAGG repeat
        // … more reads
    ])
    .with_swarm()
    .with_point_size(4.5);

// Per-point colors are not reflected in the auto-legend — supply entries manually.
let legend_entries = vec![
    LegendEntry { label: "ATTC".into(),  color: "tomato".into(),       shape: LegendShape::Circle, dasharray: None },
    LegendEntry { label: "GCGC".into(),  color: "seagreen".into(),     shape: LegendShape::Circle, dasharray: None },
    LegendEntry { label: "ATAT".into(),  color: "goldenrod".into(),    shape: LegendShape::Circle, dasharray: None },
    LegendEntry { label: "CGCG".into(),  color: "mediumpurple".into(), shape: LegendShape::Circle, dasharray: None },
    LegendEntry { label: "TTAGG".into(), color: "steelblue".into(),    shape: LegendShape::Circle, dasharray: None },
];

let plots = vec![Plot::Strip(strip)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("STR Repeat Counts — Per-point Motif Colors")
    .with_x_label("Sample")
    .with_y_label("Repeat count")
    .with_legend_title("Motif")
    .with_legend_entries(legend_entries)
    .with_legend_position(LegendPosition::OutsideRightTop);

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

Legend note: .with_colored_group does not auto-populate the legend. Supply entries manually via Layout::with_legend_entries (with LegendShape::Circle) as shown above. For per-group coloring (one color per column, not per point) see Per-group colors above.

Marker opacity and stroke

For dense datasets, the default solid fill causes points to merge into an opaque block. Two builders control fill transparency and an optional outline stroke to keep individual points distinguishable.

Dense strip — 500 points per group

With 500 points per group, solid markers pile into uniform bars and the shape of each distribution is hidden. Setting opacity = 0.25 makes denser bands visibly darker — here the bimodal "High dose" group clearly shows two sub-populations, and the skewed "Washout" distribution tapers naturally toward its tail. The thin 0.7 px stroke keeps points individually readable even where they overlap most.

#![allow(unused)]
fn main() {
use kuva::plot::StripPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

// (populate each group with 500 values from your data source)
let (control, low, high, washout) = (vec![0f64], vec![0f64], vec![0f64], vec![0f64]);
let strip = StripPlot::new()
    .with_group("Control",   control)
    .with_group("Low dose",  low)
    .with_group("High dose", high)   // bimodal — two sub-populations
    .with_group("Washout",   washout) // right-skewed
    .with_color("steelblue")
    .with_point_size(4.0)
    .with_jitter(0.3)
    .with_marker_opacity(0.25)
    .with_marker_stroke_width(0.7);

let plots = vec![Plot::Strip(strip)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Dense strip — semi-transparent markers (500 pts/group)")
    .with_y_label("Measurement");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

The stroke color always matches the fill color set by .with_color() or .with_group_colors().

API reference

Raincloud Plot

A raincloud plot (Allen et al. 2019) overlays three complementary views of each group's distribution on a shared axis:

• Cloud — a half-violin (KDE) showing the distribution shape
• Box — a narrow box-and-whisker showing the five-number summary
• Rain — jittered raw points showing every individual observation

This combination avoids the information loss of a box plot (shape is hidden), the visual clutter of a pure strip plot (structure is obscured), and the opacity of a violin (sample size is invisible). All three layers share the same y-axis so they can be compared directly.

Import path: kuva::plot::RaincloudPlot

Basic usage

Add one group per category with .with_group(label, values). Groups are rendered left-to-right in the order added.

#![allow(unused)]
fn main() {
use kuva::plot::RaincloudPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = RaincloudPlot::new()
    .with_group("Control", control_values)
    .with_group("Low dose", low_dose_values)
    .with_group("High dose", high_dose_values);

let plots = vec![Plot::Raincloud(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Drug response")
    .with_x_label("Treatment")
    .with_y_label("Response (AU)");

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

By default, multi-group plots use the category10 palette automatically. For a single group the uniform .with_color() value is used.

Toggling elements

Each of the three layers can be turned off independently. This lets you build simpler variants when not all three are needed.

#![allow(unused)]
fn main() {
use kuva::plot::RaincloudPlot;

// Cloud + box only (no raw points)
let plot = RaincloudPlot::new()
    .with_group("A", data)
    .with_rain(false);

// Cloud + rain only (no summary box)
let plot = RaincloudPlot::new()
    .with_group("A", data)
    .with_box(false);

// Box + rain only (no KDE cloud)
let plot = RaincloudPlot::new()
    .with_group("A", data)
    .with_cloud(false);
}

KDE bandwidth

The cloud shape is a kernel density estimate. By default, bandwidth is chosen automatically using Silverman's rule-of-thumb, which works well for roughly unimodal, normal-ish data but can over-smooth multimodal distributions.

Bandwidth scale

.with_bandwidth_scale(s) multiplies the auto-computed bandwidth by a factor (equivalent to ggplot2's adjust). Values below 1.0 produce a sharper, more data-sensitive curve; values above 1.0 produce a smoother curve.

#![allow(unused)]
fn main() {
use kuva::plot::RaincloudPlot;

// Tighter — reveals bimodality or shoulders
let plot = RaincloudPlot::new()
    .with_group("A", data)
    .with_bandwidth_scale(0.5);

// Wider — emphasises overall shape, less noise
let plot = RaincloudPlot::new()
    .with_group("A", data)
    .with_bandwidth_scale(2.0);
}

Explicit bandwidth

.with_bandwidth(h) sets an exact bandwidth value, overriding both Silverman's rule and .with_bandwidth_scale().

#![allow(unused)]
fn main() {
use kuva::plot::RaincloudPlot;
let plot = RaincloudPlot::new()
    .with_group("A", data)
    .with_bandwidth(0.4);
}

.with_kde_samples(n) controls how many points the KDE is evaluated at (default 200). The default is adequate for most datasets.

Flip direction

By default the cloud appears to the right of centre and rain to the left. .with_flip(true) reverses this.

#![allow(unused)]
fn main() {
use kuva::plot::RaincloudPlot;
let plot = RaincloudPlot::new()
    .with_group("A", data)
    .with_flip(true);   // cloud left, rain right
}

Per-group colors

.with_group_colors() assigns colors to groups by position.

#![allow(unused)]
fn main() {
use kuva::plot::RaincloudPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = RaincloudPlot::new()
    .with_group("Control",   control_values)
    .with_group("Low dose",  low_values)
    .with_group("High dose", high_values)
    .with_group_colors(["#4878d0", "#ee854a", "#6acc65"]);

let plots = vec![Plot::Raincloud(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Raincloud — per-group colors")
    .with_y_label("Response");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Legend

.with_legend(label) triggers per-group legend entries. Each group's label and color appear as a separate row in the legend — the string passed to .with_legend() is not used as an entry label but serves as a signal to show the legend.

#![allow(unused)]
fn main() {
use kuva::plot::RaincloudPlot;
use kuva::render::plots::Plot;
use kuva::render::layout::Layout;
use kuva::render::render::render_multiple;
use kuva::backend::svg::SvgBackend;
let plot = RaincloudPlot::new()
    .with_group("Control", control_values)
    .with_group("Treated", treated_values)
    .with_legend("show");   // triggers per-group entries

let plots = vec![Plot::Raincloud(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Treatment comparison");
let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Fine-tuning layout

The offsets and widths of all three elements can be adjusted if groups overlap or look too sparse.

#![allow(unused)]
fn main() {
use kuva::plot::RaincloudPlot;
let plot = RaincloudPlot::new()
    .with_group("A", data_a)
    .with_group("B", data_b)
    .with_cloud_width(40.0)    // wider cloud (default 30.0 px)
    .with_cloud_offset(0.20)   // cloud centre further from group centre (default 0.15)
    .with_rain_offset(0.25)    // rain centre further from group centre (default 0.20)
    .with_box_width(0.12)      // wider box (default 0.08, fraction of slot)
    .with_rain_size(2.5)       // smaller rain points (default 3.0 px radius)
    .with_rain_jitter(0.04)    // tighter horizontal spread (default 0.05)
    .with_cloud_alpha(0.6)     // slightly more transparent cloud (default 0.7)
    .with_rain_alpha(0.5)      // more transparent rain (default 0.7)
    .with_seed(123);           // different jitter seed (default 42)
}

API reference

Waterfall Chart

A waterfall chart shows a running total as a sequence of floating bars. Each bar starts where the previous one ended — rising for positive increments (green) and falling for negative ones (red). Summary bars can be placed at any point to show accumulated subtotals.

Import path: kuva::plot::WaterfallPlot

Basic usage

Add bars with .with_delta(label, value). The chart tracks a running total from left to right — each bar floats between the previous total and the new one.

#![allow(unused)]
fn main() {
use kuva::plot::WaterfallPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let wf = WaterfallPlot::new()
    .with_delta("Revenue",        850.0)
    .with_delta("Cost of goods", -340.0)
    .with_delta("Personnel",     -180.0)
    .with_delta("Operations",     -90.0)
    .with_delta("Marketing",      -70.0)
    .with_delta("Other income",    55.0)
    .with_delta("Tax",            -85.0);

let plots = vec![Plot::Waterfall(wf)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Revenue Breakdown")
    .with_y_label("USD (thousands)");

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

Green bars add to the running total; red bars subtract from it.

Total bars

.with_total(label) places a bar that spans from zero to the current running total, rendered in a distinct color (default "steelblue"). The value field is irrelevant — the bar height is the accumulated total at that position. Place totals after sections of delta bars to show intermediate subtotals.

#![allow(unused)]
fn main() {
use kuva::plot::WaterfallPlot;
use kuva::render::plots::Plot;
let wf = WaterfallPlot::new()
    .with_delta("Revenue",        850.0)
    .with_delta("Cost of goods", -340.0)
    .with_total("Gross profit")         // subtotal after first section
    .with_delta("Personnel",     -180.0)
    .with_delta("Operations",     -90.0)
    .with_delta("Marketing",      -70.0)
    .with_total("EBITDA")               // second subtotal
    .with_delta("Depreciation",   -40.0)
    .with_delta("Interest",       -20.0)
    .with_delta("Tax",            -65.0)
    .with_total("Net income");          // final total
}

The three blue bars show gross profit, EBITDA, and net income alongside the individual line items that make them up.

Connectors and value labels

.with_connectors() draws a dashed horizontal line from the top (or bottom) of each bar to the start of the next, making the running total easier to trace across wide charts. .with_values() prints the numeric value of each bar.

#![allow(unused)]
fn main() {
use kuva::plot::WaterfallPlot;
use kuva::render::plots::Plot;
let wf = WaterfallPlot::new()
    .with_delta("Q1 sales",    420.0)
    .with_delta("Q2 sales",    380.0)
    .with_delta("Returns",     -95.0)
    .with_delta("Discounts",   -60.0)
    .with_total("H1 net")
    .with_delta("Q3 sales",   410.0)
    .with_delta("Q4 sales",   455.0)
    .with_delta("Returns",   -105.0)
    .with_delta("Discounts",  -70.0)
    .with_total("H2 net")
    .with_connectors()
    .with_values();
}

Difference bars

.with_difference(label, from, to) adds a standalone comparison bar anchored at explicit y-values rather than the running total. The bar spans [from, to] — green when to > from, red when to < from — and does not change the running total.

The clearest use is when from and to match the heights of existing Total bars, so the reader can trace the connection directly. In the example below both period totals are in the chart; the difference bar sits between those two reference levels and shows the gain between them.

#![allow(unused)]
fn main() {
use kuva::plot::WaterfallPlot;
use kuva::render::plots::Plot;

let wf = WaterfallPlot::new()
    .with_delta("Revenue",   500.0)   // running total → 500
    .with_delta("Costs",    -180.0)   // running total → 320
    .with_total("Period A")           // total bar: 0 → 320
    .with_delta("Revenue",   600.0)   // running total → 920
    .with_delta("Costs",    -190.0)   // running total → 730
    .with_total("Period B")           // total bar: 0 → 730
    // from = Period A total (320), to = Period B total (730)
    .with_difference("Period A→B", 320.0, 730.0)
    .with_values();
}

The "Period A→B" bar is anchored at 320–730 regardless of where the running total is. It does not alter the "Period B" total — it is purely a visual annotation showing the improvement between the two periods.

Custom colors

Override any of the three bar colors with CSS color strings.

#![allow(unused)]
fn main() {
use kuva::plot::WaterfallPlot;
let wf = WaterfallPlot::new()
    .with_delta("Gain",  100.0)
    .with_delta("Loss",  -40.0)
    .with_total("Net")
    .with_color_positive("darkgreen")   // default: "rgb(68,170,68)"
    .with_color_negative("crimson")     // default: "rgb(204,68,68)"
    .with_color_total("navy");          // default: "steelblue"
}

API reference

Dot Plot

A dot plot (bubble matrix) places circles at the intersections of two categorical axes. Each circle encodes two independent continuous variables: size (radius) and color. This makes it well suited for compact display of multi-variable summaries across a grid — the canonical use case in bioinformatics is a gene expression dot plot where size shows the fraction of cells expressing a gene and color shows the mean expression level.

Import path: kuva::plot::DotPlot

Basic usage

Pass an iterator of (x_cat, y_cat, size, color) tuples to .with_data(). Category order on each axis follows first-seen insertion order. Enable legends independently with .with_size_legend() and .with_colorbar().

#![allow(unused)]
fn main() {
use kuva::plot::DotPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let data = vec![
    // (x_cat,   y_cat,   size,  color)
    ("CD4 T",  "CD3E",  88.0_f64, 3.8_f64),
    ("CD8 T",  "CD3E",  91.0,     4.0    ),
    ("NK",     "CD3E",  12.0,     0.5    ),
    ("CD4 T",  "CD4",   85.0,     3.5    ),
    ("CD8 T",  "CD4",    8.0,     0.3    ),
    ("NK",     "CD4",    4.0,     0.2    ),
];

let dot = DotPlot::new()
    .with_data(data)
    .with_size_legend("% Expressing")
    .with_colorbar("Mean expression");

let plots = vec![Plot::DotPlot(dot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Gene Expression")
    .with_x_label("Cell type")
    .with_y_label("Gene");

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

Eight immune marker genes across six cell types. Large circles show genes expressed in many cells; bright colors (Viridis: yellow) show high mean expression. The cell-type specificity of each marker is immediately legible — CD3E is large in T cells, MS4A1 only in B cells, LYZ highest in monocytes.

Matrix input

.with_matrix(x_cats, y_cats, sizes, colors) accepts dense 2-D data where every grid cell is filled. sizes[row_i][col_j] maps to y_cats[row_i] and x_cats[col_j]. Use this when your data comes from a matrix or 2-D array.

#![allow(unused)]
fn main() {
use kuva::plot::DotPlot;
use kuva::render::plots::Plot;

let x_cats = vec!["TypeA", "TypeB", "TypeC", "TypeD", "TypeE"];
let y_cats = vec!["Gene1", "Gene2", "Gene3", "Gene4", "Gene5", "Gene6"];

// sizes[row_i][col_j] → y_cats[row_i], x_cats[col_j]
let sizes = vec![
    vec![80.0, 25.0, 60.0, 45.0, 70.0],
    vec![15.0, 90.0, 35.0, 70.0, 20.0],
    // ...
];
let colors = vec![
    vec![3.5, 1.2, 2.8, 2.0, 3.1],
    vec![0.8, 4.1, 1.5, 3.2, 0.9],
    // ...
];

let dot = DotPlot::new()
    .with_matrix(x_cats, y_cats, sizes, colors)
    .with_size_legend("% Expressing")
    .with_colorbar("Mean expression");
}

Sparse data

With .with_data(), grid positions with no corresponding tuple are simply left empty — no circle is drawn at that cell. There is no need to fill missing values with zero or NaN.

#![allow(unused)]
fn main() {
use kuva::plot::DotPlot;
let dot = DotPlot::new().with_data(vec![
    ("TypeA", "GeneX", 80.0_f64, 2.5_f64),
    // ("TypeA", "GeneY") absent — no circle drawn
    ("TypeA", "GeneZ", 40.0,     1.2    ),
    ("TypeB", "GeneY", 90.0,     2.9    ),
]);
}

Legends

The size legend and colorbar are independent. Enable either, both, or neither.

Size legend only

.with_size_legend(label) adds a key in the right margin showing representative radii with their corresponding values. Use this when color carries no additional information (or when all dots share the same constant color value).

#![allow(unused)]
fn main() {
use kuva::plot::DotPlot;
let dot = DotPlot::new()
    .with_data(data)
    .with_size_legend("% Expressing");   // only size legend; no colorbar
}

Colorbar only

.with_colorbar(label) adds a colorbar for the color encoding. Useful when all dots should be the same size (pass a constant for the size field) so the color variable is the sole focus.

#![allow(unused)]
fn main() {
use kuva::plot::DotPlot;
let dot = DotPlot::new()
    .with_data(data)
    .with_colorbar("Mean expression");   // only colorbar; no size legend
}

Both legends

When both are set, the size legend and colorbar are stacked in a single right-margin column automatically.

#![allow(unused)]
fn main() {
use kuva::plot::DotPlot;
let dot = DotPlot::new()
    .with_data(data)
    .with_size_legend("% Expressing")
    .with_colorbar("Mean expression");
}

Clamping ranges

By default the size and color encodings are normalised to the data extent automatically. Use .with_size_range() and .with_color_range() to fix an explicit [min, max] — useful for excluding outliers or keeping a consistent scale across multiple plots.

#![allow(unused)]
fn main() {
use kuva::plot::DotPlot;
let dot = DotPlot::new()
    .with_data(data)
    // Clamp size to 0–100 % regardless of data range;
    // values above 100 map to max_radius.
    .with_size_range(0.0, 100.0)
    // Fix color scale to 0–5 log-normalised expression.
    .with_color_range(0.0, 5.0);
}

Radius range

.with_max_radius(px) and .with_min_radius(px) set the pixel size limits (defaults: 12.0 and 1.0). Increase max_radius for a larger grid or reduce it for dense plots with many categories.

#![allow(unused)]
fn main() {
use kuva::plot::DotPlot;
let dot = DotPlot::new()
    .with_data(data)
    .with_max_radius(18.0)   // default 12.0
    .with_min_radius(2.0);   // default 1.0
}

Color maps

.with_color_map(ColorMap) selects the color encoding (default Viridis). The same ColorMap variants available for heatmaps apply here: Viridis, Inferno, Grayscale, and Custom.

#![allow(unused)]
fn main() {
use kuva::plot::{DotPlot, ColorMap};
use kuva::render::plots::Plot;

let dot = DotPlot::new()
    .with_data(data)
    .with_color_map(ColorMap::Inferno);
}

API reference

Dice Plot

A dice plot places up to 6 dots in a die-face layout at each intersection of two categorical axes. Each dot position represents a third categorical variable, while dot colour and size can independently encode continuous values. This makes it ideal for compact visualisation of multivariate data across a grid — the canonical use case is displaying differential expression across multiple contrasts, tissues, or conditions in a single figure.

Ported from the ggdiceplot R package (v1.2.0).

Import path: kuva::plot::DicePlot

Categorical mode

Each input record is one observation: (x_cat, y_cat, dot_category, css_color). Dot positions are assigned by matching dot_category against the category labels. Absent positions are not drawn; tile backgrounds are white with a black border.

#![allow(unused)]
fn main() {
use kuva::plot::diceplot::DicePlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let organs = vec!["Lung".into(), "Liver".into(), "Brain".into(), "Kidney".into()];
let data = vec![
    ("miR-1", "Control",    "Lung",   "#2166ac"),
    ("miR-1", "Control",    "Liver",  "#2166ac"),
    ("miR-1", "Control",    "Brain",  "#cccccc"),
    ("miR-1", "Control",    "Kidney", "#2166ac"),
    ("miR-1", "Compound_1", "Lung",   "#2166ac"),
    ("miR-1", "Compound_1", "Liver",  "#cccccc"),
    // ...
];

let dice = DicePlot::new(4)
    .with_category_labels(organs)
    .with_records(data)
    .with_dot_legend(vec![
        ("Down",      "#2166ac"),
        ("Unchanged", "#cccccc"),
        ("Up",        "#b2182b"),
    ])
    .with_position_legend("Organ");

let plots = vec![Plot::DicePlot(dice)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("miRNA Compound Screening")
    .with_x_label("miRNA")
    .with_y_label("Compound");

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

Five miRNAs across five compound treatments. Each cell shows four organ dot positions; colour encodes expression direction (down/unchanged/up). The position legend shows which dot position maps to which organ.

Per-dot continuous mode

Each record is one dot: (x_cat, y_cat, dot_index, fill, size). Each dot gets its own colourmap fill and proportional radius. This is the mode used for ZEBRA-style domino plots where fill encodes log fold change and size encodes significance.

#![allow(unused)]
fn main() {
use std::sync::Arc;
use kuva::plot::diceplot::DicePlot;
use kuva::plot::heatmap::ColorMap;
use kuva::render::plots::Plot;

let diseases = vec![
    "Caries".into(), "Periodontitis".into(), "Healthy".into(), "Gingivitis".into(),
];

let data = vec![
    ("C. showae", "Saliva", 0_usize, Some(2.55), Some(4.82)),
    ("C. showae", "Saliva", 1,       Some(-0.67), Some(1.30)),
    // ...
];

// ggdiceplot's purple-white-green diverging scale
let cmap = ColorMap::Custom(Arc::new(|t: f64| {
    let (r, g, b) = if t < 0.5 {
        let s = t * 2.0;
        (0x40 as f64 + s * (255.0 - 0x40 as f64),
         s * 255.0,
         0x4B as f64 + s * (255.0 - 0x4B as f64))
    } else {
        let s = (t - 0.5) * 2.0;
        (255.0 * (1.0 - s),
         255.0 + s * (0x44 as f64 - 255.0),
         255.0 + s * (0x1B as f64 - 255.0))
    };
    format!("rgb({},{},{})", r as u8, g as u8, b as u8)
}));

let dice = DicePlot::new(4)
    .with_category_labels(diseases)
    .with_dot_data(data)
    .with_color_map(cmap)
    .with_fill_legend("Log2FC")
    .with_size_legend("q-value")
    .with_position_legend("Disease");
}

Six oral bacteria across two specimen types. Each dot represents a disease condition; purple-to-green fill encodes log fold change, dot size encodes statistical significance.

ZEBRA domino plot

The per-dot continuous mode scales to larger grids. This example reproduces the ZEBRA sex DEGs domino plot: 9 genes across 5 cell types with 5 disease contrasts per cell.

Each die face shows five contrasts (MS-CT, AD-CT, ASD-CT, FTD-CT, HD-CT). Fill encodes logFC (purple = down, green = up), size encodes -log10(FDR). Missing dots indicate non-significant results for that contrast.

Continuous tile mode

One record per grid cell via with_points(iter of (x, y, present_vec, fill, size)). The tile background is coloured via the colour map; dot radius encodes a second continuous variable. Present dots are filled black; absent positions show as small hollow outlines.

#![allow(unused)]
fn main() {
use kuva::plot::diceplot::DicePlot;
let data = vec![
    ("Gene_A", "Sample_1", vec![0, 1, 2, 3], Some(0.8), Some(5.0)),
    ("Gene_A", "Sample_2", vec![0, 2],       Some(0.3), Some(2.0)),
    // ...
];

let dice = DicePlot::new(4)
    .with_points(data)
    .with_fill_legend("Expression")
    .with_size_legend("Significance");
}

Legends

DicePlot supports three independent legend sections, stacked vertically in the right margin:

1. Position legend (.with_position_legend("Title")) — mini die faces showing which dot position maps to which category
2. Colour legend (.with_dot_legend(entries)) — colour swatches for categorical mode
3. Size legend (.with_size_legend("Title")) — representative circles at 25%, 50%, 100% of max radius

A colorbar is added via .with_fill_legend("Label") for continuous fill modes.

Pip sizing

Pip (dot) radius is computed using the ggdiceplot 1.2.0 tight-packing algorithm:

1. Compute minimum inter-pip distance and maximum offset from tile center
2. Find the scale factor (s_tight) where pips simultaneously touch each other and tile borders
3. Maximum pip radius = min(border_clearance, inter_pip_gap / 2)
4. Default pip_scale = 0.75 — pips fill 75% of available space
5. When pips would overflow, their positions are shifted toward the tile center

Override with .with_dot_radius(px) for a fixed radius.

API reference

Stacked Area Plot

A stacked area chart places multiple series on top of each other so the reader can see both the individual contribution of each series and the combined total at any x position. It is well suited for showing how a whole is composed of parts over a continuous axis — typically time.

Import path: kuva::plot::StackedAreaPlot

Basic usage

Set the x values with .with_x(), then add series one at a time with .with_series(). Call .with_color() and .with_legend() immediately after each series to configure it — these methods always operate on the most recently added series.

#![allow(unused)]
fn main() {
use kuva::plot::StackedAreaPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let months: Vec<f64> = (1..=12).map(|m| m as f64).collect();

let sa = StackedAreaPlot::new()
    .with_x(months)
    .with_series([420.0, 445.0, 398.0, 510.0, 488.0, 501.0,
                  467.0, 523.0, 495.0, 540.0, 518.0, 555.0])
    .with_color("steelblue").with_legend("SNVs")
    .with_series([ 95.0, 102.0,  88.0, 115.0, 108.0, 112.0,
                   98.0, 125.0, 118.0, 130.0, 122.0, 140.0])
    .with_color("orange").with_legend("Indels")
    .with_series([ 22.0,  25.0,  20.0,  28.0,  26.0,  27.0,
                   24.0,  31.0,  28.0,  33.0,  30.0,  35.0])
    .with_color("mediumseagreen").with_legend("SVs")
    .with_series([ 15.0,  17.0,  14.0,  19.0,  18.0,  18.0,
                   16.0,  21.0,  19.0,  23.0,  21.0,  24.0])
    .with_color("tomato").with_legend("CNVs");

let plots = vec![Plot::StackedArea(sa)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Monthly Variant Counts by Type")
    .with_x_label("Month")
    .with_y_label("Variant count");

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

Four variant types are stacked so the total height of each column shows the aggregate monthly count while the coloured bands show how much each type contributes. The growing trend in SNVs lifts all upper bands over time.

Normalized (100 % stacking)

.with_normalized() rescales each column so all series sum to 100 %, shifting the y-axis to span 0–100 %. Use this when you want to emphasise proportional composition rather than absolute magnitude.

#![allow(unused)]
fn main() {
use kuva::plot::StackedAreaPlot;
let sa = StackedAreaPlot::new()
    .with_x(months)
    // ... add series ...
    .with_normalized();
}

The relative dominance of SNVs (~77 %) is immediately clear and the slight month-to-month shifts in variant-type mix become visible — information that was hidden in the absolute chart by the large SNV counts.

Stroke lines

By default a stroke is drawn along the top edge of each band. .with_strokes(false) removes all outlines for a softer, flat appearance — useful when the colors provide enough contrast.

#![allow(unused)]
fn main() {
use kuva::plot::StackedAreaPlot;
let sa = StackedAreaPlot::new()
    .with_x(months)
    // ... add series ...
    .with_strokes(false);
}

Legend position

.with_legend_position(pos) accepts any LegendPosition variant. The most useful choices for stacked-area plots:

#![allow(unused)]
fn main() {
use kuva::plot::{StackedAreaPlot, LegendPosition};

let sa = StackedAreaPlot::new()
    .with_x(months)
    // ... add series ...
    .with_legend_position(LegendPosition::InsideBottomLeft);
}

Styling

Fill opacity

.with_fill_opacity(f) sets the transparency of every band (default 0.7, range 0.0–1.0). Lower values let background grid lines show through; 1.0 gives fully opaque fills.

Stroke width

.with_stroke_width(px) sets the thickness of the top-edge strokes (default 1.5). Has no effect when .with_strokes(false) is set.

#![allow(unused)]
fn main() {
use kuva::plot::StackedAreaPlot;
let sa = StackedAreaPlot::new()
    .with_x(months)
    // ... add series ...
    .with_fill_opacity(0.9)   // nearly opaque bands
    .with_stroke_width(2.5);  // thicker border lines
}

Colors

If no color is set for a series the built-in fallback palette is used (cycling when there are more than eight series):

steelblue, orange, green, red, purple, brown, pink, gray

Set an explicit color by calling .with_color() immediately after .with_series():

#![allow(unused)]
fn main() {
use kuva::plot::StackedAreaPlot;
let sa = StackedAreaPlot::new()
    .with_x([1.0, 2.0, 3.0])
    .with_series([10.0, 20.0, 15.0]).with_color("#2c7bb6").with_legend("Group A")
    .with_series([ 5.0,  8.0,  6.0]).with_color("#d7191c").with_legend("Group B");
}

API reference

Streamgraph

A streamgraph is a flowing stacked area chart with a displaced baseline. Instead of stacking series from y = 0, the baseline is shifted so the total shape undulates organically around a central axis. This makes it significantly easier to read when there are many overlapping series — the eye can track individual bands as they widen and narrow over time.

Import path: kuva::plot::StreamgraphPlot

Wiggle baseline (default)

The Byron & Wattenberg (2008) wiggle algorithm positions the baseline to minimise the sum of squared slopes across all layer boundaries, keeping the silhouette as flat as possible. This is the canonical "streamgraph" look.

#![allow(unused)]
fn main() {
use kuva::plot::StreamgraphPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;
use kuva::render::palette::Palette;

let pal = Palette::category10();
let weeks: Vec<f64> = (1..=52).map(|w| w as f64).collect();

let sg = StreamgraphPlot::new()
    .with_x(weeks)
    .with_series(firmicutes).with_color(pal[0].to_string()).with_label("Firmicutes")
    .with_series(bacteroidetes).with_color(pal[1].to_string()).with_label("Bacteroidetes")
    // … more series …
    ;

let plots = vec![Plot::Streamgraph(sg)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Gut microbiome — wiggle baseline")
    .with_x_label("Week");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Symmetric baseline (ThemeRiver)

.with_baseline(StreamBaseline::Symmetric) centres the total stack symmetrically around y = 0 at every x. The silhouette mirrors above and below the axis, giving a clear "river" aesthetic.

#![allow(unused)]
fn main() {
use kuva::plot::StreamgraphPlot;
use kuva::render::plots::Plot;
use kuva::plot::streamgraph::StreamBaseline;

let sg = StreamgraphPlot::new()
    /* … data … */
    .with_baseline(StreamBaseline::Symmetric);
}

Zero baseline

.with_baseline(StreamBaseline::Zero) stacks from y = 0 — this is equivalent to a regular stacked area chart but with Catmull-Rom smooth curves.

100 % normalised

.with_normalized() rescales each column to sum to 100 %, revealing proportional composition rather than absolute magnitude. Combines well with .with_legend("") since the y-axis no longer has meaningful units.

#![allow(unused)]
fn main() {
use kuva::plot::StreamgraphPlot;
use kuva::render::plots::Plot;
let sg = StreamgraphPlot::new()
    /* … data … */
    .with_normalized()
    .with_legend("");
}

Layer ordering

Three orderings control which series ends up in the centre vs at the edges:

#![allow(unused)]
fn main() {
use kuva::plot::StreamgraphPlot;
use kuva::render::plots::Plot;
use kuva::plot::streamgraph::StreamOrder;

let sg = StreamgraphPlot::new()
    /* … data … */
    .with_order(StreamOrder::ByTotal)
    .with_legend("Phylum");
}

Inter-stream strokes

.with_stroke() draws a thin white line along the upper edge of each band, improving legibility when adjacent streams have similar hues.

#![allow(unused)]
fn main() {
use kuva::plot::StreamgraphPlot;
use kuva::render::plots::Plot;
let sg = StreamgraphPlot::new()
    /* … data … */
    .with_stroke()
    .with_stream_labels(false)  // strokes + legend instead of inline labels
    .with_legend("");
}

Linear interpolation

.with_linear() disables Catmull-Rom smoothing and uses straight line segments. This gives the familiar angular stacked-area look, useful when the x values are very closely spaced or when sharp transitions should be preserved.

Builder reference

CLI

# Default wiggle streamgraph
kuva streamgraph data.tsv --title "My streamgraph"

# Symmetric baseline, normalised
kuva streamgraph data.tsv --baseline symmetric --normalize

# Linear segments with strokes
kuva streamgraph data.tsv --linear --stroke --no-labels

# Custom columns
kuva streamgraph data.tsv --x-col week --group-col phylum --y-col abundance

CLI flags

See also: Shared flags — output, appearance, axes.

Candlestick Plot

A candlestick chart visualises OHLC (open, high, low, close) data. Each candle encodes four values for a single period:

• The body spans from open to close. Green = close above open (bullish); red = close below open (bearish); gray = close equals open (doji).
• The wicks extend from the body to the period high (upper wick) and low (lower wick).

An optional volume panel shows trading volume as bars below the price chart.

Import path: kuva::plot::CandlestickPlot

Basic usage

Add candles one at a time with .with_candle(label, open, high, low, close). Labels are placed on the x-axis as category ticks and candles are spaced evenly.

#![allow(unused)]
fn main() {
use kuva::plot::CandlestickPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = CandlestickPlot::new()
    .with_candle("Nov 01", 142.50, 146.20, 141.80, 145.30)  // bullish
    .with_candle("Nov 02", 145.40, 147.80, 143.50, 144.10)  // bearish
    .with_candle("Nov 03", 144.10, 144.90, 142.20, 144.10)  // doji
    .with_candle("Nov 04", 143.80, 148.50, 143.20, 147.90)  // bullish
    .with_candle("Nov 05", 147.90, 150.20, 146.30, 149.80); // bullish

let plots = vec![Plot::Candlestick(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Daily OHLC — November")
    .with_x_label("Date")
    .with_y_label("Price (USD)");

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

Twenty trading days showing the full mix of bullish, bearish, and doji candles. The overall upward trend is visible from the rising body positions — two doji sessions (Nov 03 and Nov 21) mark brief pauses in the move.

Volume panel

Attach volume data with .with_volume(iter) then call .with_volume_panel() to render a bar sub-panel below the price chart. Volume bars are colored to match their candle (green for up days, red for down days).

#![allow(unused)]
fn main() {
use kuva::plot::CandlestickPlot;
let plot = CandlestickPlot::new()
    .with_candle("Nov 01", 142.50, 146.20, 141.80, 145.30)
    .with_candle("Nov 02", 145.40, 147.80, 143.50, 144.10)
    // ... more candles ...
    .with_volume([1_250_000.0, 980_000.0 /*, ... */])
    .with_volume_panel();
}

The volume panel occupies the bottom 22 % of the chart area by default. Adjust with .with_volume_ratio(f) — for example .with_volume_ratio(0.30) gives the panel 30 % of the height.

Custom colors

Replace the default green/red/gray with any CSS color string using .with_color_up(), .with_color_down(), and .with_color_doji().

#![allow(unused)]
fn main() {
use kuva::plot::CandlestickPlot;
let plot = CandlestickPlot::new()
    .with_color_up("#00c896")     // teal green
    .with_color_down("#ff4560")   // bright red
    .with_color_doji("#aaaaaa")   // light gray
    .with_candle("Mon", 100.0, 105.8, 99.2, 104.5)
    .with_candle("Tue", 104.5, 106.2, 103.1, 103.4)
    // ...
    ;
}

Numeric x-axis

.with_candle_at(x, label, open, high, low, close) places a candle at an explicit numeric x position, enabling uneven spacing and a true numeric axis. This is useful for quarterly, monthly, or any irregularly spaced data.

When using this mode, set .with_candle_width(w) to a value in data units smaller than the spacing between candles (e.g. 0.15 for quarterly data spaced 0.25 apart).

#![allow(unused)]
fn main() {
use kuva::plot::CandlestickPlot;
let plot = CandlestickPlot::new()
    // x = fractional year; candles spaced 0.25 apart
    .with_candle_at(2023.00, "Q1'23", 110.5, 118.0, 110.0, 116.8)
    .with_candle_at(2023.25, "Q2'23", 116.8, 122.0, 115.5, 121.0)
    .with_candle_at(2023.50, "Q3'23", 121.0, 125.5, 119.0, 120.2)
    .with_candle_at(2023.75, "Q4'23", 120.2, 128.0, 119.8, 127.0)
    .with_candle_width(0.15);
}

Twelve quarters (2022 Q1 – 2024 Q4) on a continuous fractional-year axis. The x-axis tick marks are placed at round numeric values rather than category slots.

Legend

.with_legend(label) adds a legend box inside the plot area identifying the series.

#![allow(unused)]
fn main() {
use kuva::plot::CandlestickPlot;
let plot = CandlestickPlot::new()
    .with_candle("Jan", 100.0, 108.0, 98.0, 106.0)
    .with_candle("Feb", 106.0, 112.0, 104.0, 110.5)
    .with_legend("ACME Corp");
}

Sizing

API reference

Contour Plot

A contour plot draws iso-lines (or filled iso-bands) on a 2D scalar field, connecting all points that share the same z value. It is well suited for visualising any continuous surface: density functions, spatial expression gradients, topographic elevation, or any field that varies over an x–y plane.

Import path: kuva::plot::ContourPlot

Basic usage — iso-lines from a grid

Supply a pre-computed grid with .with_grid(z, x_coords, y_coords). z[row][col] is the scalar value at position (x_coords[col], y_coords[row]). By default, n_levels evenly spaced iso-lines are drawn (default 8).

#![allow(unused)]
fn main() {
use kuva::plot::ContourPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

// Build a 60×60 Gaussian grid over [-3, 3]²
let n = 60_usize;
let coords: Vec<f64> = (0..n)
    .map(|i| -3.0 + i as f64 / (n - 1) as f64 * 6.0)
    .collect();
let z: Vec<Vec<f64>> = coords.iter()
    .map(|&y| coords.iter()
        .map(|&x| (-(x * x + y * y) / 2.0).exp())
        .collect())
    .collect();

let cp = ContourPlot::new()
    .with_grid(z, coords.clone(), coords)
    .with_n_levels(10)
    .with_line_color("steelblue")
    .with_line_width(1.2);

let plots = vec![Plot::Contour(cp)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Iso-line Contours — Gaussian Peak")
    .with_x_label("x")
    .with_y_label("y");

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

Ten evenly spaced iso-lines trace the nested ellipses of the Gaussian peak. A fixed line color is used here; without .with_line_color() each iso-line would be colored by the active colormap.

Filled contours

.with_filled() fills each band between adjacent iso-levels using the colormap. .with_legend(label) enables a colorbar in the right margin.

#![allow(unused)]
fn main() {
use kuva::plot::ContourPlot;
use kuva::render::plots::Plot;
let cp = ContourPlot::new()
    .with_grid(z, xs, ys)
    .with_n_levels(9)
    .with_filled()
    .with_legend("Density");
}

A bimodal surface with two overlapping peaks. The Viridis colormap maps low z values to purple/blue and high values to yellow. The colorbar on the right shows the full z range.

Scattered input — IDW interpolation

.with_points(iter) accepts an iterator of (x, y, z) triples at arbitrary positions — no regular grid required. The values are interpolated onto an internal 50×50 grid using inverse-distance weighting (IDW) before iso-lines are computed. This is the natural input mode for spatial data such as tissue sample coordinates or irregular sensor readings.

#![allow(unused)]
fn main() {
use kuva::plot::{ContourPlot, ColorMap};
use kuva::render::plots::Plot;
// 121 sample points from a bimodal function
let pts: Vec<(f64, f64, f64)> = (-5..=5)
    .flat_map(|i| (-5..=5).map(move |j| {
        let (x, y) = (i as f64, j as f64);
        let z = (- ((x - 1.5) * (x - 1.5) + (y - 1.5) * (y - 1.5)) / 4.0).exp()
              + 0.7 * (- ((x + 2.0) * (x + 2.0) + (y + 1.5) * (y + 1.5)) / 3.0).exp();
        (x, y, z)
    }))
    .collect();

let cp = ContourPlot::new()
    .with_points(pts)
    .with_n_levels(8)
    .with_filled()
    .with_colormap(ColorMap::Inferno)
    .with_legend("Value");
}

The Inferno colormap with filled bands on IDW-interpolated data. Denser point clouds produce sharper interpolations; the 50×50 internal grid is fixed regardless of input count.

Explicit iso-levels

.with_levels(&[…]) pins the iso-lines to specific z values. This overrides n_levels. Use it when lines should correspond to meaningful thresholds — specific expression cutoffs, probability contours, or fixed elevation intervals.

#![allow(unused)]
fn main() {
use kuva::plot::ContourPlot;
use kuva::render::plots::Plot;
let (z, xs, ys) = (vec![vec![0.0f64]], vec![0.0f64], vec![0.0f64]);
let cp = ContourPlot::new()
    .with_grid(z, xs, ys)
    .with_levels(&[0.1, 0.25, 0.5, 0.75, 0.9])
    .with_line_color("darkgreen")
    .with_line_width(1.5);
}

Five explicit iso-lines at z = 0.1, 0.25, 0.5, 0.75, 0.9 on the same Gaussian. The innermost ring at 0.9 is very tight around the peak; the outermost at 0.1 reaches almost to the grid boundary.

Line color

By default each iso-line is colored using the active colormap. .with_line_color(s) overrides this with a single fixed color for all lines — useful for clean black-and-white figures or when the colormap is reserved for a filled background.

#![allow(unused)]
fn main() {
use kuva::plot::ContourPlot;
let (z, xs, ys) = (vec![vec![0.0f64]], vec![0.0f64], vec![0.0f64]);
let cp = ContourPlot::new()
    .with_grid(z, xs, ys)
    .with_line_color("navy")    // all iso-lines in navy
    .with_line_width(1.2);
}

Color maps

.with_colormap(map) selects the colormap (default Viridis). The same ColorMap variants available for heatmaps apply: Viridis, Inferno, Grayscale, and Custom.

#![allow(unused)]
fn main() {
use kuva::plot::{ContourPlot, ColorMap};
let (z, xs, ys) = (vec![vec![0.0f64]], vec![0.0f64], vec![0.0f64]);
let cp = ContourPlot::new()
    .with_grid(z, xs, ys)
    .with_filled()
    .with_colormap(ColorMap::Inferno)
    .with_legend("Density");
}

API reference

Chord Diagram

A chord diagram arranges N nodes around a circle and connects them with ribbons whose widths are proportional to flow magnitudes from an N×N matrix. Each node occupies an arc on the outer ring; arc length is proportional to the node's total flow. It is well suited for showing pairwise relationships in network data — co-occurrence, migration, regulatory influence, or any square flow matrix.

Import path: kuva::plot::ChordPlot

Basic usage

Supply an N×N matrix with .with_matrix() and node labels with .with_labels(). The diagram renders in pixel space — no x/y axis system is used. A title set on the Layout is still shown.

#![allow(unused)]
fn main() {
use kuva::plot::ChordPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

// Co-clustering proximity scores between PBMC cell types
let matrix = vec![
    //         CD4T   CD8T    NK   Bcell   Mono
    vec![   0.0, 120.0,  70.0,  40.0,  25.0],  // CD4 T
    vec![ 120.0,   0.0,  88.0,  32.0,  18.0],  // CD8 T
    vec![  70.0,  88.0,   0.0,  15.0,  35.0],  // NK
    vec![  40.0,  32.0,  15.0,   0.0,  10.0],  // B cell
    vec![  25.0,  18.0,  35.0,  10.0,   0.0],  // Monocyte
];

let chord = ChordPlot::new()
    .with_matrix(matrix)
    .with_labels(["CD4 T", "CD8 T", "NK", "B cell", "Monocyte"]);

let plots = vec![Plot::Chord(chord)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("PBMC Cell Type Co-clustering");

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

The symmetric matrix means each ribbon has equal width at both ends. The CD4 T–CD8 T ribbon is the widest because those two cell types have the highest co-clustering score (120); B cell–Monocyte is the thinnest (10). Colors come from the default category10 palette.

Asymmetric (directed) flows

When matrix[i][j] ≠ matrix[j][i], flows are directed — for example regulatory influence, migration counts, or transition probabilities. The ribbon is thicker at the source end (high outgoing flow) and thinner at the target end.

Use .with_colors() to assign explicit per-node colors, and .with_legend() to show a color-coded node legend.

#![allow(unused)]
fn main() {
use kuva::plot::ChordPlot;
use kuva::render::plots::Plot;
// Directed regulatory influence between five transcription factors
let matrix = vec![
    vec![ 0.0, 85.0, 20.0, 45.0, 10.0],  // TF1 → others
    vec![15.0,  0.0, 65.0, 30.0,  8.0],  // TF2 → others
    vec![30.0, 12.0,  0.0, 75.0, 25.0],  // TF3 → others
    vec![ 5.0, 40.0, 18.0,  0.0, 90.0],  // TF4 → others
    vec![50.0,  8.0, 35.0, 12.0,  0.0],  // TF5 → others
];

let chord = ChordPlot::new()
    .with_matrix(matrix)
    .with_labels(["TF1", "TF2", "TF3", "TF4", "TF5"])
    .with_colors(["#e6194b", "#3cb44b", "#4363d8", "#f58231", "#911eb4"])
    .with_gap(3.0)
    .with_legend("Transcription factors");
}

TF4→TF5 (90) and TF1→TF2 (85) are the strongest regulatory edges. Asymmetry is visible — the TF4→TF5 ribbon is much thicker at the TF4 end than the TF5→TF4 end (5). The legend in the top-right corner maps each color to its node label.

Gap and opacity

.with_gap(degrees) controls the white space between adjacent arc segments (default 2.0°). Larger gaps make individual nodes easier to distinguish at the cost of compressing arc lengths.

.with_opacity(f) sets ribbon transparency (default 0.7). Reducing opacity helps readability when many ribbons overlap in the centre.

#![allow(unused)]
fn main() {
use kuva::plot::ChordPlot;
let matrix = vec![vec![0.0_f64; 5]; 5];
let chord = ChordPlot::new()
    .with_matrix(matrix)
    .with_labels(["CD4 T", "CD8 T", "NK", "B cell", "Monocyte"])
    .with_gap(6.0)       // default 2.0 — wider arc separation
    .with_opacity(0.45); // default 0.7 — more transparent ribbons
}

The same co-clustering data as the basic example. Wider gaps make each cell type's arc clearly separate; the lower opacity lets the arc ring show through the ribbon bundle in the centre.

Matrix layout

The N×N matrix convention:

Arc length for node i is proportional to the row sum of matrix[i]. In a symmetric matrix this equals the column sum, so arcs represent total pairwise interaction strength.

Colors

Without .with_colors(), node colors are assigned automatically from the category10 palette (cycling for more than ten nodes). Supply explicit per-node colors to match publication figures or color-blind-safe palettes:

#![allow(unused)]
fn main() {
use kuva::plot::ChordPlot;
let chord = ChordPlot::new()
    .with_matrix(vec![vec![0.0, 1.0], vec![1.0, 0.0]])
    .with_labels(["Group A", "Group B"])
    .with_colors(["#377eb8", "#e41a1c"]);   // ColorBrewer blue / red
}

API reference

Network Plot

A network (graph) plot visualises nodes connected by edges, laid out with a force-directed (Fruchterman-Reingold), Kamada-Kawai, or circular algorithm. It is well suited for showing gene regulatory networks, protein-protein interactions, social graphs, or any pairwise relationship data. Edge weight can control stroke width, edges can be directed (arrowheads) or undirected, and nodes can be coloured by group.

Import path: kuva::plot::NetworkPlot

Basic usage

Supply edges with .with_edge(source, target, weight). Nodes are auto-created from edge endpoints. The force-directed layout places connected nodes closer together.

#![allow(unused)]
fn main() {
use kuva::plot::NetworkPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let net = NetworkPlot::new()
    .with_edge("TP53", "MDM2", 0.95)
    .with_edge("TP53", "BAX", 0.82)
    .with_edge("TP53", "CDKN1A", 0.78)
    .with_edge("MDM2", "TP53", 0.88)
    .with_edge("BRCA1", "TP53", 0.65)
    .with_edge("BRCA1", "RAD51", 0.72)
    .with_edge("RAD51", "BRCA2", 0.68)
    .with_edge("BRCA2", "BRCA1", 0.55)
    .with_edge("MYC", "CCND1", 0.91)
    .with_edge("MYC", "CDK4", 0.74)
    .with_edge("CCND1", "CDK4", 0.83)
    .with_labels();

let plots = vec![Plot::Network(net)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Gene Interaction Network");

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

Edge thickness is proportional to weight. The Fruchterman-Reingold layout clusters tightly connected nodes (the TP53-MDM2 hub) while spacing out loosely connected components.

Directed edges

Use .with_directed() to draw arrowheads indicating edge direction — useful for regulatory networks, citation graphs, or state machines.

#![allow(unused)]
fn main() {
use kuva::plot::NetworkPlot;
use kuva::render::plots::Plot;
let net = NetworkPlot::new()
    .with_edge("TP53", "MDM2", 0.95)
    .with_edge("MDM2", "TP53", 0.88)
    .with_edge("CDK4", "RB1", 0.79)
    .with_edge("RB1", "E2F1", 0.86)
    .with_edge("E2F1", "MYC", 0.62)
    .with_directed()
    .with_labels();
}

Arrowheads point from source to target. Reciprocal edges (TP53 <-> MDM2) are drawn as two separate arrows. Edge lines stop at the node boundary so arrowheads are clearly visible.

Grouped nodes with legend

Assign nodes to groups with .with_node_group() for automatic colour-coding. Use .with_legend() to display a colour key. Combine with .with_layout(NetworkLayout::Circle) for a circular arrangement.

#![allow(unused)]
fn main() {
use kuva::plot::network::{NetworkPlot, NetworkLayout};
use kuva::render::plots::Plot;
let net = NetworkPlot::new()
    .with_edge("TP53", "MDM2", 0.95)
    .with_edge("BRCA1", "RAD51", 0.72)
    .with_edge("MYC", "CCND1", 0.91)
    .with_edge("TP53", "RB1", 0.45)
    .with_node_group("TP53", "DNA damage")
    .with_node_group("MDM2", "DNA damage")
    .with_node_group("BRCA1", "DNA repair")
    .with_node_group("RAD51", "DNA repair")
    .with_node_group("MYC", "Cell cycle")
    .with_node_group("CCND1", "Cell cycle")
    .with_node_group("RB1", "Cell cycle")
    .with_layout(NetworkLayout::Circle)
    .with_labels()
    .with_legend("Pathway");
}

Nodes are coloured by group using the category10 palette. The legend maps each colour to its group label. The circle layout spaces nodes evenly around the perimeter.

Input formats

Edge list (builder API)

The primary input: call .with_edge(source, target, weight) or .with_edges(iter). Nodes are auto-created from edge endpoints.

Adjacency matrix

Use .with_matrix(matrix, labels) to build from an N×N matrix. Non-zero entries become edges; the value is the weight. For undirected graphs (default), only the upper triangle is read.

#![allow(unused)]
fn main() {
use kuva::plot::NetworkPlot;
let matrix = vec![
    vec![0.0, 1.0, 1.0],
    vec![1.0, 0.0, 1.0],
    vec![1.0, 1.0, 0.0],
];
let net = NetworkPlot::new()
    .with_matrix(matrix, ["A", "B", "C"]);
}

Layout algorithms

User-supplied positions can pin individual nodes with .with_node_position(label, x, y) in normalised [0, 1] space; unpinned nodes are placed by the layout algorithm.

Self-loops

Self-loops (source == target) are rendered as a small arc pointing outward from the graph centre. They work with both directed (arrowhead) and undirected modes.

API reference

Sankey Diagram

A Sankey diagram arranges nodes in columns and connects them with tapered ribbons whose widths are proportional to flow magnitude. It is well suited for showing multi-stage flows — energy transfer, budget allocation, data processing pipelines, or any directed network where quantities must be conserved through each stage.

Import path: kuva::plot::SankeyPlot

Basic usage

Add directed links with .with_link(source, target, value). Nodes are created automatically from the label strings; column positions are inferred by tracing the flow graph from left to right.

#![allow(unused)]
fn main() {
use kuva::plot::SankeyPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let sankey = SankeyPlot::new()
    .with_link("Input", "Process A", 50.0)
    .with_link("Input", "Process B", 30.0)
    .with_link("Process A", "Output X", 40.0)
    .with_link("Process A", "Output Y", 10.0)
    .with_link("Process B", "Output X", 10.0)
    .with_link("Process B", "Output Y", 20.0);

let plots = vec![Plot::Sankey(sankey)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Energy Flow");

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

Node heights are proportional to the larger of incoming and outgoing flow at each node. Colors come from the default category10 palette. Each label is printed to the left or right of its column.

Node colors & legend

Set per-node fill colors with .with_node_color(label, color). Call .with_legend("") to enable the legend; each node's name becomes an entry label automatically.

#![allow(unused)]
fn main() {
use kuva::plot::SankeyPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let sankey = SankeyPlot::new()
    .with_node_color("Input",     "#888888")
    .with_node_color("Process A", "#377eb8")
    .with_node_color("Process B", "#4daf4a")
    .with_node_color("Output",    "#984ea3")
    .with_link("Input",     "Process A", 40.0)
    .with_link("Input",     "Process B", 30.0)
    .with_link("Process A", "Output",    35.0)
    .with_link("Process B", "Output",    25.0)
    .with_node_width(24.0)
    .with_legend("Stage");

let plots = vec![Plot::Sankey(sankey)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Node Colors & Legend");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Ribbons inherit the source node color by default. To color nodes without linking them first (e.g. to control palette order), use .with_node(label) to declare a node explicitly before adding links.

Link coloring

Gradient ribbons

.with_gradient_links() renders each ribbon as a linear gradient from the source node color to the target node color.

#![allow(unused)]
fn main() {
use kuva::plot::SankeyPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let sankey = SankeyPlot::new()
    .with_node_color("Budget",    "#e41a1c")
    .with_node_color("R&D",       "#377eb8")
    .with_node_color("Marketing", "#4daf4a")
    .with_node_color("Ops",       "#ff7f00")
    .with_node_color("Product A", "#984ea3")
    .with_node_color("Product B", "#a65628")
    .with_link("Budget",    "R&D",       40.0)
    .with_link("Budget",    "Marketing", 25.0)
    .with_link("Budget",    "Ops",       35.0)
    .with_link("R&D",       "Product A", 25.0)
    .with_link("R&D",       "Product B", 15.0)
    .with_link("Marketing", "Product A", 15.0)
    .with_link("Marketing", "Product B", 10.0)
    .with_link("Ops",       "Product A", 20.0)
    .with_link("Ops",       "Product B", 15.0)
    .with_gradient_links()
    .with_link_opacity(0.6);

let plots = vec![Plot::Sankey(sankey)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Budget Allocation — Gradient Ribbons");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
}

Per-link colors

For full control, supply a color on each link individually with .with_link_colored(), then call .with_per_link_colors() to activate that mode:

#![allow(unused)]
fn main() {
use kuva::plot::SankeyPlot;
let sankey = SankeyPlot::new()
    .with_link_colored("Budget", "R&D",       40.0, "#377eb8")
    .with_link_colored("Budget", "Marketing", 25.0, "#e41a1c")
    .with_link_colored("Budget", "Ops",       35.0, "#4daf4a")
    // …remaining links…
    .with_per_link_colors()
    .with_link_opacity(0.55);
}

Bulk link loading

.with_links() accepts any iterator of (source, target, value) triples, which is convenient when links come from a data file or computed table:

#![allow(unused)]
fn main() {
use kuva::plot::SankeyPlot;
let edges: Vec<(&str, &str, f64)> = vec![
    ("A", "B", 10.0),
    ("A", "C", 20.0),
    ("B", "D", 10.0),
    ("C", "D", 20.0),
];

let sankey = SankeyPlot::new().with_links(edges);
}

Column layout