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

plotnine/__init__.py

@@ -1,3 +1,9 @@
+# Do not edit this file by hand.
+#
+# Generate it using:
+#
+# $ python -c 'from plotnine._utils import dev; print(dev.get_init_py())'
+
 from importlib.metadata import PackageNotFoundError, version
 
 try:
@@ -9,12 +15,6 @@ finally:
     del version
     del PackageNotFoundError
 
-# Imports below are generated with the following command:
-#
-# python -c "from plotnine._utils.dev import get_plotnine_all; get_plotnine_all()"  # noqa: E501
-#
-# added to the clipboard. Run it and paste the results. Do not edit by hand.
-
 from .coords import (
     coord_cartesian,
     coord_equal,
@@ -180,12 +180,10 @@ from .scales import (
     scale_fill_manual,
     scale_fill_ordinal,
     scale_linetype,
-    scale_linetype_continuous,
     scale_linetype_discrete,
     scale_linetype_identity,
     scale_linetype_manual,
     scale_shape,
-    scale_shape_continuous,
     scale_shape_discrete,
     scale_shape_identity,
     scale_shape_manual,
@@ -200,7 +198,6 @@ from .scales import (
     scale_size_radius,
     scale_stroke,
     scale_stroke_continuous,
-    scale_stroke_discrete,
     scale_x_continuous,
     scale_x_date,
     scale_x_datetime,
@@ -279,23 +276,27 @@ from .watermark import (
 )
 
 __all__ = (
+    "aes",
+    "after_scale",
+    "after_stat",
+    "annotate",
+    "annotation_logticks",
+    "annotation_stripes",
+    "arrow",
+    "as_labeller",
     "coord_cartesian",
     "coord_equal",
     "coord_fixed",
     "coord_flip",
     "coord_trans",
-    "as_labeller",
+    "element_blank",
+    "element_line",
+    "element_rect",
+    "element_text",
+    "expand_limits",
     "facet_grid",
     "facet_null",
     "facet_wrap",
-    "label_both",
-    "label_context",
-    "label_value",
-    "labeller",
-    "annotate",
-    "annotation_logticks",
-    "annotation_stripes",
-    "arrow",
     "geom_abline",
     "geom_area",
     "geom_bar",
@@ -342,19 +343,17 @@ __all__ = (
     "geom_vline",
     "ggplot",
     "ggsave",
-    "save_as_pdf_pages",
+    "ggtitle",
     "guide_colorbar",
     "guide_colourbar",
     "guide_legend",
     "guides",
-    "ggtitle",
+    "label_both",
+    "label_context",
+    "label_value",
+    "labeller",
     "labs",
-    "xlab",
-    "ylab",
-    "aes",
-    "after_scale",
-    "after_stat",
-    "stage",
+    "lims",
     "position_dodge",
     "position_dodge2",
     "position_fill",
@@ -364,8 +363,7 @@ __all__ = (
     "position_nudge",
     "position_stack",
     "qplot",
-    "expand_limits",
-    "lims",
+    "save_as_pdf_pages",
     "scale_alpha",
     "scale_alpha_continuous",
     "scale_alpha_datetime",
@@ -425,12 +423,10 @@ __all__ = (
     "scale_fill_manual",
     "scale_fill_ordinal",
     "scale_linetype",
-    "scale_linetype_continuous",
     "scale_linetype_discrete",
     "scale_linetype_identity",
     "scale_linetype_manual",
     "scale_shape",
-    "scale_shape_continuous",
     "scale_shape_discrete",
     "scale_shape_identity",
     "scale_shape_manual",
@@ -445,7 +441,6 @@ __all__ = (
     "scale_size_radius",
     "scale_stroke",
     "scale_stroke_continuous",
-    "scale_stroke_discrete",
     "scale_x_continuous",
     "scale_x_date",
     "scale_x_datetime",
@@ -464,8 +459,7 @@ __all__ = (
     "scale_y_sqrt",
     "scale_y_symlog",
     "scale_y_timedelta",
-    "xlim",
-    "ylim",
+    "stage",
     "stat_bin",
     "stat_bin2d",
     "stat_bin_2d",
@@ -508,9 +502,9 @@ __all__ = (
     "theme_update",
     "theme_void",
     "theme_xkcd",
-    "element_blank",
-    "element_line",
-    "element_rect",
-    "element_text",
     "watermark",
+    "xlab",
+    "xlim",
+    "ylab",
+    "ylim",
 )

plotnine/_mpl/gridspec.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from functools import cached_property
+from typing import TYPE_CHECKING, cast
+
+try:
+    from matplotlib.gridspec import GridSpecBase, SubplotParams
+except ImportError:
+    # MPL 3.8
+    from matplotlib.figure import SubplotParams
+    from matplotlib.gridspec import GridSpecBase
+
+from matplotlib.transforms import Bbox, BboxTransformTo, TransformedBbox
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+    from matplotlib.gridspec import SubplotSpec
+    from matplotlib.patches import Rectangle
+    from matplotlib.transforms import Transform
+
+    from plotnine._mpl.layout_manager._spaces import GridSpecParams
+
+
+class p9GridSpec(GridSpecBase):
+    """
+    Gridspec for plotnine plots
+
+    This gridspec does not read any subplot parameter values from matplotlib's
+    rcparams and the default a grid that fills up all the available space;
+    there is no space along the edges and between the subplots.
+
+    This gridspec can also be initialised while contained/nested in a given
+    subplot.
+
+    Parameters
+    ----------
+    nest_into :
+        If given, this gridspec will be contained in the subplot.
+    """
+
+    _subplot_params: SubplotParams
+    """
+    The subplot spacing parameters of this gridspec
+
+    These values are relative to where (figure or subplot) that the
+    gridspec is contained. Use .get_subplot_params to get the absolute
+    values (those in figure coordinates).
+    """
+    _nested_gridspecs: list[p9GridSpec]
+    """
+    All gridspecs that are nested into any of the subplots of this one
+    """
+    _patch: Rectangle
+
+    def __init__(
+        self,
+        nrows,
+        ncols,
+        figure: Figure,
+        *,
+        width_ratios=None,
+        height_ratios=None,
+        nest_into: SubplotSpec | None = None,
+    ):
+        self.figure = figure
+        self._nested_gridspecs = []
+
+        super().__init__(
+            nrows,
+            ncols,
+            width_ratios=width_ratios,
+            height_ratios=height_ratios,
+        )
+
+        if nest_into:
+            self._parent_subplot_spec = nest_into
+            # MPL GridSpecBase expects only the subclasses that will be nested
+            # to have the .get_topmost_subplotspec method.
+            self.get_topmost_subplotspec = self._get_topmost_subplotspec
+
+            # Register this gridspec as nested
+            gs = cast("p9GridSpec", nest_into.get_gridspec())
+            gs._nested_gridspecs.append(self)
+
+        self.update(
+            left=0,
+            bottom=0,
+            top=1,
+            right=1,
+            wspace=0,
+            hspace=0,
+        )
+
+    @property
+    def patch(self) -> Rectangle:
+        """
+        Background patch for the whole gridspec
+        """
+        return self._patch
+
+    @patch.setter
+    def patch(self, value: Rectangle):
+        """
+        Set value and update position
+        """
+        self._patch = value
+        self._update_patch_position()
+
+    @property
+    def nested(self):
+        """
+        Return True if this gridspec is nested
+        """
+        return hasattr(self, "_parent_subplot_spec")
+
+    def update(
+        self,
+        left=None,
+        bottom=None,
+        right=None,
+        top=None,
+        wspace=None,
+        hspace=None,
+    ):
+        """
+        Update the gridpec's suplot parameters and all that depend on them
+        """
+        if not hasattr(self, "_subplot_params"):
+            self._subplot_params = SubplotParams()
+
+        self._subplot_params.update(
+            left=left,
+            bottom=bottom,
+            top=top,
+            right=right,
+            wspace=wspace,
+            hspace=hspace,
+        )
+
+    def _update_patch_position(self):
+        """
+        Update the position and size of the patch
+
+        The patch position should be updated whenever the subplot
+        parameters change.
+        """
+        if not hasattr(self, "_patch"):
+            return
+
+        ss_bbox = self[0].get_position(None)  # pyright: ignore[reportArgumentType]
+        self.patch.set_xy((ss_bbox.x0, ss_bbox.y0))
+        self.patch.set_width(ss_bbox.width)
+        self.patch.set_height(ss_bbox.height)
+
+    def _update_axes_position(self):
+        """
+        Update the position of the axes in this gridspec
+        """
+        for ax in self.figure.axes:
+            if ss := ax.get_subplotspec():
+                ax._set_position(ss.get_position(self))  # pyright: ignore[reportAttributeAccessIssue, reportArgumentType]
+
+    def _update_artists(self):
+        """
+        Update the artist positions that depend on this gridspec
+        """
+        self._update_patch_position()
+        self._update_axes_position()
+        for gs in self._nested_gridspecs:
+            gs._update_artists()
+
+    def layout(self, gsparams: GridSpecParams):
+        """
+        Update the layout of the gridspec
+        """
+        self.update(**asdict(gsparams))
+        self._update_artists()
+
+    def get_subplot_params(self, figure=None) -> SubplotParams:
+        """
+        Return the subplot parameters (in figure coordinates) for the gridspec
+        """
+        params = self._subplot_params
+
+        if not self.nested:
+            return params
+
+        # When the gridspec is nested the subplot params of this gridspec
+        # are relative to the position of parent subplot. We want values that
+        # are relative to the figure, so we add these param values as offsets
+        # to the position of the parent subplot.
+        parent_bbox = self._parent_subplot_spec.get_position(figure)  # pyright: ignore
+        _left, _bottom, _right, _top = parent_bbox.extents
+
+        left = _left + params.left
+        bottom = _bottom + params.bottom
+        right = _right - (1 - params.right)
+        top = _top - (1 - params.top)
+
+        return SubplotParams(
+            left=left,
+            bottom=bottom,
+            right=right,
+            top=top,
+            wspace=params.wspace,
+            hspace=params.hspace,
+        )
+
+    def _get_topmost_subplotspec(self) -> SubplotSpec:
+        """
+        Return the topmost `.SubplotSpec` instance associated with the subplot.
+
+        This method starts with an underscore so that mpl's GridSpecBase does
+        not think that any/all instances of this class are nested. It is then
+        only dynamically assigned (without the underscore) to an instance of
+        this class when it is nested into a subplot.
+        """
+        return self._parent_subplot_spec.get_topmost_subplotspec()
+
+    @cached_property
+    def parent_gridspec(self) -> p9GridSpec | None:
+        if self.nested and (ss := self._parent_subplot_spec):
+            return ss.get_gridspec()  # pyright: ignore[reportReturnType]
+
+    @property
+    def bbox_relative(self):
+        """
+        Bounding box for the gridspec relative to the figure
+
+        This bbox is in figure coordinates.
+        """
+        params = self.get_subplot_params()
+        return Bbox.from_extents(
+            params.left, params.bottom, params.right, params.top
+        )
+
+    @property
+    def bbox(self):
+        """
+        Bounding box of the gridspec
+
+        This bbox is in display coordinates.
+        """
+        return TransformedBbox(self.bbox_relative, self.figure.transSubfigure)
+
+    def to_transform(self) -> Transform:
+        """
+        Return transform of this gridspec
+
+        Where:
+            - (0, 0) is the bottom left of the gridspec
+            - (1, 1) is the top right of the gridspec
+
+        The output of this transform is in the display units of the figure.
+        """
+        return BboxTransformTo(self.bbox)
+
+    def set_height_ratios(self, height_ratios):
+        super().set_height_ratios(height_ratios)
+        self._update_artists()
+
+    def set_width_ratios(self, width_ratios):
+        super().set_width_ratios(width_ratios)
+        self._update_artists()

plotnine/_mpl/layout_manager/__init__.py

@@ -0,0 +1,6 @@
+from ._engine import PlotnineCompositionLayoutEngine, PlotnineLayoutEngine
+
+__all__ = (
+    "PlotnineLayoutEngine",
+    "PlotnineCompositionLayoutEngine",
+)

plotnine/_mpl/layout_manager/_engine.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from warnings import warn
+
+from matplotlib.layout_engine import LayoutEngine
+
+from ...exceptions import PlotnineWarning
+from ._layout_tree import LayoutTree
+from ._spaces import LayoutSpaces
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+    from plotnine import ggplot
+    from plotnine.plot_composition import Compose
+
+
+class PlotnineLayoutEngine(LayoutEngine):
+    """
+    Implement geometry management for plotnine plots
+
+    This layout manager automatically adjusts the location of
+    objects placed around the plot panels and the subplot
+    spacing parameters so that the plot fits cleanly within
+    the figure area.
+    """
+
+    _adjust_compatible = True
+    _colorbar_gridspec = False
+
+    def __init__(self, plot: ggplot):
+        self.plot = plot
+        self.theme = plot.theme
+
+    def execute(self, fig: Figure):
+        from contextlib import nullcontext
+
+        renderer = fig._get_renderer()  # pyright: ignore[reportAttributeAccessIssue]
+
+        with getattr(renderer, "_draw_disabled", nullcontext)():
+            spaces = LayoutSpaces(self.plot)
+
+        gsparams = spaces.get_gridspec_params()
+        self.plot.facet._panels_gridspec.layout(gsparams)
+        spaces.items._adjust_positions(spaces)
+
+
+class PlotnineCompositionLayoutEngine(LayoutEngine):
+    """
+    Layout Manager for Plotnine Composition
+    """
+
+    _adjust_compatible = True
+    _colorbar_gridspec = False
+
+    def __init__(self, composition: Compose):
+        self.composition = composition
+
+    def execute(self, fig: Figure):
+        from contextlib import nullcontext
+
+        renderer = fig._get_renderer()  # pyright: ignore[reportAttributeAccessIssue]
+
+        # Caculate the space taken up by all plot artists
+        lookup_spaces: dict[ggplot, LayoutSpaces] = {}
+        with getattr(renderer, "_draw_disabled", nullcontext)():
+            for ps in self.composition.plotspecs:
+                lookup_spaces[ps.plot] = LayoutSpaces(ps.plot)
+
+        # Adjust the size and placements of the plots
+        tree = LayoutTree.create(self.composition, lookup_spaces)
+        tree.harmonise()
+
+        # Set the final positions of the artists in each plot
+        for plot, spaces in lookup_spaces.items():
+            gsparams = spaces.get_gridspec_params()
+            if not gsparams.valid:
+                warn(
+                    "The layout manager failed, the figure size is too small "
+                    "to contain all the plots. Use theme() increase the "
+                    "figure size and/or reduce the size of the texts.",
+                    PlotnineWarning,
+                )
+                break
+            plot.facet._panels_gridspec.layout(gsparams)
+            spaces.items._adjust_positions(spaces)