plotnine 0.14.4__py3-none-any.whl → 0.15.0.dev1__py3-none-any.whl

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):
@@ -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

@@ -76,7 +76,7 @@ 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):
@@ -132,14 +132,14 @@ class guide(ABC, metaclass=Register):
         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 +191,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")
 
@@ -218,9 +218,11 @@ class GuideElements:
 
     @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:

plotnine/guides/guide_colorbar.py

@@ -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

plotnine/guides/guide_legend.py

@@ -226,10 +226,10 @@ class guide_legend(guide):
                 ncol = int(np.ceil(nbreak / 15))
 
         if nrow is None:
-            ncol = cast(int, ncol)
+            ncol = cast("int", ncol)
             nrow = int(np.ceil(nbreak / ncol))
         elif ncol is None:
-            nrow = cast(int, nrow)
+            nrow = cast("int", nrow)
             ncol = int(np.ceil(nbreak / nrow))
 
         return nrow, ncol
@@ -255,7 +255,7 @@ class guide_legend(guide):
         elements = self.elements
 
         # title
-        title = cast(str, self.title)
+        title = cast("str", self.title)
         title_box = TextArea(title)
         targets.legend_title = title_box._text  # type: ignore
 
@@ -403,7 +403,7 @@ class GuideElementsLegend(GuideElements):
         dimensions are big enough.
         """
         #  Note the different height sizes for the entries
-        guide = cast(guide_legend, self.guide)
+        guide = cast("guide_legend", self.guide)
         min_size = (
             self.theme.getp("legend_key_width"),
             self.theme.getp("legend_key_height"),
@@ -452,7 +452,7 @@ class GuideElementsLegend(GuideElements):
         If legend is horizontal, then key heights must be equal, so we
         use the maximum
         """
-        hs = [h for h, _ in self._key_dimensions]
+        hs = [h for _, h in self._key_dimensions]
         if self.is_horizontal:
             return [max(hs)] * len(hs)
         return hs

plotnine/guides/guides.py

@@ -342,8 +342,8 @@ class guides:
             if isinstance(position, str) and isinstance(just, (float, int)):
                 setattr(legends, position, outside_legend(aob, just))
             else:
-                position = cast(tuple[float, float], position)
-                just = cast(tuple[float, float], just)
+                position = cast("tuple[float, float]", position)
+                just = cast("tuple[float, float]", just)
                 legends.inside.append(inside_legend(aob, just, position))
 
         return legends
@@ -467,7 +467,7 @@ class GuidesElements:
             if just is None:
                 just = (0.5, 0.5)
             elif just in VALID_JUSTIFICATION_WORDS:
-                just = ensure_xy_location(just)  # pyright: ignore[reportArgumentType]
+                just = ensure_xy_location(just)
             elif isinstance(just, (float, int)):
                 just = (just, just)
             return just[idx]

plotnine/iapi.py

@@ -76,6 +76,7 @@ class labels_view:
     title: Optional[str] = None
     caption: Optional[str] = None
     subtitle: Optional[str] = None
+    tag: Optional[str] = None
 
     def update(self, other: labels_view):
         """

plotnine/labels.py

@@ -90,6 +90,11 @@ class labs:
     The caption at the bottom of the plot.
     """
 
+    tag: str | None = None
+    """
+    A plot tag
+    """
+
     def __post_init__(self):
         kwargs: dict[str, str] = {
             f.name: value

plotnine/options.py

@@ -10,14 +10,11 @@ if TYPE_CHECKING:
     from plotnine import theme
     from plotnine.typing import FigureFormat
 
-close_all_figures = False
-"""
-Development flag, e.g. set to `True` to prevent
-the queuing up of figures when errors happen.
-"""
-
 current_theme: Optional[theme | Type[theme]] = None
-"""Theme used when none is added to the ggplot object"""
+"""Theme used when none is added to the ggplot object
+
+Another way to do it, to set a default theme using `theme_set()`.
+"""
 
 base_family: str = "sans-serif"
 """
@@ -77,6 +74,11 @@ def get_option(name: str) -> Any:
     ----------
     name :
         Name of the option
+
+    Notes
+    -----
+    See [reference](/reference/#options) for a list of all the available
+    options.
     """
     d = globals()
 
@@ -103,6 +105,11 @@ def set_option(name: str, value: Any) -> Any:
     -------
     :
         Old value of the option
+
+    Notes
+    -----
+    See [reference](/reference/#options) for a list of all the available
+    options.
     """
     d = globals()
 

plotnine/plot_composition/__init__.py

@@ -0,0 +1,10 @@
+from ._compose import ADD, DIV, OR, Compose
+from ._spacer import spacer
+
+__all__ = (
+    "Compose",
+    "ADD",
+    "DIV",
+    "OR",
+    "spacer",
+)