Metadata-Version: 2.4
Name: panelxai
Version: 0.1.0
Summary: Explainable AI for panel time-series econometrics: structured (variable x lag x unit x time) SHAP, factor / cross-sectional-dependence-aware attribution, regime-aware explanation drift, constrained counterfactuals, bootstrap uncertainty, and hybrid econometric-core + ML-residual models.
Author-email: Dr Merwan Roudane <merwanroudane920@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/merwanroudane/panelxai
Project-URL: Repository, https://github.com/merwanroudane/panelxai
Project-URL: Issues, https://github.com/merwanroudane/panelxai/issues
Keywords: explainable ai,xai,shap,panel data,time series,dynamic panel,econometrics,cross-sectional dependence,common factors,fixed effects,counterfactual,regime,interpretable machine learning,hybrid models
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.9
Requires-Dist: scikit-learn>=1.1
Requires-Dist: statsmodels>=0.13
Requires-Dist: matplotlib>=3.5
Requires-Dist: shap>=0.41
Requires-Dist: xgboost>=1.6
Requires-Dist: linearmodels>=4.27
Requires-Dist: tabulate>=0.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# panelxai

**Explainable AI for panel time-series econometrics.**

Most XAI work either explains *time series* (TimeSHAP, WindowSHAP, TFT) **or**
applies SHAP to *panel-shaped* data — but rarely respects the econometric
structure of a **dynamic panel**: distributed lags, cross-sectional dependence,
common factors, unit heterogeneity, regime change, fixed effects.

`panelxai` closes that gap. A raw SHAP value is indexed only by
*(observation, feature)*. Because the design builder encodes
**variable**, **lag**, and **kind** (own regressor vs cross-sectional-average
factor proxy) into every feature name, `panelxai` re-indexes attributions onto
the structure that matters:

```
variable  ×  lag  ×  unit  ×  time     +     own-vs-factor (CSD) decomposition
```

Author: **Dr Merwan Roudane** · MIT License · `pip install -e .`

---

## What it provides

| Capability | Function / class | Idea |
|---|---|---|
| Panel TS simulator | `simulate_panel_ts` | DGP with true lag drivers, common factors (CSD), regime switch, non-linearity |
| Lag + CCE design | `build_design` | within-FE design with own lags and cross-sectional averages |
| Models | `GBPanel`, `HybridPanel` | XGBoost on the design; or **linear econometric core + ML residual** |
| Structured SHAP | `StructuredExplainer` | importance by variable, by lag, variable×lag matrix, per-unit |
| Factor-aware XAI | `.own_vs_factor()` | share of explanation from own dynamics vs common factors / CSD |
| Regime-aware XAI | `regime_importance`, `regime_effect_sign`, `explanation_drift` | importance & **effect-sign flips** across regimes; rolling drift |
| Counterfactual XAI | `counterfactual` | minimal, box-constrained change to move a prediction |
| Uncertainty-aware XAI | `bootstrap_importance` | unit cluster-bootstrap CIs + stability flag for importances |
| Plots / tables / report | `plot_*`, `tables`, `Report` | publication-ready outputs |

## Quick start

```python
import panelxai as px

df = px.simulate_panel_ts(n_units=30, n_periods=40, n_features=4,
                          n_lags=2, n_factors=1, seed=7)

model = px.GBPanel(lags=2, csa=True).fit(df)      # explains the full model
ex = px.StructuredExplainer(model)

ex.variable_importance()      # which variable matters
ex.lag_importance()           # at which lag (temporal profile)
ex.variable_lag_matrix("own") # variable × lag heatmap data
ex.own_vs_factor()            # own dynamics vs common-factor / CSD share
ex.unit_importance()          # cross-sectional heterogeneity of explanations

px.plot_variable_lag_heatmap(ex, save="varlag.png")
```

On the built-in DGP (x1 drives `y` at lag 0, x2 at lag 1, x3 at lag 2) the
structured SHAP **recovers exactly that** — each variable's mass concentrates at
its true lag.

## Hybrid econometric core + ML

```python
m = px.HybridPanel(lags=2).fit(df)   # y = linear dynamic-panel core + ML residual
print(px.Report(m).text())           # SHAP here explains only the NON-LINEAR part
```

## Regime-aware (sign-flip detection)

```python
df = px.simulate_panel_ts(regime_break=0.5, seed=11)   # x1 effect flips at midpoint
ex = px.StructuredExplainer(px.GBPanel(lags=2).fit(df))
px.regime_effect_sign(ex, n_regimes=2)   # x1: +corr -> -corr  => sign_flip = True
```

## Uncertainty

```python
boot = px.bootstrap_importance(lambda: px.GBPanel(lags=2),
                               df, n_boot=30, level=0.90)
boot   # mean, lo, hi, stable (CI excludes zero)
```

## Examples

Runnable scripts in [`examples/`](examples):

1. `01_structured_shap.py` — variable × lag × own/factor decomposition
2. `02_regime_drift.py` — regime sign-flip & explanation drift
3. `03_hybrid_counterfactual.py` — hybrid model + constrained counterfactual
4. `04_uncertainty.py` — bootstrap importance CIs

## Design notes

- **Fixed effects** are absorbed by the `fe="within"` transform, so SHAP
  explains *within-unit* deviations (the dynamic signal), not level differences.
- **Cross-sectional dependence** is handled CCE-style: period-`t`
  cross-sectional averages enter the design as proxies for unobserved common
  factors; their SHAP share is reported separately from own dynamics.
- **The hybrid model** keeps a transparent linear econometric core and lets the
  ML learner — and SHAP — speak only to the residual non-linearity, the honest
  target of post-hoc XAI in an econometric setting.

## Status & scope

v0.1.0 implements the structured / temporal, factor-aware, regime-aware,
counterfactual, uncertainty, and hybrid families on a tree-ensemble backbone.
Planned extensions: causal/interventional SHAP, deep-sequence models
(LSTM/TFT) with Integrated Gradients, and graph XAI for network panels.

## Requirements

Python ≥ 3.9; numpy, pandas, scipy, scikit-learn, statsmodels, matplotlib,
shap, xgboost, linearmodels, tabulate.
