Metadata-Version: 2.4
Name: gmmselector
Version: 0.1.0
Summary: Tu dong chon bien cong cu cho System/Difference GMM (Arellano-Bond / Blundell-Bond), xtabond2 <-> pydynpd.
Author-email: Anh Le <anhlh_vnc@hub.edu.vn>
License: MIT
Project-URL: Homepage, https://github.com/anhle32
Project-URL: Issues, https://github.com/anhle32
Keywords: GMM,dynamic panel,Arellano-Bond,Blundell-Bond,xtabond2,pydynpd,econometrics,panel data,instrument selection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: pydynpd>=0.2.2
Requires-Dist: openpyxl
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# gmmselector

Tự động lựa chọn biến công cụ (instrument) cho mô hình **System / Difference GMM**
(Arellano–Bond, Blundell–Bond) — tương đương `xtabond2` (Stata) ↔ `pydynpd` (Python).

Thư viện sinh toàn bộ lưới đặc tả ứng viên (kết hợp cách xử lý ngoại sinh / tiền định /
nội sinh, độ trễ, `collapse`, biến giả thời gian, System vs Difference), ước lượng từng
đặc tả, lọc theo 4 điều kiện chuẩn và xếp hạng để chọn ra đặc tả tốt nhất; đồng thời chạy
kiểm định nội sinh Difference-in-Hansen cho **tất cả** các biến, gồm cả **biến trễ của
biến phụ thuộc**.

## Cài đặt

```bash
pip install gmmselector
```

Khi phát triển cục bộ:

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

Phụ thuộc: `numpy`, `pandas`, `scipy`, `pydynpd>=0.2.2`, `openpyxl`.

> Lưu ý numpy 2.x: `pydynpd 0.2.2` còn gọi `numpy.in1d` (đã bị gỡ ở numpy ≥ 2.0).
> `gmmselector` tự vá `numpy.in1d = numpy.isin` ngay khi import nên chạy được trên cả
> Jupyter/numpy mới lẫn Google Colab.

## Sử dụng (Python / notebook)

```python
import gmmselector as gs

# 1) Cấu hình
gs.configure(
    data="sd_gdp.csv",          # đường dẫn .csv/.xlsx, hoặc một pandas.DataFrame
    id_col="id",                # cột panel id
    time_col="year",            # cột thời gian
    dep="sd_gdp",               # biến phụ thuộc
    indeps=["private", "trade", "lngdp", "inflation", "employment"],
)

# 2) Báo cáo kiểm định nội sinh TẤT CẢ biến (gồm cả biến trễ phụ thuộc L1.sd_gdp)
gs.endogeneity()

# 3) Tự chạy B2–B5 và xuất kết quả ra Excel
gs.search()                     # mặc định xuất gmm_selection_results.xlsx
```

`configure()` tự thêm trễ bậc 1 của biến phụ thuộc (`L1.sd_gdp`) để tạo mô hình động.
Nếu bạn muốn **mô hình tĩnh** (không có biến trễ phụ thuộc), đặt `add_dep_lag=False`.

### Dùng theo kiểu hướng đối tượng

```python
from gmmselector import GMMSelector

m = GMMSelector(
    data="sd_gdp.csv", id_col="id", time_col="year",
    dep="sd_gdp",
    indeps=["private", "trade", "lngdp", "inflation", "employment"],
)
m.endogeneity()                 # -> DataFrame, đồng thời in báo cáo
res = m.search(output="ket_qua.xlsx")   # -> DataFrame các đặc tả đã xếp hạng
```

## Sử dụng (dòng lệnh)

```bash
gmmselector --data sd_gdp.csv --id id --time year \
    --dep sd_gdp \
    --indeps private trade lngdp inflation employment \
    --output ket_qua.xlsx
```

Thêm `--no-dep-lag` cho mô hình tĩnh, `--no-endogeneity` để bỏ qua bước B1.

## Bốn điều kiện lọc

1. Số công cụ < số nhóm (`inst < groups`).
2. AR(1) p < 0,10.
3. AR(2) p > 0,10.
4. Hansen p > 0,10 (cảnh báo nếu p > 0,25 hoặc > 0,80 — nguy cơ "loãng công cụ", Roodman 2009).

Xếp hạng ưu tiên: đạt cả 4 điều kiện → ưu tiên System GMM → ít công cụ nhất → Hansen cao nhất.
Báo cáo `search()` cho biết rõ đặc tả thắng là **SYSTEM GMM** hay **DIFFERENCE GMM**, kèm
phân bố số đặc tả System vs Difference trong nhóm đạt chuẩn.

## Ràng buộc cách xử lý từng biến theo lý thuyết

Mặc định lưới thử cả ba cách xử lý (`exog`/`predet`/`endog`) cho mọi biến. Nếu muốn ép theo
phân loại nội sinh (từ lý thuyết hoặc từ kết quả `endogeneity()`), truyền vào `search()`:

```python
gs.search(
    reg_allow=("endog",),                     # mặc định cho mọi biến
    reg_allow_map={"trade": ("predet",),      # trade: tiền định
                   "employment": ("exog",)},  # employment: ngoại sinh
)
```

## Lưu ý phương pháp

- Kiểm định Difference-in-Hansen có **lực kiểm định thấp**; "không bác bỏ" không đồng nghĩa
  biến chắc chắn ngoại sinh — nhất là khi số nhóm N nhỏ.
- GMM động chủ yếu được biện minh bởi **biến trễ phụ thuộc** (chệch panel động, Nickell 1981),
  không chỉ bởi nội sinh của các regressor. Nếu mô hình không thực sự động và các biến ngoại
  sinh, hãy cân nhắc FE/RE; nếu động nhưng N nhỏ, cân nhắc LSDV hiệu chỉnh chệch.

## Tham khảo

Arellano & Bond (1991); Arellano & Bover (1995); Blundell & Bond (1998);
Hansen (1982); Roodman (2009, *Stata Journal* & *Oxford Bull. Econ. Stat.*); Nickell (1981).

## Giấy phép

MIT © 2026 Anh Le
