shiftshap 0.2.0__tar.gz

shiftshap-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mayowa Samuel Olokun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shiftshap-0.2.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: shiftshap
+Version: 0.2.0
+Summary: Monitor whether your model's SHAP explanations still hold as data drifts.
+Author: Mayowa Samuel Olokun
+License: MIT
+Project-URL: Homepage, https://github.com/OWNER/shiftshap
+Project-URL: Issues, https://github.com/OWNER/shiftshap/issues
+Keywords: shap,explainability,xai,drift,distribution-shift,model-monitoring,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.4; extra == "plot"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: matplotlib>=3.4; extra == "dev"
+Dynamic: license-file
+
+# shiftshap
+
+**Monitor whether your model's SHAP explanations still hold as your data drifts.**
+
+`shiftshap` answers a question every team running a model in production eventually
+asks: *are my model's explanations still trustworthy?* Models live for months or
+years — they get retrained, upstream pipelines change, and feature distributions
+shift. When that happens, the model's reasoning quietly changes with it. The
+feature that drove your predictions last quarter may not be the one driving them
+today.
+
+SHAP is excellent at explaining a model **at a single point in time**, but it has
+no built-in way to tell you how those explanations have **changed** between two
+points. Today people work around this by pickling explanation objects and writing
+their own comparison scripts, or by using data-drift tools that know nothing about
+SHAP's structure. `shiftshap` fills that gap.
+
+---
+
+## Install
+
+```bash
+pip install shiftshap            # core
+pip install shiftshap[plot]      # + matplotlib for the drift chart
+```
+
+## Quickstart
+
+If you already use SHAP, you already have everything you need. Take your SHAP
+values from two periods — training vs. production, or last month vs. this month —
+and pass them in:
+
+```python
+import shiftshap
+
+report = shiftshap.compare(reference_shap, current_shap)
+
+print(report.summary())
+#  2 of 5 features show HIGH explanation drift (0 medium).
+#  Top driver changed from 'income' to 'balance'.
+#  Overall rank stability (Spearman): 0.70.
+
+print(report.details())          # plain-English narrative of the biggest movers
+report.to_frame()                # full per-feature table
+report.plot()                    # rank-drift bump chart
+shiftshap.metric_definitions()   # what every metric means, in plain words
+```
+
+Inputs can be `shap.Explanation` objects, NumPy arrays, lists, or pandas
+DataFrames of shape `(n_samples, n_features)`. **Multi-class SHAP** (3D arrays)
+is supported — by default classes are aggregated, or pass `class_index=k` to
+focus on one class. The two periods don't need the same number of samples.
+
+### Robust by design
+
+`shiftshap` is built to survive real, messy production data. It handles NaNs
+(ignored with a note), zero-variance features, tiny samples (with an explicit
+"results unreliable" warning rather than false alarms), and multi-class outputs —
+and it fails with clear, actionable errors on genuinely broken input (infinities,
+mismatched feature counts, empty arrays) instead of cryptic stack traces.
+
+## What it tells you
+
+For every feature, `shiftshap` reports:
+
+- **Importance drift** — how the mean absolute SHAP value changed between periods.
+- **PSI** (Population Stability Index) on the SHAP distribution — the industry-standard
+  shift metric, with the accepted `0.2` threshold flagging significant drift.
+- **Rank drift** — whether your most important features reordered, plus an overall
+  Spearman rank-stability score.
+- **Severity** — a `high` / `medium` / `low` label per feature, so the output is
+  actionable at a glance.
+
+And a **bump chart** showing how the feature-importance ranking shifted:
+
+![rank drift chart](examples/rank_drift.png)
+
+## Why it matters
+
+An explanation that has silently drifted is worse than no explanation — it gives
+false confidence. In regulated settings (finance, insurance, healthcare) teams are
+increasingly required to show that model explanations remain valid over time.
+`shiftshap` turns that check into two lines of code.
+
+## Roadmap
+
+`v0.1` deliberately does one thing well: compare two snapshots of SHAP explanations
+for tabular models. Planned next:
+
+- Persistent explanation store for many time-points (not just two).
+- Research-grade **faithfulness-under-shift** metrics beyond distributional PSI.
+- Alerting hooks for monitoring pipelines.
+- Support for image and text explanations.
+
+Contributions and issues welcome.
+
+## License
+
+MIT

shiftshap-0.2.0/README.md

