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

plotnine/plot_composition/_compose.py

@@ -0,0 +1,462 @@
+from __future__ import annotations
+
+import abc
+from copy import deepcopy
+from dataclasses import dataclass
+from io import BytesIO
+from typing import TYPE_CHECKING
+
+from .._utils.ipython import (
+    get_display_function,
+    get_ipython,
+)
+from ..options import get_option
+from ._plotspec import plotspec
+
+if TYPE_CHECKING:
+    from pathlib import Path
+    from typing import Generator, Iterator, Self
+
+    from matplotlib.figure import Figure
+
+    from plotnine._mpl.gridspec import p9GridSpec
+    from plotnine._utils.ipython import FigureFormat
+    from plotnine.ggplot import PlotAddable, ggplot
+
+
+class Compose:
+    """
+    Arrange two or more plots
+
+    Parameters
+    ----------
+    operands:
+        The objects to be put together (composed).
+    """
+
+    def __init__(self, operands: list[ggplot | Compose]):
+        self.operands = operands
+
+        # These are created in the _create_figure method
+        self.figure: Figure
+        self.plotspecs: list[plotspec]
+        self.gridspec: p9GridSpec
+
+    @abc.abstractmethod
+    def __or__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Add rhs as a column
+        """
+
+    @abc.abstractmethod
+    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Add rhs as a row
+        """
+
+    def __add__(self, rhs: ggplot | Compose | PlotAddable) -> Compose:
+        """
+        Add rhs to the composition
+
+        Parameters
+        ----------
+        rhs:
+            What to add to the composition
+        """
+        from plotnine import ggplot
+
+        if not isinstance(rhs, (ggplot, Compose)):
+            cmp = deepcopy(self)
+            cmp.last_plot = cmp.last_plot + rhs
+            return cmp
+        return self.__class__([*self, rhs])
+
+    def __sub__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Add the rhs besides the composition
+
+        Parameters
+        ----------
+        rhs:
+            What to place besides the composition
+        """
+        return self.__class__([self, rhs])
+
+    def __and__(self, rhs: PlotAddable) -> Compose:
+        """
+        Add rhs to all plots in the composition
+
+        Parameters
+        ----------
+        rhs:
+            What to add.
+        """
+        self = deepcopy(self)
+
+        def add_other(op: Compose):
+            for item in op:
+                if isinstance(item, Compose):
+                    add_other(item)
+                else:
+                    item += rhs
+
+        add_other(self)
+        return self
+
+    def __mul__(self, rhs: PlotAddable) -> Compose:
+        """
+        Add rhs to the outermost nesting level of the composition
+
+        Parameters
+        ----------
+        rhs:
+            What to add.
+        """
+        from plotnine import ggplot
+
+        self = deepcopy(self)
+
+        for item in self:
+            if isinstance(item, ggplot):
+                item += rhs
+        return self
+
+    def __len__(self) -> int:
+        """
+        Number of operand
+        """
+        return len(self.operands)
+
+    def __iter__(self) -> Iterator[ggplot | Compose]:
+        """
+        Return an iterable of all the operands
+        """
+        return iter(self.operands)
+
+    def _ipython_display_(self):
+        """
+        Display plot in the output of the cell
+        """
+        return self._display()
+
+    @property
+    def nrow(self) -> int:
+        """
+        Number of rows in the composition
+        """
+        return 0
+
+    @property
+    def ncol(self) -> int:
+        """
+        Number of cols in the composition
+        """
+        return 0
+
+    @property
+    def last_plot(self) -> ggplot:
+        """
+        Last plot added to the composition
+        """
+        from plotnine import ggplot
+
+        last_operand = self.operands[-1]
+        if isinstance(last_operand, ggplot):
+            return last_operand
+        else:
+            return last_operand.last_plot
+
+    @last_plot.setter
+    def last_plot(self, plot: ggplot):
+        """
+        Replace the last plot in the composition
+        """
+        from plotnine import ggplot
+
+        last_operand = self.operands[-1]
+        if isinstance(last_operand, ggplot):
+            self.operands[-1] = plot
+        else:
+            last_operand.last_plot = plot
+
+    def __deepcopy__(self, memo):
+        """
+        Deep copy without copying the figure
+        """
+        cls = self.__class__
+        result = cls.__new__(cls)
+        memo[id(self)] = result
+        old = self.__dict__
+        new = result.__dict__
+
+        shallow = {"figure", "gridsspec", "__copy"}
+        for key, item in old.items():
+            if key in shallow:
+                new[key] = item
+                memo[id(new[key])] = new[key]
+            else:
+                new[key] = deepcopy(item, memo)
+
+        old["__copy"] = result
+
+        return result
+
+    def _to_retina(self):
+        from plotnine import ggplot
+
+        for item in self:
+            if isinstance(item, ggplot):
+                item.theme = item.theme.to_retina()
+            else:
+                item._to_retina()
+
+    def _create_gridspec(self, figure, nest_into):
+        """
+        Create the gridspec for this composition
+        """
+        from plotnine._mpl.gridspec import p9GridSpec
+
+        self.gridspec = p9GridSpec(
+            self.nrow, self.ncol, figure, nest_into=nest_into
+        )
+
+    def _create_figure(self):
+        import matplotlib.pyplot as plt
+
+        from plotnine import ggplot
+        from plotnine._mpl.gridspec import p9GridSpec
+
+        def _make_plotspecs(
+            cmp: Compose, parent_gridspec: p9GridSpec | None
+        ) -> Generator[plotspec]:
+            """
+            Return the plot specification for each subplot in the composition
+            """
+            # This gridspec contains a composition group e.g.
+            # (p2 | p3) of p1 | (p2 | p3)
+            ss_or_none = parent_gridspec[0] if parent_gridspec else None
+            cmp._create_gridspec(self.figure, ss_or_none)
+
+            # Each subplot in the composition will contain one of:
+            #    1. A plot
+            #    2. A plot composition
+            #    3. Nothing
+            # Iterating over the gridspec yields the SubplotSpecs for each
+            # "subplot" in the grid. The SubplotSpec is the handle that
+            # allows us to set it up for a plot or to nest another gridspec
+            # in it.
+            for item, subplot_spec in zip(cmp, cmp.gridspec):  # pyright: ignore[reportArgumentType]
+                if isinstance(item, ggplot):
+                    yield plotspec(
+                        item,
+                        self.figure,
+                        cmp.gridspec,
+                        subplot_spec,
+                        p9GridSpec(1, 1, self.figure, nest_into=subplot_spec),
+                    )
+                elif item:
+                    yield from _make_plotspecs(
+                        item,
+                        p9GridSpec(1, 1, self.figure, nest_into=subplot_spec),
+                    )
+
+        self.figure = plt.figure()
+        self.plotspecs = list(_make_plotspecs(self, None))
+
+    def _display(self):
+        """
+        Display plot in the cells output
+
+        This function is called for its side-effects.
+
+        It draws the plot to an io buffer then uses ipython display
+        methods to show the result.
+        """
+        ip = get_ipython()
+        format: FigureFormat = get_option(
+            "figure_format"
+        ) or ip.config.InlineBackend.get("figure_format", "retina")
+
+        if format == "retina":
+            self = deepcopy(self)
+            self._to_retina()
+
+        buf = BytesIO()
+        self.save(buf, "png" if format == "retina" else format)
+        figure_size_px = self.last_plot.theme._figure_size_px
+        display_func = get_display_function(format, figure_size_px)
+        display_func(buf.getvalue())
+
+    def draw(self, *, show: bool = False) -> Figure:
+        """
+        Render the composed plots
+
+        Parameters
+        ----------
+        show :
+            Whether to show the plot.
+
+        Returns
+        -------
+        :
+            Matplotlib figure
+        """
+        from .._mpl.layout_manager import PlotnineCompositionLayoutEngine
+
+        with plot_composition_context(self, show):
+            self._create_figure()
+            figure = self.figure
+
+            for ps in self.plotspecs:
+                ps.plot.draw()
+
+            self.figure.set_layout_engine(
+                PlotnineCompositionLayoutEngine(self)
+            )
+        return figure
+
+    def save(self, filename: str | Path | BytesIO, format: str | None = None):
+        """
+        Save a Compose object as an image file
+
+        Parameters
+        ----------
+        filename :
+            File name to write the plot to. If not specified, a name
+        format :
+            Image format to use, automatically extract from
+            file name extension.
+        """
+        figure = self.draw()
+        figure.savefig(filename, format=format)
+
+
+@dataclass
+class plot_composition_context:
+    cmp: Compose
+    show: bool
+
+    def __post_init__(self):
+        import matplotlib as mpl
+
+        # The dpi is needed when the figure is created, either as
+        # a parameter to plt.figure() or an rcParam.
+        # https://github.com/matplotlib/matplotlib/issues/24644
+        # When drawing the Composition, the dpi themeable is infective
+        # because it sets the rcParam after this figure is created.
+        rcParams = {"figure.dpi": self.cmp.last_plot.theme.getp("dpi")}
+        self._rc_context = mpl.rc_context(rcParams)
+
+    def __enter__(self) -> Self:
+        """
+        Enclose in matplolib & pandas environments
+        """
+        self._rc_context.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc_value, exc_traceback):
+        import matplotlib.pyplot as plt
+
+        if exc_type is None:
+            if self.show:
+                plt.show()
+            else:
+                plt.close(self.cmp.figure)
+        else:
+            # There is an exception, close any figure
+            if hasattr(self.cmp, "figure"):
+                plt.close(self.cmp.figure)
+
+        self._rc_context.__exit__(exc_type, exc_value, exc_traceback)
+
+
+class OR(Compose):
+    """
+    Compose by adding a column
+    """
+
+    @property
+    def nrow(self) -> int:
+        return 1
+
+    @property
+    def ncol(self) -> int:
+        return len(self)
+
+    def __or__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Add rhs as a column
+        """
+        # This is adjacent or i.e. (OR | rhs) so we collapse the
+        # operands into a single operation
+        return OR([*self, rhs])
+
+    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Add rhs as a row
+        """
+        return DIV([self, rhs])
+
+
+class DIV(Compose):
+    """
+    Compose by adding a row
+    """
+
+    @property
+    def nrow(self) -> int:
+        return len(self)
+
+    @property
+    def ncol(self) -> int:
+        return 1
+
+    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Add rhs as a row
+        """
+        # This is an adjacent div i.e. (DIV | rhs) so we collapse the
+        # operands into a single operation
+        return DIV([*self, rhs])
+
+    def __or__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Add rhs as a column
+        """
+        return OR([self, rhs])
+
+
+class ADD(Compose):
+    """
+    Compose by adding
+    """
+
+    @property
+    def nrow(self) -> int:
+        from plotnine.facets.facet_wrap import wrap_dims
+
+        return wrap_dims(len(self))[0]
+
+    @property
+    def ncol(self) -> int:
+        from plotnine.facets.facet_wrap import wrap_dims
+
+        return wrap_dims(len(self))[1]
+
+    def __or__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Add rhs as a column
+        """
+        return OR([self, rhs])
+
+    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Add rhs as a row
+        """
+        return DIV([self, rhs])
+
+    def __sub__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Add rhs as a column
+        """
+        return OR([self, rhs])

