panelxai 0.1.0__tar.gz

panelxai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dr Merwan Roudane
+
+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.

panelxai-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+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.

panelxai-0.1.0/README.md

@@ -0,0 +1,115 @@
+# 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.

panelxai-0.1.0/panelxai/__init__.py

@@ -0,0 +1,50 @@
+"""panelxai - 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
+models.
+
+Author : Dr Merwan Roudane <merwanroudane920@gmail.com>
+GitHub : https://github.com/merwanroudane/panelxai
+"""
+from .data import (
+    simulate_panel_ts, build_design, build_lags,
+    add_cross_sectional_averages, panel_describe,
+    make_feature_name, parse_feature_name, DesignSpec,
+)
+from .models import PanelModel, GBPanel, HybridPanel
+from .explain import (
+    StructuredExplainer, regime_importance, regime_effect_sign,
+    explanation_drift, counterfactual, bootstrap_importance,
+)
+from .plots import (
+    plot_variable_lag_heatmap, plot_lag_profile, plot_own_vs_factor,
+    plot_unit_heterogeneity, plot_regime_drift, plot_importance_ci,
+    plot_counterfactual,
+)
+from . import tables
+from .reports import Report
+
+__author__  = "Dr Merwan Roudane"
+__email__   = "merwanroudane920@gmail.com"
+__url__     = "https://github.com/merwanroudane/panelxai"
+__version__ = "0.1.0"
+
+__all__ = [
+    # data
+    "simulate_panel_ts", "build_design", "build_lags",
+    "add_cross_sectional_averages", "panel_describe",
+    "make_feature_name", "parse_feature_name", "DesignSpec",
+    # models
+    "PanelModel", "GBPanel", "HybridPanel",
+    # explain
+    "StructuredExplainer", "regime_importance", "regime_effect_sign",
+    "explanation_drift", "counterfactual", "bootstrap_importance",
+    # plots
+    "plot_variable_lag_heatmap", "plot_lag_profile", "plot_own_vs_factor",
+    "plot_unit_heterogeneity", "plot_regime_drift", "plot_importance_ci",
+    "plot_counterfactual",
+    # misc
+    "tables", "Report",
+]

panelxai-0.1.0/panelxai/data.py

