plotnine 0.15.3__py3-none-any.whl → 0.16.0a1__py3-none-any.whl

plotnine/iapi.py

@@ -14,7 +14,7 @@ from functools import cached_property
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from typing import Any, Iterator, Optional, Sequence
+    from typing import Any, Iterator, Literal, Optional, Sequence
 
     from matplotlib.axes import Axes
     from matplotlib.figure import Figure
@@ -26,8 +26,10 @@ if TYPE_CHECKING:
         FloatArrayLike,
         HorizontalJustification,
         ScaledAestheticsName,
+        Side,
         StripPosition,
         VerticalJustification,
+        VerticalTextJustification,
     )
 
     from ._mpl.offsetbox import FlexibleAnchoredOffsetbox
@@ -385,3 +387,17 @@ class legend_artists:
         )
         inside = (l.box for l in self.inside)
         return list(itertools.chain([*lrtb, *inside]))
+
+
+@dataclass
+class guide_text:
+    """
+    Processed guide text
+    """
+
+    margins: Sequence[float]
+    aligns: Sequence[Side | Literal["center"]]
+    fontsize: float
+    has: Sequence[HorizontalJustification]
+    vas: Sequence[VerticalTextJustification]
+    is_blank: bool

plotnine/scales/scale.py

@@ -31,8 +31,8 @@ if TYPE_CHECKING:
 
 @dataclass(kw_only=True)
 class scale(
-    Generic[RangeT, BreaksUserT, LimitsUserT, GuideTypeT],
     ABC,
+    Generic[RangeT, BreaksUserT, LimitsUserT, GuideTypeT],
     metaclass=Register,
 ):
     """

plotnine/stats/binning.py

@@ -47,7 +47,7 @@ def breaks_from_binwidth(
     binwidth: float,
     center: Optional[float] = None,
     boundary: Optional[float] = None,
-):
+) -> FloatArray:
     """
     Calculate breaks given binwidth
 
@@ -82,13 +82,12 @@ def breaks_from_binwidth(
         if center is not None:
             boundary = center - boundary
 
-    epsilon = np.finfo(float).eps
     shift = np.floor((x_range[0] - boundary) / binwidth)
     origin = boundary + shift * binwidth
-    # The (1-epsilon) factor prevents numerical roundoff in the
+    # The nextafter reduction prevents numerical roundoff in the
     # binwidth from creating an extra break beyond the one that
     # includes x_range[1].
-    max_x = x_range[1] + binwidth * (1 - epsilon)
+    max_x = np.nextafter(x_range[1] + binwidth, -np.inf)
     breaks = np.arange(origin, max_x, binwidth)
     return breaks
 
@@ -98,7 +97,7 @@ def breaks_from_bins(
     bins: int = 30,
     center: Optional[float] = None,
     boundary: Optional[float] = None,
-):
+) -> FloatArray:
     """
     Calculate breaks given binwidth
 
@@ -303,48 +302,21 @@ def fuzzybreaks(
 
     # To minimise precision errors, we do not pass the boundary and
     # binwidth into np.arange as params. The resulting breaks
-    # can then be adjusted with finer(epsilon based rather than
-    # some arbitrary small number) precision.
+    # can then be adjusted to the next floating point number.
     breaks = np.arange(boundary, srange[1] + binwidth, binwidth)
     return _adjust_breaks(breaks, right)
 
 
 def _adjust_breaks(breaks: FloatArray, right: bool) -> FloatArray:
-    epsilon = np.finfo(float).eps
-    plus = 1 + epsilon
-    minus = 1 - epsilon
-
-    sign = np.sign(breaks)
-    pos_idx = np.where(sign == 1)[0]
-    neg_idx = np.where(sign == -1)[0]
-    zero_idx = np.where(sign == 0)[0]
-
-    fuzzy = breaks.copy()
-    if right:
-        # [_](_](_](_]
-        lbreak = breaks[0]
-        fuzzy[pos_idx] *= plus
-        fuzzy[neg_idx] *= minus
-        fuzzy[zero_idx] = epsilon
-        # Left closing break
-        if lbreak == 0:
-            fuzzy[0] = -epsilon
-        elif lbreak < 0:
-            fuzzy[0] = lbreak * plus
-        else:
-            fuzzy[0] = lbreak * minus
-    else:
-        # [_)[_)[_)[_]
-        rbreak = breaks[-1]
-        fuzzy[pos_idx] *= minus
-        fuzzy[neg_idx] *= plus
-        fuzzy[zero_idx] = -epsilon
-        # Right closing break
-        if rbreak == 0:
-            fuzzy[-1] = epsilon
-        elif rbreak > 0:
-            fuzzy[-1] = rbreak * plus
-        else:
-            fuzzy[-1] = rbreak * minus
+    """
+    Adjust breaks to include/exclude every right break
 
