plotnine 0.14.5__py3-none-any.whl → 0.15.0a2__py3-none-any.whl

plotnine/geoms/geom.py

@@ -426,7 +426,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 +440,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_bar.py

@@ -20,6 +20,11 @@ class geom_bar(geom_rect):
     Parameters
     ----------
     {common_parameters}
+    just : float, default=0.5
+        How to align the column with respect to the axis breaks. The default
+        `0.5` aligns the center of the column with the break. `0` aligns the
+        left of the of the column with the break and `1` aligns the right of
+        the column with the break.
     width : float, default=None
         Bar width. If `None`{.py}, the width is set to
         `90%` of the resolution of the data.
@@ -35,6 +40,7 @@ class geom_bar(geom_rect):
         "stat": "count",
         "position": "stack",
         "na_rm": False,
+        "just": 0.5,
         "width": None,
     }
 
@@ -45,6 +51,8 @@ class geom_bar(geom_rect):
             else:
                 data["width"] = resolution(data["x"], False) * 0.9
 
+        just = self.params.get("just", 0.5)
+
         bool_idx = data["y"] < 0
 
         data["ymin"] = 0.0
@@ -53,7 +61,7 @@ class geom_bar(geom_rect):
         data["ymax"] = data["y"]
         data.loc[bool_idx, "ymax"] = 0.0
 
-        data["xmin"] = data["x"] - data["width"] / 2
-        data["xmax"] = data["x"] + data["width"] / 2
+        data["xmin"] = data["x"] - data["width"] * just
+        data["xmax"] = data["x"] + data["width"] * (1 - just)
         del data["width"]
         return data

plotnine/geoms/geom_col.py

@@ -17,6 +17,11 @@ class geom_col(geom_bar):
     Parameters
     ----------
     {common_parameters}
+    just : float, default=0.5
+        How to align the column with respect to the axis breaks. The default
+        `0.5` aligns the center of the column with the break. `0` aligns the
+        left of the of the column with the break and `1` aligns the right of
+        the column with the break.
     width : float, default=None
         Bar width. If `None`{.py}, the width is set to
         `90%` of the resolution of the data.
@@ -32,5 +37,6 @@ class geom_col(geom_bar):
         "stat": "identity",
         "position": "stack",
         "na_rm": False,
+        "just": 0.5,
         "width": None,
     }

plotnine/geoms/geom_crossbar.py

@@ -88,7 +88,7 @@ class geom_crossbar(geom):
         group = data["group"]
 
         # From violin
-        notchwidth = typing.cast(float, params.get("notchwidth"))
+        notchwidth = typing.cast("float", params.get("notchwidth"))
         # ynotchupper = data.get('ynotchupper')
         # ynotchlower = data.get('ynotchlower')
 
@@ -110,8 +110,7 @@ class geom_crossbar(geom):
 
             if any(ynotchlower < ymin) or any(ynotchupper > ymax):
                 warn(
-                    "Notch went outside the hinges. "
-                    "Try setting notch=False.",
+                    "Notch went outside the hinges. Try setting notch=False.",
                     PlotnineWarning,
                 )
 

plotnine/geoms/geom_path.py

@@ -91,7 +91,7 @@ class geom_path(geom):
 
         # return data
         n1 = len(data)
-        data = data.loc[bool_idx]  # pyright: ignore[reportCallIssue,reportArgumentType]
+        data = data.loc[bool_idx]
         data.reset_index(drop=True, inplace=True)
         n2 = len(data)
 
@@ -482,7 +482,7 @@ def _draw_segments(data: pd.DataFrame, ax: Axes, **params: Any):
     linestyle = data.loc[indices, "linetype"]
 
     coll = LineCollection(
-        segments,  # pyright: ignore[reportArgumentType]
+        segments,
         edgecolor=edgecolor,
         linewidth=linewidth,
         linestyle=linestyle,

plotnine/geoms/geom_violin.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-import typing
+from typing import TYPE_CHECKING, cast
 
 import numpy as np
 import pandas as pd
@@ -11,7 +11,7 @@ from .geom import geom
 from .geom_path import geom_path
 from .geom_polygon import geom_polygon
 
-if typing.TYPE_CHECKING:
+if TYPE_CHECKING:
     from typing import Any
 
     from matplotlib.axes import Axes
@@ -115,10 +115,17 @@ class geom_violin(geom):
         ax: Axes,
         **params: Any,
     ):
