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

plotnine/themes/theme_seaborn.py

@@ -1,5 +1,11 @@
 from ..options import get_option
-from .elements import element_blank, element_line, element_rect, element_text
+from .elements import (
+    element_blank,
+    element_line,
+    element_rect,
+    element_text,
+    margin,
+)
 from .theme import theme
 
 
@@ -49,22 +55,22 @@ class theme_seaborn(theme):
             text=element_text(size=base_size, rotation=0, margin={}),
             axis_text=element_text(
                 size=base_size * 0.8,
-                margin={
-                    "t": line_margin,
-                    "b": line_margin,
-                    "l": line_margin,
-                    "r": line_margin,
-                    "units": "pt",
-                },
+                margin=margin(
+                    t=line_margin,
+                    b=line_margin,
+                    l=line_margin,
+                    r=line_margin,
+                    unit="pt",
+                ),
             ),
             axis_title_x=element_text(
-                va="bottom", ha="center", margin={"t": m, "units": "fig"}
+                va="bottom", ha="center", margin=margin(t=m, unit="fig")
             ),
             axis_title_y=element_text(
                 angle=90,
                 va="center",
                 ha="left",
-                margin={"r": m, "units": "fig"},
+                margin=margin(r=m, unit="fig"),
             ),
             legend_box_margin=0,
             legend_box_spacing=m * 3,  # figure units
@@ -77,23 +83,11 @@ class theme_seaborn(theme):
             legend_position="right",
             legend_spacing=10,  # points
             legend_text=element_text(
-                margin={
-                    "t": m / 1.5,
-                    "b": m / 1.5,
-                    "l": m / 1.5,
-                    "r": m / 1.5,
-                    "units": "fig",
-                },
+                margin=margin(m / 1.5, m / 1.5, m / 1.5, m / 1.5, "fig")
             ),
             legend_ticks=element_line(color="#CCCCCC", size=1),
             legend_title=element_text(
-                margin={
-                    "t": m,
-                    "b": m / 2,
-                    "l": m * 2,
-                    "r": m * 2,
-                    "units": "fig",
-                },
+                margin=margin(t=m, l=m * 2, b=m / 2, r=m * 2, unit="fig")
             ),
             panel_spacing=m,
             plot_caption=element_text(
@@ -101,33 +95,36 @@ class theme_seaborn(theme):
                 ha="right",
                 va="bottom",
                 ma="left",
-                margin={"t": m, "units": "fig"},
+                margin=margin(t=m, unit="fig"),
             ),
             plot_margin=m,
             plot_subtitle=element_text(
                 size=base_size * 1,
                 va="top",
                 ma="left",
-                margin={"b": m, "units": "fig"},
+                margin=margin(b=m, unit="fig"),
             ),
             plot_title=element_text(
                 size=base_size * 1.2,
                 va="top",
                 ma="left",
-                margin={"b": m, "units": "fig"},
+                margin=margin(b=m, unit="fig"),
             ),
+            plot_tag=element_text(
+                size=base_size * 1.2,
+                va="center",
+                ha="center",
+            ),
+            plot_title_position="panel",
+            plot_caption_position="panel",
+            plot_tag_location="margin",
+            plot_tag_position="topleft",
             strip_align=0,
             strip_background=element_rect(color="none", fill="#D1CDDF"),
             strip_text=element_text(
                 size=base_size * 0.8,
                 linespacing=1.0,
-                margin={
-                    "t": 1 / 3,
-                    "b": 1 / 3,
-                    "l": 1 / 3,
-                    "r": 1 / 3,
-                    "units": "lines",
-                },
+                margin=margin(1 / 3, 1 / 3, 1 / 3, 1 / 3, "lines"),
             ),
             strip_text_y=element_text(rotation=-90),
             complete=True,

plotnine/themes/theme_void.py

@@ -1,5 +1,5 @@
 from ..options import get_option
-from .elements import element_blank, element_line, element_text
+from .elements import element_blank, element_line, element_text, margin
 from .theme import theme
 
 
@@ -32,7 +32,7 @@ class theme_void(theme):
                 size=base_size,
                 linespacing=0.9,
                 rotation=0,
