7  guide_axis_theta()

guide_axis_theta() is a specialized guide for the theta axis in coord_radial() plots. It controls how tick labels are oriented around the circle.

The examples below are adapted from the ggplot2 reference page.

Caution

The examples on this page require the coord-polar branch of iangow/plotnine. Standard releases of plotnine do not yet include these changes.

import polars as pl
import plotnine_polars as p9
from plotnine.data import mtcars
from plotnine_polars import aes

7.1 Base plot

The base plot uses coord_radial(theta_labels=True) to display tick labels on the outer edge of the circle. By default, Matplotlib renders each label horizontally.

mtcars_pl = pl.from_pandas(mtcars)

p = (
    mtcars_pl
    .ggplot(aes("disp", "mpg"))
    .geom_point()
    .coord_radial(theta_labels=True)
    .add_theme(figure_size=(5, 5))
)
p
Figure 7.1: Base coord_radial() plot with theta labels

7.2 angle = 0: tangential labels

Passing guide_axis_theta(angle=0) to .add_guides() orients each label tangentially, parallel to the arc, at its position around the circle. This is the most common use and mirrors guide_axis_theta(angle = 0) in ggplot2.

p.add_guides(theta=p9.guide_axis_theta(angle=0))
Figure 7.2: Theta labels rotated to follow the arc (angle=0)

7.3 angle = 90: radial labels

Setting angle=90 rotates each label a further 90 degrees from the tangential direction, so labels point outward along the spoke.

p.add_guides(theta=p9.guide_axis_theta(angle=90))
Figure 7.3: Theta labels pointing radially outward (angle=90)

7.4 Relationship between angle and the tangent

The angle parameter is an offset from the tangential direction at each tick position, not an absolute rotation.

angle Label orientation
0 Tangential, parallel to the arc (default ggplot2 heuristic)
90 Radial, pointing outward from the centre
-90 Radial, pointing inward toward the centre

This matches ggplot2’s semantics, where the heuristics for waiver() also choose an angle relative to the arc direction. In contrast, Matplotlib’s default tick_params(labelrotation=N) sets an absolute angle, which is why guide_axis_theta() patches the tick rotation mode directly.

Note

The minor_ticks and cap parameters of ggplot2’s guide_axis_theta() are not yet implemented in the Python version.