plotnine 0.15.0.dev3__py3-none-any.whl → 0.15.2__py3-none-any.whl

plotnine/themes/elements/margin.py

@@ -1,5 +1,5 @@
 """
-Theme elements used to decorate the graph.
+Margin
 """
 
 from __future__ import annotations
@@ -17,17 +17,55 @@ if TYPE_CHECKING:
 
 @dataclass
 class margin:
+    """
+    Margin
+    """
+
     t: float = 0
+    """
+    Top margin
+    """
+
     r: float = 0
+    """
+    Right margin
+    """
+
     b: float = 0
+    """
+    Bottom margin
+    """
+
     l: float = 0
+    """
+    Left Margin
+    """
+
     unit: Literal["pt", "in", "lines", "fig"] = "pt"
+    """
+    The units (coordinate space) of the values
+    """
 
     # These are set by the themeable when it is applied
     fontsize: float = field(init=False, default=0)
+    """
+    Font size of text that this margin applies to
+    """
+
     figure_size: tuple[float, float] = field(init=False, default=(0, 0))
+    """
+    Size of the figure in inches
+    """
 
     def setup(self, theme: theme, themeable_name: str):
+        """
+        Setup the margin to be used in the layout
+
+        For the margin's values to be useful, we need to be able to
+        convert them to different units as is required. Here we get
+        all the parameters that we shall need to do the conversions.
+        """
+        self.themeable_name = themeable_name
         self.fontsize = theme.getp((themeable_name, "size"), 11)
         self.figure_size = theme.getp("figure_size")
 
@@ -35,6 +73,8 @@ class margin:
     def pt(self) -> margin:
         """
         Return margin in points
+
+        These are the units of the display coordinate system
         """
         return self.to("pt")
 
@@ -42,6 +82,8 @@ class margin:
     def inch(self) -> margin:
         """
         Return margin in inches
+
+        These are the units of the figure-inches coordinate system
         """
         return self.to("in")
 
@@ -56,6 +98,8 @@ class margin:
     def fig(self) -> margin:
         """
         Return margin in figure units
+
+        These are the units of the figure coordinate system
         """
         return self.to("fig")
 
@@ -102,3 +146,22 @@ class margin:
         }
 
         return functions[conversion](value)
+
+
+def margin_auto(
+    t: float = 0.0,
+    r: float | None = None,
+    b: float | None = None,
+    l: float | None = None,
+    unit: Literal["pt", "in", "lines", "fig"] = "pt",
+) -> margin:
+    """
+    Create margin with minimal arguments
+    """
+    if r is None:
+        r = t
+    if b is None:
+        b = t
+    if l is None:
+        l = r
+    return margin(t, r, b, l, unit)

plotnine/themes/theme.py

