plotnine 0.16.0a13__tar.gz → 0.16.0a14__tar.gz

{plotnine-0.16.0a13 → plotnine-0.16.0a14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotnine
-Version: 0.16.0a13
+Version: 0.16.0a14
 Summary: A Grammar of Graphics for Python
 Author-email: Hassan Kibirige <has2k1@gmail.com>
 License: The MIT License (MIT)
@@ -44,9 +44,10 @@ Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: contourpy>=1.2.0
 Requires-Dist: matplotlib>=3.10.0
 Requires-Dist: pandas>=2.2.0
-Requires-Dist: mizani~=0.14.0
+Requires-Dist: mizani~=0.14.5
 Requires-Dist: numpy>=1.25.0
 Requires-Dist: scipy>=1.15.0
 Requires-Dist: statsmodels>=0.14.6

{plotnine-0.16.0a13 → plotnine-0.16.0a14}/doc/_quartodoc.yml

@@ -37,6 +37,7 @@ quartodoc:
         - after_stat
         - after_scale
         - stage
+        - I
 
     - subtitle: Functions in the Aesthetic Evaluation Environment
       desc: |
@@ -70,10 +71,13 @@ quartodoc:
         - geom_blank
         - geom_boxplot
         - geom_col
+        - geom_contour
+        - geom_contour_filled
         - geom_count
         - geom_crossbar
         - geom_density
         - geom_density_2d
+        - geom_density_2d_filled
         - geom_dotplot
         - geom_errorbar
         - geom_errorbarh
@@ -142,9 +146,12 @@ quartodoc:
         - stat_bin_2d
         - stat_bindot
         - stat_boxplot
+        - stat_contour
+        - stat_contour_filled
         - stat_count
         - stat_density
         - stat_density_2d
+        - stat_density_2d_filled
         - stat_ecdf
         - stat_ellipse
         - stat_function

{plotnine-0.16.0a13 → plotnine-0.16.0a14}/doc/changelog.qmd

@@ -89,6 +89,31 @@ title: Changelog
   which you can place the strip on any side of the panel; `"top"` (default),
   `"bottom"`, `"left"` or `"right"`.
 
+- Added [](:class:`~plotnine.geom_contour`) and
+  [](:class:`~plotnine.geom_contour_filled`) to represent a gridded surface
+  with contour lines and filled bands.
+  ({{< issue 1084 >}})
+
+- Added [](:class:`~plotnine.geom_density_2d_filled`), the filled
+  counterpart of [](:class:`~plotnine.geom_density_2d`).
+
+- [](:class:`~plotnine.geom_polygon`) can now draw polygons with holes.
+  Use the new `subgroup` aesthetic to identify each ring within a polygon.
+
+- Plot components that take a `random_state` now also accept a
+  [](`numpy.random.Generator`), in addition to an integer seed or a
+  [](`~numpy.random.RandomState`).
+
+- Added [](:func:`~plotnine.I`), with which you can mark a value as literal.
+  A literal value takes no scale, so it is not trained, not mapped, and gets
+  no legend. One layer can draw literal colours while another maps the same
+  aesthetic through a scale. ({{< issue 1008 >}})
+
+- You can now place an annotation relative to the panel by wrapping a position
+  in [](:func:`~plotnine.I`). `x=I(0.5)` is the centre of the panel and
+  `x=I(0.9)` is 90% across, whatever the data, the limits or the expansion.
+  ({{< issue 939 >}})
+
 ### API Changes
 
 - Removed `geom.to_layer()`, `stat.to_layer()`, `annotate.to_layer()`,
@@ -126,6 +151,15 @@ title: Changelog
 - `statsmodels>=0.14.6` is now required on every platform. This replaces the
   separate `statsmodels<=0.14.4` requirement for Pyodide.
 
+- `contourpy>=1.2.0` is now required. It computes the contours of a surface.
+
+- [](:class:`~plotnine.stat_density_2d`) gained `contour_var`, `bins`,
+  `binwidth` and `breaks`. Every panel now uses the same contour heights.
+  The stat divides density into ten bands by default instead of five, so
+  [](:class:`~plotnine.geom_density_2d`) draws more contour lines for the
+  same data. The `levels` parameter is deprecated; use `bins` or `breaks`
+  instead.
+
 ### Bug Fixes
 
 - [](:class:`~plotnine.scale_size_datetime`) now honours its `range`
@@ -144,6 +178,17 @@ title: Changelog
   rectangle is now drawn as its own polygon instead of merging a bar's
   segments into a single path.
 
+- Under a non-linear coordinate system such as
+  [](:class:`~plotnine.coord_trans`), a [](:class:`~plotnine.geom_polygon`)
+  with several groups no longer draws an edge from one polygon to the next.
+
+- Under a non-linear coordinate system, separate
+  [](:class:`~plotnine.geom_path`) groups no longer connect when an aesthetic
+  such as `color` varies along the path. The fix also applies to
+  [](:class:`~plotnine.geom_line`), [](:class:`~plotnine.geom_step`),
+  [](:class:`~plotnine.geom_density`) and the line drawn by
+  [](:class:`~plotnine.geom_smooth`).
+
 - In a non-linear coordinate system (e.g. [](:class:`~plotnine.coord_trans`)),
   both edges of a [](:class:`~plotnine.geom_ribbon`) or
   [](:class:`~plotnine.geom_area`) now curve. Previously each edge held the
@@ -190,6 +235,32 @@ title: Changelog
   prevented layout from reserving their space, so the labels could render
   outside the figure.
 
+- Saving a composition now honours the `dpi` argument. For example,
+  `(p1 | p2).save("composition.png", dpi=200)` saves the image at 200 DPI
+  instead of the default resolution.
+
+- Plots containing an unseeded [](:class:`~plotnine.geom_sina`) can now be
+  copied, including when the geom has been added to every plot in a
+  composition. Copying previously raised
+  `TypeError: cannot pickle 'module' object`.
+  ({{< issue 1115 >}})
+
+- [](:class:`~plotnine.position_jitter`) and
+  [](:class:`~plotnine.position_jitterdodge`) now make independent random
+  draws for the horizontal and vertical axes when given a seed. Both axes
+  previously received identical offsets, placing points along a diagonal.
+
+- [](:class:`~plotnine.position_jitter`),
+  [](:class:`~plotnine.position_jitterdodge`),
+  [](:class:`~plotnine.stat_summary`), and
+  [](:class:`~plotnine.stat_summary_bin`) now treat `0` as a valid
+  `random_state` seed. They previously selected NumPy's global random state,
+  so results depended on other random draws.
+
+- Broadcasting a layer to every plot in a composition with `&` or `*` now
+  gives each target plot an independent copy. Changes made while drawing one
+  plot no longer affect the layer in another plot.
+
 ### Enhancements
 
 - The `factor` function available when evaluating expressions in

{plotnine-0.16.0a13 → plotnine-0.16.0a14}/plotnine/__init__.py

@@ -47,10 +47,13 @@ from .geoms import (
     geom_blank,
     geom_boxplot,
     geom_col,
+    geom_contour,
+    geom_contour_filled,
     geom_count,
     geom_crossbar,
     geom_density,
     geom_density_2d,
+    geom_density_2d_filled,
     geom_dotplot,
     geom_errorbar,
     geom_errorbarh,
@@ -102,6 +105,7 @@ from .labels import (
     ylab,
 )
 from .mapping import (
+    I,
     aes,
     after_scale,
     after_stat,
@@ -230,9 +234,12 @@ from .stats import (
     stat_bin_2d,
     stat_bindot,
     stat_boxplot,
+    stat_contour,
+    stat_contour_filled,
     stat_count,
     stat_density,
     stat_density_2d,
+    stat_density_2d_filled,
     stat_ecdf,
     stat_ellipse,
     stat_function,
@@ -281,6 +288,7 @@ from .watermark import (
 )
 
 __all__ = (
+    "I",
     "aes",
     "after_scale",
     "after_stat",
@@ -313,10 +321,13 @@ __all__ = (
     "geom_blank",
     "geom_boxplot",
     "geom_col",
+    "geom_contour",
+    "geom_contour_filled",
     "geom_count",
     "geom_crossbar",
     "geom_density",
     "geom_density_2d",
+    "geom_density_2d_filled",
     "geom_dotplot",
     "geom_errorbar",
     "geom_errorbarh",
@@ -475,9 +486,12 @@ __all__ = (
     "stat_bin_2d",
     "stat_bindot",
     "stat_boxplot",
+    "stat_contour",
+    "stat_contour_filled",
     "stat_count",
     "stat_density",
     "stat_density_2d",
+    "stat_density_2d_filled",
     "stat_ecdf",
     "stat_ellipse",
     "stat_function",

{plotnine-0.16.0a13 → plotnine-0.16.0a14}/plotnine/_utils/__init__.py

@@ -36,6 +36,8 @@ if TYPE_CHECKING:
         FloatArrayLike,
         HorizontalJustification,
         PolarSide,
+        RandomGenerator,
+        RandomStateLike,
         Side,
         VerticalJustification,
     )
@@ -467,6 +469,30 @@ def uniquecols(data):
     return data
 
 
+def normalise_random_state(
+    random_state: RandomStateLike | None,
+) -> RandomGenerator | None:
+    """
+    Convert an integer seed into a random number generator
+
+    Parameters
+    ----------
+    random_state :
+        Integer seed or random number generator. `None` remains unchanged
+        so the caller can select NumPy's global random state.
+
+    Notes
+    -----
+    Convert a seed once when several draws must advance the same stream.
+    Preserving `None` lets callers defer access to NumPy's global random
+    state without storing the unpicklable [](`numpy.random`) module in
+    plot parameters.
+    """
+    if isinstance(random_state, int):
+        return np.random.RandomState(random_state)
+    return random_state
+
+
 def jitter(x, factor=1, amount=None, random_state=None):
     """
     Add a small amount of noise to values in an array_like
@@ -485,9 +511,10 @@ def jitter(x, factor=1, amount=None, random_state=None):
         If `None` then `amount = factor * d/5`, where d is about
         the smallest difference between `x` values and `z` is the
         range of the `x` values.
-    random_state : int | ~numpy.random.RandomState, default=None
-        Seed or Random number generator to use. If `None`, then
-        numpy global generator [](`numpy.random`) is used.
+    random_state :
+        Integer seed, [](`~numpy.random.RandomState`), or
+        [](`numpy.random.Generator`). If `None`, draw from NumPy's global
+        random state.
 
     References:
 
@@ -498,10 +525,9 @@ def jitter(x, factor=1, amount=None, random_state=None):
     if len(x) == 0:
         return x
 
+    random_state = normalise_random_state(random_state)
     if random_state is None:
         random_state = np.random
-    elif isinstance(random_state, int):
-        random_state = np.random.RandomState(random_state)
 
     x = np.asarray(x)
 
@@ -583,7 +609,7 @@ def groupby_apply(
     df: pd.DataFrame,
     cols: str | list[str],
     func: Callable[..., pd.DataFrame],
-    *args: tuple[Any],
+    *args: Any,
     **kwargs: Any,
 ) -> pd.DataFrame:
     """

{plotnine-0.16.0a13 → plotnine-0.16.0a14}/plotnine/composition/_compose.py

@@ -330,7 +330,7 @@ class Compose:
             ):
                 self[i] = item & rhs
             else:
-                item += copy(rhs)
+                item += deepcopy(rhs)
 
         return self
 
@@ -349,7 +349,7 @@ class Compose:
 
         for item in self:
             if isinstance(item, ggplot):
-                item += copy(rhs)
+                item += deepcopy(rhs)
 
         return self
 
@@ -842,19 +842,26 @@ class Compose:
             Image format to use, automatically extract from
             file name extension.
         dpi :
-            DPI to use for raster graphics. If None, defaults to using
-            the `dpi` of theme to the first plot.
+            DPI for raster graphics. If `None`, use the composition theme's
+            `dpi`.
         **kwargs :
             These are ignored. Here to "softly" match the API of
             `ggplot.save()`.
         """
         from plotnine import theme
 
-        # To set the dpi, we only need to change the dpi of
-        # the last plot and theme gets added to the last plot
-        plot = (self + theme(dpi=dpi)) if dpi else self
-        figure = plot.draw()
-        figure.savefig(filename, format=format)
+        # Set the composition theme's DPI because the composition owns the
+        # figure. Inner plots inherit this value.
+        cmp = self
+        if dpi:
+            cmp = deepcopy(self)
+            cmp.theme = cmp.theme + theme(dpi=dpi)
+
+        figure = cmp.draw()
+
+        # Pass the DPI explicitly so `savefig.dpi` cannot override the
+        # requested resolution.
+        figure.savefig(filename, format=format, dpi=figure.get_dpi())
 
 
 def _renders_legend_inside(t: theme) -> bool:

{plotnine-0.16.0a13 → plotnine-0.16.0a14}/plotnine/coords/coord.py

@@ -11,7 +11,7 @@ from ..iapi import panel_ranges
 from ..mapping.aes import POSITION_AESTHETICS
 
 if typing.TYPE_CHECKING:
-    from typing import Any, Sequence
+    from typing import Any, Literal, Sequence
 
     import numpy.typing as npt
     import pandas as pd
@@ -398,6 +398,28 @@ class coord:
         """
         return self.range(panel_params)
 
+    def panel_fraction_to_data(
+        self,
+        fractions: FloatArrayLike,
+        panel_params: panel_view,
+        dimension: Literal["x", "y"],
+    ) -> FloatArray:
+        """
+        Convert panel fractions to data coordinates
+
+        Parameters
+        ----------
+        fractions :
+            Fractions where 0 and 1 mark the panel edges along
+            `dimension`. Values outside that range fall outside the panel.
+        panel_params :
+            Panel ranges and breaks.
+        dimension :
+            Data dimension represented by the fractions.
+        """
+        lo, hi = getattr(self.backtransform_range(panel_params), dimension)
+        return lo + np.asarray(fractions, dtype=float) * (hi - lo)
+
     def distance(
         self,
         x: FloatSeries,
@@ -426,9 +448,19 @@ class coord:
             data.loc[y_posinf, "y"] = ranges.y[1]
 
         dist = self.distance(data["x"], data["y"], panel_params)
-        bool_idx = (
-            data["group"].to_numpy()[1:] != data["group"].to_numpy()[:-1]
-        )
+        group = data["group"].to_numpy()
+        bool_idx = group[1:] != group[:-1]
+        if "subgroup" in data:
+            # Each `subgroup` identifies a ring within one polygon group.
+            # Ring boundaries are also segment boundaries; interpolating
+            # between rings would draw a spurious edge.
+            # Consecutive missing subgroup values belong to the same ring.
+            # Compare them as equal despite `nan != nan`.
+            subgroup = data["subgroup"].to_numpy()
+            missing = data["subgroup"].isna().to_numpy()
+            bool_idx |= (subgroup[1:] != subgroup[:-1]) & ~(
+                missing[1:] & missing[:-1]
+            )
         dist[bool_idx] = np.nan
 
         # Munch
@@ -460,9 +492,13 @@ def munch_data(data: pd.DataFrame, dist: FloatArray) -> pd.DataFrame:
     """
     segment_length = 0.01
 
-    # Count new points per segment, excluding the final endpoint.
-    dist[np.isnan(dist)] = 1
-    extra = np.maximum(np.floor(dist / segment_length), 1)
+    # Count new points per segment, excluding the final endpoint. `dist` is
+    # `NaN` at a path break. Give a break only its starting point;
+    # interpolation would connect the paths on either side.
+    is_break = np.isnan(dist)
+    extra = np.maximum(
+        np.floor(np.where(is_break, 0, dist) / segment_length), 1
+    )
     extra = extra.astype(int)
 
     # Every position aesthetic defines path geometry. Replicating `ymin` and

{plotnine-0.16.0a13 → plotnine-0.16.0a14}/plotnine/coords/coord_trans.py

@@ -4,13 +4,15 @@ from types import SimpleNamespace as NS
 from typing import TYPE_CHECKING, cast
 from warnings import warn
 
+import numpy as np
+
 from ..exceptions import PlotnineWarning
 from ..iapi import panel_ranges, panel_view
 from ..positions.position import transform_position
 from .coord import coord, dist_euclidean
 
 if TYPE_CHECKING:
-    from typing import Optional
+    from typing import Literal, Optional
 
     import pandas as pd
     from mizani.transforms import trans
@@ -19,6 +21,7 @@ if TYPE_CHECKING:
     from plotnine.scales.scale_xy import ScaleX, ScaleY
     from plotnine.typing import (
         FloatArray,
+        FloatArrayLike,
         FloatSeries,
         TFloatArrayLike,
     )
@@ -98,6 +101,35 @@ class coord_trans(coord):
             y=self.trans_y.inverse(panel_params.y.range),
         )
 
+    def panel_fraction_to_data(
+        self,
+        fractions: FloatArrayLike,
+        panel_params: panel_view,
+        dimension: Literal["x", "y"],
+    ) -> FloatArray:
+        """
+        Convert panel fractions to data coordinates
+
+        Measure the fraction in transformed drawing space, then invert it
+        before storing it in the data column that this coordinate system
+        transforms again during drawing.
+
+        Parameters
+        ----------
+        fractions :
+            Fractions where 0 and 1 mark the panel edges along
+            `dimension`. Values outside that range fall outside the
+            panel.
+        panel_params :
+            Panel ranges and breaks.
+        dimension :
+            Data dimension represented by the fractions.
+        """
+        trans = self.trans_x if dimension == "x" else self.trans_y
+        lo, hi = getattr(panel_params, dimension).range
+        value = lo + np.asarray(fractions, dtype=float) * (hi - lo)
+        return trans.inverse(value)
+
     def setup_panel_params(self, scale_x, scale_y) -> panel_view:
         """
         Compute the range and break information for the panel

{plotnine-0.16.0a13 → plotnine-0.16.0a14}/plotnine/facets/facet.py

@@ -12,6 +12,7 @@ import pandas.api.types as pdtypes
 from .._mpl.axes import p9Axes
 from .._utils import cross_join, match
 from ..exceptions import PlotnineError
+from ..mapping._asis import asis_columns
 from ..scales.scales import Scales
 from .strips import Strips
 
@@ -274,10 +275,12 @@ class facet:
         # loop over each layer, training x and y scales in turn
         for layer in layers:
             data = layer.data
+            asis = asis_columns(data)
             match_id = match(data["PANEL"], _layout["PANEL"])
             if panel_scales_x:
                 x_vars = list(
-                    set(panel_scales_x[0].aesthetics) & set(data.columns)
+                    (set(panel_scales_x[0].aesthetics) & set(data.columns))
+                    - asis
                 )
                 # the scale index for each data point
                 SCALE_X = _layout["SCALE_X"].iloc[match_id].tolist()
@@ -285,7 +288,8 @@ class facet:
 
             if panel_scales_y:
                 y_vars = list(
-                    set(panel_scales_y[0].aesthetics) & set(data.columns)
+                    (set(panel_scales_y[0].aesthetics) & set(data.columns))
+                    - asis
                 )
                 # the scale index for each data point
                 SCALE_Y = _layout["SCALE_Y"].iloc[match_id].tolist()

{plotnine-0.16.0a13 → plotnine-0.16.0a14}/plotnine/facets/layout.py

@@ -8,6 +8,7 @@ import numpy as np
 from .._utils import match
 from ..exceptions import PlotnineError
 from ..iapi import labels_view, layout_details, pos_scales
+from ..mapping._asis import asis_columns
 
 if typing.TYPE_CHECKING:
     import pandas as pd
@@ -120,17 +121,26 @@ class Layout:
 
         for layer in layers:
             data = layer.data
+            asis = asis_columns(data)
             match_id = match(data["PANEL"], _layout["PANEL"])
             if self.panel_scales_x:
                 x_vars = list(
-                    set(self.panel_scales_x[0].aesthetics) & set(data.columns)
+                    (
+                        set(self.panel_scales_x[0].aesthetics)
+                        & set(data.columns)
+                    )
+                    - asis
                 )
                 SCALE_X = _layout["SCALE_X"].iloc[match_id].tolist()
                 self.panel_scales_x.map(data, x_vars, SCALE_X)
 
             if self.panel_scales_y:
                 y_vars = list(
-                    set(self.panel_scales_y[0].aesthetics) & set(data.columns)
+                    (
+                        set(self.panel_scales_y[0].aesthetics)
+                        & set(data.columns)
+                    )
+                    - asis
                 )
                 SCALE_Y = _layout["SCALE_Y"].iloc[match_id].tolist()
                 self.panel_scales_y.map(data, y_vars, SCALE_Y)

{plotnine-0.16.0a13 → plotnine-0.16.0a14}/plotnine/geoms/__init__.py

@@ -12,10 +12,13 @@ from .geom_bin_2d import geom_bin2d, geom_bin_2d
 from .geom_blank import geom_blank
 from .geom_boxplot import geom_boxplot
 from .geom_col import geom_col
+from .geom_contour import geom_contour
+from .geom_contour_filled import geom_contour_filled
 from .geom_count import geom_count
 from .geom_crossbar import geom_crossbar
 from .geom_density import geom_density
 from .geom_density_2d import geom_density_2d
+from .geom_density_2d_filled import geom_density_2d_filled
 from .geom_dotplot import geom_dotplot
 from .geom_errorbar import geom_errorbar
 from .geom_errorbarh import geom_errorbarh
@@ -61,10 +64,13 @@ __all__ = (
     "geom_blank",
     "geom_boxplot",
     "geom_col",
+    "geom_contour",
+    "geom_contour_filled",
     "geom_count",
     "geom_crossbar",
     "geom_density",
     "geom_density_2d",
+    "geom_density_2d_filled",
     "geom_dotplot",
     "geom_errorbar",
     "geom_errorbarh",