plotnine 0.16.0a2__tar.gz → 0.16.0a4__tar.gz

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotnine
-Version: 0.16.0a2
+Version: 0.16.0a4
 Summary: A Grammar of Graphics for Python
 Author-email: Hassan Kibirige <has2k1@gmail.com>
 License: The MIT License (MIT)
@@ -49,7 +49,7 @@ Requires-Dist: pandas>=2.2.0
 Requires-Dist: mizani~=0.14.0
 Requires-Dist: numpy>=1.23.5
 Requires-Dist: scipy>=1.8.0
-Requires-Dist: statsmodels>=0.14.5
+Requires-Dist: statsmodels>=0.14.6
 Provides-Extra: all
 Requires-Dist: plotnine[extra]; extra == "all"
 Requires-Dist: plotnine[doc]; extra == "all"
@@ -68,8 +68,9 @@ Requires-Dist: pyarrow>=19.0.1; extra == "extra"
 Provides-Extra: doc
 Requires-Dist: jupyter; extra == "doc"
 Requires-Dist: click; extra == "doc"
+Requires-Dist: griffe==1.15.0; extra == "doc"
 Requires-Dist: numpydoc>=0.9.1; extra == "doc"
-Requires-Dist: quartodoc>=0.7.2; extra == "doc"
+Requires-Dist: quartodoc>=0.11.1; extra == "doc"
 Provides-Extra: lint
 Requires-Dist: ruff; extra == "lint"
 Provides-Extra: test
@@ -251,12 +252,5 @@ Testing
 -------
 
 Plotnine has tests that generate images which are compared to baseline images known
-to be correct. To generate images that are consistent across all systems you have
-to install matplotlib from source. You can do that with ``pip`` using the command.
-
-```console
-$ pip install matplotlib --no-binary matplotlib
-```
-
-Otherwise there may be small differences in the text rendering that throw off the
-image comparisons.
+to be correct. There may be small differences in the text rendering that throw off the
+image comparisons, and the tests allow some very small differences.

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/README.md

@@ -162,12 +162,5 @@ Testing
 -------
 
 Plotnine has tests that generate images which are compared to baseline images known
-to be correct. To generate images that are consistent across all systems you have
-to install matplotlib from source. You can do that with ``pip`` using the command.
-
-```console
-$ pip install matplotlib --no-binary matplotlib
-```
-
-Otherwise there may be small differences in the text rendering that throw off the
-image comparisons.
+to be correct. There may be small differences in the text rendering that throw off the
+image comparisons, and the tests allow some very small differences.

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/doc/_quartodoc.yml

@@ -477,6 +477,10 @@ quartodoc:
         - plot_background
         - plot_caption
         - plot_caption_position
+        - plot_footer
+        - plot_footer_background
+        - plot_footer_line
+        - plot_footer_position
         - plot_margin
         - plot_margin_bottom
         - plot_margin_left
@@ -582,6 +586,10 @@ quartodoc:
       contents:
           - get_aesthetic_limits
 
+    - package: plotnine.session
+      contents:
+          - last_plot
+
     - title: Datasets
       desc: |
         These datasets ship with the plotnine and you can import them with

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/doc/changelog.qmd

@@ -19,12 +19,48 @@ title: Changelog
 - Added [](:class:`~plotnine.composition.plot_annotation`), allowing you to add title,
   subtitle or caption to a composition.
 
+
+- [](:class:`~plotnine.labs`) can now be used to create a `footer`.
+  This footer can be styled using the `plot_footer` parameter to [](:class:`~plotnine.theme`).
+
+  ```python
+  theme(plot_footer=element_text(size=13))
+  ```
+  And you can also give the footer a background with:
+
+  ```python
+  theme(plot_footer_background=element_text(fill="pink"))
+  ```
+
+ Or separate it from the `caption` or the rest of the plot with a line.
+
+  ```python
+  theme(plot_footer_line=element_line(color="black"))
+  ```
+
 ### Bug Fixes
 
 - Fixed [](:class:`~plotnine.geom_smooth`) / [](:class:`~plotnine.stat_smooth`) when using a linear model via "lm" with weights for the model to do a weighted regression. This bug did not affect the formula API of the linear model. ({{< issue 1005 >}})
 
 - Fixed rendering of SVGs in jupyter notebooks.
 
