Document polar coordinates

Author: iangow

doc/.gitignore

@@ -13,3 +13,5 @@ objects.json
 objects.txt
 objects.inv
 gallery/thumbnails
+
+**/*.quarto_ipynb

doc/_quartodoc.yml

@@ -535,6 +535,8 @@ quartodoc:
         - coord_equal
         - coord_fixed
         - coord_flip
+        - coord_polar
+        - coord_radial
         - coord_trans
 
     - title: Composing Plots

plotnine/coords/coord_polar.py

@@ -11,18 +11,18 @@
 if TYPE_CHECKING:
     import pandas as pd
     from matplotlib.axes import Axes
+
     from plotnine.iapi import panel_view
     from plotnine.scales.scale import scale
 
 
 class coord_polar(coord):
     """
-    Polar coordinate system.
+    Polar coordinate system
 
-    Uses Matplotlib's native ``PolarAxes`` so every standard geom
-    (including bar → pie/bullseye) renders correctly without manual
-    Cartesian conversion.  Concentric-circle and radial-spoke grid
-    lines are drawn automatically by Matplotlib.
+    `coord_polar` maps one position aesthetic to the angle and the other
+    to the radius. It is commonly used for pie charts, which are stacked
+    bar charts in polar coordinates.
 
     Parameters
     ----------
@@ -34,7 +34,33 @@ class coord_polar(coord):
     direction :
         ``1`` = clockwise (default), ``-1`` = counter-clockwise.
     expand :
-        Add a small buffer around the data on the radius axis. Default ``True``.
+        Add a small buffer around the data on the radius axis.
+        Default ``True``.
+
+    Notes
+    -----
+    Unlike ggplot2, plotnine coordinate systems do not currently expose a
+    ``clip`` argument.
+
+    For partial arcs, donut charts, and theta/radius limits, use
+    ``coord_radial``.
+
+    Examples
+    --------
+    A pie chart is a stacked bar chart with the y position mapped to angle.
+
+    ```python
+    import pandas as pd
+    from plotnine import aes, coord_polar, geom_col, ggplot
+
+    df = pd.DataFrame({
+        "x": [1, 1, 1],
+        "y": [2, 3, 5],
+        "group": ["a", "b", "c"],
+    })
+
+    ggplot(df, aes("x", "y", fill="group")) + geom_col() + coord_polar("y")
+    ```
     """
 
     is_linear = False
@@ -56,9 +82,7 @@ def __init__(
     # Panel params
     # ------------------------------------------------------------------
 
-    def setup_panel_params(
-        self, scale_x: scale, scale_y: scale
-    ) -> panel_view:
+    def setup_panel_params(self, scale_x: scale, scale_y: scale) -> panel_view:
         from .coord_cartesian import coord_cartesian
 
         # Theta fills exactly one full revolution — no expansion on that axis.
@@ -95,7 +119,8 @@ def setup_panel_params(
             labels=[],
         )
 
-        # y → r axis: use the scale for the r dimension with its natural breaks.
+        # y → r axis: use the scale for the r dimension with its natural
+        # breaks.
         new_y = replace(r_sv)
 
         return replace(pv_exp, x=new_x, y=new_y)
@@ -140,7 +165,9 @@ def transform(
 
         data = data.copy()
         data[theta_col] = self._to_radians(data[theta_col].to_numpy())
-        has_endpoints = theta_end_col in data.columns and r_end_col in data.columns
+        has_endpoints = (
+            theta_end_col in data.columns and r_end_col in data.columns
+        )
         if has_endpoints:
             data[theta_end_col] = self._to_radians(
                 data[theta_end_col].to_numpy()
@@ -204,7 +231,7 @@ def draw(self, axs: list[Axes]) -> None:
         mpl_direction = -1 if self.direction == 1 else 1
 
         for ax in axs:
-            ax.set_theta_zero_location("N")   # 12 o'clock = 0
+            ax.set_theta_zero_location("N")  # 12 o'clock = 0
             ax.set_theta_direction(mpl_direction)
             if np.isfinite(r_min) and np.isfinite(r_max) and r_min != r_max:
                 ax.set_rlim(float(r_min), float(r_max))

plotnine/coords/coord_radial.py

@@ -10,20 +10,19 @@
 if TYPE_CHECKING:
     import pandas as pd
     from matplotlib.axes import Axes
+
     from plotnine.iapi import panel_view
     from plotnine.scales.scale import scale
 
 
 class coord_radial(coord_polar):
     """
-    Radial coordinate system.
-
-    A modernised polar coordinate system that adds support for partial arcs,
-    inner radius (donut/gauge charts), configurable radial-axis placement, and
-    automatic rotation of the ``angle`` aesthetic to align with theta.
+    Radial coordinate system
 
-    Inherits from :class:`coord_polar`; all standard geoms work without
-    modification.
+    `coord_radial` maps one position aesthetic to the angle and the other
+    to the radius. Compared with ``coord_polar``, it adds support for
+    partial arcs, inner radius holes, theta/radius limits, radial-axis
+    placement, and rotation of the ``angle`` aesthetic.
 
     Parameters
     ----------
@@ -39,7 +38,8 @@ class coord_radial(coord_polar):
         ``1`` = clockwise (default), ``-1`` = counter-clockwise.
         Only used when *end* is ``None``.
     expand :
-        Add a small buffer around the data on the radius axis. Default ``True``.
+        Add a small buffer around the data on the radius axis.
+        Default ``True``.
     inner_radius :
         Size of the inner hole as a fraction of the outer radius, in
         ``[0, 1)``.  ``0`` (default) means no hole; ``0.3`` creates a 30 %
@@ -50,7 +50,11 @@ class coord_radial(coord_polar):
         * ``None`` (default) — let Matplotlib decide (usually outside).
         * ``True`` — force inside, aligned just past the *start* angle.
         * ``False`` — force outside (Matplotlib default).
-        * *float* — place at this theta angle in radians (clockwise from North).
+        * *float* — place at this theta angle in radians (clockwise from
+          North).
+
+        Unlike ggplot2's ``r.axis.inside``, a length-2 value for separate
+        primary and secondary axis placement is not supported.
     rotate_angle :
         If ``True``, automatically add the local theta angle (in degrees) to
         the ``angle`` aesthetic so that text or other rotated marks align with
@@ -71,6 +75,52 @@ class coord_radial(coord_polar):
     theta_label_pad :
         Distance in points between the outer circle spine and the theta tick
         labels.  Default ``8``.  Only applied when theta labels are shown.
+
+    Notes
+    -----
+    The Python API uses snake_case names for arguments that are dotted in
+    ggplot2: ``inner_radius``, ``r_axis_inside``, and ``rotate_angle``.
+
+    Unlike ggplot2, plotnine coordinate systems do not currently expose a
+    ``clip`` argument. The ggplot2 ``reverse`` argument is not currently
+    implemented.
+
+    Examples
+    --------
+    A donut chart is a stacked bar chart with an inner radius.
+
+    ```python
+    import pandas as pd
+    from plotnine import aes, coord_radial, geom_col, ggplot
+
+    df = pd.DataFrame({
+        "x": [1, 1, 1],
+        "y": [2, 3, 5],
+        "group": ["a", "b", "c"],
+    })
+
+    (
+        ggplot(df, aes("x", "y", fill="group"))
+        + geom_col()
+        + coord_radial(theta="y", inner_radius=0.4)
+    )
+    ```
+
+    Partial arcs can be used for gauge-like displays.
+
+    ```python
+    import numpy as np
+    import pandas as pd
+    from plotnine import aes, coord_radial, geom_point, ggplot
+
+    df = pd.DataFrame({"x": [1, 2, 3], "y": [2, 4, 3]})
+
+    ggplot(df, aes("x", "y")) + geom_point() + coord_radial(
+        start=-0.4 * np.pi,
+        end=0.4 * np.pi,
+        inner_radius=0.3,
+    )
+    ```
     """
 
     def __init__(
@@ -111,7 +161,9 @@ def setup_panel_params(self, scale_x: scale, scale_y: scale) -> panel_view:
         from .coord_cartesian import coord_cartesian
 
         # Capture data-space theta breaks before super() clears them.
-        pv_data = coord_cartesian(expand=False).setup_panel_params(scale_x, scale_y)
+        pv_data = coord_cartesian(expand=False).setup_panel_params(
+            scale_x, scale_y
+        )
         if self.theta == "x":
             theta_breaks = list(pv_data.x.breaks)
             theta_labels = list(pv_data.x.labels)
@@ -121,7 +173,8 @@ def setup_panel_params(self, scale_x: scale, scale_y: scale) -> panel_view:
 
         pv = super().setup_panel_params(scale_x, scale_y)
 
-        # thetalim: zoom the theta data range — only this slice maps to the arc.
+        # thetalim: zoom the theta data range — only this slice maps to the
+        # arc.
         if self.thetalim is not None:
             self.params["theta_range"] = tuple(self.thetalim)
 
@@ -155,7 +208,9 @@ def setup_panel_params(self, scale_x: scale, scale_y: scale) -> panel_view:
         # pac-man / coxcomb charts keep breaks=[] as set by super()).
         x_updates: dict = {}
         if theta_breaks and (arc_lo is not None or self.theta_labels):
-            radian_pos = list(self._to_radians(np.asarray(theta_breaks, dtype=float)))
+            radian_pos = list(
+                self._to_radians(np.asarray(theta_breaks, dtype=float))
+            )
             if arc_lo is not None:
                 keep = [arc_lo <= r <= arc_hi for r in radian_pos]
                 radian_pos = [r for r, k in zip(radian_pos, keep) if k]
@@ -181,7 +236,11 @@ def setup_panel_params(self, scale_x: scale, scale_y: scale) -> panel_view:
 
     @property
     def _arc(self) -> float:
-        """Total arc in radians (signed: positive when going clockwise for direction=1)."""
+        """
+        Total arc in radians.
+
+        A positive value represents clockwise movement when ``direction=1``.
+        """
         if self.end is not None:
             return self.end - self.start
         return self.direction * 2.0 * np.pi
@@ -207,7 +266,11 @@ def transform(
     ) -> pd.DataFrame:
         data = super().transform(data, panel_params, munch=munch)
         # After super().transform(), data["x"] is always theta in radians.
-        if self.rotate_angle and "angle" in data.columns and "x" in data.columns:
+        if (
+            self.rotate_angle
+            and "angle" in data.columns
+            and "x" in data.columns
+        ):
             data = data.copy()
             data["angle"] = data["angle"] + np.degrees(data["x"])
         return data
@@ -252,10 +315,14 @@ def draw(self, axs: list[Axes]) -> None:
                         # Just inside the start angle keeps it out of the data.
                         ax.set_rlabel_position(np.degrees(self.start) + 10)
                 else:
-                    ax.set_rlabel_position(np.degrees(float(self.r_axis_inside)))
+                    ax.set_rlabel_position(
+                        np.degrees(float(self.r_axis_inside))
+                    )
 
     def post_setup_ax(self, ax: Axes) -> None:
-        """Apply theta label pad after facet has set tick positions and padding."""
+        """
+        Apply theta label pad after facet has set tick positions and padding.
+        """
         if self.theta_labels or self.end is not None:
             ax.tick_params(axis="x", pad=self.theta_label_pad)
         # Allow geom_text labels to extend past the polar axes bounding box