Metadata-Version: 2.4
Name: groupedpaneldatamodels
Version: 0.1.2
Summary: A Simple Python library that implements the most commonly used Grouped Panel Data Models
Author-email: Micha den Heijer <micha@michadenheijer.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: numpy>=2.0.0,<3.0.0
Requires-Dist: scipy>=1.15.0,<2.0.0
Requires-Dist: scikit-learn>=1.6.0,<2.0.0
Requires-Dist: skglm~=0.4
Requires-Dist: numba>=0.61.0,<1.0.0
Requires-Dist: statsmodels>=0.14.0,<1.0.0
Requires-Dist: tqdm>=4.0.0,<5.0.0
Requires-Dist: black ; extra == "dev"
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: coverage ; extra == "dev"
Requires-Dist: mypy ; extra == "dev"
Project-URL: Documentation, https://groupedpaneldatamodels.michadenheijer.com
Project-URL: Source, https://github.com/michadenheijer/groupedpaneldatamodels
Project-URL: Tracker, https://github.com/michadenheijer/groupedpaneldatamodels/issues
Provides-Extra: dev

# ```groupedpaneldatamodels```: A Python Library for Grouped Fixed and Interactive Effects Models

```groupedpaneldatamodels``` is an open‑source Python library that implements a collection of *Grouped Panel Data Models* (GPDMs) for econometric research.

`groupedpaneldatamodels` is an Open Source Python library that implements multiple Grouped Panel Data Models (GPDMs) for Econometric research. These models offer a middle ground between fully homogeneous (which are often incorrectly specified) and fully heterogeneous (which are often difficult to estimate) by grouping multiple individuals and assuming the same coeficients for all members of the groupings.

## Features
This package implements the models and algorithms proposed by the following four papers, which each suggest different GPDMS.

* **Grouped Fixed Effects (GFE)**
  * [Bonhomme & Manresa (2015)](https://doi.org/10.3982/ECTA11319) clustering estimator
  * [Su, Shi & Phillips (2016)](https://doi.org/10.3982/ECTA12560) C‑Lasso estimator
* **Grouped Interactive Fixed Effects (GIFE)**
  * [Ando & Bai (2016)](https://doi.org/10.1002/jae.2467) clustering estimator
  * [Su & Ju (2018)](https://doi.org/10.1016/j.jeconom.2018.06.014) C‑Lasso estimator
* Automatic group selection via Information Criteria (BIC, AIC, HQIC).
* Analytical or bootstrap standard errors
* Fast NumPy and JIT-compiled Numba core with optional parallel bootstrap for large panels
* Familiar, `statsmodels`‑like API

## Installation

```bash
pip install groupedpaneldatamodels
# or update
pip install --upgrade groupedpaneldatamodels
```

To grab the bleeding‑edge version:

```bash
git clone https://github.com/michadenheijer/groupedpaneldatamodels.git
cd groupedpaneldatamodels
pip install .
```

---

## Quick start

```python
import numpy as np
import groupedpaneldatamodels as gpdm

# Y  shape (N, T, 1); X  shape (N, T, K)
gfe = gpdm.GroupedFixedEffects(Y, X, G=3, model="bonhomme_manresa")
gfe.fit()
print(gfe.summary())

gife = gpdm.GroupedInteractiveFixedEffects(Y, X, G=3,
                                           model="ando_bai",
                                           GF=[2, 2, 2])            # 2 common factors per grouping
gife.fit()
betas = gife.params["beta"]
```

### Selecting the number of groups

```python
best = gpdm.grid_search_by_ic(
    gpdm.GroupedFixedEffects,
    param_ranges={"G": range(1, 7)},
    init_params={"dependent": Y, "exog": X},
    pit_params={"gife_iterations": 100},
    ic_criterion="BIC"
)
print(best.G)          # optimal group count
```

## Documentation

An API reference with proper installation and guidelines is available at
<https://groupedpaneldatamodels.michadenheijer.com>


## Simulation Study

A simulation study has been done for the Master's thesis creating this package. This thesis has shown that this package
can succesfully reproduce the properties of the underlying estimators and can reduce the RMSE compared to a fully heterogeneous
model when `N` is large and `T` is small.

---

## Citation

Please cite the thesis if you use `groupedpaneldatamodels`:

```bibtex
@mastersthesis{denheijer2025,
    author      = {Micha den Heijer},
    title       = {groupedpaneldatamodels: A Python Library for Grouped Fixed and Interactive Effects Models},
    school      = {Vrije Universiteit Amsterdam},
    year        = {2025},
    month       = {July},
    date        = {2025-07-01},
    url         = {https://groupedpaneldatamodels.michadenheijer.com/_static/thesis.pdf}
}
```

---

## License

Released under the MIT License. See [LICENSE](LICENSE) for details.