-                margin={},
+                margin=margin(),
             ),
             axis_text_x=element_blank(),
             axis_text_y=element_blank(),
@@ -54,23 +54,11 @@ class theme_void(theme):
             legend_spacing=10,
             legend_text=element_text(
                 size=base_size * 0.8,
-                margin={
-                    "t": m / 1.5,
-                    "b": m / 1.5,
-                    "l": m / 1.5,
-                    "r": m / 1.5,
-                    "units": "fig",
-                },
+                margin=margin(m / 1.5, m / 1.5, m / 1.5, m / 1.5, "fig"),
             ),
             legend_ticks=element_line(color="#CCCCCC", size=1),
             legend_title=element_text(
-                margin={
-                    "t": m,
-                    "b": m / 2,
-                    "l": m * 2,
-                    "r": m * 2,
-                    "units": "fig",
-                },
+                margin=margin(t=m, l=m * 2, b=m / 2, r=m * 2, unit="fig")
             ),
             panel_spacing=m,
             plot_caption=element_text(
@@ -78,33 +66,36 @@ class theme_void(theme):
                 ha="right",
                 va="bottom",
                 ma="left",
-                margin={"t": m, "units": "fig"},
+                margin=margin(t=m, unit="fig"),
             ),
             plot_margin=0,
             plot_subtitle=element_text(
                 size=base_size * 1,
                 va="top",
                 ma="left",
-                margin={"b": m, "units": "fig"},
+                margin=margin(b=m, unit="fig"),
             ),
             plot_title=element_text(
                 size=base_size * 1.2,
                 va="top",
                 ma="left",
-                margin={"b": m, "units": "fig"},
+                margin=margin(b=m, unit="fig"),
             ),
+            plot_tag=element_text(
+                size=base_size * 1.2,
+                va="center",
+                ha="center",
+            ),
+            plot_title_position="panel",
+            plot_caption_position="panel",
+            plot_tag_location="margin",
+            plot_tag_position="topleft",
             strip_align=0,
             strip_text=element_text(
                 color="#1A1A1A",
                 size=base_size * 0.8,
                 linespacing=1.0,
-                margin={
-                    "t": 1 / 3,
-                    "b": 1 / 3,
-                    "l": 1 / 3,
-                    "r": 1 / 3,
-                    "units": "lines",
-                },
+                margin=margin(1 / 3, 1 / 3, 1 / 3, 1 / 3, "lines"),
             ),
             complete=True,
         )

plotnine/themes/themeable.py

@@ -719,6 +719,89 @@ class plot_caption(themeable):
             text.set_visible(False)
 
 
+class plot_tag(themeable):
+    """
+    Plot tag
+
+    Parameters
+    ----------
+    theme_element : element_text
+
+    Notes
+    -----
+    The `ha` & `va` of element_text will only have an effect if the
+    have no effect if the
+    [](:class:`~plotnine.themes.themeable.plot_tag_position`)
+    is given as x-y coordinates.
+    """
+
+    _omit = ["margin"]
+
+    def apply_figure(self, figure: Figure, targets: ThemeTargets):
+        super().apply_figure(figure, targets)
+        if text := targets.plot_tag:
+            text.set(**self.properties)
+
+    def blank_figure(self, figure: Figure, targets: ThemeTargets):
+        super().blank_figure(figure, targets)
+        if text := targets.plot_tag:
+            text.set_visible(False)
+
+
+class plot_title_position(themeable):
+    """
+    How to align the plot title and plot subtitle
+
+    Parameters
+    ----------
+    theme_element : Literal["panel", "plot"], default = "panel"
+        If "panel", the title / subtitle are aligned with respect
+        to the panels. If "plot", they are aligned with the plot,
+        excluding the margin space
+    """
+
+
+class plot_caption_position(themeable):
+    """
+    How to align the plot caption
+
+    Parameters
+    ----------
+    theme_element : Literal["panel", "plot"], default = "panel"
+        If "panel", the caption is aligned with respect to the
+        panels. If "plot", it is aligned with the plot, excluding
+        the margin space.
+    """
+
+
+class plot_tag_location(themeable):
+    """
+    The area where the tag will be positioned
+
+    Parameters
+    ----------
+    theme_element : Literal["margin", "plot", "panel"], default = "margin"
+        If "margin", it is placed within the plot_margin.
+        If "plot", it is placed in the figure, ignoring any margins.
+        If "panel", it is placed within the panel area.
+    """
+
+
+class plot_tag_position(themeable):
+    """
+    Position of the tag
+
+    Parameters
+    ----------
+    theme_element : Literal["topleft", "top", "topright", "left" \
+                    "right", "bottomleft", "bottom", "bottomleft"] \
+                    | tuple[float, float], default = "topleft"
+        If the value is a string, the tag will be managed by the layout
+        manager. If it is a tuple of (x, y) coordinates, they should be
+        in figure space and the tag will be ignored by the layout manager.
+    """
+
+
 class strip_text_x(MixinSequenceOfValues):
     """
     Facet labels along the horizontal axis
@@ -775,7 +858,9 @@ class strip_text(strip_text_x, strip_text_y):
     """
 
 
