Add footer line

has2k1 · has2k1 · commit 0368b663e0b8 · 2026-02-03T13:14:52.000+03:00
diff --git a/doc/_quartodoc.yml b/doc/_quartodoc.yml
@@ -479,6 +479,7 @@ quartodoc:
         - plot_caption_position
         - plot_footer
         - plot_footer_background
+        - plot_footer_line
         - plot_footer_position
         - plot_margin
         - plot_margin_bottom
diff --git a/doc/changelog.qmd b/doc/changelog.qmd
@@ -32,10 +32,11 @@ title: Changelog
   theme(plot_footer_background=element_text(fill="pink"))
   ```
 
-- Added footer labels which are placed below the caption.
+ Or separate it from the `caption` or the rest of the plot with a line.
 
-  which you can set with  [](:class:`~plotnine.themeable.`), allowing you to add title,
-  subtitle or caption to a composition.
+  ```python
+  theme(plot_footer_line=element_line(color="black"))
+  ```
 
 ### Bug Fixes
 
diff --git a/plotnine/_mpl/layout_manager/_composition_layout_items.py b/plotnine/_mpl/layout_manager/_composition_layout_items.py
@@ -14,6 +14,7 @@
 if TYPE_CHECKING:
     from typing import Any
 
+    from matplotlib.lines import Line2D
     from matplotlib.patches import Rectangle
 
     from plotnine.composition._compose import Compose
@@ -50,6 +51,7 @@ def get(name: str) -> Any:
         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)
@@ -92,6 +94,7 @@ def _move_artists(self, spaces: CompositionSideSpaces):
                 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):
         """
@@ -105,6 +108,19 @@ def _resize_plot_footer_background(self, spaces: CompositionSideSpaces):
         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):
     """
diff --git a/plotnine/_mpl/layout_manager/_plot_layout_items.py b/plotnine/_mpl/layout_manager/_plot_layout_items.py
@@ -26,6 +26,7 @@
 
     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
 
@@ -97,6 +98,7 @@ def get(name: str) -> Any:
         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)
@@ -385,6 +387,7 @@ def _move_artists(self, spaces: PlotSideSpaces):
                 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")
@@ -532,6 +535,19 @@ def _resize_plot_footer_background(self, spaces: PlotSideSpaces):
         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:
     """
diff --git a/plotnine/composition/_compose.py b/plotnine/composition/_compose.py
@@ -123,6 +123,7 @@ class Compose:
     |   -------------   |
     |                   |
     |           caption |
+    |-------------------|
     |       footer      |
      -------------------
     """
@@ -574,6 +575,7 @@ def _draw_composition_background(self):
         """
         Draw the background rectangle of the composition
         """
+        from matplotlib.lines import Line2D
         from matplotlib.patches import Rectangle
 
         zorder = -1000
@@ -589,6 +591,12 @@ def _draw_composition_background(self):
             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
diff --git a/plotnine/ggplot.py b/plotnine/ggplot.py
@@ -127,6 +127,7 @@ class ggplot:
     |   axis_text             |
     |   axis_title            |
     |                 caption |
+    |-------------------------|
     |          footer         |
      -------------------------
     """
@@ -592,6 +593,7 @@ def _draw_watermarks(self):
             wm.draw(self.figure)
 
     def _draw_plot_background(self):
+        from matplotlib.lines import Line2D
         from matplotlib.patches import Rectangle
 
         zorder = -1000
@@ -600,15 +602,21 @@ def _draw_plot_background(self):
         self._gridspec.patch = rect
         self.theme.targets.plot_background = rect
 
-        # Footer background only if there is a footer, and put it on top of
-        # the plot background
+        # 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
diff --git a/plotnine/themes/targets.py b/plotnine/themes/targets.py
@@ -7,6 +7,7 @@
     from typing import Optional
 
     from matplotlib.collections import LineCollection
+    from matplotlib.lines import Line2D
     from matplotlib.patches import Rectangle
     from matplotlib.text import Text
 
@@ -42,6 +43,7 @@ class ThemeTargets:
     plot_title: Optional[Text] = None
     plot_background: Optional[Rectangle] = None
     plot_footer_background: Optional[Rectangle] = None
+    plot_footer_line: Optional[Line2D] = None
     strip_background_x: list[StripTextPatch] = field(default_factory=list)
     strip_background_y: list[StripTextPatch] = field(default_factory=list)
     strip_text_x: list[StripText] = field(default_factory=list)
diff --git a/plotnine/themes/theme.py b/plotnine/themes/theme.py
@@ -159,6 +159,7 @@ def __init__(
         panel_grid_major=None,
         panel_grid_minor=None,
         panel_grid=None,
+        plot_footer_line=None,
         line=None,
         legend_key=None,
         legend_frame=None,
diff --git a/plotnine/themes/theme_gray.py b/plotnine/themes/theme_gray.py
@@ -117,6 +117,7 @@ def __init__(self, base_size=11, base_family=None):
                 margin=margin(t=1 / 3, b=1 / 3, unit="lines"),
             ),
             plot_footer_background=element_blank(),
+            plot_footer_line=element_blank(),
             plot_margin=m,
             plot_subtitle=element_text(
                 va="top",
diff --git a/plotnine/themes/theme_matplotlib.py b/plotnine/themes/theme_matplotlib.py
@@ -99,6 +99,7 @@ def __init__(self, rc=None, fname=None, use_defaults=True):
                 margin=margin(b=m, unit="fig"),
             ),
             plot_footer_background=element_blank(),
+            plot_footer_line=element_blank(),
             plot_title=element_text(
                 va="top",
                 ma="left",
diff --git a/plotnine/themes/theme_seaborn.py b/plotnine/themes/theme_seaborn.py
@@ -108,6 +108,7 @@ def __init__(
                 margin=margin(t=1 / 3, b=1 / 3, unit="lines"),
             ),
             plot_footer_background=element_blank(),
+            plot_footer_line=element_blank(),
             plot_margin=m,
             plot_subtitle=element_text(
                 size=base_size * 1,
diff --git a/plotnine/themes/themeable.py b/plotnine/themes/themeable.py
@@ -1517,7 +1517,27 @@ class panel_grid(panel_grid_major, panel_grid_minor):
     """
 
 
-class line(axis_line, axis_ticks, panel_grid, legend_ticks):
+class plot_footer_line(themeable):
+    """
+    Line above the footer
+
+    Parameters
+    ----------
+    theme_element : element_line
+    """
+
+    def apply_figure(self, figure: Figure, targets: ThemeTargets):
+        super().apply_figure(figure, targets)
+        if targets.plot_footer_line:
+            targets.plot_footer_line.set(**self.properties)
+
+    def blank_figure(self, figure: Figure, targets: ThemeTargets):
+        super().blank_figure(figure, targets)
+        if targets.plot_footer_line:
+            targets.plot_footer_line.set_visible(False)
+
+
+class line(axis_line, axis_ticks, panel_grid, legend_ticks, plot_footer_line):
     """
     All line elements
 
diff --git a/tests/baseline_images/test_plot_composition/footer.png b/tests/baseline_images/test_plot_composition/footer.png
diff --git a/tests/baseline_images/test_plot_composition/footers.png b/tests/baseline_images/test_plot_composition/footers.png
diff --git a/tests/test_plot_composition.py b/tests/test_plot_composition.py
@@ -1,6 +1,8 @@
 import pytest
 
 from plotnine import (
+    element_line,
+    element_rect,
     element_text,
     facet_grid,
     facet_wrap,
@@ -397,3 +399,39 @@ def test_plot_annotation_addition():
 
     assert p == "plot_annotation_addition"
     assert p_alt == "plot_annotation_addition"
+
+
+def test_footers():
+    def _make_footer(color):
+        return [
+            labs(
+                footer=f"{color.title()} Footer",
+                caption=f"The {color} caption",
+            ),
+            theme(
+                plot_footer=element_text(color=color),
+                plot_footer_line=element_line(color=color),
+                plot_caption=element_text(color=color, style="italic", size=8),
+                plot_footer_position="panel",
+            ),
+        ]
+
+    p1 = plot.red + _make_footer("red")
+    p2 = plot.green + _make_footer("green")
+    p3 = plot.blue + _make_footer("blue")
+    ann = plot_annotation(
+        title="The Title of the Red, Green and Blue Composition",
+        subtitle="The subtitle of the red, green and blue composition",
+        caption="The caption of the red, green and blue composition",
+        footer="THE COMPOSITION FOOTER",
+        theme=theme(
+            plot_margin_left=0,
+            plot_margin_right=0,
+            plot_title_position="plot",
+            plot_footer=element_text(weight="bold"),
+            plot_footer_line=element_line(size=0.75),
+            plot_footer_background=element_rect(fill="lightgray"),
+        ),
+    )
+    p = ((p1 | p2) / p3) + ann
+    assert p == "footers"