@@ -0,0 +1,99 @@
+# shiftshap
+
+**Monitor whether your model's SHAP explanations still hold as your data drifts.**
+
+`shiftshap` answers a question every team running a model in production eventually
+asks: *are my model's explanations still trustworthy?* Models live for months or
+years — they get retrained, upstream pipelines change, and feature distributions
+shift. When that happens, the model's reasoning quietly changes with it. The
+feature that drove your predictions last quarter may not be the one driving them
+today.
+
+SHAP is excellent at explaining a model **at a single point in time**, but it has
+no built-in way to tell you how those explanations have **changed** between two
+points. Today people work around this by pickling explanation objects and writing
+their own comparison scripts, or by using data-drift tools that know nothing about
+SHAP's structure. `shiftshap` fills that gap.
+
+---
+
+## Install
+
+```bash
+pip install shiftshap            # core
+pip install shiftshap[plot]      # + matplotlib for the drift chart
+```
+
+## Quickstart
+
+If you already use SHAP, you already have everything you need. Take your SHAP
+values from two periods — training vs. production, or last month vs. this month —
+and pass them in:
+
+```python
+import shiftshap
+
+report = shiftshap.compare(reference_shap, current_shap)
+
+print(report.summary())
+#  2 of 5 features show HIGH explanation drift (0 medium).
+#  Top driver changed from 'income' to 'balance'.
+#  Overall rank stability (Spearman): 0.70.
+
+print(report.details())          # plain-English narrative of the biggest movers
+report.to_frame()                # full per-feature table
+report.plot()                    # rank-drift bump chart
+shiftshap.metric_definitions()   # what every metric means, in plain words
+```
+
+Inputs can be `shap.Explanation` objects, NumPy arrays, lists, or pandas
+DataFrames of shape `(n_samples, n_features)`. **Multi-class SHAP** (3D arrays)
+is supported — by default classes are aggregated, or pass `class_index=k` to
+focus on one class. The two periods don't need the same number of samples.
+
+### Robust by design
+
+`shiftshap` is built to survive real, messy production data. It handles NaNs
+(ignored with a note), zero-variance features, tiny samples (with an explicit
+"results unreliable" warning rather than false alarms), and multi-class outputs —
+and it fails with clear, actionable errors on genuinely broken input (infinities,
+mismatched feature counts, empty arrays) instead of cryptic stack traces.
+
+## What it tells you
+
+For every feature, `shiftshap` reports:
+
+- **Importance drift** — how the mean absolute SHAP value changed between periods.
+- **PSI** (Population Stability Index) on the SHAP distribution — the industry-standard
+  shift metric, with the accepted `0.2` threshold flagging significant drift.
+- **Rank drift** — whether your most important features reordered, plus an overall
+  Spearman rank-stability score.
+- **Severity** — a `high` / `medium` / `low` label per feature, so the output is
+  actionable at a glance.
+
+And a **bump chart** showing how the feature-importance ranking shifted:
+
+![rank drift chart](examples/rank_drift.png)
+
+## Why it matters
+
+An explanation that has silently drifted is worse than no explanation — it gives
+false confidence. In regulated settings (finance, insurance, healthcare) teams are
+increasingly required to show that model explanations remain valid over time.
+`shiftshap` turns that check into two lines of code.
+
+## Roadmap
+
+`v0.1` deliberately does one thing well: compare two snapshots of SHAP explanations
+for tabular models. Planned next:
+
+- Persistent explanation store for many time-points (not just two).
+- Research-grade **faithfulness-under-shift** metrics beyond distributional PSI.
+- Alerting hooks for monitoring pipelines.
+- Support for image and text explanations.
+
+Contributions and issues welcome.
+
+## License
+
+MIT

