plotnine 0.16.0 alpha releases

No file, test, or entry point is named; the body is a release announcement with installation commands and feature examples. Review the documented examples first, then identify the intended documentation location and a specific update with maintainers. Done is not defined by this issue alone.

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:

import math

import pandas as pd

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])

Use axes and axis_title to show one shared axis between composed plots

def drive(code, label):
  return (
      ggplot(mpg[mpg["drv"] == code], aes("displ", "hwy"))
      + geom_point(alpha=0.6)
      + scale_x_continuous(limits=(1.5, 7.5))
      + scale_y_continuous(limits=(10, 45))
      + labs(title=label)
  )

d1 = drive("4", "four-wheel")
d2 = drive("f", "front-wheel")
d3 = drive("r", "rear-wheel")

(d1 | d2 | d3) + plot_layout(axes="collect")

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")

Secondary axes

Add a second axis to either dimension. Either transforming the primary axis one-to-one with sec_axis or as a copy of it with dup_axis:

(
    ggplot(mtcars, aes("wt", "mpg"))
    + geom_point()
    + scale_y_continuous(sec_axis=sec_axis(lambda x: x * 0.354006, name="km/L"))
    + scale_x_continuous(sec_axis=dup_axis())
)

Strip position and placement

facet_wrap gained a strip_position parameter, which puts the strips on any
side of the panel.

(
    ggplot(mpg, aes("displ", "hwy"))
    + geom_point()
    + facet_wrap("drv", strip_position="bottom")
    + scale_x_continuous(position="top")
    + theme(strip_placement="outside")
)

Polar Coordinates

(
    ggplot(mpg, aes("class", fill="class"))
    + geom_bar()
    + coord_radial(inner_radius=0.1)
    + theme(legend_position="none")
)

(
    ggplot(mtcars, aes("wt", "mpg"))
    + geom_point()
    + coord_radial(start=-math.pi / 2, end=math.pi / 2, inner_radius=0.3)
    + theme(
        axis_line_theta=element_line(color="maroon"),
        axis_ticks_major_theta=element_line(color="maroon"),
        axis_text_theta=element_text(color="maroon"),
        axis_line_r=element_line(color="steelblue"),
        axis_ticks_major_r=element_line(color="steelblue"),
        axis_text_r=element_text(color="steelblue"),
    )
)

Contours

geom_contour and geom_contour_filled represent a gridded surface in two dimensions. The x and y values must form a grid with one z value per coordinate.

from plotnine.data import faithful, faithfuld

(
    ggplot(faithfuld, aes("waiting", "eruptions", z="density"))
    + geom_contour(aes(color=after_stat("level")))
)

(
    ggplot(faithfuld, aes("waiting", "eruptions", z="density"))
    + geom_contour_filled()
)

geom_density_2d_filled is the filled counterpart of geom_density_2d. It estimates the density of raw points and fills the bands between contours.

(
    ggplot(faithful, aes("waiting", "eruptions"))
    + geom_density_2d_filled()
)

Polygons with holes

geom_polygon gained a subgroup aesthetic, which identifies the rings within one polygon. The first ring forms the exterior, and each later ring with the opposite winding direction cuts a hole. Filled contour bands are drawn this way.

square = pd.DataFrame({
    "x": [0, 4, 4, 0, 1, 1, 3, 3],
    "y": [0, 0, 4, 4, 1, 3, 3, 1],
    "subgroup": [0, 0, 0, 0, 1, 1, 1, 1],
})

(
    ggplot(square, aes("x", "y", subgroup="subgroup"))
    + geom_polygon(fill="#3B6E8F", color="black", size=1)
)

I() for positioning relative to the panel and literal values

(
    ggplot(mpg, aes("displ", "hwy"))
    + geom_point()
    + annotate("text", x=3, y=I(0.9), label="90%", color="red")
)