plotnine 0.15.0.dev3__py3-none-any.whl → 0.15.2__py3-none-any.whl

plotnine/doctools.py

@@ -71,7 +71,7 @@ STAT_SIGNATURE_TPL = """
 
 common_params_doc = {
     "mapping": """\
-Aesthetic mappings created with [aes](:class:`plotnine.mapping.aes`). If \
+Aesthetic mappings created with [aes](:class:`plotnine.mapping.aes.aes`). If \
 specified and `inherit_aes=True`{.py}, it is combined with the default \
 mapping for the plot. You must supply mapping if there is no plot mapping.""",
     "data": """\
@@ -103,7 +103,7 @@ the final image is in vector format.""",
 
 
 GEOM_PARAMS_TPL = """
-mapping : ~plotnine.mapping.aes, default=None
+mapping : ~plotnine.mapping.aes.aes, default=None
     {mapping}
     {_aesthetics_doc}
 data : ~pandas.DataFrame, default=None
@@ -124,7 +124,7 @@ raster : bool, default={default_raster}
 """
 
 STAT_PARAMS_TPL = """
-mapping : ~plotnine.mapping.aes, default=None
+mapping : ~plotnine.mapping.aes.aes, default=None
     {mapping}
     {_aesthetics_doc}
 data : ~pandas.DataFrame, default=None
@@ -451,7 +451,7 @@ def document_geom(geom: type[geom]) -> type[geom]:
     table = dict_to_table(("Aesthetic", "Default value"), contents)
     aesthetics_table = AESTHETICS_TABLE_TPL.format(table=table)
     tpl = dedent(geom._aesthetics_doc).strip()
-    aesthetics_doc = tpl.format(aesthetics_table=aesthetics_table)
+    aesthetics_doc = tpl.replace("{aesthetics_table}", aesthetics_table)
     aesthetics_doc = indent(aesthetics_doc, " " * 4)
 
     # common_parameters

plotnine/facets/facet.py

@@ -130,13 +130,13 @@ class facet:
             "y": scales in ("free_y", "free"),
         }
 
-    def __radd__(self, plot: ggplot) -> ggplot:
+    def __radd__(self, other: ggplot) -> ggplot:
         """
         Add facet to ggplot object
         """
-        plot.facet = copy(self)
-        plot.facet.environment = plot.environment
-        return plot
+        other.facet = copy(self)
+        other.facet.environment = other.environment
+        return other
 
     def setup(self, plot: ggplot):
         self.plot = plot

plotnine/facets/strips.py

@@ -67,56 +67,45 @@ class strip:
         if position == "top":
             # The x & y values are just starting locations
             # The final location is determined by the layout manager.
-            y = 1
+            bg_y = 1
             ha = theme.getp(("strip_text_x", "ha"), "center")
-            va = theme.getp(("strip_text_x", "va"), "bottom")
+            va = theme.getp(("strip_text_x", "va"), "center")
             rotation = theme.getp(("strip_text_x", "rotation"))
-            box_width = 1
-            box_height = 0  # Determined by the text size
-            # TODO: Allow two unique paddings for either side.
-            # Requires implementing an mpl.patches.boxstyle that recognises
-            # two padding values.
-            strip_text_margin = (
-                theme.getp(("strip_text_x", "margin")).to("lines").b
-            )
+            bg_height = 0  # Determined by the text size
+            margin = theme.getp(("strip_text_x", "margin")).to("lines")
             strip_align = theme.getp("strip_align_x")
 
             # x & width properties of the background slide and
             # shrink the strip horizontally.
-            x = theme.getp(("strip_text_x", "x"), 0)
-            box_width = theme.getp(("strip_background_x", "width"), 1)
+            bg_x = theme.getp(("strip_text_x", "x"), 0)
+            bg_width = theme.getp(("strip_background_x", "width"), 1)
 
         elif position == "right":
             # The x & y values are just starting locations
             # The final location is determined by the layout manager.
