Ferrum chart examples: linear model, decision boundary, pairplot, SHAP beeswarm

Ferrum

Grammar-of-graphics statistical visualization for Python, with a Rust core.

Ferrum builds every chart — scatter plot, faceted histogram, ROC curve, SHAP beeswarm — from the same grammar of data, encodings, marks, scales, and statistical transforms. The declaration layer is Python; the computation engine is Rust compiled via PyO3.

Install

For 'batteries included'-- ML diagnostic plots and interactive Jupyter rendering:

pip install ferrum-viz[all]   # recommended — optional deps for fitted-model diagnostics (scikit-learn), SHAP, and Jupyter interactive

For a lean install without optional extras:

pip install ferrum-viz

Quickstart

import ferrum as fm
import polars as pl

df = pl.DataFrame({"x": [1, 2, 3, 4], "y": [2, 4, 3, 5], "group": ["a", "a", "b", "b"]})

chart = fm.Chart(df).mark_point().encode(x="x", y="y", color="group:N")
chart.save("scatter.svg")
chart.to_png()  # raster output, no display server needed

Key features

  • One chart model — scatter plots, statistical graphics, and ML diagnostics share the same grammar and compose with +, |, &.
  • Stat transforms in the pipeline — KDE, LOESS, bootstrap CIs, binning, and aggregations are declared in the chart spec and computed in Rust.
  • Model diagnostics as charts — fm.roc_chart(model, X, y), fm.confusion_matrix_chart(...), fm.shap_chart(...) return regular Chart objects.
  • Zero system dependencies — no Cairo, no X11, no display server. Renders anywhere pip install works.
  • DataFrame pluralism — polars, pandas, modin, cuDF, dask, ibis, and pyarrow all work through Chart(data).
  • Interactive rendering — chart.interactive() switches to a GPU-backed WASM renderer with selections, zoom/pan, linked views, and tooltips. Backed by anywidget for Jupyter.

Themes

Twelve built-in themes — from warm cream (Paper Ink, the default) to dark, publication, and editorial styles.

All 12 Ferrum themes

Performance

200,000-point scatter benchmark (median of 3 runs, Apple M-series):

Metric Ferrum plotnine seaborn Altair Plotly
SVG render 27 ms 7.56 s 1.95 s 2.86 s 2.51 s
SVG file size 590 KB 137 MB 32.6 MB 57.8 MB 267 KB
PNG render 78 ms 2.35 s 119 ms — 2.50 s
Interactive HTML 4.9 MB — — 14.3 MB 9.8 MB

At 1M points, Altair OOMs and plotnine takes 39 s. Ferrum renders in 57 ms. Full benchmarks →

How Ferrum compares

Ferrum plotnine seaborn Altair Plotly
Grammar Layered, typed encodings, faceting ggplot2 port, full GoG Convenience helpers Vega-Lite declarative Imperative traces
Diagnostics 44 helpers, 28 visualizers — — — —
Composition + | & operators + layers, facets only Manual subplots | & (Vega-Lite) make_subplots
Interactivity WASM/GPU, selections, linked views matplotlib backends matplotlib backends Vega-Lite selections Plotly.js
Scale ceiling 10M+ rows ~100k marks ~100k marks ~5k rows ~500k marks
DataFrames polars, pandas, modin, cuDF, dask, ibis pandas only pandas only pandas, polars pandas, polars
System deps None matplotlib matplotlib None None
Backend Rust (SVG, raster, WASM) matplotlib matplotlib Vega-Lite (V8) Plotly.js (kaleido)

Detailed migration guides → for plotnine, seaborn, yellowbrick, and scikit-plot.

Examples

# Layer a LOESS trend on a scatter plot
points = fm.Chart(df).mark_point(opacity=0.6).encode(x="x", y="y", color="group:N")
trend = fm.Chart(df).mark_smooth(method="loess").encode(x="x", y="y", color="group:N")
chart = points + trend

# Compose diagnostics into a model report
source = fm.ModelSource(model, X_test, y_test)
report = (fm.roc_chart(source) | fm.confusion_matrix_chart(source)) & fm.importance_chart(source)
report.save("model_report.svg")

# Figure-level helpers
fm.displot(df, x="value", hue="group", kind="kde")
fm.catplot(df, x="species", y="measurement", kind="violin")
fm.pairplot(df, vars=["a", "b", "c"], hue="label")

Architecture

Layer Role
src/ferrum/ Python declaration API — Chart, encodings, marks, themes, plots
crates/ferrum-core/ Rust computation engine — transforms, scales, rendering
Arrow CDI Zero-copy data transport between Python and Rust via pyo3-arrow

Development

Requires Python 3.10+, Rust toolchain, and maturin.

uv sync
unset CONDA_PREFIX && uv run --no-sync maturin develop   # build Rust extension
uv run pytest                                            # run tests

How this was built

[!NOTE] Built in 10 days by one human and an agentic Claude framework. 975 commits · 103k lines · 3,829 tests · 12 phases · 13 agents · 16 skills

Read the retrospective →

Documentation

Full docs at ferrumviz.com.

License

See LICENSE for details.

Project links

Data verified by PyPI on Jul 24, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.21.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for cjsantiago from gravatar.com cjsantiago

Credits

Author: chris-santiago

GitHub Statistics

Data verified by PyPI on Jul 24, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License

Requires

Python >=3.10

Provides Extra

all jupyter models shap

Tags

