Migrating from plotnine¶

plotnine is the most faithful ggplot2 port in Python — a full grammar-of-graphics implementation with layers, facets, scales, coordinates, and themes. Ferrum inherits the same grammar-first philosophy but replaces the matplotlib rendering backend with a Rust engine, adds model diagnostics, and extends composition beyond faceting.

If you think in ggplot() + geom_*() + facet_*(), the translation to Ferrum is direct.

Concept mapping¶

Key differences¶

Composition beyond faceting¶

plotnine composes layers with + and panels with facet_wrap / facet_grid. That covers faceted views of the same data, but not arbitrary chart arrangements.

Ferrum adds horizontal and vertical concatenation for unrelated charts:

# plotnine — no equivalent for side-by-side unrelated charts
# You'd need patchwork (R) or manual matplotlib subplot management

# Ferrum
scatter = fm.Chart(df).mark_point().encode(x="x", y="y")
histogram = fm.Chart(df).mark_histogram().encode(x="value")
combined = scatter | histogram  # side by side
stacked = scatter & histogram   # top and bottom
combined.save("report.svg")

No matplotlib dependency¶

plotnine renders through matplotlib. Ferrum renders SVG, PNG, and interactive HTML directly from Rust. There is no plt.show(), no figure/axes management, no Cairo or Tk dependency, and no implicit display state.

# plotnine
from plotnine import ggplot, aes, geom_point
p = ggplot(df, aes("x", "y")) + geom_point()
p.save("scatter.svg")  # renders through matplotlib

# Ferrum
import ferrum as fm
chart = fm.Chart(df).mark_point().encode(x="x", y="y")
chart.save("scatter.svg")  # renders through Rust

Scale ceiling¶

plotnine inherits matplotlib's rendering pipeline, which means individual SVG elements per mark. At ~100k marks, renders slow significantly and files balloon. Ferrum's auto-raster transparently switches to rasterized output at high mark counts — the same chart spec works at 100 rows and 10M rows.

DataFrame pluralism¶

plotnine requires pandas. Ferrum accepts polars, pandas, modin, cuDF, dask, ibis, and pyarrow through the same Chart(data) constructor.

Interactive rendering¶

plotnine has no built-in interactivity beyond matplotlib's GUI backends. Ferrum's .interactive() produces a GPU-backed WASM renderer with selections, zoom/pan, linked views, and tooltips — in Jupyter via anywidget or as standalone HTML.

Model diagnostics¶

plotnine has no model evaluation surface. Ferrum includes 44 figure-level helpers and 28 visualizer classes for classification, regression, clustering, and explainability diagnostics — all returning the same Chart objects that compose with grammar operators. See Model diagnostics for the full surface.

Themes are values, not global state¶

plotnine uses theme_set() to mutate global matplotlib rcParams. Ferrum themes are immutable values applied per-chart or scope-bounded via context manager:

# plotnine — global mutation
from plotnine import theme_set, theme_bw
theme_set(theme_bw())

# Ferrum — per-chart or scoped
chart.theme(fm.themes.publication)
# or process-wide (scope-bounded):
with fm.theme_context(fm.themes.dark):
    ...

Statistical transforms in Rust¶

plotnine delegates statistical computation to scipy and statsmodels via matplotlib. Ferrum declares transforms in the chart spec and computes them in Rust — KDE, LOESS, bootstrap CIs, binning, and aggregations run in the engine, not in Python.

Coverage comparison¶

Where to go next¶

• Marks & encodings for the full mark and channel reference.
• Composition for the +, |, & operators.
• Themes for Ferrum's twelve built-in themes.
• Gallery for rendered examples with code.