plotnine 0.15.3__py3-none-any.whl → 0.16.0a1__py3-none-any.whl

plotnine/ggplot.py

@@ -13,6 +13,7 @@ from typing import (
     Iterable,
     Optional,
     cast,
+    overload,
 )
 from warnings import warn
 
@@ -52,6 +53,7 @@ if TYPE_CHECKING:
 
     from plotnine import watermark
     from plotnine._mpl.gridspec import p9GridSpec
+    from plotnine._mpl.layout_manager._plot_side_space import PlotSideSpaces
     from plotnine.composition import Compose
     from plotnine.coords.coord import coord
     from plotnine.facets.facet import facet
@@ -104,6 +106,31 @@ class ggplot:
     figure: Figure
     axs: list[Axes]
     _gridspec: p9GridSpec
+    """
+    Gridspec (1x1) that contains the whole plot
+    """
+
+    _sub_gridspec: p9GridSpec
+    """
+    Gridspec (nxn) that contains the facet panels
+
+     -------------------------
+    |  title                  |<----- ._gridspec
+    |  subtitle               |
+    |                         |
+    |   -------------         |
+    |  |      |      |<-------+------ ._sub_gridspec
+    |  |      |      |        |
+    |  |      |      | legend |
+    |   -------------         |
+    |   axis_ticks            |
+    |   axis_text             |
+    |   axis_title            |
+    |                 caption |
+     -------------------------
+    """
+
+    _sidespaces: PlotSideSpaces
 
     def __init__(
         self,
@@ -128,7 +155,7 @@ class ggplot:
         self.watermarks: list[watermark] = []
 
         # build artefacts
-        self._build_objs = NS()
+        self._build_objs = NS(meta={})
 
     def __str__(self) -> str:
         """
@@ -230,10 +257,19 @@ class ggplot:
             other.__radd__(self)
         return self
 
+    @overload
     def __add__(
         self,
         rhs: PlotAddable | list[PlotAddable] | None,
-    ) -> ggplot:
+    ) -> ggplot: ...
+
+    @overload
+    def __add__(self, rhs: ggplot) -> Compose: ...
+
+    def __add__(
+        self,
+        rhs: PlotAddable | list[PlotAddable] | None | ggplot,
+    ) -> ggplot | Compose:
         """
         Add to ggplot
 
@@ -243,7 +279,15 @@ class ggplot:
             Either an object that knows how to "radd"
             itself to a ggplot, or a list of such objects.
         """
+        from .composition import Compose
+
         self = deepcopy(self)
+
+        if isinstance(rhs, (ggplot, Compose)):
+            from .composition import Wrap
+
+            return Wrap([self, rhs])
+
         return self.__iadd__(rhs)
 
     def __or__(self, rhs: ggplot | Compose) -> Compose:
@@ -306,9 +350,14 @@ class ggplot:
             self._build()
 
             # setup
-            self.axs = self.facet.setup(self)
+            self._sub_gridspec, self.axs = self.facet.setup(self)
             self.guides._setup(self)
-            self.theme.setup(self)
+            self.theme._setup(
+                figure,
+                self.axs,
+                self.labels.title,
+                self.labels.subtitle,
+            )
 
             # Drawing
             self._draw_layers()
@@ -317,7 +366,7 @@ class ggplot:
             self.guides.draw()
             self._draw_figure_texts()
             self._draw_watermarks()
-            self._draw_figure_background()
+            self._draw_plot_background()
 
             # Artist object theming
             self.theme.apply()
@@ -329,9 +378,7 @@ class ggplot:
         """
         Setup this instance for the building process
         """
-        if not hasattr(self, "figure"):
-            self._create_figure()
-
+        self._create_figure()
         self.labels.add_defaults(self.mapping.labels)
         return self.figure
 
@@ -339,6 +386,9 @@ class ggplot:
         """
         Create gridspec for the panels
         """
+        if hasattr(self, "figure"):
+            return
+
         import matplotlib.pyplot as plt
 
         from ._mpl.gridspec import p9GridSpec
@@ -536,7 +586,7 @@ class ggplot:
         for wm in self.watermarks:
             wm.draw(self.figure)
 
-    def _draw_figure_background(self):
+    def _draw_plot_background(self):
         from matplotlib.patches import Rectangle
 
         rect = Rectangle((0, 0), 0, 0, facecolor="none", zorder=-1000)
@@ -577,6 +627,9 @@ class ggplot:
         This method has the same arguments as [](`~plotnine.ggplot.save`).
         Use it to get access to the figure that will be saved.
         """
+        if format is None and isinstance(filename, (str, Path)):
+            format = str(filename).split(".")[-1]
+
         fig_kwargs: Dict[str, Any] = {"format": format, **kwargs}
 
         if limitsize is None:
@@ -626,6 +679,7 @@ class ggplot:
         if dpi is not None:
             self.theme = self.theme + theme(dpi=dpi)
 
+        self._build_objs.meta["figure_format"] = format
         figure = self.draw(show=False)
         return mpl_save_view(figure, fig_kwargs)
 

plotnine/guides/guide.py

@@ -11,13 +11,14 @@ from .._utils.registry import Register
 from ..themes.theme import theme as Theme
 
 if TYPE_CHECKING:
-    from typing import Literal, Optional, TypeAlias
+    from typing import Literal, Optional, Sequence, TypeAlias
 
     import pandas as pd
     from matplotlib.offsetbox import PackerBase
     from typing_extensions import Self
 
     from plotnine import aes, guides
+    from plotnine.iapi import guide_text
     from plotnine.layer import Layers, layer
     from plotnine.scales.scale import scale
     from plotnine.typing import (
@@ -113,7 +114,7 @@ class guide(ABC, metaclass=Register):
         # guide theme has priority and its targets are tracked
         # independently.
         self.theme = guides.plot.theme + self.theme
-        self.theme.setup(guides.plot)
+        self.theme._setup(guides.plot.figure)
         self.plot_layers = guides.plot.layers
         self.plot_mapping = guides.plot.mapping
         self.elements = self._elements_cls(self.theme, self)
@@ -139,6 +140,13 @@ class guide(ABC, metaclass=Register):
             just = cast("tuple[float, float]", just)
             return (pos, just)
 
+    @property
+    def num_breaks(self) -> int:
+        """
+        Number of breaks
+        """
+        return len(self.key)
+
     def train(
         self, scale: scale, aesthetic: Optional[str] = None
     ) -> Self | None:
@@ -148,6 +156,12 @@ class guide(ABC, metaclass=Register):
         Returns guide if training is successful
         """
 
+    def merge(self, other: Self) -> Self:
+        """
+        Merge with another guide
+        """
+        return self
+
     def draw(self) -> PackerBase:
         """
         Draw guide
@@ -176,6 +190,10 @@ class GuideElements:
     theme: Theme
     guide: guide
 
+    @cached_property
+    def text(self) -> guide_text:
+        raise NotImplementedError
+
     def __post_init__(self):
         self.guide_kind = type(self.guide).__name__.split("_")[-1]
         self._elements_cls = GuideElements
@@ -210,16 +228,16 @@ class GuideElements:
         )
 
     @cached_property
-    def text_position(self) -> Side:
+    def text_positions(self) -> Sequence[Side]:
         raise NotImplementedError
 
     @cached_property
-    def _text_margin(self) -> float:
+    def _text_margin(self) -> Sequence[float]:
         _margin = self.theme.getp(
             (f"legend_text_{self.guide_kind}", "margin")
         ).pt
-        _loc = get_opposite_side(self.text_position)[0]
-        return getattr(_margin, _loc)
+        locs = (get_opposite_side(p)[0] for p in self.text_positions)
+        return [getattr(_margin, loc) for loc in locs]
 
     @cached_property
     def title_position(self) -> Side:

plotnine/guides/guide_colorbar.py

@@ -11,6 +11,8 @@ import numpy as np
 import pandas as pd
 from mizani.bounds import rescale
 
+from plotnine.iapi import guide_text
+
 from .._utils import get_opposite_side
 from ..exceptions import PlotnineError, PlotnineWarning
 from ..mapping.aes import rename_aesthetics
@@ -26,6 +28,7 @@ if TYPE_CHECKING:
     from matplotlib.text import Text
 
     from plotnine import theme
+    from plotnine.guides import guides
     from plotnine.scales.scale import scale
     from plotnine.typing import Side
 
@@ -48,7 +51,12 @@ class guide_colorbar(guide):
     """
 
     display: Literal["gradient", "rectangles", "raster"] = "gradient"
-    """How to render the colorbar."""
+    """
+    How to render the colorbar
+
+    SVG figures will always use "rectangles" to create gradients. This has
+    better support across applications that render svg images.
+    """
 
     alpha: Optional[float] = None
     """
@@ -74,6 +82,12 @@ class guide_colorbar(guide):
         if self.nbin is None:
             self.nbin = 300  # if self.display == "gradient" else 300
 
+    def setup(self, guides: guides):
+        super().setup(guides)
+        # See: add_segmented_colorbar
+        if guides.plot._build_objs.meta.get("figure_format") == "svg":
+            self.display = "rectangles"
+
     def train(self, scale: scale, aesthetic=None):
         self.nbin = cast("int", self.nbin)
         self.title = cast("str", self.title)
@@ -121,12 +135,6 @@ class guide_colorbar(guide):
         self.hash = hashlib.sha256(info.encode("utf-8")).hexdigest()
         return self
 
-    def merge(self, other):
-        """
-        Simply discards the other guide
-        """
-        return self
-
     def create_geoms(self):
         """
         Return self if colorbar will be drawn and None if not
@@ -177,6 +185,7 @@ class guide_colorbar(guide):
         nbars = len(self.bar)
         elements = self.elements
         raster = self.display == "raster"
+        alpha = self.alpha
 
         colors = self.bar["color"].tolist()
         labels = self.key["label"].tolist()
@@ -225,9 +234,9 @@ class guide_colorbar(guide):
 
         # colorbar
         if self.display == "rectangles":
-            add_segmented_colorbar(auxbox, colors, elements)
+            add_segmented_colorbar(auxbox, colors, alpha, elements)
         else:
-            add_gradient_colorbar(auxbox, colors, elements, raster)
+            add_gradient_colorbar(auxbox, colors, alpha, elements, raster)
 
         # ticks
         visible = slice(
@@ -270,6 +279,7 @@ guide_colourbar = guide_colorbar
 def add_gradient_colorbar(
     auxbox: AuxTransformBox,
     colors: Sequence[str],
+    alpha: float | None,
     elements: GuideElementsColorbar,
     raster: bool = False,
 ):
@@ -325,6 +335,7 @@ def add_gradient_colorbar(
         shading="gouraud",
         cmap=cmap,
         array=Z.ravel(),
+        alpha=alpha,
         rasterized=raster,
     )
     auxbox.add_artist(coll)
@@ -333,6 +344,7 @@ def add_gradient_colorbar(
 def add_segmented_colorbar(
     auxbox: AuxTransformBox,
     colors: Sequence[str],
+    alpha: float | None,
     elements: GuideElementsColorbar,
 ):
     """
@@ -341,6 +353,21 @@ def add_segmented_colorbar(
     from matplotlib.collections import PolyCollection
 
     nbreak = len(colors)
+    # Problem:
+    # 1. Webbrowsers do not properly render SVG with QuadMesh
+    #    colorbars. Also when the QuadMesh is "rasterized",
+    #    the colorbar is misplaced within the SVG (and pdfs!).
+    #    So SVGs cannot use `add_gradient_colobar` at all.
+    # 2. Webbrowsers do not properly render SVG with PolyCollection
+    #    colorbars when the adjacent rectangles that make up the
+    #    colorbar touch each other precisely. The "bars" appear to
+    #    be separated by lines.
+    #
+    # For a wayout, we overlap the bars. Overlapping creates artefacts
+    # when alpha < 1, but having a gradient + alpha is rare. And, we can
+    # minimise apparent artefacts by using a large overlap_factor.
+    # A value of 2 gives the best results in the rare case should alpha < 1.
+    overlap_factor = 2
     if elements.is_vertical:
         colorbar_height = elements.key_height
         colorbar_width = elements.key_width
@@ -351,6 +378,8 @@ def add_segmented_colorbar(
         for i in range(nbreak):
             y1 = i * linewidth
             y2 = y1 + linewidth
+            if i > 1:
+                y1 -= linewidth * overlap_factor
             verts.append(((x1, y1), (x1, y2), (x2, y2), (x2, y1)))
     else:
         colorbar_width = elements.key_height
@@ -362,12 +391,15 @@ def add_segmented_colorbar(
         for i in range(nbreak):
             x1 = i * linewidth
             x2 = x1 + linewidth
+            if i > 1:
+                x1 -= linewidth * overlap_factor
             verts.append(((x1, y1), (x1, y2), (x2, y2), (x2, y1)))
 
     coll = PolyCollection(
         verts,
         facecolors=colors,
         linewidth=0,
+        alpha=alpha,
         antialiased=False,
     )
     auxbox.add_artist(coll)
@@ -417,28 +449,29 @@ def add_labels(
     """
     from matplotlib.text import Text
 
-    n = len(labels)
-    sep = elements.text.margin
+    seps = elements.text.margins
     texts: list[Text] = []
-    props = {"ha": elements.text.ha, "va": elements.text.va}
+    has = elements.text.has
+    vas = elements.text.vas
+    width = elements.key_width
 
     # The horizontal and vertical alignments are set in the theme
     # or dynamically calculates in GuideElements and added to the
     # themeable properties dict
     if elements.is_vertical:
-        if elements.text_position == "right":
-            xs = [elements.key_width + sep] * n
-        else:
-            xs = [-sep] * n
+        xs = [
+            width + sep if side == "right" else -sep
+            for side, sep in zip(elements.text_positions, seps)
+        ]
     else:
         xs = ys
-        if elements.text_position == "bottom":
-            ys = [-sep] * n
-        else:
-            ys = [elements.key_width + sep] * n
+        ys = [
+            -sep if side == "bottom" else width + sep
+            for side, sep in zip(elements.text_positions, seps)
+        ]
 
-    for x, y, s in zip(xs, ys, labels):
-        t = Text(x, y, s, **props)
+    for x, y, s, ha, va in zip(xs, ys, labels, has, vas):
+        t = Text(x, y, s, ha=ha, va=va)
         auxbox.add_artist(t)
         texts.append(t)
 
@@ -474,43 +507,52 @@ class GuideElementsColorbar(GuideElements):
         ha = self.theme.getp(("legend_text_colorbar", "ha"))
         va = self.theme.getp(("legend_text_colorbar", "va"))
         is_blank = self.theme.T.is_blank("legend_text_colorbar")
+        n = self.guide.num_breaks
 
         # Default text alignment depends on the direction of the
         # colorbar
-        _loc = get_opposite_side(self.text_position)
+        centers = ("center",) * n
+        has = (ha,) * n if isinstance(ha, str) else ha
+        vas = (va,) * n if isinstance(va, str) else va
+        opposite_sides = [get_opposite_side(s) for s in self.text_positions]
         if self.is_vertical:
-            ha = ha or _loc
-            va = va or "center"
+            has = has or opposite_sides
+            vas = vas or centers
         else:
-            va = va or _loc
-            ha = ha or "center"
-
-        return NS(
-            margin=self._text_margin,
-            align=None,
+            vas = vas or opposite_sides
+            has = has or centers
+        return guide_text(
+            self._text_margin,
+            aligns=centers,
             fontsize=size,
-            ha=ha,
-            va=va,
+            has=has,  # pyright: ignore[reportArgumentType]
+            vas=vas,  # pyright: ignore[reportArgumentType]
             is_blank=is_blank,
         )
 
     @cached_property
-    def text_position(self) -> Side:
-        if not (position := self.theme.getp("legend_text_position")):
+    def text_positions(self) -> Sequence[Side]:
+        if not (user_position := self.theme.getp("legend_text_position")):
             position = "right" if self.is_vertical else "bottom"
+            return (position,) * self.guide.num_breaks
 
-        if self.is_vertical and position not in ("right", "left"):
-            msg = (
-                "The text position for a vertical legend must be "
-                "either left or right."
-            )
-            raise PlotnineError(msg)
-        elif self.is_horizontal and position not in ("bottom", "top"):
-            msg = (
-                "The text position for a horizonta legend must be "
-                "either top or bottom."
+        alternate = {"left-right", "right-left", "bottom-top", "top-bottom"}
+        if user_position in alternate:
+            tup = user_position.split("-")
+            return [tup[i % 2] for i in range(self.guide.num_breaks)]
+
+        position = cast("Side | Sequence[Side]", user_position)
+
+        if isinstance(position, str):
+            position = (position,) * self.guide.num_breaks
+
+        valid = {"right", "left"} if self.is_vertical else {"bottom", "top"}
+        if any(p for p in position if p not in valid):
+            raise PlotnineError(
+                "The text position for a horizontal legend must be "
+                f"either one of {valid!r}. I got {user_position!r}."
             )
-            raise PlotnineError(msg)
+
         return position
 
     @cached_property

plotnine/guides/guide_legend.py

@@ -5,20 +5,21 @@ from contextlib import suppress
 from dataclasses import dataclass, field
 from functools import cached_property
 from itertools import islice
-from types import SimpleNamespace as NS
 from typing import TYPE_CHECKING, cast
 from warnings import warn
 
 import numpy as np
 import pandas as pd
 
+from plotnine.iapi import guide_text
+
 from .._utils import remove_missing
 from ..exceptions import PlotnineError, PlotnineWarning
 from ..mapping.aes import rename_aesthetics
 from .guide import GuideElements, guide
 
 if TYPE_CHECKING:
-    from typing import Any, Optional
+    from typing import Any, Optional, Sequence
 
     from matplotlib.artist import Artist
     from matplotlib.offsetbox import PackerBase
@@ -209,7 +210,7 @@ class guide_legend(guide):
         self, elements: GuideElementsLegend
     ) -> tuple[int, int]:
         nrow, ncol = self.nrow, self.ncol
-        nbreak = len(self.key)
+        nbreak = self.num_breaks
 
         if nrow and ncol:
             if nrow * ncol < nbreak:
@@ -248,7 +249,7 @@ class guide_legend(guide):
 
         obverse = slice(0, None)
         reverse = slice(None, None, -1)
-        nbreak = len(self.key)
+        nbreak = self.num_breaks
         targets = self.theme.targets
         keys_order = reverse if self.reverse else obverse
         elements = self.elements
@@ -259,8 +260,12 @@ class guide_legend(guide):
         targets.legend_title = title_box._text  # type: ignore
 
         # labels
-        props = {"ha": elements.text.ha, "va": elements.text.va}
-        labels = [TextArea(s, textprops=props) for s in self.key["label"]]
+        has = elements.text.has
+        vas = elements.text.vas
+        labels = [
+            TextArea(s, textprops={"ha": ha, "va": va})
+            for s, ha, va in zip(self.key["label"], has, vas)
+        ]
         _texts = [l._text for l in labels]  # type: ignore
         targets.legend_text_legend = _texts
 
@@ -287,18 +292,28 @@ class guide_legend(guide):
             "bottom": (VPacker, reverse),
             "top": (VPacker, obverse),
         }
-        packer, slc = lookup[elements.text_position]
+
         if self.elements.text.is_blank:
             key_boxes = [d for d in drawings][keys_order]
         else:
+            packers, slices = [], []
+            for side in elements.text_positions:
+                tup = lookup[side]
+                packers.append(tup[0])
+                slices.append(tup[1])
+
+            seps = elements.text.margins
+            aligns = elements.text.aligns
             key_boxes = [
                 packer(
                     children=[l, d][slc],
-                    sep=elements.text.margin,
-                    align=elements.text.align,
+                    sep=sep,
+                    align=align,
                     pad=0,
                 )
-                for d, l in zip(drawings, labels)
+                for d, l, packer, slc, sep, align in zip(
+                    drawings, labels, packers, slices, seps, aligns
+                )
             ][keys_order]
 
         # Put the entries together in rows or columns
@@ -364,26 +379,38 @@ class GuideElementsLegend(GuideElements):
         ha = self.theme.getp(("legend_text_legend", "ha"), "center")
         va = self.theme.getp(("legend_text_legend", "va"), "center")
         is_blank = self.theme.T.is_blank("legend_text_legend")
+        n = self.guide.num_breaks
 
         # The original ha & va values are used by the HPacker/VPacker
         # to align the TextArea with the DrawingArea.
         # We set ha & va to values that combine best with the aligning
         # for the text area.
-        align = va if self.text_position in {"left", "right"} else ha
-        return NS(
-            margin=self._text_margin,
-            align=align,
+        has = (ha,) * n if isinstance(ha, str) else ha
+        vas = (va,) * n if isinstance(va, str) else va
+        aligns = [
+            va if side in ("right", "left") else ha
+            for side, ha, va in zip(self.text_positions, has, vas)
+        ]
+        return guide_text(
+            margins=self._text_margin,
+            aligns=aligns,  # pyright: ignore[reportArgumentType]
             fontsize=size,
-            ha="center",
-            va="baseline",
+            has=("center",) * n,
+            vas=("baseline",) * n,
             is_blank=is_blank,
         )
 
     @cached_property
-    def text_position(self) -> Side:
-        if not (pos := self.theme.getp("legend_text_position")):
-            pos = "right"
-        return pos
+    def text_positions(self) -> Sequence[Side]:
+        if not (position := self.theme.getp("legend_text_position")):
+            return ("right",) * self.guide.num_breaks
+
+        position = cast("Side | Sequence[Side]", position)
+
+        if isinstance(position, str):
+            position = (position,) * self.guide.num_breaks
+
+        return position
 
     @cached_property
     def key_spacing_x(self) -> float:

plotnine/guides/guides.py

@@ -31,12 +31,12 @@ if TYPE_CHECKING:
     from plotnine.scales.scale import scale
     from plotnine.scales.scales import Scales
     from plotnine.typing import (
+        Justification,
         LegendPosition,
         NoGuide,
         Orientation,
         ScaledAestheticsName,
         Side,
-        TextJustification,
     )
 
     LegendOrColorbar: TypeAlias = (
@@ -437,7 +437,7 @@ class GuidesElements:
         return ensure_xy_location(just)
 
     @cached_property
-    def box_just(self) -> TextJustification:
+    def box_just(self) -> Justification | Literal["baseline"]:
         if not (box_just := self.theme.getp("legend_box_just")):
             box_just = (
                 "left" if self.position in {"left", "right"} else "right"