DaSPi 2.3.2__tar.gz → 2.3.3__tar.gz

{daspi-2.3.2 → daspi-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: DaSPi
-Version: 2.3.2
+Version: 2.3.3
 Summary: Visualize and analyze your data with DaSPi. This package is designed for users who want to find relevant influencing factors in processes and validate improvements.
 Author-Email: Reto Jäggli <reto@jaeggli.email>
 License: MIT

{daspi-2.3.2 → daspi-2.3.3}/daspi/plotlib/plotter.py

@@ -264,6 +264,21 @@ class SpreadOpacity:
         alphas = ((i + 1) * COLOR.FILL_ALPHA / n for i in range(n))
         return {q: a for q, a in zip(self.agreements[::-1], alphas)}
     
+    @staticmethod
+    def _unique_subgroups(column: Series) -> list[float | int]:
+        """Get the distinct subgroup labels referenced in `column`, 
+        in first-seen order. Entries are either plain labels or 
+        `(own, next)` tuples produced by `subgroup_values` with 
+        `sharp_edges=True`, so a plain `.unique()` on `column` would 
+        not work: it would return the tuples themselves instead of 
+        the individual labels they contain."""
+        seen: list[float | int] = []
+        for label in column:
+            for value in (label if isinstance(label, tuple) else (label,)):
+                if value not in seen:
+                    seen.append(value)
+        return seen
+    
     def _kw_fill(
             self,
             color: str | tuple,
@@ -290,14 +305,28 @@ class SpreadOpacity:
         dict[str, Any]
             A dictionary containing keyword arguments for the fill
             operation, including color, alpha (transparency), edgecolor,
-            linewidth, where, and interpolate."""
+            linewidth, where, and interpolate.
+
+        Notes
+        -----
+        - `edgecolor` is forced to 'none' because the mplstyle sheets 
+          set a default `patch.edgecolor`, which would otherwise stroke 
+          each separate quantile patch and leave a visible seam where 
+          adjacent patches meet.
+        - A boundary sample may belong to two subgroups at once, stored 
+          as a `(own, next)` tuple by `subgroup_values` (see 
+          `sharp_edges`). `where` treats such a sample as a match for 
+          both of its labels, so the neighboring patches share that 
+          exact point and meet without a gap or an overlapping area."""
         alpha = self._alphas.get(agreement, COLOR.FILL_ALPHA)
+        labels = data[PLOTTER.SUBGROUP]
         kw = {
             'color': color,
             'alpha': alpha,
-            'edgecolor': mcolors.to_rgb(color) + (alpha/2,),
-            'linewidth': 1,
-            'where': data[PLOTTER.SUBGROUP]==agreement,
+            'edgecolor': 'none',
+            'where': labels.apply(
+                lambda label: agreement in label
+                if isinstance(label, tuple) else label == agreement),
             'interpolate': False}
         return kw
 
@@ -338,8 +367,9 @@ class SpreadOpacity:
     def subgroup_values(
             self,
             sequence: NDArray | list[float] | int,
-            quantiles: list[float]
-            ) -> list[float | int]:
+            quantiles: list[float],
+            sharp_edges: bool = False
+            ) -> list[float | int | tuple[float | int, ...]]:
         """Generate a list of subgroup values based on the agreements.
 
         This method creates a list of subgroup values derived from the 
@@ -358,12 +388,25 @@ class SpreadOpacity:
         quantiles : list[float]
             The list of quantiles used to determine the subgroup 
             boundaries.
+        sharp_edges : bool, optional
+            If True, the last sample of each subgroup run is turned 
+            into a `(own, next)` tuple instead of a plain label, so it 
+            also belongs to the following subgroup. `_kw_fill` then 
+            includes that same sample in both neighboring `where` 
+            masks, so the two `fill_between`/`fill_betweenx` patches 
+            share one exact point and meet without a gap or an 
+            overlapping area. Needed for continuous curves (e.g. 
+            `DensityCurve`), whose quantile bands are carved out of 
+            one shared curve; not for discrete areas (e.g. 
+            `QuantileBoxes`), whose rows already have their own 
+            explicit bounds. Default is False.
 
         Returns
         -------
-        list[float | int]:
+        list[float | int | tuple[float | int, ...]]:
             A list of subgroup values, which can include both floats 
-            and integers.
+            and integers. If `sharp_edges` is True, boundary samples 
+            are `(own, next)` tuples instead of plain labels.
         """
         subgroup = []
         names = self.agreements[::-1] + self.agreements[1:]
@@ -389,7 +432,13 @@ class SpreadOpacity:
                 subgroup = subgroup[:difference]
             else:
                 subgroup.extend([names[-1]] * difference)
-        return subgroup
+        
+        if not sharp_edges:
+            return subgroup
+        return [
+            name if i == len(subgroup) - 1 or name == subgroup[i + 1]
+            else (name, subgroup[i + 1])
+            for i, name in enumerate(subgroup)]
 
 
 class Plotter(ABC):
@@ -4345,7 +4394,10 @@ class DensityCurve(SpreadOpacity, TransformPlotter):
         If margin is 0, The two ends of the estimated density curve then 
         show the minimum and maximum value. Default is 0.
     fill : bool, optional
-        Flag whether to fill in the curves, by default True
+        Flag whether to fill in the curves, by default True. Has no 
+        effect if `cumulative` is True: the area under a CDF has no 
+        meaningful interpretation as probability mass (unlike a PDF), 
+        so it is never filled.
     agreements : tuple[float, ...] or tuple[int, ...], optional
         Specifies the tolerated process variation for calculating 
         quantiles. These quantiles are used to represent the filled area 
@@ -4429,6 +4481,11 @@ class DensityCurve(SpreadOpacity, TransformPlotter):
     n_points: int
     """Number of points that have the density estimation and its
     sequence."""
+    _draw_lower_line_: bool = False
+    """Whether the lower estimation is also drawn as a line. The lower 
+    estimation is a flat line at the feature base for most subclasses, 
+    so only double-sided curves (e.g. `Violin`) need to set this to 
+    True."""
 
     def __init__(
             self,
@@ -4483,7 +4540,7 @@ class DensityCurve(SpreadOpacity, TransformPlotter):
     def kw_default(self) -> dict[str, Any]:
         """Default keyword arguments for plotting (read-only)"""
         kwds = {
-            'color': COLOR.DARKEN if self.fill else self.color,}
+            'color': COLOR.DARKEN if self.fill and not self.cumulative else self.color,}
         return kwds
     
     @property
@@ -4498,8 +4555,12 @@ class DensityCurve(SpreadOpacity, TransformPlotter):
 
     @property
     def highlight_quantiles(self) -> bool:
-        """Flag indicating whether the quantiles should be highlighted."""
-        return bool(self.agreements) and self.fill
+        """Flag indicating whether the quantiles should be highlighted.
+        Always False for `cumulative` curves: the area under a CDF has
+        no meaningful interpretation as probability mass (unlike a
+        PDF), so quantile fill bands would shade a large area for a
+        small probability range and be visually misleading."""
+        return bool(self.agreements) and self.fill and not self.cumulative
 
     def estimate(
             self,
@@ -4620,7 +4681,7 @@ class DensityCurve(SpreadOpacity, TransformPlotter):
         ones = np.ones(len(sequence))
         if self.highlight_quantiles and len(sequence) > 1:
             quantiles = self.quantiles(target_data)
-            subgroups = self.subgroup_values(sequence, quantiles)
+            subgroups = self.subgroup_values(sequence, quantiles, sharp_edges=True)
         else:
             subgroups = 0 * ones
 
@@ -4631,22 +4692,18 @@ class DensityCurve(SpreadOpacity, TransformPlotter):
             PLOTTER.F_BASE_NAME: feature_data * ones})
         return data
     
