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

Quick start

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

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)

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

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/:

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.