plotnine 0.16.0 alpha releases

[has2k1]

Pre-releases for plotnine 0.16.0 are now being published to PyPI. This is an early opportunity to try out new features as they're being developed. Some more features will be added in subsequent releases.

Installation

uv pip install --pre plotnine
pip install --pre plotnine

Key Features

Improved Plot Composition

Building on the composition system introduced in v0.15.0, you can now have finer control over how plots are arranged and annotated.

plot_layout - Customize the grid arrangement

Control the number of rows, columns, relative widths/heights, and fill order:

from plotnine import *
from plotnine.data import mtcars, mpg
from plotnine.composition import plot_layout, plot_annotation, inset_element

p1 = ggplot(mtcars, aes("wt", "mpg")) + geom_point()
p2 = ggplot(mtcars, aes("factor(cyl)")) + geom_bar()
p3 = ggplot(mpg, aes("displ", "hwy")) + geom_point()
p4 = ggplot(mpg, aes("class")) + geom_bar() + coord_flip()

# Arrange 4 plots in a 2x2 grid with custom column widths
(p1 + p2 + p3 + p4) + plot_layout(ncol=2, widths=[2, 1])

# Control row heights
(p1 / p2 / p3) + plot_layout(heights=[2, 1, 1])

plot_annotation - Add titles and captions to compositions

Add a title, subtitle, caption, or footer to the entire composition:

cmp = (p1 | p2) / p3
cmp + plot_annotation(
    title="Vehicle Comparisons",
    subtitle="Analyzing weight, cylinders, and displacement",
    caption="Data: mtcars and mpg datasets"
)

You can also theme the composition annotations:

cmp + plot_annotation(
    title="My Dashboard",
    theme=theme(
        plot_title=element_text(size=16, face="bold"),
        figure_size=(10, 8)
    )
)

New footer label for plots and compositions

Plots can now have a footer, set via labs() and styled with theme:

(
    ggplot(mtcars, aes("wt", "mpg"))
    + geom_point()
    + labs(
        title="Fuel Efficiency",
        caption=(
            "I installed an alpha release of plotnine and now I also carry the weighty \n"
            "burden of distinguishing captions from footers. I doubt I will get far."
        ),
        footer=f"Source: Motor Trend 1974 {" "*96} By: Plotnine v0.16.0a3 User",
    )
    + theme(
        plot_caption=element_text(color="brown"),
        plot_footer=element_text(color="#333"),
        plot_footer_background=element_rect(fill="#F2F2F2"),
        plot_footer_line=element_line(color="black", size=0.5)
    )
)

inset_element — Place plots and images inside another plot

Compose a plot, composition, or raster image inside a host plot using fractional coordinates. Adding an inset_element to a composition attaches it to the most recently added plot.

p1 + inset_element(p2, left=0.6, bottom=0.6, right=1, top=1)

p1 + inset_element(p2 | p3, left=0.4, bottom=0.5, right=1, top=1)

You can also inset PIL.Image.Image or numpy.ndarray. The image is letterboxed inside the bounding box so its aspect ratio is preserved, and anchor controls where it sits within the letterbox:

from PIL import Image
logo = Image.open("images/plotnine-hex.png")
p1 + inset_element(logo, 0, 0, .2, .2, anchor="bottom-left")