ggplot-rs 0.35.3

A Rust implementation of ggplot2's Grammar of Graphics
Documentation

ggplot-rs

CI Crates.io npm Documentation codecov License: MIT OR Apache-2.0

A Rust implementation of ggplot2's Grammar of Graphics, rendering through a self-contained SVG backend (no dependencies) or, with the default plotters feature, the plotters SVG/bitmap backend.

Validated against R. Computed layers — binning, density, stacking, QQ/ECDF, LOESS, and axis-tick placement (extended-Wilkinson) — are checked against R ggplot2 4.0.3's ggplot_build() output, so a histogram or a stacked bar comes out where ggplot2 puts it. See validation/.

No polars required. polars is a convenient — and fully optional — input adapter. The core pipeline runs on its own internal DataFrame, so you can plot straight from plain Rust vectors, or from Apache Arrow RecordBatches produced by DuckDB — with polars switched off entirely. See Data Input and Feature Flags.

Gallery

Every image below is produced by examples/gallery.rs — regenerate them all with cargo run --features sf --example gallery (the choropleth needs the sf feature; drop it for the rest). The supplier_leadtime*.png images come from examples/supplier_leadtime.rs, and inventory_twin.png from examples/inventory_twin.rs (its composed SVG, rasterised), and map_tiles.png from examples/map_tiles.rs (--features tiles,plotters).

More chart types

Highcharts-style chart types, each one layer in the grammar (tracked under the highcharts-parity label).

Family Builders
Business / KPI geom_waterfall, geom_pareto, geom_bullet, geom_funnel, geom_pyramid, geom_variwide, geom_marimekko, geom_lollipop, geom_dumbbell
Time geom_stream (stack offsets), Interpolate splines on line/area/ribbon, geom_timeline, geom_xrange (Gantt), geom_flags
Flows & networks geom_sankey, geom_chord, geom_arcdiagram, geom_network, geom_flow (sf)
Hierarchies geom_treemap, geom_sunburst, geom_icicle, geom_tree / org charts, geom_dendrogram, geom_packed_bubble
Sets & units geom_venn, geom_waffle, geom_parliament, geom_wordcloud, geom_variable_pie
Finance geom_candlestick (filled / hollow), geom_ohlc, geom_hlc, geom_heikin_ashi, geom_renko, geom_point_figure, StatIndicator (SMA, EMA, WMA, Bollinger, MACD, RSI, ATR, VWAP, stochastic, ZigZag)
Maps & weather geom_sf, coord_sf, geom_tilemap (+ us_state_grid), geom_flow (sf), annotation_map_tile (tiles), geom_windbarb
Radial coord_polar, coord_radar, gauges via CoordPolar::with_span

Publication-ready (ggpubr-style)

Journal palettes, theme_pubr(), GAM smoothing, and statistical annotations — the last two need the regression / ggpubr features. Regenerate with cargo run --no-default-features --features regression,ggpubr,plotters --example ggpubr_gallery.

Themes

The same plot under each built-in theme — swap with a single .theme(theme_*()) call.

Quick Start

use ggplot_rs::prelude::*;
use polars::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let df = df! {
        "sepal_length" => [5.1, 4.9, 4.7, 7.0, 6.4],
        "sepal_width"  => [3.5, 3.0, 3.2, 3.2, 3.2],
        "species"      => ["setosa", "setosa", "setosa", "versicolor", "versicolor"],
    }?;

    GGPlot::new(df)
        .aes(Aes::new().x("sepal_length").y("sepal_width").color("species"))
        .geom_point()
        .save("scatter.svg")?;

    Ok(())
}

Features

Geoms