+    @staticmethod
     def _get_lower_estimation_(
-        self,
         f_base: float | int, # noqa: PYI041
         estim_upp: Series
         ) -> Series:
-        """Get the lower estimation of the kernel density. For the KDE 
-        it is just a straight line at the location of the feature base. 
-        For Violin the upper kernel density estimate is mirrored at the
-        feature base."""
-        if self.__class__.__name__ == 'Violin':
-            estim_low = 2 * f_base - estim_upp
-        else:
-            estim_low = pd.Series(
-                f_base * np.ones(len(estim_upp)),
-                index=estim_upp.index)
-        return estim_low
+        """Get the lower estimation of the density curve as a straight 
+        line at the location of the feature base. Subclasses whose 
+        curve is double-sided (e.g. `Violin`) override this to mirror 
+        `estim_upp` at the feature base instead."""
+        return pd.Series(
+            f_base * np.ones(len(estim_upp)),
+            index=estim_upp.index)
         
     def __call__(
             self,
@@ -4675,20 +4732,28 @@ class DensityCurve(SpreadOpacity, TransformPlotter):
             estim_low = self._get_lower_estimation_(f_base, estim_upp) # pyright: ignore[reportArgumentType]
             sequence = group[self.target]
             
-            for agreement in group[PLOTTER.SUBGROUP].unique():
+            for agreement in self._unique_subgroups(group[PLOTTER.SUBGROUP]):
                 _kwds = self._kw_fill(self.color, agreement, group) | kwds
                 if self.target_on_y:
-                    if self.fill:
+                    if self.fill and not self.cumulative:
                         self.ax.fill_betweenx(
                             sequence, estim_low, estim_upp, **_kwds)
-                    self.ax.plot(
-                        estim_upp, sequence, estim_low, sequence, **_kw_line)
+                    if self._draw_lower_line_:
+                        self.ax.plot(
+                            estim_upp, sequence, estim_low, sequence,
+                            **_kw_line)
+                    else:
+                        self.ax.plot(estim_upp, sequence, **_kw_line)
                 else:
-                    if self.fill:
+                    if self.fill and not self.cumulative:
                         self.ax.fill_between(
                             sequence, estim_low, estim_upp, **_kwds)
-                    self.ax.plot(
-                        sequence, estim_upp, sequence, estim_low,**_kw_line)
+                    if self._draw_lower_line_:
+                        self.ax.plot(
+                            sequence, estim_upp, sequence, estim_low,
+                            **_kw_line)
+                    else:
+                        self.ax.plot(sequence, estim_upp, **_kw_line)
 
 
 class GaussianKDE(DensityCurve):
@@ -5505,6 +5570,19 @@ class Violin(GaussianKDE):
         kwds = {'color': self.color, 'alpha': COLOR.FILL_ALPHA}
         return kwds
 
+    _draw_lower_line_: bool = True
+    """The violin is double-sided, so the lower estimation is also 
+    drawn as a line."""
+
+    @staticmethod
+    def _get_lower_estimation_(
+        f_base: float | int, # noqa: PYI041
+        estim_upp: Series
+        ) -> Series:
+        """Mirror the upper kernel density estimate at the feature 
+        base to get the lower estimation for the double-sided violin."""
+        return 2 * f_base - estim_upp
+
 
 class FittedDensity(DensityCurve):
     """Class for plotting a fitted probability density function (PDF)

{daspi-2.3.2 → daspi-2.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "DaSPi"
-version = "2.3.2"
+version = "2.3.3"
 description = "Visualize and analyze your data with DaSPi. This package is designed for users who want to find relevant influencing factors in processes and validate improvements."
 authors = [
     { name = "Reto Jäggli", email = "reto@jaeggli.email" },