Metadata-Version: 2.4
Name: mlpaneldata
Version: 0.1.0
Summary: ML / Econometric Panel-Data Library: Interpretable Neural Networks with Persistent Change Filters and Deep Neural Panel Estimation, with full pre/post tests, diagnostics, tables and plots.
Author-email: Dr Merwan Roudane <merwanroudane920@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/merwanroudane/mlpaneldata
Project-URL: Repository, https://github.com/merwanroudane/mlpaneldata
Project-URL: Issues, https://github.com/merwanroudane/mlpaneldata/issues
Keywords: panel data,machine learning,neural networks,econometrics,fixed effects,random effects,interpretable ML,persistent change filter,hybrid models,diagnostics
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: seaborn>=0.12
Requires-Dist: torch>=1.13
Requires-Dist: tabulate>=0.9
Requires-Dist: linearmodels>=4.27
Requires-Dist: tqdm>=4.64
Dynamic: license-file

# mlpaneldata

> **Hybrid Machine-Learning / Econometric Panel-Data Library**
>
> Author: **Dr Merwan Roudane** — merwanroudane920@gmail.com
> GitHub: https://github.com/merwanroudane/mlpaneldata

`mlpaneldata` is a one-stop Python package for **hybrid panel-data analysis**
that mixes classical econometrics (Pooled OLS, Fixed Effects, Random
Effects, Mundlak, First Differences) with two state-of-the-art neural-network
panel methodologies:

1. **Interpretable Neural Networks with Persistent Change Filters**
   (Yang, Zheng & E, 2020 — *Interpretable Neural Networks for Panel Data
   Analysis in Economics*, arXiv:2010.05311).
2. **Deep Neural Network Panel Estimation with Common + Idiosyncratic
   Decomposition** (Chronopoulos, Chrysikou, Kapetanios, Mitchell &
   Raftapostolos, 2023 — *Deep Neural Network Estimation in Panel Data
   Models*, arXiv:2305.19921).

It also implements a **fully integrated hybrid estimator** combining a
linear panel model and a neural component on the residuals (parametric +
non-parametric two-step), with a complete suite of diagnostics.

## Features

* **Pre-tests** — Hausman, F-test for FE, Breusch–Pagan LM (RE), Pesaran CD,
  Friedman, Frees, Pesaran CIPS / IPS / LLC unit-root, poolability,
  multicollinearity (VIF), Jarque–Bera, Wooldridge serial correlation,
  Breusch–Pagan / White heteroskedasticity.
* **Post-tests** — RESET, residual diagnostics, Diebold–Mariano,
  Clark–West, encompassing, robust covariance (cluster, Driscoll–Kraay).
* **Diagnostics** — partial derivatives, marginal effects, feature
  importance (gradient × input, permutation), heterogeneity by unit,
  learning curves.
* **Plots** — residual / fitted, QQ, PDP / ICE, persistent-change-filter
  curves, training history, coefficient stability, heatmaps, forecast
  plots, partial-derivative time profiles, dashboard.
* **Tables** — publication-quality regression tables, diagnostic tables.
* **Reports** — `Report` object that bundles everything into Markdown / HTML.

## Installation

```bash
pip install -e .
```

## Quick start

```python
from mlpaneldata.data    import simulate_panel
from mlpaneldata.models  import HybridPanel
from mlpaneldata.tests   import full_pretest_suite, full_posttest_suite
from mlpaneldata.plots   import diagnostic_dashboard
from mlpaneldata.tables  import regression_table

df = simulate_panel(n_units=30, n_periods=40, n_features=6, seed=0)

pre = full_pretest_suite(df, y="y", X=["x1","x2","x3","x4","x5","x6"],
                         unit="unit", time="time")
print(pre.summary())

m = HybridPanel(linear_part="within", nn_part="dnn_panel",
                hidden=[64,64], lambda_l1=1e-3, epochs=200, lr=1e-3)
m.fit(df, y="y", X=["x1","x2","x3","x4","x5","x6"],
      unit="unit", time="time")

print(regression_table([m]))
print(full_posttest_suite(m).summary())
diagnostic_dashboard(m, save="dashboard.png")
```

## Modules

| module                          | content                                       |
|---------------------------------|-----------------------------------------------|
| `mlpaneldata.data`              | panel utilities, simulators                   |
| `mlpaneldata.models.linear`     | Pooled, FE, RE, Mundlak, First-Differences    |
| `mlpaneldata.models.filters`    | Persistent Change Filter (paper 1)            |
| `mlpaneldata.models.inn`        | Interpretable NN for panel data (paper 1)     |
| `mlpaneldata.models.dnn_panel`  | Deep NN panel — common + idiosyncratic (paper 2)|
| `mlpaneldata.models.hybrid`     | Hybrid linear + NN estimator                  |
| `mlpaneldata.tests.pretests`    | All pre-estimation tests                      |
| `mlpaneldata.tests.posttests`   | All post-estimation tests                     |
| `mlpaneldata.diagnostics`       | Partial derivatives, importance, marginals    |
| `mlpaneldata.plots`             | All plotting routines                         |
| `mlpaneldata.tables`            | Pretty tables                                 |
| `mlpaneldata.reports`           | One-shot Markdown / HTML report               |

## Citation

If you use this library, please cite:

> Roudane, M. (2026). *mlpaneldata: Hybrid ML / Econometric Panel-Data
> Library.* https://github.com/merwanroudane/mlpaneldata

and the underlying papers (`arXiv:2010.05311` and `arXiv:2305.19921`).
