Getting started

The fastest ways to go from zero to a stability heatmap. Pick whichever suits you.

1. Try it in your browser (no install)

Open the live demo and explore two built-in examples: regime-shap demo on Hugging Face Spaces. Pick a dataset, run the analysis, and step through the regime-by-regime stability heatmap without installing anything.

2. Install and run on your own data

pip install "regime-shap[examples]"

The [examples] extra adds Jupyter and XGBoost so you can run the notebooks. Keep the double quotes; some shells treat [examples] as a pattern otherwise. The same command works on macOS, Linux, and Windows (PowerShell or Command Prompt).

The whole analysis runs from one object: give it a fitted tree model, the feature matrix, and a set of regimes (one label per row, or date ranges).

from xgboost import XGBRegressor
from regime_shap import RegimeSHAPAnalyzer

model = XGBRegressor().fit(X, y)         # your fitted tree model
regimes = df["your_period_column"]        # one label per row (a season, era, or period)

analyzer = RegimeSHAPAnalyzer(model, X, regimes)
analyzer.stability_classified()           # each regime pair, with its stability band
analyzer.plot_stability()                 # the banded heatmap
analyzer.to_html(title="My analysis")     # a self-contained HTML report

See the Quickstart for the full API, and Concepts for what the numbers mean.

3. No data of your own? Use the practice pack

Download practice-datasets.zip from the latest release. It contains ten ready-to-use public datasets, a README with a copy-paste settings block for each, and a fill-in-the-blanks notebook, try_your_own_data.ipynb.

Open the notebook and run it: it works on a bundled dataset out of the box, so you see a full result straight away. Then edit the one config cell to point at another dataset, or at your own CSV.

Tell us how it went

Feedback of any kind is welcome, including what confused you. Post in GitHub Discussions.

One caveat worth knowing up front: regime-shap measures how stable a model’s explanations are, not whether the model itself is any good. It will report “stable” even for a weak or leaky model, so read the stability result alongside your model’s own performance.