charcoal

A declarative, DataFrame-native chart library for Polars. No browser. No Python. No C FFI.

[dependencies]
charcoal = "0.1.1"

Quickstart

use charcoal::{Chart, Theme};
use polars::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let df = DataFrame::new(vec![
        Series::new("x",     &[1.0f64, 2.0, 3.0, 4.0, 5.0]),
        Series::new("y",     &[2.3f64, 3.1, 2.8, 4.5, 3.9]),
        Series::new("group", &["a", "a", "b", "b", "b"]),
    ])?;

    let chart = Chart::scatter(&df)
        .x("x")
        .y("y")
        .color_by("group")
        .title("My First Chart")
        .theme(Theme::Default)
        .build()?;

    chart.save_svg("output.svg")?;
    chart.save_html("output.html")?;
    Ok(())
}

Chart Types

Chart	Method	Required Columns
Scatter	`Chart::scatter(&df)`	`.x()`, `.y()`
Line	`Chart::line(&df)`	`.x()`, `.y()`
Bar	`Chart::bar(&df)`	`.x()`, `.y()`
Histogram	`Chart::histogram(&df)`	`.x()`
Heatmap	`Chart::heatmap(&df)`	`.x()`, `.y()`, `.z()`
Box Plot	`Chart::box_plot(&df)`	`.x()`, `.y()`
Area	`Chart::area(&df)`	`.x()`, `.y()`

Output Formats

Format	Method	Feature Flag
SVG string	`chart.svg()`	none
SVG file	`chart.save_svg("out.svg")`	none
Standalone HTML	`chart.save_html("out.html")`	none
PNG / JPEG / WEBP	`chart.save_png("out.png")`	`static`
evcxr notebook	`chart.display()`	`notebook`

Feature Flags

Feature	Enables	Extra Dependencies
(default)	SVG and HTML output	—
`static`	PNG/JPEG/WEBP raster export	`resvg` (pure Rust)
`notebook`	Inline display in evcxr	`evcxr_runtime`
`ndarray`	`Array2<f64>` input for heatmaps	`ndarray`
`interactive`	Plotly.js interactive HTML export	none

Themes

Theme::Default     // clean light theme
Theme::Dark        // dark background
Theme::Minimal     // no gridlines, minimal chrome
Theme::Colorblind  // Wong 8-color palette

Error Quality

charcoal errors tell you what went wrong, where, and what to do next:

CharcoalError::ColumnNotFound
  column "sepal_lenght" not found
  Did you mean: sepal_length
  Available: sepal_length, sepal_width, petal_length, petal_width, species

Null Handling

Every column role has a documented null policy. Nulls are never silently dropped without a warning. Access warnings after rendering:

let chart = Chart::scatter(&df)
    .x("sepal_length")
    .y("sepal_width")
    .build()?;

for warning in chart.warnings() {
    eprintln!("warning: {warning}");
}

Row Limits

Above 500k rows: warning emitted, scatter points subsampled
Above 1M rows: .build() returns Err(CharcoalError::DataTooLarge)

Configure the limit via the builder:

Chart::scatter(&df)
    .x("x")
    .y("y")
    .row_limit(2_000_000)
    .build()?;

Alternatives

Plotters is a low-level drawing library that gives you full control over rendering primitives, but axis scaling, layout, and data mapping are all your responsibility. charcoal trades that flexibility for a DataFrame-in, chart-out API: if your data is already in Polars, charcoal needs one builder chain where Plotters needs a full rendering pipeline.

plotly wraps Plotly.js and produces rich interactive charts, but output requires a browser and a JavaScript runtime at view time. charcoal targets static, self-contained SVG and HTML — no JavaScript engine, no network dependency, embeddable anywhere.

charts-rs produces SVG output with a similar philosophy but uses a JSON/config-driven API and has no Polars integration. charcoal is built around Polars DataFrames as the primary input, so column selection, null handling, and type inference come for free.

License

Licensed under either of MIT or Apache 2.0 at your option.

charcoal 0.1.1