-            x = 1
-            ha = theme.getp(("strip_text_y", "ha"), "left")
+            bg_x = 1
+            ha = theme.getp(("strip_text_y", "ha"), "center")
             va = theme.getp(("strip_text_y", "va"), "center")
             rotation = theme.getp(("strip_text_y", "rotation"))
-            box_width = 0  # Determine by the text height
-            # TODO: Allow two unique paddings for either side.
-            # Requires implementing an mpl.patches.boxstyle that recognises
-            # two padding values.
-            strip_text_margin = (
-                theme.getp(("strip_text_y", "margin")).to("lines").r
-            )
+            bg_width = 0  # Determine by the text height
+            margin = theme.getp(("strip_text_y", "margin")).to("lines")
             strip_align = theme.getp("strip_align_y")
 
             # y & height properties of the background slide and
             # shrink the strip vertically.
-            y = theme.getp(("strip_text_y", "y"), 0)
-            box_height = theme.getp(("strip_background_y", "height"), 1)
+            bg_y = theme.getp(("strip_text_y", "y"), 0)
+            bg_height = theme.getp(("strip_background_y", "height"), 1)
         else:
             raise ValueError(f"Unknown position for strip text: {position!r}")
 
         return strip_draw_info(
-            x=x,
-            y=y,
+            bg_x=bg_x,
+            bg_y=bg_y,
             ha=ha,
             va=va,
-            box_width=box_width,
-            box_height=box_height,
-            strip_text_margin=strip_text_margin,
+            bg_width=bg_width,
+            bg_height=bg_height,
+            margin=margin,
             strip_align=strip_align,
             position=position,
             label=self.label_info.text(),

plotnine/geoms/annotate.py

@@ -64,16 +64,16 @@ class annotate:
     def __init__(
         self,
         geom: str | type[geom_base_class],
-        x: float | None = None,
-        y: float | None = None,
-        xmin: float | None = None,
-        xmax: float | None = None,
-        xend: float | None = None,
-        xintercept: float | None = None,
-        ymin: float | None = None,
-        ymax: float | None = None,
-        yend: float | None = None,
-        yintercept: float | None = None,
+        x: float | list[float] | None = None,
+        y: float | list[float] | None = None,
+        xmin: float | list[float] | None = None,
+        xmax: float | list[float] | None = None,
+        xend: float | list[float] | None = None,
+        xintercept: float | list[float] | None = None,
+        ymin: float | list[float] | None = None,
+        ymax: float | list[float] | None = None,
+        yend: float | list[float] | None = None,
+        yintercept: float | list[float] | None = None,
         **kwargs: Any,
     ):
         variables = locals()
@@ -131,12 +131,12 @@ class annotate:
             **kwargs,
         )
 
-    def __radd__(self, plot: ggplot) -> ggplot:
+    def __radd__(self, other: ggplot) -> ggplot:
         """
         Add to ggplot
         """