geom_point, geom_line, geom_bar, geom_col, geom_histogram, geom_boxplot, geom_violin, geom_smooth, geom_density, geom_area, geom_ribbon, geom_errorbar, geom_segment, geom_rug, geom_text, geom_label, geom_tile, geom_raster, geom_bin2d, geom_hex, geom_contour, geom_contour_filled, geom_path, geom_step, geom_hline, geom_vline, geom_abline, and more (40+)

  • geom_boxplot(stat = "identity") (0.22): supply the five-number summary directly via Aes::lower/middle/upper (plus the usual ymin/ymax) instead of letting ggplot-rs compute it, with an Aes::outliers("7, 9") comma list (brackets optional) drawn as points that now also widen the y axis to fit them. The box reads tooltip()/data_attr() like any other geom.
  • geom_text/geom_label honour a discrete position_dodge (0.22), landing at the same x as a dodged geom_col's bar centres.
  • geom_errorbar caps shrink under a discrete position_dodge (0.22) by the number of dodged groups, so adjacent caps don't visually overlap.

Stats

StatIdentity, StatCount, StatBin, StatBoxplot, StatSmooth (Lm + Loess), StatDensity, StatLoess, StatSummary, StatEcdf, StatFunction, StatEllipse, StatContour, StatBin2d, StatBinHex, StatSum, StatYDensity, StatQQ, StatSummary2d, StatQuantile (feature regression), and more

Scales

  • Continuous: linear, log10, log2, ln, sqrt, reverse, logit, probit, pseudo-log, reciprocal, exp, and Box–Cox transforms
  • Discrete: automatic categorical mapping
  • Color: discrete palettes (Viridis, Brewer Set1/Dark2, etc.), continuous gradients, diverging gradient2, binned/stepped scales (scale_color_steps/fermenter), manual color assignment
  • Shape & Linetype: discrete mapping for point shapes and line styles
  • scale_size_area(max_size) (0.22): size scale where area — not radius — is proportional to the value, so 0 maps to 0 (ggplot2 parity).
  • Locale-aware labels: GGPlot::locale(Locale::from_tag("de-DE")) renders default axis and legend labels with the locale's marks (1.000, 2,5) and date axes with its month names (Okt. 2026, 15. Okt. 2026); presets en_us, en_gb, de_de, fr_fr. Without it, output is unchanged.
use ggplot_rs::prelude::*;

let de = Locale::from_tag("de-DE");
assert_eq!(label_currency_locale(&de, Some(0.01))(1234.5), "1.234,50 €");
assert_eq!(label_currency_locale(&Locale::en_us(), Some(0.01))(1234.5), "$1,234.50");
assert_eq!(label_percent_locale(&de, None)(0.123), "12,3 %");
assert_eq!(label_number_marks(Some(0.1), "", " kg", 1.0, ",", ".")(1234.56), "1.234,6 kg");

// Plot-wide: German number marks on every default axis/legend, German month names.
let plot = GGPlot::new(df)
    .aes(Aes::new().x("date").y("revenue"))
    .geom_line()
    .scale_y_continuous(ScaleContinuous::new().with_label_formatter(label_currency_locale(&de, None)))
    .locale(de);

Coordinates

coord_cartesian, coord_flip, coord_fixed, coord_polar, coord_trans

Spatial (geom_sf)

Behind the optional sf feature, geom_sf renders simple-features geometry — points, lines, and (multi)polygons with holes — from a geometry column of WKT strings. It uses a self-contained WKT parser, so the spatial layer pulls in no extra dependencies. The fill aesthetic drives a choropleth, and axes/legends/facets come from the rest of the grammar as usual:

let df = df! {
    "geometry"   => ["POLYGON ((0 0, 3 0, 3 2, 0 2, 0 0))", "POLYGON ((3 0, 6 0, 6 3, 3 2, 3 0))"],
    "population" => [4.2, 9.5],
}?;
GGPlot::new(df)
    .aes(Aes::new().fill("population"))
    .geom_sf()
    .scale_fill_viridis_c();

Projections & aspect. Pass a projection to geom_sf and pair it with coord_sf() (equal-aspect, derived from the data extent) for a shape-correct map — e.g. a conformal Web Mercator:

use ggplot_rs::spatial::SfProjection;
use ggplot_rs::geom::sf::GeomSf;

GGPlot::new(df)                        // lon/lat WKT in `geometry`
    .aes(Aes::new().fill("value"))
    .geom_sf_with(GeomSf::default().project(SfProjection::Mercator))
    .coord_sf();