visualization plotting grammar-of-graphics charts rust statistics diagnostics

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ferrum_viz-0.20.2.tar.gz (5.6 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

ferrum_viz-0.20.2-cp310-abi3-win_amd64.whl (9.1 MB view details)

Uploaded CPython 3.10+Windows x86-64

ferrum_viz-0.20.2-cp310-abi3-musllinux_1_2_x86_64.whl (9.1 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ x86-64

ferrum_viz-0.20.2-cp310-abi3-musllinux_1_2_aarch64.whl (8.2 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

ferrum_viz-0.20.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.8 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

ferrum_viz-0.20.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (8.0 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

ferrum_viz-0.20.2-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (15.2 MB view details)

Uploaded CPython 3.10+macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

File details

Details for the file ferrum_viz-0.20.2.tar.gz.

File metadata

  • Download URL: ferrum_viz-0.20.2.tar.gz
  • Upload date:
  • Size: 5.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for ferrum_viz-0.20.2.tar.gz
Algorithm Hash digest
SHA256 b1b8b14fa99e4d6381a48c3b81a4065e85a2075a767fa3109c4cb0813ffb158b
MD5 b55eac2d66bcf4bfb912c44f021549c0
BLAKE2b-256 9d0f5f4aabdb56e223cfbc34a9ab5f79cede29405f37505e799226f665f6da84

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferrum_viz-0.20.2.tar.gz:

Publisher: publish.yaml on chris-santiago/ferrum

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferrum_viz-0.20.2-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: ferrum_viz-0.20.2-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 9.1 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for ferrum_viz-0.20.2-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 47e48bb10eb54b0dfc087e05be67e56e87a5b6ebdb77c2229f1f81ee1931bdcd
MD5 9c80a5e1709d245281643a2c454a60f0
BLAKE2b-256 82914451e0b1154adcb457843571b4c7950e12ba51dd17efee4c750c10e84d3f

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferrum_viz-0.20.2-cp310-abi3-win_amd64.whl:

Publisher: publish.yaml on chris-santiago/ferrum

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferrum_viz-0.20.2-cp310-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for ferrum_viz-0.20.2-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 f4b37c093d1d3a9adb3c09cbea025282a4cceb05d44d8a99358beabdda948f17
MD5 02d4fafebaea356d5ddc662f93154175
BLAKE2b-256 a02289fd7db120ba6a118b50787dce12a78903489d9e488b7fb5ded6fc8abcfe

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferrum_viz-0.20.2-cp310-abi3-musllinux_1_2_x86_64.whl:

Publisher: publish.yaml on chris-santiago/ferrum

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferrum_viz-0.20.2-cp310-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for ferrum_viz-0.20.2-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 496ea7b6261a21df58cfb11da4dc22e8b4f3410bb4ef7d0df0a11fc88c708743
MD5 12eaf9d27b6ac6f62450bf84e3deb707
BLAKE2b-256 82a18677af206506bb56ecaa2274addf21eab2a8ef38900a4a5f6cfb1677262d

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferrum_viz-0.20.2-cp310-abi3-musllinux_1_2_aarch64.whl:

Publisher: publish.yaml on chris-santiago/ferrum

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferrum_viz-0.20.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for ferrum_viz-0.20.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 14475e73a2daa8606bf275a385f0a810821de8a14072452d2bbca66ecb219d64
MD5 b0d6ee686fc5653b7c6b719092343f61
BLAKE2b-256 a03c6cac006865c2fc62c629ba64e3b64d8a8497f5ccfc8ac53b8eebd4ca76b8

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferrum_viz-0.20.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yaml on chris-santiago/ferrum

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferrum_viz-0.20.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for ferrum_viz-0.20.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 c7d1b1ce8d378116087aaad2b8ef9522ca6e6440474e4b75566bfdd8ed80d932
MD5 8e11550f3916f9a93aec0251f51ee31b
BLAKE2b-256 0a7929bdd345d36e58bfc84b4145b15978c91ecf7edcbc7aaaa5b76cf2a1029c

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferrum_viz-0.20.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish.yaml on chris-santiago/ferrum

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferrum_viz-0.20.2-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

File hashes

Hashes for ferrum_viz-0.20.2-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 5f5b7ced452eacbabfff92905e8ffb24d95dd137d0d5d5539caf9ac5f67fcc4d
MD5 7d97e1297c4db2f14042946a3e8aa5b2
BLAKE2b-256 9d86acf6e128e4da57f30ab6ddd081845725b62d36cb2d1e805ae7dcd7a9471e

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferrum_viz-0.20.2-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl:

Publisher: publish.yaml on chris-santiago/ferrum

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.21.0

7 files

This release

0.20.2 This release

7 files

0.20.1

7 files

0.20.0

7 files

0.19.0

7 files

0.18.2

7 files

0.18.1

7 files

0.18.0

7 files

0.17.1

7 files

0.17.0

7 files

0.16.2

9 files

0.16.1

4 files

0.16.0

4 files

0.15.3

4 files

0.15.2

4 files

0.15.1

4 files

0.15.0

4 files

0.14.0

4 files

0.13.0

4 files

0.12.0

4 files

0.11.2

4 files

0.11.1

4 files

0.11.0

4 files

0.10.0

4 files

0.9.1

4 files

0.9.0

4 files

0.8.3

4 files

0.8.2

4 files

0.8.1

3 files

0.8.0

3 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page