Added guide_axis_theta() (initial pass).

Author: iangow

plotnine/__init__.py

@@ -90,6 +90,7 @@
     save_as_pdf_pages,
 )
 from .guides import (
+    guide_axis_theta,
     guide_colorbar,
     guide_colourbar,
     guide_legend,
@@ -349,6 +350,7 @@
     "ggplot",
     "ggsave",
     "ggtitle",
+    "guide_axis_theta",
     "guide_colorbar",
     "guide_colourbar",
     "guide_legend",

plotnine/coords/coord_radial.py

@@ -334,7 +334,21 @@ def setup_ax(
         super().setup_ax(ax, panel_params, theme)
         if self.theta_labels or self.end is not None:
             ax.tick_params(axis="x", pad=self.theta_label_pad)
+            if (angle := self._theta_guide_angle(theme)) is not None:
+                ax.tick_params(axis="x", labelrotation=angle)
+                for label in ax.get_xticklabels():
+                    label.set_rotation(angle)
+                    label.set_rotation_mode("anchor")
         # Allow geom_text labels to extend past the polar axes bounding box
         # (e.g. spoke labels placed just beyond the outermost bar tip).
         for text in ax.texts:
             text.set_clip_on(False)
+
+    @staticmethod
+    def _theta_guide_angle(theme: theme) -> float | None:
+        """
+        Return the angle from guides(theta=guide_axis_theta(...)).
+        """
+        guide = getattr(getattr(theme, "owner", None), "guides", None)
+        guide = getattr(guide, "theta", None)
+        return getattr(guide, "angle", None)

plotnine/guides/__init__.py

@@ -1,5 +1,12 @@
+from .guide_axis_theta import guide_axis_theta
 from .guide_colorbar import guide_colorbar, guide_colourbar
 from .guide_legend import guide_legend
 from .guides import guides
 
-__all__ = ("guide_colorbar", "guide_colourbar", "guide_legend", "guides")
+__all__ = (
+    "guide_axis_theta",
+    "guide_colorbar",
+    "guide_colourbar",
+    "guide_legend",
+    "guides",
+)

plotnine/guides/guide_axis_theta.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..themes.theme import theme as Theme
+
+
+@dataclass
+class guide_axis_theta:
+    """
+    Theta-axis guide for radial coordinates.
+
+    This guide is consumed by ``coord_radial`` when it draws theta-axis
+    tick labels. It is not drawn as a legend or colorbar.
+    """
+
+    title: str | None = None
+    """Title of the guide. Currently unused."""
+
+    theme: Theme = field(default_factory=Theme)
+    """A theme to style the guide. Currently unused."""
+
+    angle: float | None = None
+    """
+    Angle in degrees at which to draw theta-axis tick labels.
+
+    If ``None``, Matplotlib's default theta tick label rotation is used.
+    """
+
+    minor_ticks: bool | None = None
+    """Whether to draw minor ticks. Currently unused."""
+
+    cap: bool | None = None
+    """Whether to cap the axis line. Currently unused."""
+
+    order: int = 0
+    """Order of this guide among multiple guides. Currently unused."""
+
+    position: str | None = None
+    """Guide position. Currently unused."""

plotnine/guides/guides.py

@@ -27,7 +27,13 @@
     from matplotlib.figure import Figure
     from matplotlib.offsetbox import OffsetBox, PackerBase
 
-    from plotnine import ggplot, guide_colorbar, guide_legend, theme
+    from plotnine import (
+        ggplot,
+        guide_axis_theta,
+        guide_colorbar,
+        guide_legend,
+        theme,
+    )
     from plotnine._mpl.offsetbox import FlexibleAnchoredOffsetbox
     from plotnine.composition import Compose
     from plotnine.iapi import labels_view
@@ -47,6 +53,7 @@
         guide_legend | guide_colorbar | Literal["legend", "colorbar"]
     )
     LegendOnly: TypeAlias = guide_legend | Literal["legend"]
+    ThetaGuide: TypeAlias = guide_axis_theta
 
     class LegendOwner(Protocol):
         """
@@ -116,6 +123,9 @@ class guides:
     colour: Optional[LegendOnly | NoGuide] = None
     """Guide for colour scale."""
 
+    theta: Optional[ThetaGuide | NoGuide] = None
+    """Guide for theta axis labels in radial coordinates."""
+
     def __post_init__(self):
         self.plot: ggplot
         self.plot_scales: Scales

tests/test_coord_polar.py

@@ -12,6 +12,8 @@
     geom_point,
     geom_text,
     ggplot,
+    guide_axis_theta,
+    guides,
     theme,
 )
 from plotnine.coords.coord_cartesian import coord_cartesian
@@ -307,3 +309,25 @@ def test_coord_radial_setup_ax_sets_pad_and_unclips_text():
         assert not ax.texts[0].get_clip_on()
     finally:
         plt.close(fig)
+
+
+def test_coord_radial_uses_guide_axis_theta_angle():
+    data = pd.DataFrame({"x": [1, 2, 3], "y": [1, 2, 3]})
+    p = (
+        ggplot(data, aes("x", "y"))
+        + geom_point()
+        + coord_radial(theta_labels=True)
+        + guides(theta=guide_axis_theta(angle=35))
+    )
+
+    fig = p.draw()
+    try:
+        rotations = [
+            label.get_rotation()
+            for label in fig.axes[0].get_xticklabels()
+            if label.get_text()
+        ]
+        assert rotations
+        assert rotations == [35] * len(rotations)
+    finally:
+        plt.close(fig)