-        plot += self.to_layer()  # Add layer
-        return plot
+        other += self.to_layer()  # Add layer
+        return other
 
     def to_layer(self) -> layer:
         """

plotnine/geoms/annotation_logticks.py

@@ -46,9 +46,7 @@ class _geom_logticks(geom_rug):
     }
     draw_legend = staticmethod(geom_path.draw_legend)
 
-    def draw_layer(
-        self, data: pd.DataFrame, layout: Layout, coord: coord, **params: Any
-    ):
+    def draw_layer(self, data: pd.DataFrame, layout: Layout, coord: coord):
         """
         Draw ticks on every panel
         """
@@ -56,7 +54,7 @@ class _geom_logticks(geom_rug):
             ploc = pid - 1
             panel_params = layout.panel_params[ploc]
             ax = layout.axs[ploc]
-            self.draw_panel(data, panel_params, coord, ax, **params)
+            self.draw_panel(data, panel_params, coord, ax)
 
     @staticmethod
     def _check_log_scale(
@@ -184,8 +182,8 @@ class _geom_logticks(geom_rug):
         panel_params: panel_view,
         coord: coord,
         ax: Axes,
-        **params: Any,
     ):
+        params = self.params
         # Any passed data is ignored, the relevant data is created
         sides = params["sides"]
         lengths = params["lengths"]
@@ -203,9 +201,8 @@ class _geom_logticks(geom_rug):
         ):
             for position, length in zip(tick_positions, lengths):
                 data = pd.DataFrame({axis: position, **_aesthetics})
-                geom.draw_group(
-                    data, panel_params, coord, ax, length=length, **params
-                )
+                params["length"] = length
+                geom.draw_group(data, panel_params, coord, ax, params)
 
         if isinstance(coord, coord_flip):
             tick_range_x = panel_params.y.range
@@ -285,4 +282,6 @@ class annotation_logticks(annotate):
             linetype=linetype,
             lengths=lengths,
             base=base,
+            inherit_aes=False,
+            show_legend=False,
         )

plotnine/geoms/annotation_stripes.py

@@ -72,6 +72,8 @@ class annotation_stripes(annotate):
             fill_range=fill_range,
             extend=extend,
             direction=direction,
+            inherit_aes=False,
+            show_legend=False,
             **kwargs,
         )
 
@@ -94,9 +96,7 @@ class _geom_stripes(geom):
     }
     draw_legend = staticmethod(geom_polygon.draw_legend)
 
-    def draw_layer(
-        self, data: pd.DataFrame, layout: Layout, coord: coord, **params: Any
-    ):
+    def draw_layer(self, data: pd.DataFrame, layout: Layout, coord: coord):
         """
         Draw stripes on every panel
         """
@@ -104,7 +104,7 @@ class _geom_stripes(geom):
             ploc = pid - 1
             panel_params = layout.panel_params[ploc]
             ax = layout.axs[ploc]
-            self.draw_group(data, panel_params, coord, ax, **params)
+            self.draw_group(data, panel_params, coord, ax, self.params)
 
     @staticmethod
     def draw_group(
@@ -112,7 +112,7 @@ class _geom_stripes(geom):
         panel_params: panel_view,
         coord: coord,
         ax: Axes,
-        **params: Any,
+        params: dict[str, Any],
     ):
         extend = params["extend"]
         fill_range = params["fill_range"]
@@ -193,4 +193,4 @@ class _geom_stripes(geom):
             }
         )
 
-        return geom_rect.draw_group(data, panel_params, coord, ax, **params)
+        return geom_rect.draw_group(data, panel_params, coord, ax, params)

plotnine/geoms/geom.py

@@ -2,18 +2,20 @@ from __future__ import annotations
 
 import typing
 from abc import ABC
+from contextlib import suppress
 from copy import deepcopy
 from itertools import chain, repeat
 
+import numpy as np
+
 from .._utils import (
     data_mapping_as_kwargs,
-    is_list_like,
     remove_missing,
 )
 from .._utils.registry import Register, Registry
 from ..exceptions import PlotnineError
 from ..layer import layer
-from ..mapping.aes import is_valid_aesthetic, rename_aesthetics
+from ..mapping.aes import rename_aesthetics
 from ..mapping.evaluation import evaluate
 from ..positions.position import position
 from ..stats.stat import stat
@@ -171,6 +173,26 @@ class geom(ABC, metaclass=Register):
 
         return result
 
+    def setup_params(self, data: pd.DataFrame):
+        """
+        Override this method to verify and/or adjust parameters
+
+        Parameters
+        ----------
+        data :
+            Data
+        """
+
+    def setup_aes_params(self, data: pd.DataFrame):
+        """
+        Override this method to verify and/or adjust aesthetic parameters
+
+        Parameters
+        ----------
+        data :
+            Data
+        """
+
     def setup_data(self, data: pd.DataFrame) -> pd.DataFrame:
         """
         Modify the data before drawing takes place