@@ -72,7 +72,7 @@ class theme:
         ```
 
         will only modify the x-axis text.
-    kwargs: dict
+    kwargs: Any
         kwargs are `themeables`. The themeables are elements that are
         subclasses of `themeable`. Many themeables are defined using
         theme elements i.e
@@ -276,6 +276,14 @@ class theme:
         """
         return self.themeables.getp((name, "margin"))
 
+    @cached_property
+    def get_ha(self):
+        return self.themeables.get_ha
+
+    @cached_property
+    def get_va(self):
+        return self.themeables.get_va
+
     def apply(self):
         """
         Apply this theme, then apply additional modifications in order.

plotnine/themes/theme_538.py

@@ -23,7 +23,6 @@ class theme_538(theme_gray):
             axis_ticks=element_blank(),
             title=element_text(color="#3C3C3C"),
             legend_background=element_rect(fill="none"),
-            legend_key=element_rect(fill="#E0E0E0"),
             panel_background=element_rect(fill=bgcolor),
             panel_border=element_blank(),
             panel_grid_major=element_line(color="#D5D5D5"),

plotnine/themes/theme_bw.py

@@ -20,7 +20,6 @@ class theme_bw(theme_gray):
         super().__init__(base_size, base_family)
         self += theme(
             axis_text=element_text(size=0.8 * base_size),
-            legend_key=element_rect(fill="none", color="#CCCCCC"),
             panel_background=element_rect(fill="white"),
             panel_border=element_rect(fill="none", color="#7f7f7f"),
             panel_grid_major=element_line(color="#E5E5E5"),

plotnine/themes/theme_dark.py

@@ -24,7 +24,6 @@ class theme_dark(theme_gray):
         self += theme(
             axis_ticks=element_line(color="#666666", size=0.5),
             axis_ticks_minor=element_blank(),
-            legend_key=element_rect(fill="#7F7F7F", color="#666666", size=0.5),
             panel_background=element_rect(fill="#7F7F7F", color="none"),
             panel_grid_major=element_line(color="#666666", size=0.5),
             panel_grid_minor=element_line(color="#737373", size=0.25),

plotnine/themes/theme_gray.py

@@ -6,6 +6,7 @@ from .elements import (
     element_rect,
     element_text,
     margin,
+    margin_auto,
 )
 from .theme import theme
 
@@ -27,6 +28,7 @@ class theme_gray(theme):
 
     def __init__(self, base_size=11, base_family=None):
         base_family = base_family or get_option("base_family")
+        half_line = base_size / 2
         quarter_line = base_size / 4
         fifth_line = base_size / 5
         eighth_line = base_size / 8
@@ -81,7 +83,6 @@ class theme_gray(theme):
             legend_frame=element_blank(),
             legend_key_spacing_x=6,
             legend_key_spacing_y=2,
-            legend_key=element_rect(fill="#F2F2F2", colour="none"),
             legend_key_size=base_size * 0.8 * 1.8,
             legend_ticks_length=0.2,
             legend_margin=0,  # points
@@ -89,13 +90,13 @@ class theme_gray(theme):
             legend_spacing=10,  # points
             legend_text=element_text(
                 size=base_size * 0.8,
-                margin=margin(m / 1.5, m / 1.5, m / 1.5, m / 1.5, "fig"),
+                margin=margin_auto(m / 1.5, unit="fig"),
             ),
             legend_ticks=element_line(color="#CCCCCC", size=1),
             legend_title=element_text(
                 margin=margin(t=m, l=m * 2, b=m / 2, r=m * 2, unit="fig")
             ),
-            panel_background=element_rect(fill="#EBEBEB"),
+            panel_background=element_rect(fill="#EBEBEB", color="none"),
             panel_border=element_blank(),
             panel_grid_major=element_line(color="white", size=1),
             panel_grid_minor=element_line(color="white", size=0.5),
@@ -136,8 +137,8 @@ class theme_gray(theme):
             strip_text=element_text(
                 color="#1A1A1A",
                 size=base_size * 0.8,
-                linespacing=1.0,
-                margin=margin(1 / 3, 1 / 3, 1 / 3, 1 / 3, "lines"),
+                linespacing=1.5,
+                margin=margin_auto(half_line * 0.8),
             ),
             strip_text_y=element_text(rotation=-90),
             complete=True,

plotnine/themes/theme_light.py

@@ -24,7 +24,7 @@ class theme_light(theme_gray):
         self += theme(
             axis_ticks=element_line(color="#B3B3B3", size=0.5),
             axis_ticks_minor=element_blank(),
-            legend_key=element_rect(fill="white", color="#7F7F7F", size=0.72),
+            legend_key=element_rect(color="#7F7F7F", size=0.72),
             panel_background=element_rect(fill="white"),
             panel_border=element_rect(fill="none", color="#B3B3B3", size=1),
             panel_grid_major=element_line(color="#D9D9D9", size=0.5),

plotnine/themes/theme_matplotlib.py

@@ -5,6 +5,7 @@ from .elements import (
     element_rect,
     element_text,
     margin,
+    margin_auto,
 )
 from .theme import theme
 
@@ -33,6 +34,7 @@ class theme_matplotlib(theme):
         m = get_option("base_margin")
         base_size = mpl.rcParams.get("font.size", 11)
         linewidth = mpl.rcParams.get("grid.linewidth", 0.8)
+        half_line = base_size / 2
 
         super().__init__(
             line=element_line(size=linewidth),
@@ -63,15 +65,12 @@ class theme_matplotlib(theme):
             legend_key_spacing_x=6,
             legend_key_spacing_y=2,
             legend_frame=element_rect(color="black"),
-            legend_key=element_blank(),
             legend_key_size=16,
             legend_ticks_length=0.2,
             legend_margin=0,
             legend_position="right",
             legend_spacing=10,
-            legend_text=element_text(
-                margin=margin(m / 2, m / 2, m / 2, m / 2, "fig")
-            ),
+            legend_text=element_text(margin=margin_auto(m / 2, unit="fig")),
             legend_ticks=element_line(color="black"),
             legend_title=element_text(
                 ha="left",
@@ -112,7 +111,8 @@ class theme_matplotlib(theme):
                 fill="#D9D9D9", color="black", size=linewidth
             ),
             strip_text=element_text(
-                margin=margin(1 / 3, 1 / 3, 1 / 3, 1 / 3, "lines"),
+                linespacing=1.5,
+                margin=margin_auto(half_line * 0.8),
             ),
             strip_text_y=element_text(rotation=-90),
             complete=True,

plotnine/themes/theme_seaborn.py

@@ -5,6 +5,7 @@ from .elements import (
     element_rect,
     element_text,
     margin,
+    margin_auto,
 )
 from .theme import theme
 
@@ -20,7 +21,7 @@ class theme_seaborn(theme):
 
     Parameters
     ----------
-    style: "whitegrid", "darkgrid", "nogrid", "ticks"
+    style: "white", "dark", "whitegrid", "darkgrid",  "ticks"
         Style of axis background.
     context: "notebook", "talk", "paper", "poster"]``
         Intended context for resulting figures.
@@ -83,13 +84,15 @@ class theme_seaborn(theme):
             legend_position="right",
             legend_spacing=10,  # points
             legend_text=element_text(
-                margin=margin(m / 1.5, m / 1.5, m / 1.5, m / 1.5, "fig")
+                size=base_size * 0.8,
+                margin=margin_auto(m / 1.5, unit="fig"),
             ),
             legend_ticks=element_line(color="#CCCCCC", size=1),
             legend_title=element_text(
                 margin=margin(t=m, l=m * 2, b=m / 2, r=m * 2, unit="fig")
             ),
             panel_spacing=m,
+            panel_background=element_rect(fill=rcparams["axes.facecolor"]),
             plot_caption=element_text(
                 size=base_size * 0.8,
                 ha="right",
@@ -123,8 +126,8 @@ class theme_seaborn(theme):
             strip_background=element_rect(color="none", fill="#D1CDDF"),
             strip_text=element_text(
                 size=base_size * 0.8,
-                linespacing=1.0,
-                margin=margin(1 / 3, 1 / 3, 1 / 3, 1 / 3, "lines"),
+                linespacing=1.5,
+                margin=margin_auto(half_line * 0.8),
             ),
             strip_text_y=element_text(rotation=-90),
             complete=True,

plotnine/themes/theme_void.py

@@ -1,5 +1,11 @@
 from ..options import get_option
-from .elements import element_blank, element_line, element_text, margin
+from .elements import (
+    element_blank,
+    element_line,
+    element_text,
+    margin,
+    margin_auto,
+)
 from .theme import theme
 
 
@@ -54,7 +60,7 @@ class theme_void(theme):
             legend_spacing=10,
             legend_text=element_text(
                 size=base_size * 0.8,
-                margin=margin(m / 1.5, m / 1.5, m / 1.5, m / 1.5, "fig"),
+                margin=margin_auto(m / 1.5, unit="fig"),
             ),
             legend_ticks=element_line(color="#CCCCCC", size=1),
             legend_title=element_text(
@@ -91,11 +97,6 @@ class theme_void(theme):
             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=margin(1 / 3, 1 / 3, 1 / 3, 1 / 3, "lines"),
-            ),
+            strip_text=element_text(size=base_size * 0.8),
             complete=True,
         )

plotnine/themes/theme_xkcd.py

@@ -50,7 +50,6 @@ class theme_xkcd(theme_gray):
             legend_background=element_rect(color="black"),
             legend_box_margin=2,
             legend_margin=5,
-            legend_key=element_rect(fill="none"),
             panel_border=element_rect(color="black", size=1),
             panel_grid=element_blank(),
             panel_background=element_rect(fill="white"),

plotnine/themes/themeable.py

@@ -17,7 +17,7 @@ from warnings import warn
 
 import numpy as np
 
-from .._utils import to_rgba
+from .._utils import has_alpha_channel, to_rgba
 from .._utils.registry import RegistryHierarchyMeta
 from ..exceptions import PlotnineError, deprecated_themeable_name
 from .elements import element_blank
@@ -377,6 +377,36 @@ class Themeables(dict[str, themeable]):
 
         return default
 
+    def get_ha(self, name: str) -> float:
+        """
+        Get the horizontal alignement of themeable as a float
+
+        The themeable should be and element_text
+        """
+        lookup = {"left": 0.0, "center": 0.5, "right": 1.0}
+        ha: str | float = self.getp((name, "ha"), "center")
+        if isinstance(ha, str):
+            ha = lookup[ha]
+        return ha
+
+    def get_va(self, name) -> float:
+        """
+        Get the vertical alignement of themeable as a float
+
+        The themeable should be and element_text
+        """
+        lookup = {
+            "bottom": 0.0,
+            "center": 0.5,
+            "baseline": 0.5,
+            "center_baseline": 0.5,
+            "top": 1.0,
+        }
+        va: str | float = self.getp((name, "va"), "center")
+        if isinstance(va, str):
+            va = lookup[va]
+        return va
+
     def property(self, name: str, key: str = "value") -> Any:
         """
         Get the value a specific themeable(s) property
@@ -474,6 +504,25 @@ class MixinSequenceOfValues(themeable):
                 a.set(**{name: value})
 
 
+def blend_alpha(
+    properties: dict[str, Any], key: str = "color"
+) -> dict[str, Any]:
+    """
+    Blend color with alpha
+
+    When setting color property values of matplotlib objects,
+    for a color with an alpha channel, we don't want the alpha
+    property if any to have any effect on that color.
+    """
+    if (color := properties.get(key)) is not None:
+        if "alpha" in properties:
+            properties[key] = to_rgba(color, properties["alpha"])
+            properties["alpha"] = None
+        elif has_alpha_channel(color):
+            properties["alpha"] = None
+    return properties
+
+
 # element_text themeables
 
 
@@ -729,18 +778,29 @@ class plot_tag(themeable):
 
     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.
+    The `ha` & `va` of element_text have no effect in some cases. e.g.
+    if [](:class:`~plotnine.themes.themeable.plot_tag_position`) is "margin"
+    and the tag is at the top it cannot be vertically aligned.
+
+    Also `ha` & `va` can be floats if it makes sense to justify the tag
+    over a span. e.g. along the panel or plot, or when aligning with
+    other tags in a composition.
     """
 
     _omit = ["margin"]
 
     def apply_figure(self, figure: Figure, targets: ThemeTargets):
         super().apply_figure(figure, targets)
+        props = self.properties
+
+        if "va" in props and not isinstance(props["va"], str):
+            del props["va"]
+
+        if "ha" in props and not isinstance(props["ha"], str):
+            del props["ha"]
+
         if text := targets.plot_tag:
-            text.set(**self.properties)
+            text.set(**props)
 
     def blank_figure(self, figure: Figure, targets: ThemeTargets):
         super().blank_figure(figure, targets)
@@ -811,7 +871,7 @@ class strip_text_x(MixinSequenceOfValues):
     theme_element : element_text
     """
 
-    _omit = ["margin", "ha"]
+    _omit = ["margin", "ha", "va"]
 
     def apply_figure(self, figure: Figure, targets: ThemeTargets):
         super().apply_figure(figure, targets)
@@ -834,7 +894,7 @@ class strip_text_y(MixinSequenceOfValues):
     theme_element : element_text
     """
 
-    _omit = ["margin", "va"]
+    _omit = ["margin", "ha", "va"]
 
     def apply_figure(self, figure: Figure, targets: ThemeTargets):
         super().apply_figure(figure, targets)
@@ -894,13 +954,28 @@ class axis_text_x(MixinSequenceOfValues):
 
     def apply_ax(self, ax: Axes):
         super().apply_ax(ax)
-        self.set(ax.get_xticklabels())
+
+        # TODO: Remove this code when the minimum matplotlib >= 3.10.0,
+        # and use the commented one below it
+        import matplotlib as mpl
+        from packaging import version
+
+        vinstalled = version.parse(mpl.__version__)
+        v310 = version.parse("3.10.0")
+        name = "labelbottom" if vinstalled >= v310 else "labelleft"
+        if not ax.xaxis.get_tick_params()[name]:
+            return
+
+        # if not ax.xaxis.get_tick_params()["labelbottom"]:
+        #     return
+
+        labels = [t.label1 for t in ax.xaxis.get_major_ticks()]
+        self.set(labels)
 
     def blank_ax(self, ax: Axes):
         super().blank_ax(ax)
-        ax.xaxis.set_tick_params(
-            which="both", labelbottom=False, labeltop=False
-        )
+        for t in ax.xaxis.get_major_ticks():
+            t.label1.set_visible(False)
 
 
 class axis_text_y(MixinSequenceOfValues):
@@ -927,13 +1002,17 @@ class axis_text_y(MixinSequenceOfValues):
 
     def apply_ax(self, ax: Axes):
         super().apply_ax(ax)
-        self.set(ax.get_yticklabels())
+
+        if not ax.yaxis.get_tick_params()["labelleft"]:
+            return
+
+        labels = [t.label1 for t in ax.yaxis.get_major_ticks()]
+        self.set(labels)
 
     def blank_ax(self, ax: Axes):
         super().blank_ax(ax)
-        ax.yaxis.set_tick_params(
-            which="both", labelleft=False, labelright=False
-        )
+        for t in ax.yaxis.get_major_ticks():
+            t.label1.set_visible(False)
 
 
 class axis_text(axis_text_x, axis_text_y):
@@ -1306,7 +1385,7 @@ class panel_grid_major_x(themeable):
 
     def apply_ax(self, ax: Axes):
         super().apply_ax(ax)
-        ax.xaxis.grid(which="major", **self.properties)
+        ax.xaxis.grid(which="major", **blend_alpha(self.properties))
 
     def blank_ax(self, ax: Axes):
         super().blank_ax(ax)
@@ -1324,7 +1403,7 @@ class panel_grid_major_y(themeable):
 
     def apply_ax(self, ax: Axes):
         super().apply_ax(ax)
-        ax.yaxis.grid(which="major", **self.properties)
+        ax.yaxis.grid(which="major", **blend_alpha(self.properties))
 
     def blank_ax(self, ax: Axes):
         super().blank_ax(ax)
@@ -1448,8 +1527,13 @@ class legend_key(MixinSequenceOfValues):
     def apply_figure(self, figure: Figure, targets: ThemeTargets):
         super().apply_figure(figure, targets)
         properties = self.properties
+        edgecolor = properties.get("edgecolor", None)
+
+        if isinstance(self, rect) and edgecolor:
+            del properties["edgecolor"]
+
         # Prevent invisible strokes from having any effect
-        if properties.get("edgecolor") in ("none", "None"):
+        if edgecolor in ("none", "None"):
             properties["linewidth"] = 0
 
         rects = [da.patch for da in targets.legend_key]
@@ -1533,7 +1617,7 @@ class legend_box_background(themeable):
     """
 
 
-class panel_background(themeable):
+class panel_background(legend_key):
     """
     Panel background
 
@@ -1542,13 +1626,12 @@ class panel_background(themeable):
     theme_element : element_rect
     """
 
+    def apply_figure(self, figure: Figure, targets: ThemeTargets):
+        super().apply_figure(figure, targets)
+
     def apply_ax(self, ax: Axes):
         super().apply_ax(ax)
-        d = self.properties
-        if "facecolor" in d and "alpha" in d:
-            d["facecolor"] = to_rgba(d["facecolor"], d["alpha"])
-            del d["alpha"]
-
+        d = blend_alpha(self.properties, "facecolor")
         d["edgecolor"] = "none"
         d["linewidth"] = 0
         ax.patch.set(**d)
@@ -1574,16 +1657,12 @@ class panel_border(MixinSequenceOfValues):
         if not (rects := targets.panel_border):
             return
 
-        d = self.properties
+        d = blend_alpha(self.properties, "edgecolor")
 
         with suppress(KeyError):
             if d["edgecolor"] == "none" or d["size"] == 0:
                 return
 
-        if "edgecolor" in d and "alpha" in d:
-            d["edgecolor"] = to_rgba(d["edgecolor"], d["alpha"])
-            del d["alpha"]
-
         self.set(rects, d)
 
     def blank_figure(self, figure: Figure, targets: ThemeTargets):
@@ -1663,7 +1742,6 @@ class strip_background(strip_background_x, strip_background_y):
 
 
 class rect(
-    legend_key,
     legend_frame,
     legend_background,
     panel_background,

plotnine/typing.py

@@ -1,14 +1,13 @@
 from __future__ import annotations
 
-import sys
-from datetime import datetime, timedelta
 from typing import (
-    TYPE_CHECKING,
     Any,
     Callable,
     Literal,
+    NotRequired,
     Protocol,
     Sequence,
+    TypedDict,
     TypeVar,
 )
 
@@ -80,7 +79,7 @@ FacetSpaceRatios: TypeAlias = dict[Literal["x", "y"], Sequence[float]]
 
 StripPosition: TypeAlias = Literal["top", "right"]
 
-## Scales
+# Scales
 
 # Name names of scaled aesthetics
 ScaledAestheticsName: TypeAlias = Literal[
@@ -110,11 +109,11 @@ ScaledAestheticsName: TypeAlias = Literal[
     "upper",
 ]
 
-## Coords
+# Coords
 CoordRange: TypeAlias = tuple[float, float]
 
 # Guide
-SidePosition: TypeAlias = Literal["left", "right", "top", "bottom"]
+Side: TypeAlias = Literal["left", "right", "top", "bottom"]
 LegendPosition: TypeAlias = (
     Literal["left", "right", "top", "bottom", "inside"] | tuple[float, float]
 )
@@ -142,3 +141,15 @@ class PTransform(Protocol):
     """
 
     def __call__(self, x: TFloatArrayLike) -> TFloatArrayLike: ...
+
+
+class DisplayMetadata(TypedDict):
+    """
+    Metadata for the IPython output
+    """
+
+    width: NotRequired[int]
+    height: NotRequired[int]
+
+
+MimeBundle: TypeAlias = tuple[dict[str, bytes], dict[str, DisplayMetadata]]

plotnine/watermark.py

@@ -50,12 +50,12 @@ class watermark:
             kwargs["zorder"] = 99.9
         self.kwargs = kwargs
 
-    def __radd__(self, plot: p9.ggplot) -> p9.ggplot:
+    def __radd__(self, other: p9.ggplot) -> p9.ggplot:
         """
         Add watermark to ggplot object
         """
-        plot.watermarks.append(self)
-        return plot
+        other.watermarks.append(self)
+        return other
 
     def draw(self, figure: matplotlib.figure.Figure):
         """