+- Fixed [](:class:`~plotnine.geom_legend`) to show an empty key for
+  [](:class:`~plotnine.geom_point`) when the shape is mapped to variable with missing
+  values.
+
+### Enhancements
+
+- Increased the default linespacing used by themes from `0.9` to `1.2`.
+  This gives multiline titles, subtitles and captions a better balance between looking compact and looking crumpled.
+
+## v0.15.3
+(2025-01-28)
+
+### Enhancements
+
+- Removed warnings about copy-on-write for pandas >= 3.0.0
+
+
 ## v0.15.2
 (2025-12-12)
 

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/plotnine/_mpl/layout_manager/_composition_layout_items.py

@@ -14,6 +14,9 @@ from plotnine._mpl.utils import (
 if TYPE_CHECKING:
     from typing import Any
 
+    from matplotlib.lines import Line2D
+    from matplotlib.patches import Rectangle
+
     from plotnine.composition._compose import Compose
 
     from ._composition_side_space import CompositionSideSpaces
@@ -44,6 +47,11 @@ class CompositionLayoutItems:
         self.plot_title: Text | None = get("plot_title")
         self.plot_subtitle: Text | None = get("plot_subtitle")
         self.plot_caption: Text | None = get("plot_caption")
+        self.plot_footer: Text | None = get("plot_footer")
+        self.plot_footer_background: Rectangle | None = get(
+            "plot_footer_background"
+        )
+        self.plot_footer_line: Line2D | None = get("plot_footer_line")
 
     def _is_blank(self, name: str) -> bool:
         return self.cmp.theme.T.is_blank(name)
@@ -55,6 +63,7 @@ class CompositionLayoutItems:
         theme = self.cmp.theme
         plot_title_position = theme.getp("plot_title_position", "panel")
         plot_caption_position = theme.getp("plot_caption_position", "panel")
+        plot_footer_position = theme.getp("plot_footer_position", "plot")
         justify = CompositionTextJustifier(spaces)
 
         if self.plot_title:
@@ -78,6 +87,40 @@ class CompositionLayoutItems:
                 self.plot_caption, ha, plot_caption_position
             )
 
+        if self.plot_footer:
+            ha = theme.getp(("plot_footer", "ha"), "left")
+            self.plot_footer.set_y(spaces.b.y1("plot_footer"))
+            justify.horizontally_about(
+                self.plot_footer, ha, plot_footer_position
+            )
+            self._resize_plot_footer_background(spaces)
+            self._resize_plot_footer_line(spaces)
+
+    def _resize_plot_footer_background(self, spaces: CompositionSideSpaces):
+        """
+        Resize the plot footer to the size of the footer
+        """
+        if not self.plot_footer_background:
+            return
+
+        self.plot_footer_background.set_x(spaces.l.offset)
+        self.plot_footer_background.set_y(spaces.b.offset)
+        self.plot_footer_background.set_height(spaces.b.footer_height)
+        self.plot_footer_background.set_width(spaces.plot_width)
+
+    def _resize_plot_footer_line(self, spaces: CompositionSideSpaces):
+        """
+        Resize the footer line to be a border above the footer
+        """
+        if not self.plot_footer_line:
+            return
+
+        x1 = spaces.l.offset
+        x2 = x1 + spaces.plot_width
+        y1 = y2 = spaces.b.offset + spaces.b.footer_height
+        self.plot_footer_line.set_xdata([x1, x2])
+        self.plot_footer_line.set_ydata([y1, y2])
+
 
 class CompositionTextJustifier(TextJustifier):
     """

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/plotnine/_mpl/layout_manager/_composition_side_space.py

@@ -218,6 +218,9 @@ class composition_bottom_space(_composition_side_space):
     Ordered from the edge of the figure and going inwards
     """
 
