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 regularChartobjects. - Zero system dependencies — no Cairo, no X11, no display server. Renders anywhere
pip installworks. - 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 byanywidgetfor Jupyter.
Themes
Twelve built-in themes — from warm cream (Paper Ink, the default) to dark, publication, and editorial styles.
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
Documentation
Full docs at ferrumviz.com.
License
See LICENSE for details.
1 maintainer
Metadata
1 maintainer
Release files for ferrum-viz 0.22.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ferrum_viz-0.22.0.tar.gz | 6.3 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| ferrum_viz-0.22.0-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| ferrum_viz-0.22.0-cp310-abi3-musllinux_1_2_x86_64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ x86-64 | Details |
| ferrum_viz-0.22.0-cp310-abi3-musllinux_1_2_aarch64.whl | CPython 3.10 | abi3 | Linux musl 1.2+ ARM64 | Details |
| ferrum_viz-0.22.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| ferrum_viz-0.22.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| ferrum_viz-0.22.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64, macOS 10.12+ universal2 (ARM64, x86-64), macOS 11.0+ ARM64 | Details |
Total release size: 66.8 MB
Release files / ferrum_viz-0.22.0.tar.gz
| Download URL | ferrum_viz-0.22.0.tar.gz |
|---|---|
| Size | 6.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a1d9d3c57855b0480849065c7a75637089b24435b17d676cf20adf4ce14bc773
|
|
BLAKE2b-256 checksum How to use checksums |
4679c0cbabe0b759bf2ee5b1fba4f70bedfdce53794e9011d2201f37cb292704
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / ferrum_viz-0.22.0-cp310-abi3-win_amd64.whl
| Download URL | ferrum_viz-0.22.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 9.4 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
3e50a9525cf605509f344aa814309503495be6240f72236aa788dbcf8e6bf0f8
|
|
BLAKE2b-256 checksum How to use checksums |
612e03639d6e6053bcb1300b8cb977317dd4f05a0beaaceebd4caf667e574065
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / ferrum_viz-0.22.0-cp310-abi3-musllinux_1_2_x86_64.whl
| Download URL | ferrum_viz-0.22.0-cp310-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 9.4 MB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
38332c1c6168515e3436100d4ddf7737e98f1de993321c472e550d27d16befb9
|
|
BLAKE2b-256 checksum How to use checksums |
9ebc6999f839115b60b5a9f8dfb63aeedcb16d4148df7a7a5b01f55b4cd10605
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / ferrum_viz-0.22.0-cp310-abi3-musllinux_1_2_aarch64.whl
| Download URL | ferrum_viz-0.22.0-cp310-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 8.5 MB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
cf5faf1898cfdb20673fd1f1916b222dfdb0af4b478f9952acdf0fa5fed3504a
|
|
BLAKE2b-256 checksum How to use checksums |
158ccadb598839e389a9f3990d48f12f3bcb4dc71480e045e076b8fc820f3708
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / ferrum_viz-0.22.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | ferrum_viz-0.22.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 9.2 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
9634130d763b37d70496f10edf48164cd58f05de5c6268b6947406c9be1280c2
|
|
BLAKE2b-256 checksum How to use checksums |
e4aabe248aec3979c78f6e701e1a11a4f7fd542cd97369b7d4ae2c291fadfe16
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / ferrum_viz-0.22.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | ferrum_viz-0.22.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 8.3 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
022c09d1f350fb3cb4624aaadb08528ad268b4199b75ae0330fd9c7b495e1aa7
|
|
BLAKE2b-256 checksum How to use checksums |
9447375b5aef5a4e5ef2759f8711093edd7d480959d06f940c9172f8e45503ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / ferrum_viz-0.22.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
| Download URL | ferrum_viz-0.22.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl |
|---|---|
| Size | 15.7 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
0626595c9c6c9e87dc9a98df5785a6e3357ed8c9482f89454f959c08fc945d42
|
|
BLAKE2b-256 checksum How to use checksums |
7f262f8b63172bc1fcb9898b2d58008914f2432e7d158f16158723d859e19614
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency log