plotnine/plot_composition/_plotspec.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+    from matplotlib.gridspec import SubplotSpec
+
+    from plotnine._mpl.gridspec import p9GridSpec
+    from plotnine.ggplot import ggplot
+
+
+@dataclass
+class plotspec:
+    """
+    Plot Specification
+    """
+
+    plot: ggplot
+    """
+    Plot
+    """
+
+    figure: Figure
+    """
+    Figure in which the draw the plot
+    """
+
+    composition_gridspec: p9GridSpec
+    """
+    The gridspec of the innermost composition group that contains the plot
+    """
+
+    subplotspec: SubplotSpec
+    """
+    The subplotspec that contains the plot
+
+    This is the subplot within the composition gridspec and it will
+    contain the plot's gridspec.
+    """
+
+    plot_gridspec: p9GridSpec
+    """
+    The gridspec in which the plot is drawn
+    """
+
+    def __post_init__(self):
+        self.plot.figure = self.figure
+        self.plot._gridspec = self.plot_gridspec

plotnine/plot_composition/_spacer.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from copy import deepcopy
+
+from plotnine import element_rect, ggplot, theme, theme_void
+
+
+class spacer(ggplot):
+    """
+    An empty plot
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.theme = theme_void()
+
+    def __add__(self, rhs) -> spacer:  # pyright: ignore[reportIncompatibleMethodOverride]
+        """
+        Add to spacer
+
+        All added objects are no ops except the plot_background,
+        i.e.:
+
+            theme(plot_background=element_rect(fill="red"))
+        """
+        self = deepcopy(self)
+        if isinstance(rhs, theme):
+            fill = rhs.getp(("plot_background", "facecolor"))
+            self.theme += theme(
+                plot_background=element_rect(fill=fill),
+            )
+        return self

plotnine/positions/position_dodge.py

@@ -61,7 +61,7 @@ class position_dodge(position):
             and ("xmax" not in data)
             and (self.params["width"] is None)
         ):
-            msg = "Width not defined. " "Set with `position_dodge(width = ?)`"
+            msg = "Width not defined. Set with `position_dodge(width = ?)`"
             raise PlotnineError(msg)
 
         params = copy(self.params)

plotnine/positions/position_dodge2.py

@@ -64,7 +64,7 @@ class position_dodge2(position_dodge):
             and ("xmax" not in data)
             and (self.params["width"] is None)
         ):
-            msg = "Width not defined. " "Set with `position_dodge2(width = ?)`"
+            msg = "Width not defined. Set with `position_dodge2(width = ?)`"
             raise PlotnineError(msg)
 
         params = copy(self.params)

plotnine/positions/position_stack.py

@@ -39,8 +39,7 @@ class position_stack(position):
         if "ymax" in data:
             if any((data["ymin"] != 0) & (data["ymax"] != 0)):
                 warn(
-                    "Stacking not well defined when not "
-                    "anchored on the axis.",
+                    "Stacking not well defined when not anchored on the axis.",
                     PlotnineWarning,
                 )
             var = "ymax"

plotnine/qplot.py

@@ -180,8 +180,7 @@ def qplot(
             return "wrap"
 
         warn(
-            "Could not determine the type of faceting, "
-            "therefore no faceting.",
+            "Could not determine the type of faceting, therefore no faceting.",
             PlotnineWarning,
         )
         return "null"

plotnine/scales/__init__.py

@@ -79,7 +79,6 @@ from .scale_identity import (
 # linetype
 from .scale_linetype import (
     scale_linetype,
-    scale_linetype_continuous,
     scale_linetype_discrete,
 )
 
@@ -97,7 +96,6 @@ from .scale_manual import (
 # shape
 from .scale_shape import (
     scale_shape,
-    scale_shape_continuous,
     scale_shape_discrete,
 )
 
@@ -116,7 +114,6 @@ from .scale_size import (
 from .scale_stroke import (
     scale_stroke,
     scale_stroke_continuous,
-    scale_stroke_discrete,
 )
 
 # xy position and transforms
@@ -198,11 +195,9 @@ __all__ = (
     # linetype
     "scale_linetype",
     "scale_linetype_discrete",
-    "scale_linetype_continuous",
     # shape
     "scale_shape",
     "scale_shape_discrete",
-    "scale_shape_continuous",
     # size
     "scale_size",
     "scale_size_area",
@@ -214,7 +209,6 @@ __all__ = (
     # stroke
     "scale_stroke",
     "scale_stroke_continuous",
-    "scale_stroke_discrete",
     # identity
     "scale_alpha_identity",
     "scale_color_identity",

plotnine/scales/limits.py

@@ -78,10 +78,10 @@ class _lim:
             self.aesthetic, series, limits=self.limits, trans=self.trans
         )
 
-    def __radd__(self, plot):
-        scale = self.get_scale(plot)
-        plot.scales.append(scale)
-        return plot
+    def __radd__(self, other):
+        scale = self.get_scale(other)
+        other.scales.append(scale)
+        return other
 
 
 class xlim(_lim):
@@ -194,7 +194,7 @@ class lims:
     def __init__(self, **kwargs):
         self._kwargs = kwargs
 
-    def __radd__(self, plot):
+    def __radd__(self, other):
         """
         Add limits to ggplot object
         """
@@ -206,9 +206,9 @@ class lims:
                 msg = "Cannot change limits for '{}'"
                 raise PlotnineError(msg) from e
 
-            plot += klass(value)
+            other += klass(value)
 
-        return plot
+        return other
 
 
 def expand_limits(**kwargs):

plotnine/scales/scale.py

@@ -148,12 +148,12 @@ class scale(
             self.aesthetics if self.aesthetics else self._aesthetics
         )
 
-    def __radd__(self, plot):
+    def __radd__(self, other):
         """
         Add this scale to ggplot object
         """
-        plot.scales.append(copy(self))
-        return plot
+        other.scales.append(copy(self))
+        return other
 
     def map(self, x, limits=None):
         """
@@ -243,7 +243,7 @@ class scale(
         if not (exp := self.expand):
             m1, m2 = mult if isinstance(mult, (tuple, list)) else (mult, mult)
             a1, a2 = cast(
-                tuple[float, float],
+                "tuple[float, float]",
                 (add if isinstance(add, (tuple, list)) else (add, add)),
             )
             exp = (m1, a1, m2, a2)

plotnine/scales/scale_continuous.py

@@ -520,11 +520,12 @@ class scale_continuous(
             # When user sets breaks and labels of equal size,
             # but the limits exclude some of the breaks.
             # We remove the corresponding labels
-            from collections.abc import Sized
+            from collections.abc import Iterable, Sized
 
             labels = self.labels
             if (
                 len(labels) != len(breaks)
+                and isinstance(self.breaks, Iterable)
                 and isinstance(self.breaks, Sized)
                 and len(labels) == len(self.breaks)
             ):