+    plot_footer_margin_bottom: float = 0
+    plot_footer: float = 0
+    plot_footer_margin_top: float = 0
     plot_margin: float = 0
     plot_caption_margin_bottom: float = 0
     plot_caption: float = 0
@@ -231,6 +234,11 @@ class composition_bottom_space(_composition_side_space):
         F = W / H
 
         self.plot_margin = theme.getp("plot_margin_bottom") * F
+        if items.plot_footer:
+            m = theme.get_margin("plot_footer").fig
+            self.plot_footer_margin_bottom = m.b * F
+            self.plot_footer = geometry.height(items.plot_footer)
+            self.plot_footer_margin_top = m.t * F
 
         if items.plot_caption:
             m = theme.get_margin("plot_caption").fig
@@ -269,6 +277,17 @@ class composition_bottom_space(_composition_side_space):
         """
         return self.to_figure_space(self.sum_incl(item))
 
+    @property
+    def footer_height(self):
+        """
+        The height of the footer including the margins
+        """
+        return (
+            self.plot_footer_margin_bottom
+            + self.plot_footer
+            + self.plot_footer_margin_top
+        )
+
     @property
     def items_bottom_relative(self):
         """
@@ -361,6 +380,20 @@ class CompositionSideSpaces:
             0,
         )
 
+    @property
+    def plot_width(self) -> float:
+        """
+        Width [figure dimensions] of the whole plot composition
+        """
+        return float(self.gridspec.width)
+
+    @property
+    def plot_height(self) -> float:
+        """
+        Height [figure dimensions] of the whole plot composition
+        """
+        return float(self.gridspec.height)
+
     @property
     def horizontal_space(self) -> float:
         """

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/plotnine/_mpl/layout_manager/_plot_layout_items.py

@@ -26,6 +26,8 @@ if TYPE_CHECKING:
 
     from matplotlib.axes import Axes
     from matplotlib.axis import Tick
+    from matplotlib.lines import Line2D
+    from matplotlib.patches import Rectangle
     from matplotlib.transforms import Transform
 
     from plotnine import ggplot
@@ -86,12 +88,18 @@ class PlotLayoutItems:
         # # AnchoredOffsetboxes (groups of legends)
         self.legends: legend_artists | None = get("legends")
         self.plot_caption: Text | None = get("plot_caption")
+        self.plot_footer: Text | None = get("plot_footer")
         self.plot_subtitle: Text | None = get("plot_subtitle")
         self.plot_title: Text | None = get("plot_title")
         self.plot_tag: Text | None = get("plot_tag")
         self.strip_text_x: list[StripText] | None = get("strip_text_x")
         self.strip_text_y: list[StripText] | None = get("strip_text_y")
 
+        self.plot_footer_background: Rectangle | None = get(
+            "plot_footer_background"
+        )
+        self.plot_footer_line: Line2D | None = get("plot_footer_line")
+
     def _is_blank(self, name: str) -> bool:
         return self.plot.theme.T.is_blank(name)
 
@@ -345,6 +353,7 @@ class PlotLayoutItems:
         theme = self.plot.theme
         plot_title_position = theme.getp("plot_title_position", "panel")
         plot_caption_position = theme.getp("plot_caption_position", "panel")
+        plot_footer_position = theme.getp("plot_footer_position", "plot")
         justify = PlotTextJustifier(spaces)
 
         if self.plot_tag:
@@ -371,6 +380,15 @@ class PlotLayoutItems:
                 self.plot_caption, ha, plot_caption_position
             )
 
+        if self.plot_footer:
+            ha = theme.getp(("plot_footer", "ha"), "left")
+            self.plot_footer.set_y(spaces.b.y1("plot_footer"))
+            justify.horizontally_about(
+                self.plot_footer, ha, plot_footer_position
+            )
+            self._resize_plot_footer_background(spaces)
+            self._resize_plot_footer_line(spaces)
+
         if self.axis_title_x:
             ha = theme.getp(("axis_title_x", "ha"), "center")
             self.axis_title_x.set_y(spaces.b.y1("axis_title_x"))
@@ -505,6 +523,31 @@ class PlotLayoutItems:
         for text, scale in zip(self.strip_text_y, relative_widths):
             text.patch.expand = scale
 
+    def _resize_plot_footer_background(self, spaces: PlotSideSpaces):
+        """
+        Resize the plot footer to the size of the footer
+        """
+        if not self.plot_footer_background:
+            return
+
+        self.plot_footer_background.set_x(spaces.l.offset)
+        self.plot_footer_background.set_y(spaces.b.offset)
+        self.plot_footer_background.set_height(spaces.b.footer_height)
+        self.plot_footer_background.set_width(spaces.plot_width)
+
+    def _resize_plot_footer_line(self, spaces: PlotSideSpaces):
+        """
+        Resize the footer line to be a border above the footer
+        """
+        if not self.plot_footer_line:
+            return
+
+        x1 = spaces.l.offset
+        x2 = x1 + spaces.plot_width
+        y1 = y2 = spaces.b.offset + spaces.b.footer_height
+        self.plot_footer_line.set_xdata([x1, x2])
+        self.plot_footer_line.set_ydata([y1, y2])
+
 
 def _text_is_visible(text: Text) -> bool:
     """

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/plotnine/_mpl/layout_manager/_plot_side_space.py

