DaSPi 2.4.0__tar.gz → 2.5.0__tar.gz

{daspi-2.4.0 → daspi-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: DaSPi
-Version: 2.4.0
+Version: 2.5.0
 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.4.0 → daspi-2.5.0}/daspi/__init__.py

@@ -101,6 +101,7 @@ if TYPE_CHECKING:
         SpreadWidth,
         StandardErrorMean,
         Stem,
+        StripeArea,
         StripeLine,
         StripeSpan,
         TransformPlotter,
@@ -111,6 +112,7 @@ if TYPE_CHECKING:
         BivariateUnivariateCharts,
         GageRnRCharts,
         GageStudyCharts,
+        GoodnessOfFitCharts,
         PairComparisonCharts,
         PairwiseMatrixCharts,
         ParameterRelevanceCharts,
@@ -259,6 +261,7 @@ _LAZY_SUBMODULES: dict[str, str] = {
     'SpreadWidth': '.plotlib.plotter',
     'StandardErrorMean': '.plotlib.plotter',
     'Stem': '.plotlib.plotter',
+    'StripeArea': '.plotlib.plotter',
     'StripeLine': '.plotlib.plotter',
     'StripeSpan': '.plotlib.plotter',
     'TransformPlotter': '.plotlib.plotter',
@@ -267,6 +270,7 @@ _LAZY_SUBMODULES: dict[str, str] = {
     'BivariateUnivariateCharts': '.plotlib.precast',
     'GageRnRCharts': '.plotlib.precast',
     'GageStudyCharts': '.plotlib.precast',
+    'GoodnessOfFitCharts': '.plotlib.precast',
     'PairComparisonCharts': '.plotlib.precast',
     'PairwiseMatrixCharts': '.plotlib.precast',
     'ParameterRelevanceCharts': '.plotlib.precast',
@@ -401,6 +405,7 @@ __all__ = [
     'MeanTest',
     'MeasurementUncertainty',
     'MultivariateChart',
+    'GoodnessOfFitCharts',
     'PairComparisonCharts',
     'PairwiseMatrixCharts',
     'ParallelCoordinate',
@@ -424,6 +429,7 @@ __all__ = [
     'SpreadWidth',
     'StandardErrorMean',
     'Stem',
+    'StripeArea',
     'StripeLine',
     'StripeSpan',
     'StripesFacets',

{daspi-2.4.0 → daspi-2.5.0}/daspi/anova/model.py

@@ -374,8 +374,7 @@ class LinearModel(BaseHTMLReprModel):
         target='dissolution',
         factors=['employee', 'stirrer', 'brand', 'catalyst', 'water'],
         covariates=['temperature', 'preparation'],
-        order=2,
-        covariates=None)
+        order=2,)
 
     # Store goodnes of fit values for each elimination step
     df_gof = pd.concat(model.recursive_elimination())
@@ -883,7 +882,11 @@ class LinearModel(BaseHTMLReprModel):
         DataFrame
             The goodness-of-fit metrics table as DataFrame containing
             the following columns:
-            - 'formula' = current formula
+            - 'epoch' = the given `index`, i.e. the step at which a term
+            was added or removed during recursive elimination
+            - 'formula' = current formula, can be used to refit the
+            model at this step, see `formula_at_epoch` and 
+            `refit_at_epoch`
             - 's' = Uncertainty of the model as square root of MS_Residual
             - 'aic' = Akaike's information criteria
             - 'r2' = R-squared of the model
@@ -895,17 +898,127 @@ class LinearModel(BaseHTMLReprModel):
         """
         self.anova(typ='III', vif=False)
         data = {
-            'formula': self.formula,
-            'hierarchical': self.is_hierarchical(),
-            'least_parameter': self.least_parameter(),
-            'p_least': self.p_values().max(),
+            ANOVA.EPOCH: index + 1 if isinstance(index, int) else index,
+            ANOVA.FORMULA: self.formula,
+            ANOVA.HIERARCHICAL: self.is_hierarchical(),
+            ANOVA.LEAST_PARAMETER: self.least_parameter(),
+            ANOVA.P_LEAST: self.p_values().max(),
             's': self.uncertainty,
-            'aic': self.model.aic,
-            'r2': self.model.rsquared,
-            'r2_adj': self.model.rsquared_adj,
-            'r2_pred': self.r2_pred()}
+            ANOVA.AIC: self.model.aic,
+            ANOVA.R2: self.model.rsquared,
+            ANOVA.R2_ADJ: self.model.rsquared_adj,
+            ANOVA.R2_PRED: self.r2_pred()}
         return pd.DataFrame(data, index=[index])
     
+    @staticmethod
+    def formula_at_epoch(df_gof: DataFrame, epoch: int) -> str:
+        """Extract the model formula recorded at a given elimination
+        step from a goodness-of-fit table.
+
+        Parameters
+        ----------
+        df_gof : DataFrame
+            The goodness-of-fit table collected during recursive
+            elimination, i.e. the concatenated result of 
+            `recursive_elimination`. Must contain the columns 'epoch' 
+            and 'formula', see `gof_metrics`.
+        epoch : int
+            The elimination step whose formula should be extracted.
+
+        Returns
+        -------
+        str
+            The model formula used at the given `epoch`.
+
+        Examples
+        --------
+        ```python
+        import pandas as pd
+        import daspi as dsp
+
+        df = dsp.load_dataset('painkillers-dissolution')
+        lm = dsp.LinearModel(
+            source=df,
+            target='dissolution',
+            factors=['employee', 'stirrer', 'brand', 'catalyst', 'water'],
+            covariates=['temperature', 'preparation'],
+            order=2)
+        df_gof = pd.concat(lm.recursive_elimination())
+        dsp.LinearModel.formula_at_epoch(df_gof, epoch=5)
+        ```
+        """
+        rows = df_gof[df_gof[ANOVA.EPOCH] == epoch]
+        assert not rows.empty, (
+            f'No entry found for epoch={epoch} in df_gof, got epochs '
+            f'{sorted(df_gof[ANOVA.EPOCH].unique())}')
+        return str(rows[ANOVA.FORMULA].iloc[0])
+    
+    def refit_at_epoch(self, df_gof: DataFrame, epoch: int, **kwds) -> Self:
+        """Refit this model using the formula recorded at a given
+        elimination step of a goodness-of-fit table.
+
+        This is a convenience method combining `formula_at_epoch` and
+        `fit`, allowing you to go back to any intermediate step of a
+        previously run `recursive_elimination` once you have picked a
+        preferred epoch, e.g. by inspecting a
+        `daspi.GoodnessOfFitCharts` plot.
+
+        Parameters
+        ----------
+        df_gof : DataFrame
+            The goodness-of-fit table collected during recursive
+            elimination, i.e. the concatenated result of 
+            `recursive_elimination`. Must contain the columns 'epoch' 
+            and 'formula', see `gof_metrics`.
+        epoch : int
+            The elimination step whose formula should be used to refit
+            the model.
+        **kwds
+            Additional keyword arguments for `ols` function of 
+            `statsmodels.formula.api`, passed to `fit`.
+
+        Returns
+        -------
+        Self
+            The current instance of the model, refitted with the
+            formula of the given `epoch`, for method chaining.
+
+        Notes
+        -----
+        This also resyncs the `excluded` attribute so that the
+        `formula` property and methods relying on it (`eliminate`, 
+        `include`, `recursive_elimination`) stay consistent with the
+        formula used for refitting.
+
+        Examples
+        --------
+        ```python
+        import pandas as pd
+        import daspi as dsp
+
+        df = dsp.load_dataset('painkillers-dissolution')
+        lm = dsp.LinearModel(
+            source=df,
+            target='dissolution',
+            factors=['employee', 'stirrer', 'brand', 'catalyst', 'water'],
+            covariates=['temperature', 'preparation'],
+            order=2)
+        df_gof = pd.concat(lm.recursive_elimination())
+        lm.refit_at_epoch(df_gof, epoch=5)
+        dsp.ParameterRelevanceCharts(lm).plot().stripes().label()
+        ```
+        """
+        formula = self.formula_at_epoch(df_gof, epoch)
+        terms = [t.strip() for t in formula.split('~', 1)[1].split('+')]
+        drop_intercept = '-1' in terms
+        terms = [t for t in terms if t != '-1']
+        self.excluded = {t for t in self._initial_terms if t not in terms}
+        if drop_intercept:
+            self.excluded.add(ANOVA.INTERCEPT)
+        else:
+            self.excluded.discard(ANOVA.INTERCEPT)
+        return self.fit(**kwds)
+    
     def summary(
             self, 
             anova_typ: Literal['', 'I', 'II', 'III'] | None = None,

{daspi-2.4.0 → daspi-2.5.0}/daspi/constants.py

@@ -843,6 +843,45 @@ class _Anova_:
     """Default column name for the Variance Inflation Factor values used 
     to detect multicollinearity in an ANOVA table."""
     
+    EPOCH: Literal['epoch'] = 'epoch'
+    """Column name for the step at which a term was added or removed 
+    during recursive elimination in a goodness-of-fit table, see 
+    `LinearModel.gof_metrics`."""
+    
+    FORMULA: Literal['formula'] = 'formula'
+    """Column name for the model formula at a given elimination step in 
+    a goodness-of-fit table, see `LinearModel.gof_metrics` and 
+    `LinearModel.formula_at_epoch`."""
+    
+    HIERARCHICAL: Literal['hierarchical'] = 'hierarchical'
+    """Column name for the flag indicating whether the model is 
+    hierarchical in a goodness-of-fit table, see 
+    `LinearModel.gof_metrics`."""
+    
+    LEAST_PARAMETER: Literal['least_parameter'] = 'least_parameter'
+    """Column name for the least significant term in a goodness-of-fit 
+    table, see `LinearModel.gof_metrics`."""
+    
+    P_LEAST: Literal['p_least'] = 'p_least'
+    """Column name for the p-value of the least significant term in a 
+    goodness-of-fit table, see `LinearModel.gof_metrics`."""
+    
+    AIC: Literal['aic'] = 'aic'
+    """Column name for Akaike's information criterion in a 
+    goodness-of-fit table, see `LinearModel.gof_metrics`."""
+    
+    R2: Literal['r2'] = 'r2'
+    """Column name for R-squared in a goodness-of-fit table, see 
+    `LinearModel.gof_metrics`."""
+    
+    R2_ADJ: Literal['r2_adj'] = 'r2_adj'
+    """Column name for adjusted R-squared in a goodness-of-fit table, 
+    see `LinearModel.gof_metrics`."""
+    
+    R2_PRED: Literal['r2_pred'] = 'r2_pred'
+    """Column name for predicted R-squared in a goodness-of-fit table, 
+    see `LinearModel.gof_metrics`."""
+    
     SMALLEST_INTERACTION_ORDER: int = 2
     """Smallest possible interaction order, i.e. the interaction between 
     two factors (A:B)."""

{daspi-2.4.0 → daspi-2.5.0}/daspi/plotlib/chart.py

@@ -934,9 +934,8 @@ class SingleChart(Chart):
         if not isinstance(combination, tuple): 
             combination = (combination, )
         self._last_variate = deepcopy(self._current_variate)
-        for key, name in zip(self.variate_names, combination):
-            self._current_variate[key] = name
-    
+        self._current_variate |= dict(zip(self.variate_names, combination))
+
     def dodge(self) -> None:
         """Converts the feature data to tick positions, taking dodging 
         into account."""

{daspi-2.4.0 → daspi-2.5.0}/daspi/plotlib/plotter.py

@@ -169,6 +169,7 @@ __all__ = [
     'StandardErrorMean',
     'Stem',
     'Stripe',
+    'StripeArea',
     'StripeLine',
     'StripeSpan',
     'TransformPlotter',
@@ -8314,6 +8315,186 @@ class StripeSpan(Stripe):
         self._axes.append(ax)
 
 
+class StripeArea(Stripe):
+    """Concrete implementation of `Stripe` for filling the area between
+    two boundary curves using `fill_between`/`fill_betweenx`.
+
+    Unlike `StripeSpan`, which draws a constant band across the full 
+    plotting area with `axhspan`/`axvspan`, `StripeArea` fills the 
+    region between two boundary curves that may vary along the 
+    orthogonal axis (e.g. a confidence band around a fitted line, or 
+    spec limits that change over the feature range). The `where` 
+    parameter allows the fill to be restricted to specific sections of 
+    the data range, exactly like the `where` argument of Matplotlib's 
+    `fill_between`/`fill_betweenx`.
+
+    Parameters
+    ----------
+    label : str
+        The label of the stripe as it appears in the legend.
+    base : array-like
+        The data coordinates along the orthogonal axis (x for 
+        horizontal stripes, y for vertical stripes) that the lower and
+        upper boundary values correspond to.
+    lower_values : array-like or float
+        The lower boundary of the filled area for each `base` value.
+        Scalars are broadcast across `base`.
+    upper_values : array-like or float
+        The upper boundary of the filled area for each `base` value.
+        Scalars are broadcast across `base`.
+    where : array-like of bool or None, optional
+        Boolean mask defining where the area should be filled, passed
+        directly to `fill_between`/`fill_betweenx`. If None, the area is
+        filled across the entire `base` range. Defaults to None.
+    interpolate : bool, optional
+        Whether to interpolate the boundaries at the edges of masked 
+        regions defined by `where`, passed to 
+        `fill_between`/`fill_betweenx`. Defaults to False.
+    step : {'pre', 'post', 'mid'} or None, optional
+        If not None, fill between `base` and the boundaries using steps 
+        of the given style, passed to `fill_between`/`fill_betweenx`.
+        Defaults to None.
+    orientation : {'horizontal', 'vertical'}, optional
+        The orientation of the stripe. Defaults to 'horizontal'.
+    color : str, optional
+        The fill color of the stripe. Defaults to `COLOR.STRIPE`.
+    alpha : float, optional
+        Transparency level of the stripe. Defaults to `COLOR.CI_ALPHA`.
+    zorder : float, optional
+        Drawing order of the stripe. Defaults to 0.7.
+    border_linewidth : float, optional
+        Width of the border line. Can also be set via `lw` or 
+        `linewidth` in `**kwds`. Defaults to 0.
+    **kwds :
+        Additional keyword arguments for fine-tuning appearance.
+        Priority order:
+        - Line width: `lw`, `linewidth`, then `border_linewidth`
+        - Color: `c`, then `color`
+
+    Examples
+    --------
+    Apply to an existing Axes object:
+
+    ```python
+    import numpy as np
+    import matplotlib.pyplot as plt
+    from daspi import StripeArea, COLOR
+
+    fig, ax = plt.subplots()
+    x = np.linspace(0, 10, 100)
+    lower = np.sin(x) - 0.3
+    upper = np.sin(x) + 0.3
+    band = StripeArea(
+        label='band',
+        base=x,
+        lower_values=lower,
+        upper_values=upper,
+        where=x > 5,
+        color=COLOR.STRIPE)
+    band(ax=ax)
+    ax.legend([band.handle], [band.label])
+    ```
+
+    Notes
+    -----
+    This class is part of the DaSPi visualization toolkit and is 
+    designed to integrate seamlessly with other chart components. It 
+    ensures that each stripe is only drawn once per Axes instance.
+    """
+
+    __slots__ = (
+        'base',
+        'border_linewidth',
+        'interpolate',
+        'lower_values',
+        'step',
+        'upper_values',
+        'where')
+
+    base: NDArray
+    """The data coordinates along the orthogonal axis the boundary 
+    values correspond to."""
+    border_linewidth: float
+    """Width of the border line. Could also be set during initialisation
+    via `lw` or `linewidth`."""
+    interpolate: bool
+    """Whether to interpolate the boundaries at the edges of masked 
+    regions defined by `where`."""
+    lower_values: NDArray
+    """The lower boundary of the filled area for each `base` value."""
+    step: Literal['pre', 'post', 'mid'] | None
+    """If not None, fill using steps of the given style."""
+    upper_values: NDArray
+    """The upper boundary of the filled area for each `base` value."""
+    where: NDArray | None
+    """Boolean mask defining where the area should be filled."""
+
+    def __init__(
+            self,
+            label: str,
+            base: ArrayLike,
+            lower_values: ArrayLike | float,
+            upper_values: ArrayLike | float,
+            where: ArrayLike | None = None,
+            interpolate: bool = False,
+            step: Literal['pre', 'post', 'mid'] | None = None,
+            orientation: Literal['horizontal', 'vertical'] = 'horizontal',
+            color: str = COLOR.STRIPE,
+            alpha: float = COLOR.CI_ALPHA,
+            zorder: float = 0.7,
+            border_linewidth: float = 0,
+            **kwds) -> None:
+        self.base = np.asarray(base, dtype=float)
+        self.lower_values = np.broadcast_to(
+            np.asarray(lower_values, dtype=float), self.base.shape)
+        self.upper_values = np.broadcast_to(
+            np.asarray(upper_values, dtype=float), self.base.shape)
+        self.where = None if where is None else np.asarray(where, dtype=bool)
+        self.interpolate = interpolate
+        self.step = step
+
+        position = float(np.mean(self.lower_values + self.upper_values) / 2)
+        width = float(np.mean(self.upper_values - self.lower_values))
+        super().__init__(
+            label=label,
+            orientation=orientation,
+            position=position,
+            width=width,
+            color=kwds.get('c', color),
+            alpha=alpha,
+            zorder=zorder,
+            show_position=False)
+        self.border_linewidth = kwds.get(
+            'lw', kwds.get('linewidth', border_linewidth))
+
+    @property
+    def handle(self) -> Patch:
+        """Get the handle of the stripe used for legend."""
+        handle = Patch(color=self.color, alpha=self.alpha)
+        return handle
+
+    def __call__(self, ax: Axes) -> None:
+        """Draw the stripe on the given Axes object."""
+        if ax in self._axes:
+            return
+
+        kwds = {
+            'color': self.color,
+            'alpha': self.alpha,
+            'linewidth': self.border_linewidth,
+            'zorder': self.zorder,
+            'where': self.where,
+            'interpolate': self.interpolate,
+            'step': self.step}
+        if self.orientation == 'horizontal':
+            ax.fill_between(
+                self.base, self.lower_values, self.upper_values, **kwds)
+        else:
+            ax.fill_betweenx(
+                self.base, self.lower_values, self.upper_values, **kwds)
+        self._axes.append(ax)
+
+
 class BlandAltman(Plotter):
     """Generate a Bland-Altman plot to compare two sets of measurements.