-class title(axis_title, legend_title, plot_title, plot_subtitle, plot_caption):
+class title(
+    axis_title, legend_title, plot_title, plot_subtitle, plot_caption, plot_tag
+):
     """
     All titles on the plot
 
@@ -792,6 +877,17 @@ class axis_text_x(MixinSequenceOfValues):
     Parameters
     ----------
     theme_element : element_text
+
+    Notes
+    -----
+    Use the `margin` to control the gap between the ticks and the
+    text. e.g.
+
+    ```python
+    theme(axis_text_x=element_text(margin={"t": 5, "units": "pt"}))
+    ```
+
+    creates a margin of 5 points.
     """
 
     _omit = ["margin"]
@@ -814,6 +910,17 @@ class axis_text_y(MixinSequenceOfValues):
     Parameters
     ----------
     theme_element : element_text
+
+    Notes
+    -----
+    Use the `margin` to control the gap between the ticks and the
+    text. e.g.
+
+    ```python
+    theme(axis_text_y=element_text(margin={"r": 5, "units": "pt"}))
+    ```
+
+    creates a margin of 5 points.
     """
 
     _omit = ["margin"]
@@ -836,6 +943,17 @@ class axis_text(axis_text_x, axis_text_y):
     Parameters
     ----------
     theme_element : element_text
+
+    Notes
+    -----
+    Use the `margin` to control the gap between the ticks and the
+    text. e.g.
+
+    ```python
+    theme(axis_text=element_text(margin={"t": 5, "r": 5, "units": "pt"}))
+    ```
+
+    creates a margin of 5 points.
     """
 
 
@@ -1485,11 +1603,13 @@ class plot_background(themeable):
 
     def apply_figure(self, figure: Figure, targets: ThemeTargets):
         super().apply_figure(figure, targets)
-        figure.patch.set(**self.properties)
+        if targets.plot_background:
+            targets.plot_background.set(**self.properties)
 
     def blank_figure(self, figure: Figure, targets: ThemeTargets):
         super().blank_figure(figure, targets)
-        figure.patch.set_visible(False)
+        if targets.plot_background:
+            targets.plot_background.set_visible(False)
 
 
 class strip_background_x(MixinSequenceOfValues):