@@ -553,6 +553,9 @@ class bottom_space(_plot_side_space):
     Ordered from the edge of the figure and going inwards
     """
 
+    plot_footer_margin_bottom: float = 0
+    plot_footer: float = 0
+    plot_footer_margin_top: float = 0
     plot_margin: float = 0
     tag_alignment: float = 0
     plot_tag_margin_bottom: float = 0
@@ -602,6 +605,12 @@ class bottom_space(_plot_side_space):
             self.plot_caption = geometry.height(items.plot_caption)
             self.plot_caption_margin_top = m.t * F
 
+        if items.plot_footer:
+            m = theme.get_margin("plot_footer").fig
+            self.plot_footer_margin_bottom = m.b * F
+            self.plot_footer = geometry.height(items.plot_footer)
+            self.plot_footer_margin_top = m.t * F
+
         if items.legends and items.legends.bottom:
             self.legend = self.legend_height
             self.legend_box_spacing = theme.getp("legend_box_spacing") * F
@@ -680,6 +689,17 @@ class bottom_space(_plot_side_space):
         """
         return self.y1("legend")
 
+    @property
+    def footer_height(self):
+        """
+        The height of the footer including the margins
+        """
+        return (
+            self.plot_footer_margin_bottom
+            + self.plot_footer
+            + self.plot_footer_margin_top
+        )
+
     @property
     def tag_height(self):
         """

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/plotnine/_utils/context.py

@@ -4,6 +4,7 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 import pandas as pd
+from packaging.version import Version
 
 if TYPE_CHECKING:
     from typing_extensions import Self
@@ -11,6 +12,8 @@ if TYPE_CHECKING:
     from plotnine import ggplot
     from plotnine.composition import Compose
 
+PANDAS_LT_3 = Version(pd.__version__) < Version("3.0")
+
 
 def reopen(fig):
     """
@@ -55,12 +58,11 @@ class plot_context:
 
         # Contexts
         self.rc_context = mpl.rc_context(plot.theme.rcParams)
-        # TODO: Remove this context when copy-on-write is permanent, i.e.
-        # pandas >= 3.0
-        self.pd_option_context = pd.option_context(
-            "mode.copy_on_write",
-            True,
-        )
+        if PANDAS_LT_3:
+            self.pd_option_context = pd.option_context(
+                "mode.copy_on_write",
+                True,
+            )
 
     def __enter__(self) -> Self:
         """
@@ -68,7 +70,8 @@ class plot_context:
         """
 
         self.rc_context.__enter__()
-        self.pd_option_context.__enter__()
+        if PANDAS_LT_3:
+            self.pd_option_context.__enter__()
 
         return self
 
@@ -89,7 +92,8 @@ class plot_context:
                 plt.close(self.plot.figure)
 
         self.rc_context.__exit__(exc_type, exc_value, exc_traceback)
