panelxai 0.1.0

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.

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

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.