-        quantiles = params["draw_quantiles"]
-        style = params["style"]
+        quantiles = params.pop("draw_quantiles")
+        style = params.pop("style")
+        zorder = params.pop("zorder")
+
+        for i, (group, df) in enumerate(data.groupby("group")):
+            # Place the violins with the smalleer group number on top
+            # of those with larger numbers. The group_zorder values should be
+            # in the range [zorder, zorder + 1) to stay within the layer.
+            group = cast("int", group)
+            group_zorder = zorder + 0.9 / group
 
-        for i, (_, df) in enumerate(data.groupby("group")):
             # Find the points for the line to go all the way around
             df["xminv"] = df["x"] - df["violinwidth"] * (df["x"] - df["xmin"])
             df["xmaxv"] = df["x"] + df["violinwidth"] * (df["xmax"] - df["x"])
@@ -156,7 +163,12 @@ class geom_violin(geom):
 
             # plot violin polygon
             geom_polygon.draw_group(
-                polygon_df, panel_params, coord, ax, **params
+                polygon_df,
+                panel_params,
+                coord,
+                ax,
+                zorder=group_zorder,
+                **params,
             )
 
             if quantiles is not None:
@@ -174,7 +186,12 @@ class geom_violin(geom):
 
                 # plot quantile segments
                 geom_path.draw_group(
-                    segment_df, panel_params, coord, ax, **params
+                    segment_df,
+                    panel_params,
+                    coord,
+                    ax,
+                    zorder=group_zorder,
+                    **params,
                 )
 
 

plotnine/ggplot.py

@@ -6,7 +6,15 @@ from io import BytesIO
 from itertools import chain
 from pathlib import Path
 from types import SimpleNamespace as NS