-        self.pd_option_context.__exit__(exc_type, exc_value, exc_traceback)
+        if PANDAS_LT_3:
+            self.pd_option_context.__exit__(exc_type, exc_value, exc_traceback)
 
 
 @dataclass

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/plotnine/composition/_compose.py

@@ -18,6 +18,7 @@ from ..composition._plot_annotation import plot_annotation
 from ..composition._plot_layout import plot_layout
 from ..composition._types import ComposeAddable
 from ..options import get_option
+from ..session import set_last_plot
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -123,6 +124,8 @@ class Compose:
     |   -------------   |
     |                   |
     |           caption |
+    |-------------------|
+    |       footer      |
      -------------------
     """
     _sidespaces: CompositionSideSpaces
@@ -557,6 +560,7 @@ class Compose:
             self.theme.apply()
             figure.set_layout_engine(PlotnineLayoutEngine(self))
 
+        set_last_plot(self)
         return figure
 
     def _draw_plots(self):
@@ -573,13 +577,28 @@ class Compose:
         """
         Draw the background rectangle of the composition
         """
+        from matplotlib.lines import Line2D
         from matplotlib.patches import Rectangle
 
-        rect = Rectangle((0, 0), 0, 0, facecolor="none", zorder=-1000)
+        zorder = -1000
+        rect = Rectangle((0, 0), 0, 0, facecolor="none", zorder=zorder)
         self.figure.add_artist(rect)
         self._gridspec.patch = rect
         self.theme.targets.plot_background = rect
 
+        if self.annotation.footer:
+            rect = Rectangle(
+                (0, 0), 0, 0, facecolor="none", linewidth=0, zorder=zorder + 1
+            )
+            self.figure.add_artist(rect)
+            self.theme.targets.plot_footer_background = rect
+
+            line = Line2D(
+                [0, 0], [0, 0], color="none", linewidth=0, zorder=zorder + 2
+            )
+            self.figure.add_artist(line)
+            self.theme.targets.plot_footer_line = line
+
     def _draw_annotation(self):
         """
         Draw the items in the annotation
@@ -602,6 +621,9 @@ class Compose:
         if caption := self.annotation.caption:
             targets.plot_caption = figure.text(0, 0, caption)
 
