Metadata-Version: 2.4
Name: regime-shap
Version: 0.1.0
Summary: Quantify SHAP feature importance stability across structural breaks in time-series data
Author: Faith Olan-George
License: MIT License
        
        Copyright (c) 2026 Faith Olan-George
        
        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.
Project-URL: Homepage, https://github.com/faithcodes-lab/regime-shap
Project-URL: Documentation, https://faithcodes-lab.github.io/regime-shap/
Project-URL: Repository, https://github.com/faithcodes-lab/regime-shap.git
Project-URL: Issues, https://github.com/faithcodes-lab/regime-shap/issues
Project-URL: Changelog, https://github.com/faithcodes-lab/regime-shap/blob/main/CHANGELOG.md
Keywords: SHAP,explainable AI,feature importance,time series,structural breaks
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.11
Requires-Dist: shap>=0.44
Requires-Dist: matplotlib>=3.7
Requires-Dist: seaborn>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: black>=23.10; extra == "dev"
Requires-Dist: mypy>=1.6; extra == "dev"
Requires-Dist: scikit-learn>=1.3; extra == "dev"
Provides-Extra: detection
Requires-Dist: ruptures>=1.1; extra == "detection"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Provides-Extra: examples
Requires-Dist: jupyter>=1.0; extra == "examples"
Requires-Dist: nbconvert>=7.0; extra == "examples"
Requires-Dist: ipywidgets>=8.0; extra == "examples"
Requires-Dist: xgboost>=2.0; extra == "examples"
Requires-Dist: lightgbm>=4.0; extra == "examples"
Requires-Dist: ruptures>=1.1; extra == "examples"
Dynamic: license-file

# regime-shap

> Quantify SHAP feature importance stability across structural breaks in time-series data.

[![CI](https://github.com/faithcodes-lab/regime-shap/actions/workflows/ci.yml/badge.svg)](https://github.com/faithcodes-lab/regime-shap/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/regime-shap.svg)](https://pypi.org/project/regime-shap/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://faithcodes-lab.github.io/regime-shap/)

**Install with `pip install regime-shap`. The package follows Semantic Versioning; during the 0.x series the public API may still change.**

Documentation: <https://faithcodes-lab.github.io/regime-shap/>

`regime-shap` extends SHAP feature importance analysis to time-series with structural breaks. Given a pre-trained tree model, a feature matrix, and a set of regimes, it quantifies how the model's feature importance rankings change across regimes, surfacing instability that may matter for trustworthy interpretation.

## Development status

Built so far:
- `breaks`: turn regime specifications into per-row regime labels (plus optional break detection).
- `compare`: per-regime SHAP feature importance and rankings, with small-sample flagging.
- `stability`: pairwise Spearman stability matrix, Akoglu (2018) bands, and bootstrap confidence intervals.
- `plots`: global and per-regime importance figures, and the banded stability heatmap.
- `report`: self-contained HTML report plus dict and CSV export.
- `RegimeSHAPAnalyzer`: a single high-level entry point that ties the modules together.

## Usage

```python
from regime_shap import RegimeSHAPAnalyzer

# model is a fitted tree model, X is the feature matrix, regimes is one label per row
analyzer = RegimeSHAPAnalyzer(model, X, regimes)

analyzer.stability_matrix()      # regime-by-regime Spearman correlation of importance rankings
analyzer.stability_classified()  # each regime pair with its Akoglu (2018) stability band
analyzer.plot_stability()        # the banded stability heatmap
analyzer.to_html(title="...")    # a self-contained report of every result table
```

The building-block functions in `regime_shap.breaks`, `regime_shap.compare`, and `regime_shap.stability` are also available directly if you want finer control.

## Supported models

`regime-shap` currently supports tree-based models (for example XGBoost, LightGBM, and scikit-learn tree ensembles) through SHAP's `TreeExplainer`. This is a deliberate choice: `TreeExplainer` computes exact SHAP values quickly, which is what makes the bootstrap confidence intervals feasible, since they recompute SHAP up to a thousand times per regime.

The stability methodology itself is model-agnostic. The comparison, stability, plotting, and report steps operate on SHAP values alone and never inspect the model, so only the SHAP computation is tree-specific.

Support for other model types through pluggable explainers (for example `KernelExplainer` for arbitrary models, or `LinearExplainer` for linear ones) is a possible future extension, tracked in [issue #8](https://github.com/faithcodes-lab/regime-shap/issues/8). The honest caveat is that the bootstrap confidence intervals become expensive and approximate for non-tree models, because general explainers are slower and introduce sampling variance.

## Installation

```bash
pip install regime-shap
```

For development, install from source:

```bash
git clone https://github.com/faithcodes-lab/regime-shap.git
cd regime-shap
pip install -e ".[dev]"
```

## Origin

This package generalises a SHAP stability methodology, first developed for analysing UK economic regimes (the Global Financial Crisis, Brexit, and COVID-19), into a standalone, domain-agnostic tool. Its examples span finance and energy as well as macroeconomics.

If you use `regime-shap` in research, please cite:

```bibtex
@software{olan_george_regime_shap,
  author = {Olan-George, Faith},
  title = {regime-shap: Quantifying SHAP Feature Importance Stability Across Structural Breaks},
  year = {2026},
  url = {https://github.com/faithcodes-lab/regime-shap},
}
```

## Licence

MIT, see `LICENSE` for details.