@@ -224,6 +246,9 @@ class geom(ABC, metaclass=Register):
         :
             Data used for drawing the geom.
         """
+        from plotnine.mapping import _atomic as atomic
+        from plotnine.mapping._atomic import ae_value
+
         missing_aes = (
             self.DEFAULT_AES.keys()
             - self.aes_params.keys()
@@ -240,30 +265,39 @@ class geom(ABC, metaclass=Register):
             data[ae] = evaled[ae]
 
         num_panels = len(data["PANEL"].unique()) if "PANEL" in data else 1
+        across_panels = num_panels > 1 and not self.params["inherit_aes"]
 
-        # Aesthetics set as parameters to the geom/stat
+        # Aesthetics set as parameters in the geom/stat
         for ae, value in self.aes_params.items():
-            try:
+            if isinstance(value, (str, int, float, np.integer, np.floating)):
+                data[ae] = value
+            elif isinstance(value, ae_value):
+                data[ae] = value * len(data)
+            elif across_panels:
+                value = list(chain(*repeat(value, num_panels)))
                 data[ae] = value
-            except ValueError as e:
-                # sniff out the special cases, like custom
-                # tupled linetypes, shapes and colors
-                if is_valid_aesthetic(value, ae):
-                    data[ae] = [value] * len(data)
-                elif num_panels > 1 and is_list_like(value):
-                    data[ae] = list(chain(*repeat(value, num_panels)))
-                else:
-                    msg = (
-                        f"'{value}' does not look like a "
-                        f"valid value for `{ae}`"
-                    )
+            else:
+                # Try to make sense of aesthetics whose values can be tuples
+                # or sequences of sorts.
+                ae_value_cls: type[ae_value] | None = getattr(atomic, ae, None)
+                if ae_value_cls:
+                    with suppress(ValueError):
+                        data[ae] = ae_value_cls(value) * len(data)
+                        continue
+
+                # This should catch the aesthetic assignments to
+                # non-numeric or non-string values or sequence of values.
+                # e.g. x=datetime, x=Sequence[datetime],
+                #      x=Sequence[float], shape=Sequence[str]
+                try:
+                    data[ae] = value
+                except ValueError as e:
+                    msg = f"'{ae}={value}' does not look like a valid value"
                     raise PlotnineError(msg) from e
 
         return data
 
-    def draw_layer(
-        self, data: pd.DataFrame, layout: Layout, coord: coord, **params: Any
-    ):
+    def draw_layer(self, data: pd.DataFrame, layout: Layout, coord: coord):
         """
         Draw layer across all panels
 
@@ -289,7 +323,7 @@ class geom(ABC, metaclass=Register):
             ploc = pdata["PANEL"].iloc[0] - 1
             panel_params = layout.panel_params[ploc]
             ax = layout.axs[ploc]
-            self.draw_panel(pdata, panel_params, coord, ax, **params)
+            self.draw_panel(pdata, panel_params, coord, ax)
 
     def draw_panel(
         self,
@@ -297,7 +331,6 @@ class geom(ABC, metaclass=Register):
         panel_params: panel_view,
         coord: coord,
         ax: Axes,
-        **params: Any,
     ):
         """
         Plot all groups
@@ -331,7 +364,7 @@ class geom(ABC, metaclass=Register):
         """
         for _, gdata in data.groupby("group"):
             gdata.reset_index(inplace=True, drop=True)
-            self.draw_group(gdata, panel_params, coord, ax, **params)
+            self.draw_group(gdata, panel_params, coord, ax, self.params)
 
     @staticmethod
     def draw_group(
@@ -339,7 +372,7 @@ class geom(ABC, metaclass=Register):
         panel_params: panel_view,
         coord: coord,
         ax: Axes,
-        **params: Any,
+        params: dict[str, Any],
     ):
         """
         Plot data belonging to a group.
@@ -376,7 +409,7 @@ class geom(ABC, metaclass=Register):
         panel_params: panel_view,
         coord: coord,
         ax: Axes,
-        **params: Any,
+        params: dict[str, Any],
     ):
         """
         Plot data belonging to a unit.