+        if footer := self.annotation.footer:
+            targets.plot_footer = figure.text(0, 0, footer)
+
     def save(
         self,
         filename: str | Path | BytesIO,

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/plotnine/composition/_plot_annotation.py

@@ -36,9 +36,14 @@ class plot_annotation(ComposeAddable):
     The caption of the composition
     """
 
+    footer: str | None = None
+    """
+    The footer of the composition
+    """
+
     theme: theme = field(default_factory=theme)  # pyright: ignore[reportUnboundVariable]
     """
-    Theme to use for the plot title, subtitle, caption, margin and background
+    Theme for the plot title, subtitle, caption, footer, margin and background
 
     It also controls the [](`~plotnine.themes.themeables.figure_size`) of the
     composition. The default theme is the same as the default one used for the

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/plotnine/ggplot.py

@@ -42,11 +42,13 @@ from .layer import Layers
 from .mapping.aes import aes
 from .options import get_option
 from .scales.scales import Scales
+from .session import set_last_plot
 from .themes.theme import theme, theme_get
 
 if TYPE_CHECKING:
     from typing import Protocol
 
+    import pandas as pd
     from matplotlib.axes import Axes
     from matplotlib.figure import Figure
     from typing_extensions import Self
@@ -127,6 +129,8 @@ class ggplot:
     |   axis_text             |
     |   axis_title            |
     |                 caption |
+    |-------------------------|
+    |          footer         |
      -------------------------
     """
 
@@ -372,6 +376,7 @@ class ggplot:
             self.theme.apply()
             figure.set_layout_engine(PlotnineLayoutEngine(self))
 
+        set_last_plot(self)
         return figure
 
     def _setup(self) -> Figure:
@@ -553,6 +558,7 @@ class ggplot:
         subtitle = self.labels.get("subtitle", "")
         caption = self.labels.get("caption", "")
         tag = self.labels.get("tag", "")
+        footer = self.labels.get("footer", "")
 
         # Get the axis labels (default or specified by user)
         # and let the coordinate modify them e.g. flip
@@ -570,6 +576,9 @@ class ggplot:
         if caption:
             targets.plot_caption = figure.text(0, 0, caption)
 
+        if footer:
+            targets.plot_footer = figure.text(0, 0, footer)
+
         if tag:
             targets.plot_tag = figure.text(0, 0, tag)
 
@@ -587,13 +596,30 @@ class ggplot:
             wm.draw(self.figure)
 
     def _draw_plot_background(self):
+        from matplotlib.lines import Line2D
         from matplotlib.patches import Rectangle
 
-        rect = Rectangle((0, 0), 0, 0, facecolor="none", zorder=-1000)
+        zorder = -1000
+        rect = Rectangle((0, 0), 0, 0, facecolor="none", zorder=zorder)
         self.figure.add_artist(rect)
         self._gridspec.patch = rect
         self.theme.targets.plot_background = rect
 
+        # Footer background and line only if there is a footer, and put
+        # it on top of the plot background
+        if self.labels.get("footer", ""):
+            rect = Rectangle(
+                (0, 0), 0, 0, facecolor="none", linewidth=0, zorder=zorder + 1
+            )
+            self.figure.add_artist(rect)
+            self.theme.targets.plot_footer_background = rect
+
+            line = Line2D(
+                [0, 0], [0, 0], color="none", linewidth=0, zorder=zorder + 2
+            )
+            self.figure.add_artist(line)
+            self.theme.targets.plot_footer_line = line
+
     def _save_filename(self, ext: str) -> Path:
         """
         Make a filename for use by the save method
@@ -748,6 +774,25 @@ class ggplot:
         with plot_context(self).rc_context:
             sv.figure.savefig(**sv.kwargs)
 
+    def layer_data(self, i: int = 0) -> pd.DataFrame:
+        """
+        Return the data used to draw a specific plot layer
+
+        Parameters
+        ----------
+        i :
+            Index of the layer to retrieve, starting from 0.
+
+        Returns
+        -------
+        pd.DataFrame
+            Data used by the specified layer after all transformations,
+            statistics, and position adjustments have been applied.
+        """
+        p = deepcopy(self)
+        p._build()
+        return p.layers.data[i]
+
 
 ggsave = ggplot.save
 

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/plotnine/guides/guide_legend.py

@@ -272,9 +272,12 @@ class guide_legend(guide):
         # Drawings
         drawings: list[ColoredDrawingArea] = []
         for i in range(nbreak):
-            da = ColoredDrawingArea(
-                elements.key_widths[i], elements.key_heights[i], 0, 0
-            )
+            try:
+                w, h = elements.key_widths[i], elements.key_heights[i]
+            except IndexError:
+                w, h = elements.empty_key_size
+
+            da = ColoredDrawingArea(w, h, 0, 0)
 
             # overlay geoms
             for params in self._layer_parameters:
@@ -482,3 +485,14 @@ class GuideElementsLegend(GuideElements):
         if self.is_horizontal:
             return [max(hs)] * len(hs)
         return hs
+
+    @cached_property
+    def empty_key_size(self) -> tuple[float, float]:
+        """
+        Size of an empty key
+        """
+        return (
+            (max(self.key_widths), min(self.key_heights))
+            if self.is_vertical
+            else (min(self.key_widths), max(self.key_heights))
+        )

{plotnine-0.16.0a2 → plotnine-0.16.0a4}/plotnine/iapi.py

@@ -66,7 +66,7 @@ class range_view:
 @dataclass
 class labels_view:
     """
-    Scale labels (incl. caption & title) for the plot
+    Scale labels (incl. caption, title, footer) for the plot
     """
 
     x: Optional[str] = None
@@ -80,8 +80,9 @@ class labels_view:
     size: Optional[str] = None
     stroke: Optional[str] = None
     title: Optional[str] = None
-    caption: Optional[str] = None
     subtitle: Optional[str] = None
+    caption: Optional[str] = None
+    footer: Optional[str] = None
     tag: Optional[str] = None
 
     def update(self, other: labels_view):