shiftshap-0.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shiftshap"
+version = "0.2.0"
+description = "Monitor whether your model's SHAP explanations still hold as data drifts."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Mayowa Samuel Olokun" }]
+keywords = [
+    "shap",
+    "explainability",
+    "xai",
+    "drift",
+    "distribution-shift",
+    "model-monitoring",
+    "machine-learning",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "numpy>=1.21",
+    "pandas>=1.3",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.4"]
+dev = ["pytest>=7.0", "matplotlib>=3.4"]
+
+[project.urls]
+Homepage = "https://github.com/OWNER/shiftshap"
+Issues = "https://github.com/OWNER/shiftshap/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

shiftshap-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shiftshap-0.2.0/src/shiftshap/__init__.py

@@ -0,0 +1,32 @@
+"""shiftshap -- monitor whether your model's SHAP explanations still hold as data drifts.
+
+Quickstart
+----------
+>>> import shiftshap
+>>> report = shiftshap.compare(reference_shap_values, current_shap_values)
+>>> print(report.summary())      # one-line verdict
+>>> print(report.details())      # plain-English narrative of the biggest movers
+>>> report.to_frame()            # full per-feature table
+>>> report.plot()                # rank-drift bump chart (needs matplotlib)
+>>> shiftshap.metric_definitions()  # what every column means
+"""
+
+from .core import DriftReport, compare, metric_definitions
+from .metrics import (
+    METRIC_DEFINITIONS,
+    mean_abs_importance,
+    population_stability_index,
+    spearman_rank_correlation,
+)
+
+__all__ = [
+    "compare",
+    "DriftReport",
+    "metric_definitions",
+    "METRIC_DEFINITIONS",
+    "population_stability_index",
+    "mean_abs_importance",
+    "spearman_rank_correlation",
+]
+
+__version__ = "0.2.0"

shiftshap-0.2.0/src/shiftshap/core.py

@@ -0,0 +1,261 @@
+"""The main entry point: ``shiftshap.compare``.
+
+Give it SHAP explanations from two points in time (or two data batches) and it
+tells you which features' importance has drifted, by how much, how severely,
+and whether your most important features have reordered.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Optional, Sequence
+
+import numpy as np
+import pandas as pd
+
+from .metrics import (
+    METRIC_DEFINITIONS,
+    choose_bins,
+    importance_ranks,
+    mean_abs_importance,
+    population_stability_index,
+    severity_label,
+    spearman_rank_correlation,
+    to_shap_array,
+)
+
+
+def metric_definitions() -> dict:
+    """Return plain-language definitions of every metric shiftshap reports."""
+    return dict(METRIC_DEFINITIONS)
+
+
+def _resolve_feature_names(feature_names, reference_shap, current_shap, n_features):
+    if feature_names is not None:
+        names = list(feature_names)
+    else:
+        names = (
+            getattr(reference_shap, "feature_names", None)
+            or getattr(current_shap, "feature_names", None)
+        )
+    if names is None:
+        names = [f"feature_{i}" for i in range(n_features)]
+    names = [str(n) for n in names]
+    if len(names) != n_features:
+        raise ValueError(
+            f"Got {len(names)} feature names but SHAP values have "
+            f"{n_features} features."
+        )
+    return names
+
+
+class DriftReport:
+    """Result of a ``compare`` call. Print it, tabulate it, or plot it."""
+
+    def __init__(self, frame: pd.DataFrame, rank_correlation: float,
+                 psi_thresholds: tuple[float, float], notes: Optional[list] = None):
+        self._frame = frame.sort_values("psi", ascending=False).reset_index(drop=True)
+        self.rank_correlation = rank_correlation
+        self.psi_thresholds = psi_thresholds
+        self.notes = notes or []
+
+    def to_frame(self) -> pd.DataFrame:
+        """Full per-feature drift table, sorted biggest-mover first."""
+        return self._frame.copy()
+
+    @property
+    def n_features(self) -> int:
+        return len(self._frame)
+
+    @property
+    def n_high(self) -> int:
+        return int((self._frame["severity"] == "high").sum())
+
+    @property
+    def n_medium(self) -> int:
+        return int((self._frame["severity"] == "medium").sum())
+
+    def summary(self) -> str:
+        """A short, human-readable one-to-three line summary."""
+        total = self.n_features
+        lines = [
+            f"{self.n_high} of {total} feature(s) show HIGH explanation drift "
+            f"({self.n_medium} medium)."
+        ]
+        ref_top = self._frame.sort_values("reference_rank").iloc[0]
+        cur_top = self._frame.sort_values("current_rank").iloc[0]
+        if ref_top["feature"] != cur_top["feature"]:
+            lines.append(
+                f"Top driver changed from '{ref_top['feature']}' to "
+                f"'{cur_top['feature']}'."
+            )
+        else:
+            lines.append(f"Top driver unchanged ('{cur_top['feature']}').")
+        lines.append(f"Overall rank stability (Spearman): {self.rank_correlation:.2f}.")
+        return " ".join(lines)
+
+    def details(self, top_n: int = 5) -> str:
+        """A plain-English narrative of the biggest movers -- explicit for users."""
+        low, high = self.psi_thresholds
+        out = [self.summary(), ""]
+        out.append(f"PSI thresholds: medium >= {low}, high >= {high}.")
+        out.append(f"Top {min(top_n, self.n_features)} features by drift:")
+        for _, r in self._frame.head(top_n).iterrows():
+            direction = "gained" if r["importance_change"] > 0 else "lost"
+            move = ""
+            if r["rank_change"] > 0:
+                move = f", climbed {int(r['rank_change'])} rank(s)"
+            elif r["rank_change"] < 0:
+                move = f", fell {int(-r['rank_change'])} rank(s)"
+            out.append(
+                f"  - {r['feature']}: PSI={r['psi']:.3f} ({r['severity']}); "
+                f"{direction} influence "
+                f"({r['reference_importance']:.3f} -> {r['current_importance']:.3f}){move}."
+            )
+        if self.notes:
+            out.append("")
+            out.append("Notes:")
+            out.extend(f"  - {n}" for n in self.notes)
+        return "\n".join(out)
+
+    def __repr__(self) -> str:
+        return f"<DriftReport: {self.summary()}>"
+
+    def plot(self, ax=None, top_n: Optional[int] = None):
+        """Bump chart of feature-importance rank: reference vs current.
+
+        Needs matplotlib (optional). Returns the Axes.
+        """
+        try:
+            import matplotlib.pyplot as plt
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError(
+                "Plotting needs matplotlib. Install with: pip install shiftshap[plot]"
+            ) from exc
+
+        frame = self._frame.copy()
+        if top_n is not None:
+            keep = frame.nsmallest(top_n, "reference_rank")["feature"]
+            frame = frame[frame["feature"].isin(keep)]
+
+        if ax is None:
+            _, ax = plt.subplots(figsize=(6, max(3, 0.4 * len(frame) + 1)))
+
+        colours = {"high": "#d1495b", "medium": "#edae49", "low": "#9aa5b1"}
+        for _, row in frame.iterrows():
+            ax.plot(
+                [0, 1], [row["reference_rank"], row["current_rank"]],
+                marker="o", linewidth=2.2,
+                color=colours.get(row["severity"], "#9aa5b1"),
+            )
+            ax.annotate(f" {row['feature']}", (1, row["current_rank"]),
+                        va="center", fontsize=9, color="#2b2b2b")
+
+        ax.set_xticks([0, 1])
+        ax.set_xticklabels(["reference", "current"])
+        ax.set_ylabel("importance rank (1 = most important)")
+        ax.invert_yaxis()
+        ax.set_xlim(-0.15, 1.55)
+        ax.set_title("SHAP importance rank drift")
+        ax.grid(axis="y", linestyle=":", alpha=0.4)
+        return ax
+
+
+def compare(
+    reference_shap,
+    current_shap,
+    feature_names: Optional[Sequence[str]] = None,
+    bins: int = 10,
+    psi_thresholds: tuple[float, float] = (0.1, 0.2),
+    class_index: Optional[int] = None,
+) -> DriftReport:
+    """Compare two sets of SHAP explanations and report drift.
+
+    Parameters
+    ----------
+    reference_shap, current_shap
+        SHAP values for the two periods: a ``shap.Explanation``, NumPy array,
+        list, or DataFrame of shape ``(n_samples, n_features)``. 3D multi-class
+        SHAP is supported (see ``class_index``). Sample counts may differ; the
+        feature count must match.
+    feature_names
+        Optional; else taken from a ``shap.Explanation`` or defaulted.
+    bins
+        Requested number of quantile bins for PSI (auto-reduced for small data).
+    psi_thresholds
+        ``(medium, high)`` PSI cut-offs for severity.
+    class_index
+        For multi-class SHAP: pick a single class. Default aggregates classes.
+
+    Returns
+    -------
+    DriftReport
+    """
+    if not (isinstance(psi_thresholds, (tuple, list)) and len(psi_thresholds) == 2
+            and psi_thresholds[0] <= psi_thresholds[1]):
+        raise ValueError("psi_thresholds must be (medium, high) with medium <= high.")
+
+    ref = to_shap_array(reference_shap, class_index=class_index)
+    cur = to_shap_array(current_shap, class_index=class_index)
+
+    if ref.shape[1] != cur.shape[1]:
+        raise ValueError(
+            f"Feature count mismatch: reference has {ref.shape[1]} features, "
+            f"current has {cur.shape[1]}."
+        )
+
+    n_features = ref.shape[1]
+    names = _resolve_feature_names(feature_names, reference_shap, current_shap, n_features)
+
+    notes = []
+    if np.isnan(ref).any() or np.isnan(cur).any():
+        n_bad = int(np.isnan(ref).any(axis=1).sum() + np.isnan(cur).any(axis=1).sum())
+        notes.append(
+            f"{n_bad} sample(s) contained NaN SHAP values and were ignored "
+            f"per-feature where needed."
+        )
+        warnings.warn(notes[-1], stacklevel=2)
+
+    eff_bins = choose_bins(ref.shape[0], bins)
+    if eff_bins < bins:
+        notes.append(
+            f"Reference has {ref.shape[0]} samples; PSI bins reduced from "
+            f"{bins} to {eff_bins} to stay meaningful."
+        )
+
+    min_n = min(ref.shape[0], cur.shape[0])
+    if min_n < 30:
+        msg = (
+            f"Only {min_n} sample(s) in the smaller period. PSI/drift results "
+            f"are unreliable below ~30 samples and may show false alarms -- "
+            f"treat severities with caution."
+        )
+        notes.append(msg)
+        warnings.warn(msg, stacklevel=2)
+
+    ref_imp = mean_abs_importance(ref)
+    cur_imp = mean_abs_importance(cur)
+    ref_rank = importance_ranks(ref_imp)
+    cur_rank = importance_ranks(cur_imp)
+
+    psi = np.array([
+        population_stability_index(ref[:, j], cur[:, j], bins=bins)
+        for j in range(n_features)
+    ])
+    severity = [severity_label(p, psi_thresholds) for p in psi]
+
+    frame = pd.DataFrame({
+        "feature": names,
+        "reference_importance": ref_imp,
+        "current_importance": cur_imp,
+        "importance_change": cur_imp - ref_imp,
+        "psi": psi,
+        "reference_rank": ref_rank,
+        "current_rank": cur_rank,
+        "rank_change": ref_rank - cur_rank,
+        "severity": severity,
+    })
+
+    rank_corr = spearman_rank_correlation(ref_rank, cur_rank)
+    return DriftReport(frame, rank_correlation=rank_corr,
+                       psi_thresholds=tuple(psi_thresholds), notes=notes)

shiftshap-0.2.0/src/shiftshap/metrics.py

@@ -0,0 +1,201 @@
+"""Core drift metrics for SHAP explanations.
+
+Dependency-light (NumPy only). Every function does one small, well-defined,
+testable job. All metrics are documented in ``METRIC_DEFINITIONS`` so the
+output is never a mystery number to the user.
+"""
+
+from __future__ import annotations
+
+import warnings
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# Plain-language definitions of every metric shiftshap reports.
+# Exposed to users via shiftshap.metric_definitions().
+# ---------------------------------------------------------------------------
+METRIC_DEFINITIONS = {
+    "reference_importance": (
+        "Global importance of the feature in the REFERENCE period: the mean "
+        "absolute SHAP value across all reference samples. Higher = the feature "
+        "influenced predictions more."
+    ),
+    "current_importance": (
+        "Global importance of the feature in the CURRENT period (mean absolute "
+        "SHAP value across all current samples)."
+    ),
+    "importance_change": (
+        "current_importance minus reference_importance. Negative = the feature "
+        "lost influence; positive = it gained influence."
+    ),
+    "psi": (
+        "Population Stability Index of the feature's SHAP-value distribution "
+        "between the two periods. 0 = no shift. Rule of thumb: <0.1 no "
+        "significant shift, 0.1-0.2 moderate, >=0.2 significant."
+    ),
+    "reference_rank": "Importance rank in the reference period (1 = most important).",
+    "current_rank": "Importance rank in the current period (1 = most important).",
+    "rank_change": (
+        "reference_rank minus current_rank. Positive = the feature climbed in "
+        "importance; negative = it fell."
+    ),
+    "severity": (
+        "Overall drift severity for the feature (low / medium / high), based on "
+        "its PSI against the configured thresholds."
+    ),
+    "rank_correlation": (
+        "Spearman correlation of the whole feature-importance ranking between "
+        "periods. 1.0 = identical ordering, 0 = unrelated, -1.0 = reversed."
+    ),
+}
+
+
+def to_shap_array(x, class_index: int | None = None) -> np.ndarray:
+    """Normalise a SHAP input into a 2D array ``(n_samples, n_features)``.
+
+    Accepts:
+      * a ``shap.Explanation`` (uses its ``.values``),
+      * a NumPy array / list / pandas DataFrame of SHAP values,
+      * 1D (single feature), 2D, or 3D multi-class SHAP.
+
+    Multi-class handling (3D input, shape ``(n_samples, n_features, n_classes)``):
+      * ``class_index=None`` (default): aggregate across classes using the mean
+        absolute value per (sample, feature) -> a non-negative contribution
+        magnitude whose distribution can be tracked.
+      * ``class_index=k``: analyse only class ``k``.
+    """
+    values = getattr(x, "values", x)  # duck-type shap.Explanation
+
+    # pandas DataFrame / Series -> ndarray
+    if hasattr(values, "to_numpy"):
+        values = values.to_numpy()
+
+    arr = np.asarray(values, dtype=float)
+
+    if arr.size == 0:
+        raise ValueError("SHAP input is empty (0 elements).")
+
+    if arr.ndim == 1:
+        arr = arr.reshape(-1, 1)
+    elif arr.ndim == 3:
+        n_classes = arr.shape[2]
+        if class_index is not None:
+            if not 0 <= class_index < n_classes:
+                raise ValueError(
+                    f"class_index={class_index} out of range for "
+                    f"{n_classes} classes."
+                )
+            arr = arr[:, :, class_index]
+        else:
+            # Aggregate across classes -> per (sample, feature) magnitude.
+            arr = np.mean(np.abs(arr), axis=2)
+    elif arr.ndim != 2:
+        raise ValueError(
+            f"Expected SHAP values with 1, 2 or 3 dimensions, got {arr.ndim}D "
+            f"array of shape {arr.shape}."
+        )
+
+    if np.isinf(arr).any():
+        raise ValueError(
+            "SHAP input contains infinite values. Please clean these before "
+            "comparing (inf usually signals an upstream bug)."
+        )
+    return arr
+
+
+def drop_nan_pair(ref: np.ndarray, cur: np.ndarray) -> tuple[np.ndarray, np.ndarray, int]:
+    """Return ref/cur 1D vectors with NaNs removed, plus the count dropped."""
+    ref = ref[~np.isnan(ref)]
+    cur = cur[~np.isnan(cur)]
+    return ref, cur, 0  # counts handled by caller for messaging
+
+
+def mean_abs_importance(shap_arr: np.ndarray) -> np.ndarray:
+    """Global feature importance = mean absolute SHAP value per feature.
+
+    NaN-safe: NaN entries are ignored (nanmean). A feature that is entirely NaN
+    returns 0.0 importance.
+    """
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", category=RuntimeWarning)
+        imp = np.nanmean(np.abs(shap_arr), axis=0)
+    return np.nan_to_num(imp, nan=0.0)
+
+
+def importance_ranks(importance: np.ndarray) -> np.ndarray:
+    """1-based ranks (1 = most important) for an importance vector."""
+    order = np.argsort(-importance, kind="stable")
+    ranks = np.empty(len(order), dtype=int)
+    ranks[order] = np.arange(1, len(order) + 1)
+    return ranks
+
+
+def choose_bins(n_ref: int, requested_bins: int) -> int:
+    """Pick a safe bin count so PSI stays meaningful for small samples.
+
+    We want at least ~5 reference samples per bin. Never fewer than 2 bins.
+    """
+    safe = max(2, min(requested_bins, n_ref // 5)) if n_ref >= 10 else 2
+    return safe
+
+
+def population_stability_index(
+    reference: np.ndarray,
+    current: np.ndarray,
+    bins: int = 10,
+    epsilon: float = 1e-6,
+) -> float:
+    """Population Stability Index between two 1D distributions (NaN-safe).
+
+    Bin edges come from quantiles of the reference. Returns 0.0 for a
+    degenerate reference (no variation) or when there is too little data.
+    """
+    reference = np.asarray(reference, dtype=float)
+    current = np.asarray(current, dtype=float)
+    reference = reference[~np.isnan(reference)]
+    current = current[~np.isnan(current)]
+
+    if len(reference) < 2 or len(current) < 1:
+        return 0.0
+
+    bins = choose_bins(len(reference), bins)
+
+    quantiles = np.linspace(0.0, 1.0, bins + 1)
+    edges = np.quantile(reference, quantiles)
+    edges = np.unique(edges)
+    if len(edges) < 3:
+        return 0.0  # near-constant reference -> no meaningful PSI
+    edges[0], edges[-1] = -np.inf, np.inf
+
+    ref_counts, _ = np.histogram(reference, bins=edges)
+    cur_counts, _ = np.histogram(current, bins=edges)
+
+    ref_prop = np.clip(ref_counts / max(ref_counts.sum(), 1), epsilon, None)
+    cur_prop = np.clip(cur_counts / max(cur_counts.sum(), 1), epsilon, None)
+
+    return float(np.sum((cur_prop - ref_prop) * np.log(cur_prop / ref_prop)))
+
+
+def spearman_rank_correlation(rank_a: np.ndarray, rank_b: np.ndarray) -> float:
+    """Spearman correlation between two rank vectors (distinct ranks).
+
+    1.0 = identical ordering, -1.0 = reversed. Returns 1.0 for <2 features.
+    """
+    rank_a = np.asarray(rank_a, dtype=float)
+    rank_b = np.asarray(rank_b, dtype=float)
+    n = len(rank_a)
+    if n < 2:
+        return 1.0
+    d_squared = np.sum((rank_a - rank_b) ** 2)
+    return float(1.0 - (6.0 * d_squared) / (n * (n**2 - 1)))
+
+
+def severity_label(psi: float, thresholds: tuple[float, float] = (0.1, 0.2)) -> str:
+    """Map a PSI value to low / medium / high using (medium, high) cut-offs."""
+    low, high = thresholds
+    if psi >= high:
+        return "high"
+    if psi >= low:
+        return "medium"
+    return "low"

shiftshap-0.2.0/src/shiftshap.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: shiftshap
+Version: 0.2.0
+Summary: Monitor whether your model's SHAP explanations still hold as data drifts.
+Author: Mayowa Samuel Olokun
+License: MIT
+Project-URL: Homepage, https://github.com/OWNER/shiftshap
+Project-URL: Issues, https://github.com/OWNER/shiftshap/issues
+Keywords: shap,explainability,xai,drift,distribution-shift,model-monitoring,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.4; extra == "plot"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: matplotlib>=3.4; extra == "dev"
+Dynamic: license-file
+
+# shiftshap
+
+**Monitor whether your model's SHAP explanations still hold as your data drifts.**
+
+`shiftshap` answers a question every team running a model in production eventually
+asks: *are my model's explanations still trustworthy?* Models live for months or
+years — they get retrained, upstream pipelines change, and feature distributions
+shift. When that happens, the model's reasoning quietly changes with it. The
+feature that drove your predictions last quarter may not be the one driving them
+today.
+
+SHAP is excellent at explaining a model **at a single point in time**, but it has
+no built-in way to tell you how those explanations have **changed** between two
+points. Today people work around this by pickling explanation objects and writing
+their own comparison scripts, or by using data-drift tools that know nothing about
+SHAP's structure. `shiftshap` fills that gap.
+
+---
+
+## Install
+
+```bash
+pip install shiftshap            # core
+pip install shiftshap[plot]      # + matplotlib for the drift chart
+```
+
+## Quickstart
+
+If you already use SHAP, you already have everything you need. Take your SHAP
+values from two periods — training vs. production, or last month vs. this month —
+and pass them in:
+
+```python
+import shiftshap
+
+report = shiftshap.compare(reference_shap, current_shap)
+
+print(report.summary())
+#  2 of 5 features show HIGH explanation drift (0 medium).
+#  Top driver changed from 'income' to 'balance'.
+#  Overall rank stability (Spearman): 0.70.
+
+print(report.details())          # plain-English narrative of the biggest movers
+report.to_frame()                # full per-feature table
+report.plot()                    # rank-drift bump chart
+shiftshap.metric_definitions()   # what every metric means, in plain words
+```
+
+Inputs can be `shap.Explanation` objects, NumPy arrays, lists, or pandas
+DataFrames of shape `(n_samples, n_features)`. **Multi-class SHAP** (3D arrays)
+is supported — by default classes are aggregated, or pass `class_index=k` to
+focus on one class. The two periods don't need the same number of samples.
+
+### Robust by design
+
+`shiftshap` is built to survive real, messy production data. It handles NaNs
+(ignored with a note), zero-variance features, tiny samples (with an explicit
+"results unreliable" warning rather than false alarms), and multi-class outputs —
+and it fails with clear, actionable errors on genuinely broken input (infinities,
+mismatched feature counts, empty arrays) instead of cryptic stack traces.
+
+## What it tells you
+
+For every feature, `shiftshap` reports:
+
+- **Importance drift** — how the mean absolute SHAP value changed between periods.
+- **PSI** (Population Stability Index) on the SHAP distribution — the industry-standard
+  shift metric, with the accepted `0.2` threshold flagging significant drift.
+- **Rank drift** — whether your most important features reordered, plus an overall
+  Spearman rank-stability score.
+- **Severity** — a `high` / `medium` / `low` label per feature, so the output is
+  actionable at a glance.
+
+And a **bump chart** showing how the feature-importance ranking shifted:
+
+![rank drift chart](examples/rank_drift.png)
+
+## Why it matters
+
+An explanation that has silently drifted is worse than no explanation — it gives
+false confidence. In regulated settings (finance, insurance, healthcare) teams are
+increasingly required to show that model explanations remain valid over time.
+`shiftshap` turns that check into two lines of code.
+
+## Roadmap
+
+`v0.1` deliberately does one thing well: compare two snapshots of SHAP explanations
+for tabular models. Planned next:
+
+- Persistent explanation store for many time-points (not just two).
+- Research-grade **faithfulness-under-shift** metrics beyond distributional PSI.
+- Alerting hooks for monitoring pipelines.
+- Support for image and text explanations.
+
+Contributions and issues welcome.
+
+## License
+
+MIT

shiftshap-0.2.0/src/shiftshap.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/shiftshap/__init__.py
+src/shiftshap/core.py
+src/shiftshap/metrics.py
+src/shiftshap.egg-info/PKG-INFO
+src/shiftshap.egg-info/SOURCES.txt
+src/shiftshap.egg-info/dependency_links.txt
+src/shiftshap.egg-info/requires.txt
+src/shiftshap.egg-info/top_level.txt
+tests/test_core.py

shiftshap-0.2.0/src/shiftshap.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

shiftshap-0.2.0/src/shiftshap.egg-info/requires.txt

@@ -0,0 +1,9 @@
+numpy>=1.21
+pandas>=1.3
+
+[dev]
+pytest>=7.0
+matplotlib>=3.4
+
+[plot]
+matplotlib>=3.4

shiftshap-0.2.0/src/shiftshap.egg-info/top_level.txt

@@ -0,0 +1 @@
+shiftshap

shiftshap-0.2.0/tests/test_core.py

@@ -0,0 +1,168 @@
+"""Tests for shiftshap. Run with: pytest"""
+
+import numpy as np
+import pytest
+
+import shiftshap
+from shiftshap.metrics import (
+    importance_ranks,
+    mean_abs_importance,
+    population_stability_index,
+    severity_label,
+    spearman_rank_correlation,
+)
+
+
+def test_psi_zero_for_identical_distributions():
+    rng = np.random.default_rng(0)
+    x = rng.normal(size=5000)
+    assert population_stability_index(x, x) == pytest.approx(0.0, abs=1e-9)
+
+
+def test_psi_positive_for_shifted_distribution():
+    rng = np.random.default_rng(1)
+    ref = rng.normal(0, 1, size=5000)
+    cur = rng.normal(3, 1, size=5000)  # clearly shifted
+    assert population_stability_index(ref, cur) > 0.2
+
+
+def test_importance_and_ranks():
+    # feature 1 has the largest magnitude -> rank 1
+    arr = np.array([[0.1, -2.0, 0.5], [0.2, 2.0, -0.5]])
+    imp = mean_abs_importance(arr)
+    assert np.argmax(imp) == 1
+    ranks = importance_ranks(imp)
+    assert ranks[1] == 1
+
+
+def test_spearman_bounds():
+    a = np.array([1, 2, 3, 4])
+    assert spearman_rank_correlation(a, a) == pytest.approx(1.0)
+    assert spearman_rank_correlation(a, a[::-1]) == pytest.approx(-1.0)
+
+
+def test_severity_thresholds():
+    assert severity_label(0.05) == "low"
+    assert severity_label(0.15) == "medium"
+    assert severity_label(0.30) == "high"
+
+
+def test_compare_end_to_end_detects_drift():
+    rng = np.random.default_rng(42)
+    n = 2000
+    # Reference: feature 0 dominates. Current: feature 2 takes over.
+    ref = np.column_stack([
+        rng.normal(0, 2.0, n),   # big
+        rng.normal(0, 0.5, n),
+        rng.normal(0, 0.2, n),   # small
+    ])
+    cur = np.column_stack([
+        rng.normal(0, 0.2, n),   # now small
+        rng.normal(0, 0.5, n),
+        rng.normal(0, 2.0, n),   # now big
+    ])
+    report = shiftshap.compare(ref, cur, feature_names=["a", "b", "c"])
+    frame = report.to_frame()
+
+    # The top driver should have flipped from 'a' to 'c'.
+    top_ref = frame.sort_values("reference_rank").iloc[0]["feature"]
+    top_cur = frame.sort_values("current_rank").iloc[0]["feature"]
+    assert top_ref == "a"
+    assert top_cur == "c"
+    # Rank ordering reversed -> strongly negative Spearman.
+    assert report.rank_correlation < 0
+    assert report.n_high >= 1
+
+
+def test_feature_count_mismatch_raises():
+    with pytest.raises(ValueError):
+        shiftshap.compare(np.zeros((10, 3)), np.zeros((10, 4)))
+
+
+def test_accepts_explanation_like_object():
+    class FakeExplanation:
+        def __init__(self, values, feature_names):
+            self.values = values
+            self.feature_names = feature_names
+
+    rng = np.random.default_rng(7)
+    ref = FakeExplanation(rng.normal(size=(100, 2)), ["x", "y"])
+    cur = FakeExplanation(rng.normal(size=(100, 2)), ["x", "y"])
+    report = shiftshap.compare(ref, cur)
+    assert list(report.to_frame()["feature"]) == ["x", "y"] or set(
+        report.to_frame()["feature"]
+    ) == {"x", "y"}
+
+
+# ---------------------------------------------------------------------------
+# v0.2 hardening tests: multi-class, messy inputs, clear errors, clarity
+# ---------------------------------------------------------------------------
+
+def test_multiclass_3d_aggregates():
+    rng = np.random.default_rng(0)
+    ref = rng.normal(size=(200, 4, 3))
+    cur = rng.normal(size=(200, 4, 3))
+    report = shiftshap.compare(ref, cur)
+    assert report.n_features == 4  # collapsed across classes
+
+
+def test_multiclass_class_index_selects_one_class():
+    rng = np.random.default_rng(0)
+    ref = rng.normal(size=(200, 4, 3))
+    cur = rng.normal(size=(200, 4, 3))
+    report = shiftshap.compare(ref, cur, class_index=1)
+    assert report.n_features == 4
+
+
+def test_bad_class_index_raises():
+    rng = np.random.default_rng(0)
+    with pytest.raises(ValueError):
+        shiftshap.compare(rng.normal(size=(50, 4, 3)), rng.normal(size=(50, 4, 3)), class_index=9)
+
+
+def test_inf_input_raises_clearly():
+    x = np.zeros((10, 3)); x[0, 0] = np.inf
+    with pytest.raises(ValueError, match="infinite"):
+        shiftshap.compare(x, np.zeros((10, 3)))
+
+
+def test_empty_input_raises():
+    with pytest.raises(ValueError, match="empty"):
+        shiftshap.compare(np.array([]), np.array([]))
+
+
+def test_nan_is_handled_with_note():
+    rng = np.random.default_rng(0)
+    ref = rng.normal(size=(200, 3)); ref[::10, 1] = np.nan
+    with pytest.warns(UserWarning):
+        report = shiftshap.compare(ref, rng.normal(size=(200, 3)))
+    assert any("NaN" in n for n in report.notes)
+
+
+def test_small_sample_warns():
+    rng = np.random.default_rng(0)
+    with pytest.warns(UserWarning, match="unreliable"):
+        report = shiftshap.compare(rng.normal(size=(5, 3)), rng.normal(size=(5, 3)))
+    assert any("unreliable" in n for n in report.notes)
+
+
+def test_dataframe_input_accepted():
+    import pandas as pd
+    rng = np.random.default_rng(0)
+    ref = pd.DataFrame(rng.normal(size=(100, 3)), columns=["a", "b", "c"])
+    cur = pd.DataFrame(rng.normal(size=(100, 3)), columns=["a", "b", "c"])
+    report = shiftshap.compare(ref, cur)
+    assert report.n_features == 3
+
+
+def test_bad_thresholds_raise():
+    with pytest.raises(ValueError):
+        shiftshap.compare(np.zeros((50, 2)), np.zeros((50, 2)), psi_thresholds=(0.3, 0.1))
+
+
+def test_details_and_definitions_are_strings():
+    rng = np.random.default_rng(0)
+    report = shiftshap.compare(rng.normal(size=(100, 3)), rng.normal(size=(100, 3)))
+    assert isinstance(report.details(), str)
+    defs = shiftshap.metric_definitions()
+    assert "psi" in defs and isinstance(defs["psi"], str)