Load GeoJSON. The geojson feature reads a FeatureCollection into a plot-ready frame — geometry → WKT, properties → columns:

use ggplot_rs::spatial::geojson::read_geojson_file;

let cols = read_geojson_file("countries.geojson")?;   // Vec<(String, Vec<Value>)>
GGPlot::new(cols).aes(Aes::new().fill("gdp")).geom_sf();

See examples/spatial.rs (cargo run --features sf --example spatial).

Faceting

facet_wrap and facet_grid with free/fixed scales, proportional panel sizing (space = "free" via facet_grid_space), and multi-variable columns (facet_grid_multi, R's rows ~ b + c). Computed stats (density/histogram) are estimated per panel, and so is position_stack/position_fill (0.22) — a faceted stacked bar no longer mixes rows from different panels into one shared total.

Positions

position_identity, position_dodge/dodge2, position_jitter/jitterdodge, position_nudge, and position_stack/position_fill — both take a vjust (0.22, ggplot2's position_stack(vjust =)): 1 (default) places a segment's label at its top, 0.5 at its centre, 0 at its bottom.

Themes

theme_gray, theme_bw, theme_classic, theme_minimal, theme_dark, theme_light, theme_linedraw, theme_void — plus full customization via ElementText, ElementLine, ElementRect

Annotations

annotate_text, annotate_rect, annotate_segment

Guides & axes

  • Legend inside the panel at panel-relative coords: legend_position_inside(x, y) (R's legend.position = c(x, y)).
  • Axis label rotation: axis_text_x_angle(deg) / axis_text_y_angle(deg) (R's guide_axis(angle = ...)).
  • Label dodging: axis_text_x_dodge(n) staggers crowded x labels across n rows (guide_axis(n.dodge)).
  • Outer-label fit (0.22): axis_text_x_fit(AxisLabelFit::Reserve | Shift | Clip) keeps an outer x label on-canvas instead of letting it cross the SVG edge — Reserve (default) grows the panel margin just enough, Shift moves the label at draw time without resizing the panel, Clip is the pre-0.22 behaviour.
  • check.overlap (0.22): axis_text_x_check_overlap(true) thins crowded x labels in ggplot2's own priority order (first, last, then the busiest middle), off by default.
  • Legend nrow/ncol/byrow and auto-wrap (0.22): guides(GuideLegend::new().with_nrow/ncol(n).with_byrow(true)) lays out an explicit grid (column-major, or row-major with byrow); with neither set, an overflowing single horizontal legend auto-wraps, ending in "+N more" (with_max_rows(n) caps the growth) when it still doesn't fit.
  • Corner tag: tag("A") for figure-panel labels (labs(tag)).
  • Axis position & expansion: ScaleContinuous::with_position_opposite() (x-axis on top / y on the right) and with_expand_sides(...) for per-side expansion.

Call theme-related builders after any theme_*() preset.

Computed aesthetics

An aesthetic can map an expression over columns, not just a bare column name:

GGPlot::new(data)
    .aes(Aes::new().x("log10(gdp)").y("pop / 1e6").color("deaths / cases"))
    .geom_point();

Supports + - * / % ^, parentheses, and ln/log/log10/log2/sqrt/exp/abs/sin/cos/tan/floor/ceil/round/sign. A plain column name is used directly (so existing mappings are unchanged); anything else is parsed and evaluated per row. after_scale_fill_from_color(l) / after_scale_color_from_fill(l) derive one color aesthetic from another's mapped color, lightness-adjusted (after_scale); Aes::stage(aes, start, after_stat) maps an aesthetic at two pipeline stages. The same expressions work in after_stat mappings, plus aggregate functions (sum, mean, max, min, count, median, prod) that reduce over all rows — e.g. .after_stat_y("count / sum(count)") for proportion histograms.

Command-line tool

A ggplot-rs CLI (behind the cli feature) plots parquet/CSV files or DuckDB SQL straight from the shell — DuckDB is the query engine:

cargo install ggplot-rs --features cli

# discover columns first, then plot
ggplot-rs --parquet sales.parquet --describe
ggplot-rs --parquet sales.parquet --x month --y revenue --geom line -o rev.png

# aggregate with SQL (reads parquet globs), faceted bars
ggplot-rs --sql "SELECT region, sum(qty) q FROM 'orders/*.parquet' GROUP BY 1" \
  --x region --y q --geom col --facet-wrap region --theme minimal -o orders.svg

Flags: --x/--y/--color/--fill/--size/--shape/--group, --geom, --facet-wrap/--facet-grid, --log-x/--log-y/--flip, --title/--subtitle/--xlab/--ylab/--caption, -o FILE/--stdout, --width/--height. Run --describe to list a source's columns and types.

Maps from the CLI (--spatial, --geom sf). DuckDB's spatial extension reads shapefiles, GeoJSON, GeoPackage, FlatGeobuf and more (via GDAL). Pass --spatial to load it, then ST_AsText(geom) any geometry into a geometry column and plot it with --geom sf:

ggplot-rs --spatial \
  --sql "SELECT ST_AsText(geom) AS geometry, name, pop_est
         FROM ST_Read('ne_110m_admin_0_countries.shp')" \
  --geom sf --fill pop_est --projection mercator --theme void -o world.png

ST_Read handles the file format; ST_AsText produces WKT that geom_sf consumes; --projection mercator and an equal-aspect coord_sf are applied automatically. Any SQL works, so you can join, filter, or aggregate spatial and tabular data in the same query before plotting.

Theming from the CLI: --theme <preset> (gray/bw/minimal/…), --palette <name> (Set1/Dark2/viridis/RdBu/…), --primary "r,g,b" (brand color), and --theme-config <file> — a TOML/JSON file of element overrides for full custom theming:

ggplot-rs --parquet d.parquet --x a --y b --color g --palette Dark2 --primary "26,153,136" -o p.png
ggplot-rs --parquet d.parquet --x a --y b --color g --theme-config brand.toml -o p.png

# brand.toml — applied on top of the base preset
base = "minimal"
palette = "RdBu"
primary = [200, 60, 40]
[title]
size = 22
color = [40, 40, 90]
[panel_background]
fill = [248, 246, 240]
[panel_grid_major]
linetype = "dashed"
[legend]
position = "inside"
x = 0.9
y = 0.9

AI-ready: the repo ships a Claude Code skill at .claude/skills/plot-data/ that teaches an agent the describe-then-map-then-render workflow, so "plot this parquet" just works.

In the browser (WASM)

npm: @sipemu/ggplot-rs

npm

The same grammar from JavaScript/TypeScript: a typed, layered spec in, an SVG string out. It works in the browser (Vite, plain ESM, Observable) and in Node, with no runtime dependencies. The .wasm file is about 0.6 MB gzipped. See js/README.md for the quickstart and the full spec.

npm i @sipemu/ggplot-rs

import init, { render } from "@sipemu/ggplot-rs";
await init();
const svg = render({
  data: { x: [1, 2, 3], y: [2, 4, 3], g: ["a", "b", "a"] },
  aes: { x: "x", y: "y", color: "g" },
  layers: [{ geom: "point" }, { geom: "line" }],
  facet: { wrap: "g" },
  labels: { title: "Hello from npm" },
});

The npm version always matches the crate version.

The wasm crate

▶ Live demo: https://sipemu.github.io/ggplot-rs/ — DuckDB-Wasm reads Natural Earth countries into a hover-able choropleth, plus a 100k-point scatter via the raster backend.

The crates/ggplot-rs-wasm workspace crate (a cdylib, not published) exposes a plotters-free renderer to JavaScript via wasm-bindgen. It compiles to wasm32 and uses the self-contained SvgBackend, so the bundle needs no polars and no fonts (text is <text>, which the browser draws). The ggplot-rs library itself is a plain rlib with no wasm-specific dependencies, so it also builds for wasm32-unknown-unknown / emscripten targets directly (default-features = false):

wasm-pack build crates/ggplot-rs-wasm --target web --out-dir ../../web/pkg --out-name ggplot_rs

import init, { render_geo } from "./pkg/ggplot_rs.js";
await init();
document.getElementById("plot").innerHTML = render_geo(JSON.stringify({
  geometry: [...wkt], fill: [...nums], label: [...names], projection: "mercator",
}));

Every mark is a real DOM element, so hover works out of the box — each feature carries a <title> tooltip (from a label mapping + the fill value), plus CSS :hover for highlight.

Pair it with DuckDB-Wasm (which loads the same spatial extension) to read shapefiles/GeoJSON and ST_AsText them to WKT entirely client-side.

Large N. SVG is one DOM node per mark (great to ~10k–50k). For more, the canvas feature adds a self-contained RGBA raster backend (render_rgba / render_png_raster, or the wasm crate's render_scatter_rgba) — it rasterises everything in pure Rust (text via ab_glyph), so it's fast and wasm-compatible: 500k points render in a fraction of a second to a bitmap you blit with putImageData. (Or aggregate in DuckDB — GROUP BY, hex-bins, sampling — and render the summary.) See web/ for a runnable demo that fetches Natural Earth countries:

The same render is one CLI command (native, identical render_svg_native path):

ggplot-rs --spatial \
  --sql "SELECT ST_AsText(geom) AS geometry, NAME AS label, ln(POP_EST+1) AS pop
         FROM ST_Read('ne_110m_admin_0_countries.geojson') WHERE NAME <> 'Antarctica'" \
  --geom sf --fill pop --label label --theme void -o world.png

Data Input

GGPlot::new accepts anything implementing the GGData trait. Nothing here requires polars — pick whichever source fits your stack.

Plain Rust — zero optional dependencies:

// Column-oriented
let cols: Vec<(String, Vec<Value>)> = vec![
    ("x".into(), vec![Value::Float(1.0), Value::Float(2.0), Value::Float(3.0)]),
    ("y".into(), vec![Value::Float(4.0), Value::Float(5.0), Value::Float(6.0)]),
];
GGPlot::new(cols)

// Row-oriented
let rows: Vec<HashMap<String, Value>> = vec![/* ... */];
GGPlot::new(rows)

Apache Arrow / DuckDB — feed a RecordBatch straight from a DuckDB query result, with polars switched off:

# Cargo.toml — no polars in the dependency tree (add "plotters" for render_svg/render_png)
ggplot-rs = { version = "0.16", default-features = false, features = ["arrow"] }

let batch: arrow::record_batch::RecordBatch = /* DuckDB query → Arrow */;
GGPlot::new(batch)

polars (optional, enabled by default) — for df! and polars pipelines:

let df = df! {
    "x" => [1.0, 2.0, 3.0],
    "y" => [4.0, 5.0, 6.0],
}?;
GGPlot::new(df)

Rendering

Without plotters (default-features = false) — the self-contained SVG backend, also used in the browser; zero rendering dependencies:

let svg: String = plot.render_svg_native_with_size(800, 600)?;

The remaining methods need the plotters feature (on by default). Save to a file (format inferred from the extension — svg, png, jpg, ...):

plot.save("out.svg")?;              // 800x600 default
plot.save_with_size("out.png", 1200, 800)?;
plot.ggsave("out.png", 6.0, 4.0, 150.0)?; // width_in, height_in, dpi

Or render in memory — no temp files — which is what you want when serving charts from a web/MCP service:

let svg: String   = plot.clone().render_svg()?;          // or render_svg_with_size(w, h)
let png: Vec<u8>  = plot.render_png_with_size(400, 300)?; // fully-encoded PNG bytes

Headless / no system fonts. Rendering uses plotters' ab_glyph text backend with a bundled font (DejaVu Sans), not font-kit/fontconfig — so text renders deterministically in a minimal container with no system fonts installed. Nothing to configure; there is no dependency on the host's font stack.

Theming & brand color

Everything about a theme is set at runtime, so one render process can serve many tenants' brands without touching chart code.

Inject a brand/primary color — it becomes the default for any single-series geom that has no color/fill aesthetic mapped (an explicit mapping always wins):

GGPlot::new(data)
    .aes(Aes::new().x("day").y("count"))
    .geom_col()
    .primary_color((26, 153, 136)) // DataZoo teal — no per-chart color code
    .render_svg()?;

Build a whole Theme at runtime and compose the brand into it:

let theme = theme_minimal().with_primary((26, 153, 136));
GGPlot::new(data).aes(/* … */).geom_line().theme(theme);

Supply an arbitrary sequential ramp (e.g. a green→red risk score) instead of the built-in viridis/brewer scales — pass explicit (offset, color) stops:

GGPlot::new(data)
    .aes(Aes::new().x("x").y("y").color("risk"))
    .geom_point()
    .scale_color_gradientn(vec![
        (0.0, RGBAColor::new(0, 160, 80)),   // low  = green
        (0.5, RGBAColor::new(240, 200, 0)),  // mid  = amber
        (1.0, RGBAColor::new(200, 40, 40)),  // high = red
    ]);

Feature Flags

Feature Default Provides
polars yes impl GGData for polars::DataFrame + polars re-export
plotters yes plotters-backed render_svg, render_png, save, ggsave, ggarrange_png (implies png)
png (yes) PNG encoding via image (pulled in by plotters and canvas)
arrow no impl GGData for arrow::RecordBatch (Arrow/DuckDB input)
regression no stat_quantile/geom_quantile + geom_smooth glm/rlm via anofox-regression
serde no theme::config::ThemeConfig — a serde-deserialisable partial theme overlay (TOML/JSON)
sf no geom_sf / coord_sf — render simple-features (WKT) geometry with projections; no extra deps
geojson no read GeoJSON into a plot-ready frame (spatial::geojson); adds serde_json
canvas no self-contained RGBA raster backend for large-N (render_rgba/render_png_raster); wasm-ok
wasm no deprecated alias for sf (the browser bindings moved to the crates/ggplot-rs-wasm crate)
cli no the ggplot-rs command-line tool (parquet/CSV/DuckDB → SVG/PNG), via clap + bundled DuckDB

To skip the heavy polars and plotters dependencies (e.g. an Arrow-only service that renders with render_svg_native*), disable defaults:

ggplot-rs = { version = "0.16", default-features = false, features = ["arrow"] }

With default-features = false, features = ["sf"] the whole dependency tree is ggplot-rs + indexmap (+ its two dependencies).

Examples

Run any example with:

cargo run --example scatter
cargo run --example histogram
cargo run --example bar_chart
cargo run --example continuous_color
cargo run --example density
cargo run --example faceted
cargo run --example loess_smooth
cargo run --example annotations
cargo run --example coord_flip
cargo run --example log_scale
cargo run --example color_palettes
cargo run --example gallery            # regenerates the gallery above
cargo run --example supplier_leadtime  # polars-free; runs with --no-default-features --features plotters
cargo run --example inventory_twin     # polars-free; SVG with --no-default-features, + PNG with plotters

Dependencies

  • indexmap 2 — ordered maps for internal data
  • plotters 0.3 — SVG/PNG rendering (ab_glyph text backend; no fontconfig) (optional, default)
  • image 0.24 — in-memory PNG encoding (optional, via plotters/canvas)
  • polars 0.46 — DataFrame input (optional, default)
  • arrow 53 — Arrow RecordBatch input (optional)
  • clap 4 + duckdb 1 (bundled) — the cli tool (optional)

License

Licensed under either of

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Bundled font

Bundled fonts in assets/fonts/ — DejaVu Sans (+ Bold/Oblique), Serif (+ Bold/Italic), and Sans Mono (+ Bold) — give headless rendering for family = "serif"/"monospace" and bold/italic (element_text(face=)) with real glyphs, no fontconfig. DejaVu Sans is distributed under a permissive, freely-redistributable license (Bitstream Vera