maidr also supports plotnine, the Python implementation of ggplot2’s grammar of graphics. Pass a ggplot to maidr.show(), maidr.render() or maidr.save_html(), and maidr produces a page where the chart can be read from the keyboard, as sound, as text and in braille – what maidr for R does for ggplot2 itself. For the other libraries, see the Matplotlib / Seaborn, Plotly, Bokeh and Altair pages.
plotnine support is experimental. What it reads, and how, may change without a deprecation period, whichever plot type is drawn: see Plot Type Stability. Install it with pip install "maidr[plotnine]".
maidr reads each layer’s own data as plotnine computed it – after the stat, the position adjustment and the scales – rather than the shapes it drew, so a count is the count stat_count made, a stacked segment is announced with its own value, and a box with the five numbers stat_boxplot computed. Each facet panel is a subplot. As you move through a chart, the mark being read is outlined on the plotnine drawing itself.
| plotnine | read as |
|---|---|
geom_bar, geom_col, one bar per category |
bar |
geom_bar, geom_col with position="stack" (the default) |
stacked bar |
geom_bar, geom_col with position="dodge" |
dodged bar |
geom_histogram |
histogram |
geom_point |
point |
geom_line |
line, one series per group |
geom_smooth |
smooth, with its confidence band |
geom_boxplot |
box |
geom_tile with a numeric fill |
heatmap |
facet_wrap, facet_grid |
one subplot per panel |
geom_bar, geom_col with position="fill" |
normalized stacked bar [experimental] |
geom_line, geom_path of recall against precision |
precision-recall curve [experimental] |
stat_summary(fun_data="median_hilow", geom="ribbon") with its median line |
percentile band [experimental] |
Any other geom, a jittered point, or a chart on a coordinate system other than coord_cartesian is left out with a warning naming it, and a chart with nothing maidr can read is shown as a static image. Use maidr.show(p) rather than plotnine’s own p.show() or a notebook’s display of p: those draw the chart as an ordinary matplotlib figure, which maidr cannot read beyond its points.
Each segment is announced with its own count, not the height of the stack it sits on, and a species with no penguins on an island is announced as missing rather than as zero. The series run from the bottom of the stack up.
from plotnine import aes, geom_line, ggplot, labs
from plotnine.data import economics_long
import maidr
two = economics_long[
economics_long["variable"].isin(["psavert", "uempmed"])
& (economics_long["date"].dt.year >= 2000)
]
p = (
ggplot(two, aes("date", "value", color="variable"))
+ geom_line()
+ labs(title="Savings Rate and Unemployment Duration", x="Month", y="Value")
)
maidr.show(p) Each colour is one series, named by its value of the variable color maps.
from plotnine import aes, geom_tile, ggplot, guide_colorbar, guides, labs
from plotnine.data import penguins
import maidr
means = (
penguins.groupby(["species", "island"], observed=True)["body_mass_g"]
.mean()
.round()
.reset_index()
)
p = (
ggplot(means, aes("island", "species", fill="body_mass_g"))
+ geom_tile()
+ guides(fill=guide_colorbar(display="rectangles"))
+ labs(title="Mean Body Mass (g)", x="Island", y="Species", fill="Body Mass (g)")
)
maidr.show(p) Each cell is announced with the value fill maps, not its colour. A species never recorded on an island has no tile, and is announced as missing.
guide_colorbar(display="rectangles") draws the colour bar as a stack of rectangles. plotnine’s default gradient is written to SVG as thousands of shaded triangles, which makes this one chart close to 2 MB; the rectangles look the same and weigh a few tens of kilobytes.
The points and the fitted line are two layers of one subplot; the line carries the bounds of its confidence band at every point.
Each panel is a subplot, titled by its facet as cyl = 4. Press Enter to go into one, Escape to come back out, and the arrow keys between them, in the directions they are laid out on the page.
Each segment is announced as its share of the bar, so the segments of one bar add up to 1.
import pandas as pd
from plotnine import aes, geom_path, ggplot, labs
from sklearn.datasets import make_classification
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split
from sklearn.metrics import precision_recall_curve
from sklearn.naive_bayes import GaussianNB
import maidr
X, y = make_classification(n_samples=600, weights=[0.8], random_state=0)
X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=0)
curves = []
for name, model in [("Logistic regression", LogisticRegression()),
("Naive Bayes", GaussianNB())]:
scores = model.fit(X_train, y_train).predict_proba(X_test)[:, 1]
precision, recall, _ = precision_recall_curve(y_test, scores)
curves.append(pd.DataFrame({"recall": recall, "precision": precision,
"model": name}))
p = (
ggplot(pd.concat(curves), aes("recall", "precision", color="model"))
+ geom_path()
+ labs(title="Precision-Recall Curves", x="Recall", y="Precision")
)
maidr.show(p) A geom_line or geom_path whose x is recall and whose y is precision – by the columns it maps or by its axis titles, with every value from 0 to 1 – is read as a precision-recall curve, one curve per group named as the lines of a multi-line plot are, each read from low recall up. Any other geom_path is left out, since a path need not move left to right.
import numpy as np
import pandas as pd
from plotnine import aes, ggplot, labs, stat_summary
import maidr
rng = np.random.default_rng(1)
months = np.arange(1, 13)
paths = 100 + np.cumsum(rng.normal(2, 5, size=(200, months.size)), axis=1)
sales = pd.DataFrame({"month": np.tile(months, 200), "sales": paths.ravel()})
p = (
ggplot(sales, aes("month", "sales"))
+ stat_summary(fun_data="median_hilow", geom="ribbon", alpha=0.3,
fun_args={"confidence_interval": 0.8})
+ stat_summary(fun_y=np.median, geom="line")
+ labs(title="Simulated Sales", x="Month", y="Sales")
)
maidr.show(p) median_hilow draws the band between the 10th and 90th percentiles of the observations at each month (the middle 95% unless confidence_interval says otherwise), and the line is their median. Together they are one percentile band: each month is entered on the median, announced with the band around it, and Up and Down move to the 90th and 10th percentiles. The band is read only with its median line, from one group per panel on a linear y scale; a ribbon on its own is left out.
maidr.save_html(p, "chart.html") writes the same page to a file, and maidr.render(p) returns it as HTML for a Shiny or Streamlit app. plotnine draws through matplotlib, so use_cdn behaves exactly as it does for a matplotlib figure, and use_cdn=False gives a page that works offline.