@@ -426,7 +459,7 @@ class geom(ABC, metaclass=Register):
         msg = "The geom should implement this method."
         raise NotImplementedError(msg)
 
-    def __radd__(self, plot: ggplot) -> ggplot:
+    def __radd__(self, other: ggplot) -> ggplot:
         """
         Add layer representing geom object on the right
 
@@ -440,8 +473,8 @@ class geom(ABC, metaclass=Register):
         :
             ggplot object with added layer.
         """
-        plot += self.to_layer()  # Add layer
-        return plot
+        other += self.to_layer()  # Add layer
+        return other
 
     def to_layer(self) -> layer:
         """

plotnine/geoms/geom_abline.py

@@ -102,7 +102,6 @@ class geom_abline(geom):
         panel_params: panel_view,
         coord: coord,
         ax: Axes,
-        **params: Any,
     ):
         """
         Plot all groups
@@ -116,4 +115,6 @@ class geom_abline(geom):
 
         for _, gdata in data.groupby("group"):
             gdata.reset_index(inplace=True)
-            geom_segment.draw_group(gdata, panel_params, coord, ax, **params)
+            geom_segment.draw_group(
+                gdata, panel_params, coord, ax, self.params
+            )

plotnine/geoms/geom_area.py

@@ -14,12 +14,12 @@ class geom_area(geom_ribbon):
     """
     Area plot
 
+    {usage}
+
     An area plot is a special case of geom_ribbon,
     where the minimum of the range is fixed to 0,
     and the position adjustment defaults to 'stack'.
 
-    {usage}
-
     Parameters
     ----------
     {common_parameters}

plotnine/geoms/geom_bar.py

@@ -32,6 +32,7 @@ class geom_bar(geom_rect):
     See Also
     --------
     plotnine.geom_histogram
+    plotnine.stat_count : The default `stat` for this `geom`.
     """
 
     REQUIRED_AES = {"x", "y"}

plotnine/geoms/geom_bin_2d.py

@@ -7,16 +7,20 @@ class geom_bin_2d(geom_rect):
     """
     Heatmap of 2d bin counts
 
+    {usage}
+
     Divides the plane into rectangles, counts the number of
     cases in each rectangle, and then (by default) maps the number
     of cases to the rectangle's fill. This is a useful alternative
     to geom_point in the presence of overplotting.
 
-    {usage}
-
     Parameters
     ----------
     {common_parameters}
+
+    See Also
+    --------
+    plotnine.stat_bin_2d : The default stat for this `geom`.
     """
 
     DEFAULT_PARAMS = {"stat": "bin_2d", "position": "identity", "na_rm": False}

plotnine/geoms/geom_blank.py

@@ -6,8 +6,6 @@ from ..doctools import document
 from .geom import geom
 
 if typing.TYPE_CHECKING:
-    from typing import Any
-
     import pandas as pd
     from matplotlib.axes import Axes
 
@@ -39,7 +37,6 @@ class geom_blank(geom):
         panel_params: panel_view,
         coord: coord,
         ax: Axes,
-        **params: Any,
     ):
         pass
 

plotnine/geoms/geom_boxplot.py

@@ -70,6 +70,10 @@ class geom_boxplot(geom):
     fatten : float, default=2
         A multiplicative factor used to increase the size of the
         middle bar across the box.