@@ -1726,156 +1846,6 @@ class axis_ticks_length(axis_ticks_length_major, axis_ticks_length_minor):
     """
 
 
-class axis_ticks_pad_major_x(themeable):
-    """
-    x-axis major-tick padding
-
-    Parameters
-    ----------
-    theme_element : float
-        Value in points.
-    """
-
-    def apply_ax(self, ax: Axes):
-        super().apply_ax(ax)
-        val = self.properties["value"]
-
-        for t in ax.xaxis.get_major_ticks():
-            _val = val if t.tick1line.get_visible() else 0
-            t.set_pad(_val)
-
-
-class axis_ticks_pad_major_y(themeable):
-    """
-    y-axis major-tick padding
-
-    Parameters
-    ----------
-    theme_element : float
-        Value in points.
-
-    Note
-    ----
-    Padding is not applied when the
-    [](`~plotnine.theme.themeables.axis_ticks_major_y`) are
-    blank, but it does apply when the
-    [](`~plotnine.theme.themeables.axis_ticks_length_major_y`)
-    is zero.
-    """
-
-    def apply_ax(self, ax: Axes):
-        super().apply_ax(ax)
-        val = self.properties["value"]
-
-        for t in ax.yaxis.get_major_ticks():
-            _val = val if t.tick1line.get_visible() else 0
-            t.set_pad(_val)
-
-
-class axis_ticks_pad_major(axis_ticks_pad_major_x, axis_ticks_pad_major_y):
-    """
-    Axis major-tick padding
-
-    Parameters
-    ----------
-    theme_element : float
-        Value in points.
-
-    Note
-    ----
-    Padding is not applied when the
-    [](`~plotnine.theme.themeables.axis_ticks_major`) are blank,
-    but it does apply when the
-    [](`~plotnine.theme.themeables.axis_ticks_length_major`) is zero.
-    """
-
-
-class axis_ticks_pad_minor_x(themeable):
-    """
-    x-axis minor-tick padding
-
-    Parameters
-    ----------
-    theme_element : float
-
-    Note
-    ----
-    Padding is not applied when the
-    [](`~plotnine.theme.themeables.axis_ticks_minor_x`) are
-    blank, but it does apply when the
-    [](`~plotnine.theme.themeables.axis_ticks_length_minor_x`) is zero.
-    """
-
-    def apply_ax(self, ax: Axes):
-        super().apply_ax(ax)
-        val = self.properties["value"]
-
-        for t in ax.xaxis.get_minor_ticks():
-            _val = val if t.tick1line.get_visible() else 0
-            t.set_pad(_val)
-
-
-class axis_ticks_pad_minor_y(themeable):
-    """
-    y-axis minor-tick padding
-
-    Parameters
-    ----------
-    theme_element : float
-
-    Note
-    ----
-    Padding is not applied when the
-    [](`~plotnine.theme.themeables.axis_ticks_minor_y`) are
-    blank, but it does apply when the
-    [](`~plotnine.theme.themeables.axis_ticks_length_minor_y`)
-    is zero.
-    """
-
-    def apply_ax(self, ax: Axes):
-        super().apply_ax(ax)
-        val = self.properties["value"]
-
-        for t in ax.yaxis.get_minor_ticks():
-            _val = val if t.tick1line.get_visible() else 0
-            t.set_pad(_val)
-
-
-class axis_ticks_pad_minor(axis_ticks_pad_minor_x, axis_ticks_pad_minor_y):
-    """
-    Axis minor-tick padding
-
-    Parameters
-    ----------
-    theme_element : float
-
-    Note
-    ----
-    Padding is not applied when the
-    [](`~plotnine.theme.themeables.axis_ticks_minor`) are
-    blank, but it does apply when the
-    [](`~plotnine.theme.themeables.axis_ticks_length_minor`) is zero.
-    """
-
-
-class axis_ticks_pad(axis_ticks_pad_major, axis_ticks_pad_minor):
-    """
-    Axis tick padding
-
-    Parameters
-    ----------
-    theme_element : float
-        Value in points.
-
-    Note
-    ----
-    Padding is not applied when the
-    [](`~plotnine.theme.themeables.axis_ticks`) are blank,
-    but it does apply when the
-    [](`~plotnine.theme.themeables.axis_ticks_length`) is zero.
-    """
-
-
 class panel_spacing_x(themeable):
     """
     Horizontal spacing between the facet panels