-from typing import TYPE_CHECKING, Any, Dict, Iterable, Optional, cast
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    Iterable,
+    Optional,
+    cast,
+    overload,
+)
 from warnings import warn
 
 from ._utils import (
@@ -44,9 +52,11 @@ if TYPE_CHECKING:
     from typing_extensions import Self
 
     from plotnine import watermark
+    from plotnine._mpl.gridspec import p9GridSpec
     from plotnine.coords.coord import coord
     from plotnine.facets.facet import facet
     from plotnine.layer import layer
+    from plotnine.plot_composition import Compose
     from plotnine.typing import DataLike
 
     class PlotAddable(Protocol):
@@ -54,7 +64,7 @@ if TYPE_CHECKING:
         Object that can be added to a ggplot object
         """
 
-        def __radd__(self, plot: ggplot) -> ggplot:
+        def __radd__(self, other: ggplot) -> ggplot:
             """
             Add to ggplot object
 
@@ -95,9 +105,7 @@ class ggplot:
 
     figure: Figure
     axs: list[Axes]
-    theme: theme
-    facet: facet
-    coordinates: coord
+    _gridspec: p9GridSpec
 
     def __init__(
         self,
@@ -110,7 +118,7 @@ class ggplot:
         data, mapping = order_as_data_mapping(data, mapping)
         self.data = data
         self.mapping = mapping if mapping is not None else aes()
-        self.facet = facet_null()
+        self.facet: facet = facet_null()
         self.labels = make_labels(self.mapping)
         self.layers = Layers()
         self.guides = guides()
@@ -147,6 +155,11 @@ class ggplot:
         Users should prefer this method instead of printing or repring
         the object.
         """
+        # Prevent against any modifications to the users
+        # ggplot object. Do the copy here as we may/may not
+        # assign a default theme
+        self = deepcopy(self)
+
         if is_inline_backend() or is_quarto_environment():
             # Take charge of the display because we have to make
             # adjustments for retina output.
@@ -167,18 +180,15 @@ class ggplot:
         format = get_option("figure_format") or ip.config.InlineBackend.get(
             "figure_format", "retina"
         )
-        save_format = format
-
         # While jpegs can be displayed as retina, we restrict the output
         # of "retina" to png
         if format == "retina":
             self = copy(self)
             self.theme = self.theme.to_retina()
-            save_format = "png"
 
-        figure_size_px = self.theme._figure_size_px
         buf = BytesIO()
-        self.save(buf, format=save_format, verbose=False)
+        self.save(buf, "png" if format == "retina" else format, verbose=False)
+        figure_size_px = self.theme._figure_size_px
         display_func = get_display_function(format, figure_size_px)
         display_func(buf.getvalue())
 
@@ -193,7 +203,7 @@ class ggplot:
         new = result.__dict__
 
         # don't make a deepcopy of data
-        shallow = {"data", "figure", "_build_objs"}
+        shallow = {"data", "figure", "gs", "_build_objs"}
         for key, item in old.items():
             if key in shallow:
                 new[key] = item
@@ -220,9 +230,20 @@ class ggplot:
             other.__radd__(self)
         return self
 
-    def __add__(self, other: PlotAddable | list[PlotAddable] | None) -> ggplot:
+    @overload
+    def __add__(
+        self, rhs: PlotAddable | list[PlotAddable] | None
+    ) -> ggplot: ...
+
+    @overload
+    def __add__(self, rhs: ggplot | Compose) -> Compose: ...
+
+    def __add__(
+        self,
+        rhs: PlotAddable | list[PlotAddable] | None | ggplot | Compose,
+    ) -> ggplot | Compose:
         """
-        Add to ggplot from a list
+        Add to ggplot
 
         Parameters
         ----------
@@ -230,8 +251,37 @@ class ggplot:
             Either an object that knows how to "radd"
             itself to a ggplot, or a list of such objects.
         """
+        from .plot_composition import ADD, Compose
+
+        if isinstance(rhs, (ggplot, Compose)):
+            return ADD([self, rhs])
+
         self = deepcopy(self)
-        return self.__iadd__(other)
+        return self.__iadd__(rhs)
+
+    def __or__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Compose 2 plots columnwise
+        """
+        from .plot_composition import OR
+
+        return OR([self, rhs])
+
+    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Compose 2 plots rowwise
+        """
+        from .plot_composition import DIV
+
+        return DIV([self, rhs])
+
+    def __sub__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Compose 2 plots columnwise
+        """
+        from .plot_composition import OR
+
+        return OR([self, rhs])
 
     def __rrshift__(self, other: DataLike) -> ggplot:
         """
@@ -248,7 +298,7 @@ class ggplot:
             raise TypeError(msg.format(type(other)))
         return self
 
-    def draw(self, show: bool = False) -> Figure:
+    def draw(self, *, show: bool = False) -> Figure:
         """
         Render the complete plot
 
@@ -262,23 +312,17 @@ class ggplot:
         :
             Matplotlib figure
         """
-        from ._mpl.layout_engine import PlotnineLayoutEngine
-
-        # Do not draw if drawn already.
-        # This prevents a needless error when reusing
-        # figure & axes in the jupyter notebook.
-        if hasattr(self, "figure"):
-            return self.figure
+        from ._mpl.layout_manager import PlotnineLayoutEngine
 
-        # Prevent against any modifications to the users
-        # ggplot object. Do the copy here as we may/may not
-        # assign a default theme
-        self = deepcopy(self)
         with plot_context(self, show=show):
+            if not hasattr(self, "figure"):
+                self._create_figure()
+            figure = self.figure
+
             self._build()
 
             # setup
-            self.figure, self.axs = self.facet.setup(self)
+            self.axs = self.facet.setup(self)
             self.guides._setup(self)
             self.theme.setup(self)
 
@@ -289,51 +333,24 @@ class ggplot:
             self.guides.draw()
             self._draw_figure_texts()
             self._draw_watermarks()
+            self._draw_figure_background()
 
             # Artist object theming
             self.theme.apply()
-            self.figure.set_layout_engine(PlotnineLayoutEngine(self))
+            figure.set_layout_engine(PlotnineLayoutEngine(self))
 
-        return self.figure
+        return figure
 
-    def _draw_using_figure(self, figure: Figure, axs: list[Axes]) -> ggplot:
+    def _create_figure(self):
         """
-        Draw onto already created figure and axes
-
-        This is can be used to draw animation frames,
-        or inset plots. It is intended to be used
-        after the key plot has been drawn.
-
-        Parameters
-        ----------
-        figure :
-            Matplotlib figure
-        axs :
-            Array of Axes onto which to draw the plots
+        Create gridspec for the panels
         """
-        from ._mpl.layout_engine import PlotnineLayoutEngine
+        import matplotlib.pyplot as plt
 
-        self = deepcopy(self)
-        self.figure = figure
-        self.axs = axs
-        with plot_context(self):
-            self._build()
+        from ._mpl.gridspec import p9GridSpec
 
-            # setup
-            self.figure, self.axs = self.facet.setup(self)
-            self.guides._setup(self)
-            self.theme.setup(self)
-
-            # drawing
-            self._draw_layers()
-            self._draw_breaks_and_labels()
-            self.guides.draw()
-
-            # artist theming
-            self.theme.apply()
-            self.figure.set_layout_engine(PlotnineLayoutEngine(self))
-
-        return self
+        self.figure = plt.figure()
+        self._gridspec = p9GridSpec(1, 1, self.figure)
 
     def _build(self):
         """
@@ -491,6 +508,7 @@ class ggplot:
         title = self.labels.get("title", "")
         subtitle = self.labels.get("subtitle", "")
         caption = self.labels.get("caption", "")
+        tag = self.labels.get("tag", "")
 
         # Get the axis labels (default or specified by user)
         # and let the coordinate modify them e.g. flip
@@ -508,6 +526,9 @@ class ggplot:
         if caption:
             targets.plot_caption = figure.text(0, 0, caption)
 
+        if tag:
+            targets.plot_tag = figure.text(0, 0, tag)
+
         if labels.x:
             targets.axis_title_x = figure.text(0, 0, labels.x)
 
@@ -521,6 +542,14 @@ class ggplot:
         for wm in self.watermarks:
             wm.draw(self.figure)
 
+    def _draw_figure_background(self):
+        from matplotlib.patches import Rectangle
+
+        rect = Rectangle((0, 0), 0, 0, facecolor="none", zorder=-1000)
+        self.figure.add_artist(rect)
+        self._gridspec.patch = rect
+        self.theme.targets.plot_background = rect
+
     def _save_filename(self, ext: str) -> Path:
         """
         Make a filename for use by the save method
@@ -572,7 +601,7 @@ class ggplot:
         fig_kwargs: Dict[str, Any] = {"format": format, **kwargs}
 
         if limitsize is None:
-            limitsize = cast(bool, get_option("limitsize"))
+            limitsize = cast("bool", get_option("limitsize"))
 
         # filename, depends on the object
         if filename is None:
@@ -598,7 +627,7 @@ class ggplot:
             raise PlotnineError("You must specify both width and height")
         else:
             width, height = cast(
-                tuple[float, float], self.theme.getp("figure_size")
+                "tuple[float, float]", self.theme.getp("figure_size")
             )
 
         if limitsize and (width > 25 or height > 25):

plotnine/guides/guide.py

@@ -18,18 +18,18 @@ if TYPE_CHECKING:
     from typing_extensions import Self
 
     from plotnine import aes, guides
-    from plotnine.layer import Layers
+    from plotnine.layer import Layers, layer
     from plotnine.scales.scale import scale
     from plotnine.typing import (
         LegendPosition,
         Orientation,
-        SidePosition,
+        Side,
     )
 
     from .guides import GuidesElements
 
     AlignDict: TypeAlias = dict[
-        Literal["ha", "va"], dict[tuple[Orientation, SidePosition], str]
+        Literal["ha", "va"], dict[tuple[Orientation, Side], str]
     ]
 
 
@@ -76,10 +76,10 @@ class guide(ABC, metaclass=Register):
         self.plot_layers: Layers
         self.plot_mapping: aes
         self._elements_cls = GuideElements
-        self.elements = cast(GuideElements, None)
+        self.elements = cast("GuideElements", None)
         self.guides_elements: GuidesElements
 
-    def legend_aesthetics(self, layer):
+    def legend_aesthetics(self, layer: layer):
         """
         Return the aesthetics that contribute to the legend
 
@@ -122,24 +122,21 @@ class guide(ABC, metaclass=Register):
     @property
     def _resolved_position_justification(
         self,
-    ) -> (
-        tuple[SidePosition, float]
-        | tuple[tuple[float, float], tuple[float, float]]
-    ):
+    ) -> tuple[Side, float] | tuple[tuple[float, float], tuple[float, float]]:
         """
         Return the final position & justification to draw the guide
         """
         pos = self.elements.position
         just_view = asdict(self.guides_elements.justification)
         if isinstance(pos, str):
-            just = cast(float, just_view[pos])
+            just = cast("float", just_view[pos])
             return (pos, just)
         else:
             # If no justification is given for an inside legend,
             # we use the position of the legend
             if (just := just_view["inside"]) is None:
                 just = pos
-            just = cast(tuple[float, float], just)
+            just = cast("tuple[float, float]", just)
             return (pos, just)
 
     def train(
@@ -191,9 +188,9 @@ class GuideElements:
     def title(self):
         ha = self.theme.getp(("legend_title", "ha"))
         va = self.theme.getp(("legend_title", "va"), "center")
-        _margin = self.theme.getp(("legend_title", "margin"))
+        _margin = self.theme.getp(("legend_title", "margin")).pt
         _loc = get_opposite_side(self.title_position)[0]
-        margin = _margin.get_as(_loc, "pt") if _margin else 0
+        margin = getattr(_margin, _loc)
         top_or_bottom = self.title_position in ("top", "bottom")
         is_blank = self.theme.T.is_blank("legend_title")
 
@@ -213,17 +210,19 @@ class GuideElements:
         )
 
     @cached_property
-    def text_position(self) -> SidePosition:
+    def text_position(self) -> Side:
         raise NotImplementedError
 
     @cached_property
     def _text_margin(self) -> float:
-        _margin = self.theme.getp((f"legend_text_{self.guide_kind}", "margin"))
-        _loc = get_opposite_side(self.text_position)
-        return _margin.get_as(_loc[0], "pt") if _margin else 0
+        _margin = self.theme.getp(
+            (f"legend_text_{self.guide_kind}", "margin")
+        ).pt
+        _loc = get_opposite_side(self.text_position)[0]
+        return getattr(_margin, _loc)
 
     @cached_property
-    def title_position(self) -> SidePosition:
+    def title_position(self) -> Side:
         if not (pos := self.theme.getp("legend_title_position")):
             pos = "top" if self.is_vertical else "left"
         return pos
@@ -242,7 +241,7 @@ class GuideElements:
         return direction
 
     @cached_property
-    def position(self) -> SidePosition | tuple[float, float]:
+    def position(self) -> Side | tuple[float, float]:
         if (guide_pos := self.guide.position) == "inside":
             guide_pos = self._position_inside
 
@@ -254,7 +253,7 @@ class GuideElements:
         return pos
 
     @cached_property
-    def _position_inside(self) -> SidePosition | tuple[float, float]:
+    def _position_inside(self) -> Side | tuple[float, float]:
         pos = self.theme.getp("legend_position_inside")
         if isinstance(pos, tuple):
             return pos

plotnine/guides/guide_colorbar.py

@@ -27,7 +27,7 @@ if TYPE_CHECKING:
 
     from plotnine import theme
     from plotnine.scales.scale import scale
-    from plotnine.typing import SidePosition
+    from plotnine.typing import Side
 
 
 @dataclass
@@ -75,8 +75,8 @@ class guide_colorbar(guide):
             self.nbin = 300  # if self.display == "gradient" else 300
 
     def train(self, scale: scale, aesthetic=None):
-        self.nbin = cast(int, self.nbin)
-        self.title = cast(str, self.title)
+        self.nbin = cast("int", self.nbin)
+        self.title = cast("str", self.title)
 
         if not isinstance(scale, scale_continuous):
             warn("colorbar guide needs continuous scales", PlotnineWarning)
@@ -213,7 +213,7 @@ class guide_colorbar(guide):
         auxbox = DPICorAuxTransformBox(IdentityTransform())
 
         # title
-        title = cast(str, self.title)
+        title = cast("str", self.title)
         props = {"ha": elements.title.ha, "va": elements.title.va}
         title_box = TextArea(title, textprops=props)
         targets.legend_title = title_box._text  # type: ignore
@@ -242,7 +242,7 @@ class guide_colorbar(guide):
         targets.legend_frame = frame
 
         # title + colorbar(with labels)
-        lookup: dict[SidePosition, tuple[type[PackerBase], slice]] = {
+        lookup: dict[Side, tuple[type[PackerBase], slice]] = {
             "right": (HPacker, reverse),
             "left": (HPacker, obverse),
             "bottom": (VPacker, reverse),
@@ -495,7 +495,7 @@ class GuideElementsColorbar(GuideElements):
         )
 
     @cached_property
-    def text_position(self) -> SidePosition:
+    def text_position(self) -> Side:
         if not (position := self.theme.getp("legend_text_position")):
             position = "right" if self.is_vertical else "bottom"