@@ -0,0 +1,262 @@
+"""Panel time-series data: simulation and the lag / cross-sectional-average
+design builder.
+
+The design builder is the backbone of the whole library: it engineers a
+numeric feature matrix whose *column names* encode the structure
+
+    {variable}__L{lag}__{kind}        kind in {own, csa}
+
+so that downstream explainers can recover, for every attribution, which
+*variable*, which *lag*, and whether it is an own regressor or a
+cross-sectional / common-factor proxy (a CSA in the sense of Pesaran's CCE).
+
+Author : Dr Merwan Roudane <merwanroudane920@gmail.com>
+GitHub : https://github.com/merwanroudane/panelxai
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import numpy as np
+import pandas as pd
+
+SEP = "__"
+
+
+# --------------------------------------------------------------------------- #
+#  Column-name protocol
+# --------------------------------------------------------------------------- #
+def make_feature_name(var: str, lag: int, kind: str) -> str:
+    return f"{var}{SEP}L{lag}{SEP}{kind}"
+
+
+def parse_feature_name(name: str) -> dict:
+    """Inverse of :func:`make_feature_name`. Returns var/lag/kind."""
+    parts = name.split(SEP)
+    if len(parts) != 3 or not parts[1].startswith("L"):
+        # Not a structured column (e.g. a raw passthrough); treat as own/lag0.
+        return {"var": name, "lag": 0, "kind": "own"}
+    return {"var": parts[0], "lag": int(parts[1][1:]), "kind": parts[2]}
+
+
+@dataclass
+class DesignSpec:
+    """Metadata describing a built design matrix."""
+    features: list            # ordered feature column names
+    y: str                    # target column name
+    unit: str
+    time: str
+    lags: int
+    csa_lags: int
+    fe: str                   # 'within' | 'none'
+    unit_index: np.ndarray    # unit label per design row
+    time_index: np.ndarray    # time label per design row
+
+    def meta_frame(self) -> pd.DataFrame:
+        rows = [parse_feature_name(f) for f in self.features]
+        m = pd.DataFrame(rows)
+        m.insert(0, "feature", self.features)
+        return m
+
+
+# --------------------------------------------------------------------------- #
+#  Simulation
+# --------------------------------------------------------------------------- #
+def simulate_panel_ts(
+    n_units: int = 30,
+    n_periods: int = 40,
+    n_features: int = 4,
+    n_lags: int = 2,
+    n_factors: int = 1,
+    csd_strength: float = 0.8,
+    regime_break: float | None = 0.5,
+    nonlinear: bool = True,
+    seed: int | None = None,
+) -> pd.DataFrame:
+    """Simulate a dynamic panel with the features the library is built to explain.
+
+    The data-generating process embeds, on purpose:
+
+    * **Distributed lags** - only a *subset* of (variable, lag) pairs truly
+      drive ``y`` (so importance recovery is testable).
+    * **Cross-sectional dependence** via ``n_factors`` common factors
+      ``F_t`` with heterogeneous loadings (strength ``csd_strength``).
+    * **A regime switch** at ``regime_break`` (fraction of the sample) where
+      one coefficient changes sign - this is what regime-aware explainers
+      should detect as *explanation drift*.
+    * Optional **non-linearity** (interaction + saturation) so that linear
+      models are mis-specified and ML adds value.
+
+    Returns a long (balanced) panel with columns ``unit, time, y, x1..xp``.
+    """
+    rng = np.random.default_rng(seed)
+    N, T, p = n_units, n_periods, n_features
+
+    # Common factors (shared across units) -> cross-sectional dependence.
+    F = rng.normal(size=(T, n_factors))
+    loadings = rng.normal(loc=csd_strength, scale=0.3, size=(N, n_factors))
+
+    # Regressors: persistent (AR) + a factor component.
+    x = np.zeros((N, T, p))
+    x_load = rng.normal(loc=0.5, scale=0.4, size=(N, p, n_factors))
+    for j in range(p):
+        ar = rng.uniform(0.3, 0.7)
+        for t in range(T):
+            prev = x[:, t - 1, j] if t > 0 else 0.0
+            common = x_load[:, j, :] @ F[t]
+            x[:, t, j] = ar * prev + common + rng.normal(scale=1.0, size=N)
+
+    # True distributed-lag structure: pick a few (var, lag) drivers.
+    beta = np.zeros((p, n_lags + 1))
+    beta[0, 0] = 1.2          # x1 contemporaneous
+    if n_lags >= 1:
+        beta[1, 1] = -0.9     # x2 at lag 1
+    if p >= 3 and n_lags >= 2:
+        beta[2, 2] = 0.7      # x3 at lag 2
+
+    alpha = rng.normal(scale=1.0, size=N)        # unit fixed effects
+    gamma = rng.normal(loc=0.6, scale=0.2, size=(N, n_factors))  # y factor loadings
+
+    brk = int(regime_break * T) if regime_break is not None else None
+
+    y = np.zeros((N, T))
+    for t in range(T):
+        mu = alpha + gamma @ F[t]
+        for j in range(p):
+            for l in range(n_lags + 1):
+                if beta[j, l] == 0.0 or t - l < 0:
+                    continue
+                coef = beta[j, l]
+                # Regime switch flips the sign of the x1 effect after the break.
+                if brk is not None and j == 0 and l == 0 and t >= brk:
+                    coef = -coef
+                mu = mu + coef * x[:, t - l, j]
+        if nonlinear and p >= 2:
+            mu = mu + 0.5 * x[:, t, 0] * np.tanh(x[:, t, 1])
+        y[:, t] = mu + rng.normal(scale=0.7, size=N)
+
+    # Assemble long frame.
+    units = np.repeat(np.arange(1, N + 1), T)
+    times = np.tile(np.arange(1, T + 1), N)
+    data = {"unit": units, "time": times, "y": y.reshape(-1)}
+    for j in range(p):
+        data[f"x{j + 1}"] = x[:, :, j].reshape(-1)
+    return pd.DataFrame(data)
+
+
+# --------------------------------------------------------------------------- #
+#  Design construction
+# --------------------------------------------------------------------------- #
+def build_lags(
+    df: pd.DataFrame,
+    cols: list,
+    lags: int,
+    unit: str = "unit",
+    time: str = "time",
+) -> pd.DataFrame:
+    """Add ``{col}__L{l}__own`` columns, lagging *within* each unit."""
+    out = df.sort_values([unit, time]).copy()
+    g = out.groupby(unit, sort=False)
+    for c in cols:
+        for l in range(lags + 1):
+            out[make_feature_name(c, l, "own")] = g[c].shift(l)
+    return out
+
+
+def add_cross_sectional_averages(
+    df: pd.DataFrame,
+    cols: list,
+    csa_lags: int = 0,
+    unit: str = "unit",
+    time: str = "time",
+) -> pd.DataFrame:
+    """Add ``{col}__L{l}__csa``: the period-t mean across units (a CCE-style
+    proxy for the unobserved common factors), then lagged within unit."""
+    out = df.copy()
+    means = out.groupby(time, sort=True)[cols].transform("mean")
+    g_time = out.sort_values([unit, time]).groupby(unit, sort=False)
+    for c in cols:
+        base = f"__csa_base_{c}"
+        out[base] = means[c]
+        gb = out.sort_values([unit, time]).groupby(unit, sort=False)[base]
+        for l in range(csa_lags + 1):
+            out[make_feature_name(c, l, "csa")] = gb.shift(l)
+        out = out.drop(columns=base)
+    return out
+
+
+def build_design(
+    df: pd.DataFrame,
+    y: str = "y",
+    X: list | None = None,
+    unit: str = "unit",
+    time: str = "time",
+    lags: int = 2,
+    csa: bool = True,
+    csa_lags: int = 0,
+    csa_vars: list | None = None,
+    fe: str = "within",
+):
+    """Turn a long panel into ``(X_design, y_vec, DesignSpec)``.
+
+    Parameters
+    ----------
+    lags     : number of own lags (0..lags) for each regressor in ``X``.
+    csa      : if True, append cross-sectional averages (CCE proxies for the
+               common factors driving cross-sectional dependence).
+    csa_lags : own-lags of the CSAs.
+    fe       : ``'within'`` demeans ``y`` and every feature within unit
+               (absorbing fixed effects, the standard FE transform);
+               ``'none'`` leaves levels untouched.
+    """
+    if X is None:
+        X = [c for c in df.columns if c not in (y, unit, time)]
+    csa_vars = csa_vars if csa_vars is not None else list(X)
+
+    work = build_lags(df, X, lags, unit, time)
+    if csa:
+        work = add_cross_sectional_averages(work, csa_vars, csa_lags, unit, time)
+
+    feats = [make_feature_name(v, l, "own") for v in X for l in range(lags + 1)]
+    if csa:
+        feats += [make_feature_name(v, l, "csa")
+                  for v in csa_vars for l in range(csa_lags + 1)]
+
+    work = work.dropna(subset=feats + [y]).reset_index(drop=True)
+
+    y_vec = work[y].copy()
+    X_des = work[feats].copy()
+    u_idx = work[unit].to_numpy()
+    t_idx = work[time].to_numpy()
+
+    if fe == "within":
+        # Demean target and features within unit (absorb fixed effects).
+        gy = y_vec.groupby(work[unit])
+        y_vec = y_vec - gy.transform("mean")
+        gX = X_des.groupby(work[unit].values)
+        X_des = X_des - gX.transform("mean")
+    elif fe != "none":
+        raise ValueError("fe must be 'within' or 'none'")
+
+    spec = DesignSpec(
+        features=feats, y=y, unit=unit, time=time, lags=lags,
+        csa_lags=csa_lags if csa else -1, fe=fe,
+        unit_index=u_idx, time_index=t_idx,
+    )
+    return X_des.reset_index(drop=True), y_vec.reset_index(drop=True), spec
+
+
+def panel_describe(
+    df: pd.DataFrame, unit: str = "unit", time: str = "time"
+) -> pd.DataFrame:
+    """Quick structural summary of a long panel."""
+    n_units = df[unit].nunique()
+    counts = df.groupby(unit)[time].size()
+    rows = {
+        "n_units": n_units,
+        "n_periods_min": int(counts.min()),
+        "n_periods_max": int(counts.max()),
+        "balanced": bool(counts.nunique() == 1),
+        "n_obs": len(df),
+        "n_vars": df.shape[1] - 2,
+    }
+    return pd.DataFrame.from_dict(rows, orient="index", columns=["value"])

panelxai-0.1.0/panelxai/explain/__init__.py

@@ -0,0 +1,21 @@
+"""Explainability core for panel time-series models.
+
+The unifying idea: a raw SHAP value is indexed only by (observation, feature).
+Because :mod:`panelxai.data` encodes ``variable``, ``lag`` and ``kind``
+(own vs cross-sectional-average) in every feature name, we can *re-index*
+attributions onto the structure that matters in panel econometrics:
+
+    variable  x  lag  x  unit  x  time   +   own-vs-factor decomposition.
+"""
+from .structured import StructuredExplainer
+from .regime import regime_importance, regime_effect_sign, explanation_drift
+from .counterfactual import counterfactual
+from .uncertainty import bootstrap_importance
+
+__all__ = [
+    "StructuredExplainer",
+    "regime_importance",
+    "explanation_drift",
+    "counterfactual",
+    "bootstrap_importance",
+]