@@ -2535,3 +2505,166 @@ class axis_ticks_direction(axis_ticks_direction_x, axis_ticks_direction_y):
         `in` for ticks inside the panel.
         `out` for ticks outside the panel.
     """
+
+
+class axis_ticks_pad_major_x(themeable):
+    """
+    x-axis major-tick padding
+
+    Parameters
+    ----------
+    theme_element : float
+        Value in points.
+    """
+
+    def apply_ax(self, ax: Axes):
+        super().apply_ax(ax)
+        val = self.properties["value"]
+
+        for t in ax.xaxis.get_major_ticks():
+            _val = val if t.tick1line.get_visible() else 0
+            t.set_pad(_val)
+
+
+class axis_ticks_pad_major_y(themeable):
+    """
+    y-axis major-tick padding
+
+    Parameters
+    ----------
+    theme_element : float
+        Value in points.
+
+    Note
+    ----
+    Padding is not applied when the
+    [](`~plotnine.theme.themeables.axis_ticks_major_y`) are
+    blank, but it does apply when the
+    [](`~plotnine.theme.themeables.axis_ticks_length_major_y`)
+    is zero.
+    """
+
+    def apply_ax(self, ax: Axes):
+        super().apply_ax(ax)
+        val = self.properties["value"]
+
+        for t in ax.yaxis.get_major_ticks():
+            _val = val if t.tick1line.get_visible() else 0
+            t.set_pad(_val)
+
+
+class axis_ticks_pad_major(axis_ticks_pad_major_x, axis_ticks_pad_major_y):
+    """
+    Axis major-tick padding
+
+    Parameters
+    ----------
+    theme_element : float
+        Value in points.
+
+    Note
+    ----
+    Padding is not applied when the
+    [](`~plotnine.theme.themeables.axis_ticks_major`) are blank,
+    but it does apply when the
+    [](`~plotnine.theme.themeables.axis_ticks_length_major`) is zero.
+    """
+
+
+class axis_ticks_pad_minor_x(themeable):
+    """
+    x-axis minor-tick padding
+
+    Parameters
+    ----------
+    theme_element : float
+
+    Note
+    ----
+    Padding is not applied when the
+    [](`~plotnine.theme.themeables.axis_ticks_minor_x`) are
+    blank, but it does apply when the
+    [](`~plotnine.theme.themeables.axis_ticks_length_minor_x`) is zero.
+    """
+
+    def apply_ax(self, ax: Axes):
+        super().apply_ax(ax)
+        val = self.properties["value"]
+
+        for t in ax.xaxis.get_minor_ticks():
+            _val = val if t.tick1line.get_visible() else 0
+            t.set_pad(_val)
+
+
+class axis_ticks_pad_minor_y(themeable):
+    """
+    y-axis minor-tick padding
+
+    Parameters
+    ----------
+    theme_element : float
+
+    Note
+    ----
+    Padding is not applied when the
+    [](`~plotnine.theme.themeables.axis_ticks_minor_y`) are
+    blank, but it does apply when the
+    [](`~plotnine.theme.themeables.axis_ticks_length_minor_y`)
+    is zero.
+    """
+
+    def apply_ax(self, ax: Axes):
+        super().apply_ax(ax)
+        val = self.properties["value"]
+
+        for t in ax.yaxis.get_minor_ticks():
+            _val = val if t.tick1line.get_visible() else 0
+            t.set_pad(_val)
+
+
+class axis_ticks_pad_minor(axis_ticks_pad_minor_x, axis_ticks_pad_minor_y):
+    """
+    Axis minor-tick padding
+
+    Parameters
+    ----------
+    theme_element : float
+
+    Note
+    ----
+    Padding is not applied when the
+    [](`~plotnine.theme.themeables.axis_ticks_minor`) are
+    blank, but it does apply when the
+    [](`~plotnine.theme.themeables.axis_ticks_length_minor`) is zero.
+    """
+
+
+class axis_ticks_pad(axis_ticks_pad_major, axis_ticks_pad_minor):
+    """
+    Axis tick padding
+
+    Parameters
+    ----------
+    theme_element : float
+        Value in points.
+
+    Note
+    ----
+    Padding is not applied when the
+    [](`~plotnine.theme.themeables.axis_ticks`) are blank,
+    but it does apply when the
+    [](`~plotnine.theme.themeables.axis_ticks_length`) is zero.
+    """
+
+    def __init__(self, theme_element):
+        x = theme_element
+        msg = (
+            f"Themeable '{self.__class__.__name__}' is deprecated and"
+            "will be removed in a future version. "
+            "Use the margin parameter of axis_text. e.g.\n"
+            f"axis_text_x(margin={{'t': {x}}})\n"
+            f"axis_text_y(margin={{'r': {x}}})\n"
+            f"axis_text(margin={{'t': {x}, 'r': {x}}})"
+        )
+        warn(msg, FutureWarning, stacklevel=1)
+        super().__init__(theme_element)