+    If right=True, the breaks create intervals closed on right
+    i.e. [_] (_] (_] (_]
+    If right=False, the breaks create intervals closed on the left
+    i.e. [_) [_) [_) [_]
+    """
+    limit, idx = (np.inf, 0) if right else (-np.inf, -1)
+    fuzzy = np.nextafter(breaks, limit)
+    fuzzy[idx] = np.nextafter(breaks[idx], -limit)
     return fuzzy

plotnine/stats/smoothers.py

@@ -13,6 +13,8 @@ from ..exceptions import PlotnineError, PlotnineWarning
 if TYPE_CHECKING:
     import statsmodels.api as sm
 
+    from plotnine.typing import FloatArray
+
 
 def predictdf(data, xseq, params) -> pd.DataFrame:
     """
@@ -64,7 +66,7 @@ def lm(data, xseq, params) -> pd.DataFrame:
 
     X = sm.add_constant(data["x"])
     Xseq = sm.add_constant(xseq)
-    weights = data.get("weights", None)
+    weights = data.get("weight", None)
 
     if weights is None:
         init_kwargs, fit_kwargs = separate_method_kwargs(
@@ -454,12 +456,14 @@ def gpr(data, xseq, params):
     if params["se"]:
         y, stderr = regressor.predict(Xseq, return_std=True)
         data["y"] = y
-        data["se"] = stderr
+        data["se"] = cast("FloatArray", stderr)
         data["ymin"], data["ymax"] = tdist_ci(
             y, n - 1, stderr, params["level"]
         )
     else:
-        data["y"] = regressor.predict(Xseq, return_std=True)
+        data["y"] = cast(
+            "FloatArray", regressor.predict(Xseq, return_std=False)
+        )
 
     return data
 

plotnine/stats/stat.py

@@ -144,10 +144,10 @@ class stat(ABC, metaclass=Register):
         shallow = {"_kwargs"}
         for key, item in old.items():
             if key in shallow:
-                new[key] = item
+                new[key] = item  # pyright: ignore[reportIndexIssue]
                 memo[id(new[key])] = new[key]
             else:
-                new[key] = deepcopy(item, memo)
+                new[key] = deepcopy(item, memo)  # pyright: ignore[reportIndexIssue]
 
         return result
 

plotnine/stats/stat_density_2d.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 import numpy as np
 import pandas as pd
 
+from ..doctools import document
 from .density import get_var_type, kde
 from .stat import stat
 
@@ -12,6 +13,7 @@ if TYPE_CHECKING:
     from plotnine.typing import FloatArrayLike
 
 
+@document
 class stat_density_2d(stat):
     """
     Compute 2D kernel density estimation
@@ -92,17 +94,19 @@ class stat_density_2d(stat):
         group = data["group"].iloc[0]
         range_x = scales.x.dimension()
         range_y = scales.y.dimension()
-        x = np.linspace(range_x[0], range_x[1], params["n"])
-        y = np.linspace(range_y[0], range_y[1], params["n"])
+        _x = np.linspace(range_x[0], range_x[1], params["n"])
+        _y = np.linspace(range_y[0], range_y[1], params["n"])
 
         # The grid must have a "similar" shape (n, p) to the var_data
-        X, Y = np.meshgrid(x, y)
-        var_data = np.array([data["x"].to_numpy(), data["y"].to_numpy()]).T
+        X, Y = np.meshgrid(_x, _y)
+        x = cast("FloatArrayLike", data["x"].to_numpy())
+        y = cast("FloatArrayLike", data["y"].to_numpy())
+        var_data = np.array([x, y]).T
         grid = np.array([X.flatten(), Y.flatten()]).T
         density = kde(var_data, grid, package, **kde_params)
 
         if params["contour"]:
-            Z = density.reshape(len(x), len(y))
+            Z = density.reshape(len(_x), len(_y))
             data = contour_lines(X, Y, Z, params["levels"])
             # Each piece should have a distinct group
             groups = str(group) + "-00" + data["piece"].astype(str)

plotnine/stats/stat_pointdensity.py

@@ -1,3 +1,5 @@
+from typing import TYPE_CHECKING, cast
+
 import numpy as np
 import pandas as pd
 
@@ -6,6 +8,9 @@ from ..mapping.evaluation import after_stat
 from .density import get_var_type, kde
 from .stat import stat
 
+if TYPE_CHECKING:
+    from plotnine.typing import FloatArray
+
 
 @document
 class stat_pointdensity(stat):
@@ -67,8 +72,10 @@ class stat_pointdensity(stat):
     def compute_group(self, data, scales):
         package = self.params["package"]
         kde_params = self.params["kde_params"]
+        x = cast("FloatArray", data["x"].to_numpy())
+        y = cast("FloatArray", data["y"].to_numpy())
 
-        var_data = np.array([data["x"].to_numpy(), data["y"].to_numpy()]).T
+        var_data = np.array([x, y]).T
         density = kde(var_data, var_data, package, **kde_params)
 
         data = pd.DataFrame(

plotnine/stats/stat_qq.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 import numpy as np
 import pandas as pd
@@ -11,9 +11,9 @@ from ..mapping.evaluation import after_stat
 from .stat import stat
 
 if TYPE_CHECKING:
-    from typing import Any, Sequence
+    from typing import Any
 
-    from plotnine.typing import FloatArray
+    from plotnine.typing import FloatArray, FloatArrayLike
 
 
 # Note: distribution should be a name from scipy.stat.distribution
@@ -76,7 +76,7 @@ class stat_qq(stat):
     }
 
     def compute_group(self, data, scales):
-        sample = data["sample"].sort_values().to_numpy()
+        sample = cast("FloatArray", data["sample"].sort_values().to_numpy())
         theoretical = theoretical_qq(
             sample,
             self.params["distribution"],
@@ -93,7 +93,7 @@ def theoretical_qq(
     distribution: str,
     alpha: float,
     beta: float,
-    quantiles: Sequence[float] | None,
+    quantiles: FloatArrayLike | None,
     distribution_params: dict[str, Any],
 ) -> FloatArray:
     """

plotnine/stats/stat_qq_line.py

@@ -1,3 +1,5 @@
+from typing import TYPE_CHECKING, cast
+
 import numpy as np
 import pandas as pd
 
@@ -6,6 +8,9 @@ from ..exceptions import PlotnineError
 from .stat import stat
 from .stat_qq import theoretical_qq
 
+if TYPE_CHECKING:
+    from plotnine.typing import FloatArray
+
 
 @document
 class stat_qq_line(stat):
@@ -75,7 +80,7 @@ class stat_qq_line(stat):
         dparams = self.params["dparams"]
 
         # Compute theoretical values
-        sample = data["sample"].sort_values().to_numpy()
+        sample = cast("FloatArray", data["sample"].sort_values().to_numpy())
         theoretical = theoretical_qq(
             sample,
             self.params["distribution"],

plotnine/stats/stat_sina.py

@@ -1,7 +1,9 @@
+from typing import TYPE_CHECKING, cast
+
 import numpy as np
 import pandas as pd
 
-from .._utils import array_kind, jitter, resolution
+from .._utils import array_kind, jitter, nextafter_range, resolution
 from ..doctools import document
 from ..exceptions import PlotnineError
 from ..mapping.aes import has_groups
@@ -9,6 +11,9 @@ from .binning import breaks_from_bins, breaks_from_binwidth
 from .stat import stat
 from .stat_density import compute_density
 
+if TYPE_CHECKING:
+    from plotnine.typing import FloatArray, IntArray
+
 
 @document
 class stat_sina(stat):
@@ -142,17 +147,6 @@ class stat_sina(stat):
         params = self.params
         maxwidth = params["maxwidth"]
         random_state = params["random_state"]
-        fuzz = 1e-8
-        y_dim = scales.y.dimension()
-        y_dim_fuzzed = (y_dim[0] - fuzz, y_dim[1] + fuzz)
-
-        if params["binwidth"] is not None:
-            params["bins"] = breaks_from_binwidth(
-                y_dim_fuzzed, params["binwidth"]
-            )
-        else:
-            params["bins"] = breaks_from_bins(y_dim_fuzzed, params["bins"])
-
         data = super().compute_panel(data, scales)
 
         if not len(data):
@@ -198,8 +192,8 @@ class stat_sina(stat):
         return data
 
     def compute_group(self, data, scales):
+        binwidth = self.params["binwidth"]
         maxwidth = self.params["maxwidth"]
-        bins = self.params["bins"]
         bin_limit = self.params["bin_limit"]
         weight = None
         y = data["y"]
@@ -228,8 +222,14 @@ class stat_sina(stat):
             data["density"] = densf(y)
             data["scaled"] = data["density"] / dens["density"].max()
         else:
+            expanded_y_range = nextafter_range(scales.y.dimension())
+            if binwidth is not None:
+                bins = breaks_from_binwidth(expanded_y_range, binwidth)
+            else:
+                bins = breaks_from_bins(expanded_y_range, self.params["bins"])
+
             # bin based estimation
-            bin_index = pd.cut(y, bins, include_lowest=True, labels=False)
+            bin_index = pd.cut(y, bins, include_lowest=True, labels=False)  # pyright: ignore[reportCallIssue,reportArgumentType]
             data["density"] = (
                 pd.Series(bin_index)
                 .groupby(bin_index)
@@ -254,19 +254,18 @@ class stat_sina(stat):
     def finish_layer(self, data):
         # Rescale x in case positions have been adjusted
         style = self.params["style"]
-        x_mean = data["x"].to_numpy()
+        x_mean = cast("FloatArray", data["x"].to_numpy())
         x_mod = (data["xmax"] - data["xmin"]) / data["width"]
         data["x"] = data["x"] + data["x_diff"] * x_mod
-        x = data["x"].to_numpy()
-        even = data["group"].to_numpy() % 2 == 0
+        group = cast("IntArray", data["group"].to_numpy())
+        x = cast("FloatArray", data["x"].to_numpy())
+        even = group % 2 == 0
 
         def mirror_x(bool_idx):
             """
             Mirror x locations along the mean value
             """
-            data.loc[bool_idx, "x"] = (
-                2 * x_mean[bool_idx] - data.loc[bool_idx, "x"]
-            )
+            data.loc[bool_idx, "x"] = 2 * x_mean[bool_idx] - x[bool_idx]
 
         match style:
             case "left":

plotnine/stats/stat_summary.py

@@ -1,3 +1,5 @@
+from typing import cast
+
 import numpy as np
 import pandas as pd
 
@@ -314,8 +316,8 @@ class stat_summary(stat):
         summaries = []
         for (group, x), df in data.groupby(["group", "x"]):
             summary = func(df)
-            summary["x"] = x
-            summary["group"] = group
+            summary["x"] = x  # pyright: ignore[reportCallIssue,reportArgumentType]
+            summary["group"] = cast("int", group)
             summary["n"] = len(df)
             unique = uniquecols(df)
             if "y" in unique:

plotnine/stats/stat_summary_bin.py

@@ -1,3 +1,5 @@
+from typing import TYPE_CHECKING, cast
+
 import numpy as np
 import pandas as pd
 
@@ -9,6 +11,9 @@ from .binning import fuzzybreaks
 from .stat import stat
 from .stat_summary import make_summary_fun
 
+if TYPE_CHECKING:
+    from plotnine.typing import IntArray
+
 
 @document
 class stat_summary_bin(stat):
@@ -157,7 +162,8 @@ class stat_summary_bin(stat):
         # This is a plyr::ddply
         out = groupby_apply(data, "bin", func_wrapper)
         centers = (breaks[:-1] + breaks[1:]) * 0.5
-        bin_centers = centers[out["bin"].to_numpy()]
+        bin = cast("IntArray", out["bin"].to_numpy())
+        bin_centers = centers[bin]
         out["x"] = bin_centers
         out["bin"] += 1
         if isinstance(scales.x, scale_discrete):

plotnine/themes/elements/element_line.py

@@ -37,6 +37,7 @@ class element_line(element_base):
         *,
         color: (
             str
+            | Sequence[str]
             | tuple[float, float, float]
             | tuple[float, float, float, float]
             | None
@@ -46,6 +47,7 @@ class element_line(element_base):
         lineend: Literal["butt", "projecting", "round"] | None = None,
         colour: (
             str
+            | Sequence[str]
             | tuple[float, float, float]
             | tuple[float, float, float, float]
             | None

plotnine/themes/elements/element_text.py

@@ -86,10 +86,21 @@ class element_text(element_base):
             | None
         ) = None,
         size: float | Sequence[float] | None = None,
-        ha: Literal["center", "left", "right"] | float | None = None,
+        ha: (
+            Literal["center", "left", "right"]
+            | float
+            | Sequence[Literal["center", "left", "right"] | float]
+            | None
+        ) = None,
         va: (
             Literal["center", "top", "bottom", "baseline", "center_baseline"]
             | float
+            | Sequence[
+                Literal[
+                    "center", "top", "bottom", "baseline", "center_baseline"
+                ]
+                | float
+            ]
             | None
         ) = None,
         ma: Literal["center", "left", "right"] | float | None = None,

plotnine/themes/theme.py

@@ -295,7 +295,13 @@ class theme:
         for th in self.T.values():
             th.apply(self)
 
-    def setup(self, plot: ggplot):
+    def _setup(
+        self,
+        figure: Figure,
+        axs: list[Axes] | None = None,
+        title: str | None = None,
+        subtitle: str | None = None,
+    ):
         """
         Setup theme for applying
 
@@ -306,24 +312,14 @@ class theme:
 
         It also initialises where the artists to be themed will be stored.
         """
-        self.plot = plot
-        self.figure = plot.figure
-        self.axs = plot.axs
-        self.targets = ThemeTargets()
-        self._add_default_themeable_properties()
-        self.T.setup(self)
-
-    def _add_default_themeable_properties(self):
-        """
-        Add default themeable properties that depend depend on the plot
+        self.figure = figure
+        self.axs = axs if axs is not None else []
 
-        Some properties may be left unset (None) and their final values are
-        best worked out dynamically after the plot has been built, but
-        before the themeables are applied.
+        if title or subtitle:
+            self._smart_title_and_subtitle_ha(title, subtitle)
 
-        This is where the theme is modified to add those values.
-        """
-        self._smart_title_and_subtitle_ha()
+        self.targets = ThemeTargets()
+        self.T.setup(self)
 
     @property
     def rcParams(self):
@@ -466,18 +462,16 @@ class theme:
         dpi = self.getp("dpi")
         return self + theme(dpi=dpi * 2)
 
-    def _smart_title_and_subtitle_ha(self):
+    def _smart_title_and_subtitle_ha(
+        self, title: str | None, subtitle: str | None
+    ):
         """
         Smartly add the horizontal alignment for the title and subtitle
         """
         from .elements import element_text
 
-        has_title = bool(
-            self.plot.labels.get("title", "")
-        ) and not self.T.is_blank("plot_title")
-        has_subtitle = bool(
-            self.plot.labels.get("subtitle", "")
-        ) and not self.T.is_blank("plot_subtitle")
+        has_title = bool(title) and not self.T.is_blank("plot_title")
+        has_subtitle = bool(subtitle) and not self.T.is_blank("plot_subtitle")
 
         title_ha = self.getp(("plot_title", "ha"))
         subtitle_ha = self.getp(("plot_subtitle", "ha"))

plotnine/themes/themeable.py

@@ -2368,9 +2368,23 @@ class legend_text_position(themeable):
 
     Parameters
     ----------
-    theme_element : Literal["top", "bottom", "left", "right"] | None
-        Position of the legend key text. The default depends on the
-        position of the legend.
+    theme_element : Literal["top", "bottom", "left", "right"] | \
+                    Sequence[Literal["top", "bottom"]] | \
+                    Sequence[Literal["left", "right"]] | \
+                    Literal["top-bottom", "bottom-top"] | \
+                    Literal["left-right", "right-left"] | \
+                    None
+        Position of the legend key text.
+        It must be compatible with the position of the legend e.g.
+        when the legend is at the top or bottom, text can only be top
+        or bottom as well.
+        The default depends on the position of the legend.
+        Use a sequence to specify the position of each text, or
+        hyphenated values like `"left-right"` to alternate the position.
+
+    Notes
+    -----
+    Sequences and alternation only works well for colorbars.
     """
 
 

plotnine/typing.py

@@ -122,8 +122,13 @@ GuideKind: TypeAlias = Literal["legend", "colorbar", "colourbar"]
 NoGuide: TypeAlias = Literal["none", False]
 VerticalJustification: TypeAlias = Literal["bottom", "center", "top"]
 HorizontalJustification: TypeAlias = Literal["left", "center", "right"]
+Justification: TypeAlias = HorizontalJustification | VerticalJustification
+HorizontalTextJustification: TypeAlias = HorizontalJustification
+VerticalTextJustification: TypeAlias = (
+    VerticalJustification | Literal["baseline", "center_baseline"]
+)
 TextJustification: TypeAlias = (
-    VerticalJustification | HorizontalJustification | Literal["baseline"]
+    HorizontalTextJustification | VerticalTextJustification
 )
 
 # Type Variables

{plotnine-0.15.3.dist-info → plotnine-0.16.0a1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotnine
-Version: 0.15.3
+Version: 0.16.0a1
 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.6
+Requires-Dist: statsmodels>=0.14.5
 Provides-Extra: all
 Requires-Dist: plotnine[extra]; extra == "all"
 Requires-Dist: plotnine[doc]; extra == "all"
@@ -82,7 +82,7 @@ Requires-Dist: twine; extra == "dev"
 Requires-Dist: plotnine[typing]; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Provides-Extra: typing
-Requires-Dist: pyright==1.1.404; extra == "typing"
+Requires-Dist: pyright==1.1.408; extra == "typing"
 Requires-Dist: ipython; extra == "typing"
 Requires-Dist: pandas-stubs; extra == "typing"
 Dynamic: license-file