+
+    See Also
+    --------
+    plotnine.stat_boxplot : The default `stat` for this `geom`.
     """
 
     DEFAULT_AES = {
@@ -183,7 +187,7 @@ class geom_boxplot(geom):
         panel_params: panel_view,
         coord: coord,
         ax: Axes,
-        **params: Any,
+        params: dict[str, Any],
     ):
         def flat(*args: pd.Series[Any]) -> npt.NDArray[Any]:
             """Flatten list-likes"""
@@ -245,11 +249,11 @@ class geom_boxplot(geom):
             outliers["shape"] = outlier_value("shape")
             outliers["size"] = outlier_value("size")
             outliers["stroke"] = outlier_value("stroke")
-            geom_point.draw_group(outliers, panel_params, coord, ax, **params)
+            geom_point.draw_group(outliers, panel_params, coord, ax, params)
 
         # plot
-        geom_segment.draw_group(whiskers, panel_params, coord, ax, **params)
-        geom_crossbar.draw_group(box, panel_params, coord, ax, **params)
+        geom_segment.draw_group(whiskers, panel_params, coord, ax, params)
+        geom_crossbar.draw_group(box, panel_params, coord, ax, params)
 
     @staticmethod
     def draw_legend(

plotnine/geoms/geom_col.py

@@ -7,13 +7,13 @@ class geom_col(geom_bar):
     """
     Bar plot with base on the x-axis
 
+    {usage}
+
     This is an alternate version of [](`~plotnine.geoms.geom_bar`) that maps
     the height of bars to an existing variable in your data. If
     you want the height of the bar to represent a count of cases,
     use [](`~plotnine.geoms.geom_bar`).
 
-    {usage}
-
     Parameters
     ----------
     {common_parameters}

plotnine/geoms/geom_count.py

@@ -7,15 +7,19 @@ class geom_count(geom_point):
     """
     Plot overlapping points
 
+    {usage}
+
     This is a variant [](`~plotnine.geoms.geom_point`) that counts the number
     of observations at each location, then maps the count to point
     area. It useful when you have discrete data and overplotting.
 
-    {usage}
-
     Parameters
     ----------
     {common_parameters}
+
+    See Also
+    --------
+    plotnine.stat_sum : The default `stat` for this `geom`.
     """
 
     DEFAULT_PARAMS = {"stat": "sum", "position": "identity", "na_rm": False}

plotnine/geoms/geom_crossbar.py

@@ -78,7 +78,7 @@ class geom_crossbar(geom):
         panel_params: panel_view,
         coord: coord,
         ax: Axes,
-        **params: Any,
+        params: dict[str, Any],
     ):
         y = data["y"]
         xmin = data["xmin"]
@@ -160,8 +160,8 @@ class geom_crossbar(geom):
             )
 
         copy_missing_columns(box, data)
-        geom_polygon.draw_group(box, panel_params, coord, ax, **params)
-        geom_segment.draw_group(middle, panel_params, coord, ax, **params)
+        geom_polygon.draw_group(box, panel_params, coord, ax, params)
+        geom_segment.draw_group(middle, panel_params, coord, ax, params)
 
     @staticmethod
     def draw_legend(

plotnine/geoms/geom_density_2d.py

@@ -7,13 +7,17 @@ class geom_density_2d(geom_path):
     """
     2D density estimate
 
-    This is a 2d version of [](`~plotnine.geoms.geom_density`).
-
     {usage}
 
+    This is a 2d version of [](`~plotnine.geoms.geom_density`).
+
     Parameters
     ----------
     {common_parameters}
+
+    See Also
+    --------
+    plotnine.stat_density_2d : The default `stat` for this `geom`.
     """
 
     DEFAULT_PARAMS = {

plotnine/geoms/geom_dotplot.py

@@ -46,7 +46,7 @@ class geom_dotplot(geom):
 
     See Also
     --------
-    plotnine.stat_bindot
+    plotnine.stat_bindot : The default `stat` for this `geom`.
     """
 
     DEFAULT_AES = {"alpha": 1, "color": "black", "fill": "black"}
@@ -186,7 +186,7 @@ class geom_dotplot(geom):
         panel_params: panel_view,
         coord: coord,
         ax: Axes,
-        **params: Any,
+        params: dict[str, Any],
     ):
         from matplotlib.collections import PatchCollection
         from matplotlib.patches import Ellipse