Skip to content

Commit edde324

Browse files
brycewang-stanfordclaude
brycewang-stanford
and
claude
committed
Add Chinese README with language switcher
Add README_CN.md with full Chinese translation of the project documentation. Both READMEs have a language switcher link at the top: [English](README.md) | [中文](README_CN.md) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 2a16f7e commit edde324

2 files changed

Lines changed: 337 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
[English](README.md) | [中文](README_CN.md)
2+
13
# StatsPAI: The Agent-Native Causal Inference & Econometrics Toolkit for Python
24

35
[![PyPI version](https://img.shields.io/pypi/v/StatsPAI.svg)](https://pypi.org/project/StatsPAI/)

‎README_CN.md‎

Lines changed: 335 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,335 @@
1+
[English](README.md) | [中文](README_CN.md)
2+
3+
# StatsPAI：面向 Agent 的因果推断与计量经济学 Python 工具包
4+
5+
[![PyPI version](https://img.shields.io/pypi/v/StatsPAI.svg)](https://pypi.org/project/StatsPAI/)
6+
[![Python versions](https://img.shields.io/pypi/pyversions/StatsPAI.svg)](https://pypi.org/project/StatsPAI/)
7+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/brycewang-stanford/statspai/blob/main/LICENSE)
8+
[![Tests](https://github.com/brycewang-stanford/statspai/workflows/CI%2FCD%20Pipeline/badge.svg)](https://github.com/brycewang-stanford/statspai/actions)
9+
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/statspai?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/statspai)
10+
[![status](https://joss.theoj.org/papers/9f1c837b1b1df7adfcdd538c3698e332/status.svg)](https://joss.theoj.org/papers/9f1c837b1b1df7adfcdd538c3698e332)
11+
12+
StatsPAI 是一个**面向 AI Agent** 的 Python 因果推断与应用计量经济学工具包。一个 `import`，390+ 个函数，覆盖从经典计量经济学到前沿 ML/AI 因果推断方法，再到论文级 Word、Excel、LaTeX 输出表格的完整实证研究流程。
13+
14+
**为 AI Agent 而生**：每个函数都返回结构化结果对象，附带自描述 schema（`list_functions()`、`describe_function()`、`function_schema()`），使 StatsPAI 成为首个专为 LLM 驱动的研究流程设计的计量工具包——同时对人类研究者也完全友好。
15+
16+
它将 R 的 [Causal Inference Task View](https://cran.r-project.org/web/views/CausalInference.html)（fixest、did、rdrobust、gsynth、DoubleML、MatchIt、CausalImpact……）和 Stata 的核心计量命令，统一到一个一致的 Python API 中。
17+
18+
**v0.6 新功能**：`sp.interactive(fig)` —— 类似 Stata Graph Editor 的 WYSIWYG 图表编辑器，支持 29 种学术主题、实时预览、自动生成可复现代码。
19+
20+
![alt text](image-1.png)
21+
22+
> 由 [CoPaper.AI](https://copaper.ai) 团队构建 · 斯坦福 REAP 项目
23+
24+
---
25+
26+
## 为什么选择 StatsPAI？
27+
28+
| 痛点 | Stata | R | StatsPAI |
29+
| --- | --- | --- | --- |
30+
| 包分散 | 统一环境，但 $695+/年 | 20+ 个包，API 互不兼容 | **一个 `import`，统一 API** |
31+
| 论文表格 | `outreg2`（格式有限） | `modelsummary`（最佳） | **每个函数都支持 Word + Excel + LaTeX + HTML** |
32+
| 稳健性检验 | 手动重跑 | 手动重跑 | **`spec_curve()` + `robustness_report()` —— 一行代码** |
33+
| 异质性分析 | 手动分组 + 画图 | 手动 `lapply` + `ggplot` | **`subgroup_analysis()` 含 Wald 检验** |
34+
| 现代 ML 因果 | 有限（无 DML、无因果森林） | 分散（DoubleML、grf、SuperLearner 各自独立） | **DML、因果森林、Meta-Learners、TMLE、DeepIV** |
35+
| 神经因果模型 | 无 | 无 | **TARNet、CFRNet、DragonNet** |
36+
| 因果发现 | 无 | `pcalg`（API 复杂） | **`notears()`、`pc_algorithm()`** |
37+
| 策略学习 | 无 | `policytree`（独立包） | **`policy_tree()` + `policy_value()`** |
38+
| 结果对象 | 命令间不统一 | 包间不统一 | **统一的 `CausalResult`：`.summary()`、`.plot()`、`.to_latex()`、`.cite()`** |
39+
| 交互式图表编辑 | Graph Editor（无法导出代码） | 无 | **`sp.interactive()` —— GUI 编辑 + 自动生成代码** |
40+
41+
---
42+
43+
## 完整功能列表
44+
45+
### 回归模型
46+
47+
| 函数 | 描述 | Stata 等价命令 | R 等价函数 |
48+
| --- | --- | --- | --- |
49+
| `regress()` | OLS，支持稳健/聚类/HAC 标准误 | `reg y x, r` / `vce(cluster c)` | `fixest::feols()` |
50+
| `ivreg()` | IV / 2SLS，含一阶段诊断 | `ivregress 2sls` | `fixest::feols()` + IV |
51+
| `panel()` | 固定效应、随机效应、Between、一阶差分 | `xtreg, fe` / `xtreg, re` | `plm::plm()` |
52+
| `heckman()` | Heckman 选择模型 | `heckman` | `sampleSelection::selection()` |
53+
| `qreg()`, `sqreg()` | 分位数回归 | `qreg` / `sqreg` | `quantreg::rq()` |
54+
| `tobit()` | 截断回归（Tobit） | `tobit` | `censReg::censReg()` |
55+
| `xtabond()` | Arellano-Bond 动态面板 GMM | `xtabond` | `plm::pgmm()` |
56+
| `glm()` | 广义线性模型（6 族 × 8 链接） | `glm` | `stats::glm()` |
57+
| `logit()`, `probit()` | 二元选择模型，含边际效应 | `logit` / `probit` | `stats::glm(family=binomial)` |
58+
| `mlogit()` | 多项 Logit | `mlogit` | `nnet::multinom()` |
59+
| `ologit()`, `oprobit()` | 有序 Logit / Probit | `ologit` / `oprobit` | `MASS::polr()` |
60+
| `poisson()`, `nbreg()` | 计数模型（泊松、负二项） | `poisson` / `nbreg` | `MASS::glm.nb()` |
61+
| `ppmlhdfe()` | 引力模型伪泊松 MLE | `ppmlhdfe` | `fixest::fepois()` |
62+
| `gmm()` | 一般 GMM（任意矩条件） | `gmm` | `gmm::gmm()` |
63+
| `frontier()` | 随机前沿分析 | `frontier` | `sfa::sfa()` |
64+
65+
### 因果推断 — 双重差分
66+
67+
| 函数 | 描述 | 参考文献 |
68+
| --- | --- | --- |
69+
| `did()` | 自动分派 DID（2×2 或交错） | — |
70+
| `callaway_santanna()` | 交错 DID，异质处理效应 | Callaway & Sant'Anna (2021) |
71+
| `sun_abraham()` | 交互加权事件研究 | Sun & Abraham (2021) |
72+
| `bacon_decomposition()` | TWFE 分解诊断 | Goodman-Bacon (2021) |
73+
| `honest_did()` | 平行趋势假设敏感性 | Rambachan & Roth (2023) |
74+
| `continuous_did()` | 连续处理 DID（剂量反应） | Callaway, Goodman-Bacon & Sant'Anna (2024) |
75+
| `did_imputation()` | 插补 DID 估计量 | Borusyak, Jaravel & Spiess (2024) |
76+
77+
### 因果推断 — 断点回归
78+
79+
| 函数 | 描述 | 参考文献 |
80+
| --- | --- | --- |
81+
| `rdrobust()` | 尖锐/模糊 RD，稳健偏差校正推断 | Calonico, Cattaneo & Titiunik (2014) |
82+
| `rdplot()` | RD 可视化（分箱散点图） | — |
83+
| `rddensity()` | McCrary 密度操纵检验 | McCrary (2008) |
84+
85+
### 因果推断 — 匹配与再加权
86+
87+
| 函数 | 描述 | Stata 等价命令 |
88+
| --- | --- | --- |
89+
| `match()` | PSM、Mahalanobis、CEM，含平衡诊断 | `psmatch2` / `cem` |
90+
| `ebalance()` | 熵平衡 | `ebalance` |
91+
92+
### 因果推断 — 合成控制
93+
94+
| 函数 | 描述 | 参考文献 |
95+
| --- | --- | --- |
96+
| `synth()` | Abadie-Diamond-Hainmueller SCM | Abadie et al. (2010) |
97+
| `sdid()` | 合成双重差分 | Arkhangelsky et al. (2021) |
98+
99+
### 机器学习因果推断
100+
101+
| 函数 | 描述 | 参考文献 |
102+
| --- | --- | --- |
103+
| `dml()` | 双重/去偏 ML（PLR + IRM），交叉拟合 | Chernozhukov et al. (2018) |
104+
| `causal_forest()` | 因果森林，异质处理效应 | Wager & Athey (2018) |
105+
| `deepiv()` | 深度 IV 神经网络方法 | Hartford et al. (2017) |
106+
| `metalearner()` | S/T/X/R/DR-Learner CATE 估计 | Kunzel et al. (2019), Kennedy (2023) |
107+
| `tmle()` | 目标最大似然估计 | van der Laan & Rose (2011) |
108+
109+
### 神经因果模型
110+
111+
| 函数 | 描述 | 参考文献 |
112+
| --- | --- | --- |
113+
| `tarnet()` | Treatment-Agnostic 表示网络 | Shalit et al. (2017) |
114+
| `cfrnet()` | 反事实回归网络 | Shalit et al. (2017) |
115+
| `dragonnet()` | Dragon 神经网络 CATE | Shi et al. (2019) |
116+
117+
### 估计后命令
118+
119+
| 函数 | 描述 | Stata 等价命令 |
120+
| --- | --- | --- |
121+
| `margins()` | 平均边际效应（AME/MEM） | `margins, dydx(*)` |
122+
| `test()` | 线性约束 Wald 检验 | `test x1 = x2` |
123+
| `lincom()` | 线性组合推断 | `lincom x1 + x2` |
124+
| `estat()` | 综合估计后诊断 | `estat` |
125+
| `predict()` | 样本内/外预测 | `predict` |
126+
127+
### 诊断与敏感性分析
128+
129+
| 函数 | 描述 | 参考文献 |
130+
| --- | --- | --- |
131+
| `oster_bounds()` | 系数稳定性界限 | Oster (2019) |
132+
| `sensemakr()` | 遗漏变量敏感性 | Cinelli & Hazlett (2020) |
133+
| `evalue()` | E-值（未测量混杂敏感性） | VanderWeele & Ding (2017) |
134+
| `vif()` | 方差膨胀因子 | — |
135+
| `het_test()` | Breusch-Pagan / White 异方差检验 | — |
136+
| `reset_test()` | Ramsey RESET 设定检验 | — |
137+
138+
### 智能工作流引擎 *(StatsPAI 独有 — 其他工具包没有这些功能)*
139+
140+
| 函数 | 描述 |
141+
| --- | --- |
142+
| `recommend()` | 给定数据 + 研究问题 → 推荐估计方法，附推理过程，可直接 `.run()` |
143+
| `compare_estimators()` | 多方法对比（OLS、匹配、IPW、DML……），报告一致性诊断 |
144+
| `assumption_audit()` | 一键检验任何方法的所有假设，每项给出通过/失败/补救方案 |
145+
| `sensitivity_dashboard()` | 多维度敏感性分析（样本、异常值、不可观测变量），含稳定性评级 |
146+
| `pub_ready()` | 期刊专属发表准备清单（Top 5 经济学、AEJ、RCT） |
147+
| `replicate()` | 内置经典数据集（Card 1995、LaLonde 1986、Lee 2008），含复现指南 |
148+
149+
### 稳健性分析 *(StatsPAI 独有)*
150+
151+
| 函数 | 描述 |
152+
| --- | --- |
153+
| `spec_curve()` | 规格曲线 / 多元宇宙分析 |
154+
| `robustness_report()` | 自动稳健性电池（标准误变体、缩尾、截断、增减控制变量、子样本） |
155+
| `subgroup_analysis()` | 异质性分析 + 森林图 + 交互 Wald 检验 |
156+
157+
### 论文级输出
158+
159+
| 函数 | 描述 | 格式 |
160+
| --- | --- | --- |
161+
| `modelsummary()` | 多模型对比表 | 文本、LaTeX、HTML、Word、Excel |
162+
| `outreg2()` | Stata 风格回归表导出 | Excel、LaTeX、Word |
163+
| `sumstats()` | 描述性统计（Table 1） | 文本、LaTeX、HTML、Word、Excel |
164+
| `balance_table()` | 处理前平衡检验 | 文本、LaTeX、HTML、Word、Excel |
165+
| `coefplot()` | 系数森林图 | matplotlib |
166+
| `binscatter()` | 分箱散点图（可残差化） | matplotlib |
167+
| `interactive()` | WYSIWYG 图表编辑器，29 种主题 + 自动生成代码 | Jupyter ipywidgets |
168+
169+
每个结果对象都有：
170+
171+
```python
172+
result.summary() # 格式化文本摘要
173+
result.plot() # 合适的可视化图表
174+
result.to_latex() # LaTeX 表格
175+
result.to_docx() # Word 文档
176+
result.cite() # 方法的 BibTeX 引用
177+
```
178+
179+
### 交互式图表编辑器 — Python 版 Stata Graph Editor
180+
181+
用过 Stata 的人都知道 Graph Editor——双击图表就能进入可视化编辑界面，拖字体、换颜色、调布局，所见即所得。Python 这边，matplotlib 画完图想改标题字号得回去改代码重跑。
182+
183+
**`sp.interactive(fig)`** 把任何 matplotlib 图表变成带实时预览的编辑面板——左边是图表，右边是属性控制，跟 Stata Graph Editor 一样的操作逻辑。但它比 Stata 多做了两件事：
184+
185+
1. **29 种学术主题一键切换。** 从 AER 期刊风格到 ggplot、FiveThirtyEight、暗色演示模式，选一下就能看到效果。Stata 换 scheme 要重新出图，这里是实时的。
186+
187+
2. **每一步编辑自动生成可复现代码。** 你在 GUI 里调了标题字号、换了颜色、加了注释，编辑器会把操作记录成标准 matplotlib 代码。一键复制，贴到脚本里就能复现。Stata Graph Editor 无法导出编辑操作为 do-file 命令。
188+
189+
```python
190+
import statspai as sp
191+
192+
result = sp.did(df, y='wage', treat='policy', time='year')
193+
fig, ax = result.plot()
194+
editor = sp.interactive(fig) # 打开编辑器
195+
196+
# 在 GUI 中编辑后：
197+
editor.copy_code() # 打印可复现的 Python 代码
198+
```
199+
200+
---
201+
202+
## 安装
203+
204+
```bash
205+
pip install statspai
206+
```
207+
208+
可选依赖：
209+
210+
```bash
211+
pip install statspai[plotting] # matplotlib, seaborn
212+
pip install statspai[fixest] # pyfixest 高维固定效应
213+
pip install statspai[deepiv] # PyTorch (Deep IV)
214+
```
215+
216+
**环境要求：** Python >= 3.9
217+
218+
**核心依赖：** NumPy、SciPy、Pandas、statsmodels、scikit-learn、linearmodels、patsy、openpyxl、python-docx
219+
220+
---
221+
222+
## 快速示例
223+
224+
```python
225+
import statspai as sp
226+
227+
# --- 估计 ---
228+
r1 = sp.regress("wage ~ education + experience", data=df, robust='hc1')
229+
r2 = sp.ivreg("wage ~ (education ~ parent_edu) + experience", data=df)
230+
r3 = sp.did(df, y='wage', treat='policy', time='year', id='worker')
231+
r4 = sp.rdrobust(df, y='score', x='running_var', c=0)
232+
r5 = sp.dml(df, y='wage', treat='training', covariates=['age', 'edu', 'exp'])
233+
r6 = sp.causal_forest("y ~ treatment | x1 + x2 + x3", data=df)
234+
235+
# --- 估计后 ---
236+
sp.margins(r1, data=df) # 边际效应
237+
sp.test(r1, "education = experience") # Wald 检验
238+
sp.estat(r1) # 综合诊断
239+
240+
# --- 表格（Word / Excel / LaTeX）---
241+
sp.modelsummary(r1, r2, output='table2.docx')
242+
sp.outreg2(r1, r2, r3, filename='results.xlsx')
243+
sp.sumstats(df, vars=['wage', 'education', 'age'], output='table1.docx')
244+
245+
# --- 稳健性（StatsPAI 独有）---
246+
sp.spec_curve(df, y='wage', x='education',
247+
controls=[[], ['experience'], ['experience', 'female']],
248+
se_types=['nonrobust', 'hc1']).plot()
249+
250+
# --- 智能推荐（StatsPAI 独有）---
251+
rec = sp.recommend(df, y='wage', treatment='training')
252+
print(rec.summary()) # 推荐哪个估计方法 + 原因
253+
result = rec.run() # 一键执行推荐的方法
254+
```
255+
256+
---
257+
258+
## StatsPAI vs Stata vs R：坦诚对比
259+
260+
### StatsPAI 的优势
261+
262+
| 优势 | 详情 |
263+
| --- | --- |
264+
| **统一 API** | 一个包，一个 `import`，所有方法一致的 `.summary()` / `.plot()` / `.to_latex()`。Stata 需付费插件；R 需 20+ 个接口不同的包。 |
265+
| **现代 ML 因果方法** | DML、因果森林、Meta-Learners（S/T/X/R/DR）、TMLE、DeepIV、TARNet/CFRNet/DragonNet、策略树——全在一个包里。Stata 几乎没有；R 分散在互不兼容的包中。 |
266+
| **稳健性自动化** | `spec_curve()`、`robustness_report()`、`subgroup_analysis()`——不用手动重跑。Stata 和 R 都没有开箱即用的。 |
267+
| **免费开源** | MIT 协议，$0。Stata 每年 $695–$1,595。 |
268+
| **Python 生态** | 与 pandas、scikit-learn、PyTorch、Jupyter、云端流水线天然集成。 |
269+
| **自动引用** | 每个因果方法都有 `.cite()` 返回正确的 BibTeX。Stata 和 R 都没有。 |
270+
| **交互式图表编辑** | `sp.interactive()` —— Jupyter 中的 Stata Graph Editor 风格 GUI，29 种主题，自动生成可复现代码。 |
271+
272+
### Stata 仍然领先的地方
273+
274+
| 优势 | 详情 |
275+
| --- | --- |
276+
| **大规模验证** | 40+ 年在经济学中的生产使用，边界情况处理完善。 |
277+
| **超大数据集速度** | Stata 的 C 编译后端对百万行简单 OLS/FE 更快。 |
278+
| **调查数据** | `svy:` 前缀、分层、聚类——Stata 的调查支持无人匹敌。 |
279+
| **成熟文档** | 每个命令都有 PDF 手册和示例，社区庞大。 |
280+
| **期刊认可度** | 某些领域审稿人默认信任 Stata 输出。 |
281+
282+
### R 仍然领先的地方
283+
284+
| 优势 | 详情 |
285+
| --- | --- |
286+
| **前沿方法** | 新计量方法（如 `fixest`、`did2s`、`HonestDiD`）通常先在 R 社区出现。 |
287+
| **ggplot2 可视化** | R 的图形语法比 matplotlib 更灵活。 |
288+
| **CRAN 质量控制** | R 包经过同行评审。Python 包质量参差不齐。 |
289+
| **空间计量** | `spdep`、`spatialreg`——R 的空间生态更深。 |
290+
291+
---
292+
293+
## 关于
294+
295+
**StatsPAI Inc.** 是 [CoPaper.AI](https://copaper.ai)——AI 辅助实证研究协作平台的研究基础设施公司，诞生于斯坦福 [REAP](https://reap.fsi.stanford.edu/) 项目。
296+
297+
**CoPaper.AI** — 上传数据，设定研究问题，生成完全可复现的学术论文，含代码、表格和格式化输出。底层由 StatsPAI 驱动。[copaper.ai](https://copaper.ai)
298+
299+
**团队：**
300+
301+
- **Bryce Wang** — 创始人。经济学、金融学、计算机与 AI。斯坦福 REAP。
302+
- **Dr. Scott Rozelle** — 联合创始人兼战略顾问。斯坦福高级研究员，《看不见的中国》作者。
303+
304+
---
305+
306+
## 贡献
307+
308+
```bash
309+
git clone https://github.com/brycewang-stanford/statspai.git
310+
cd statspai
311+
pip install -e ".[dev,plotting,fixest]"
312+
pytest
313+
```
314+
315+
---
316+
317+
## 引用
318+
319+
```bibtex
320+
@software{wang2025statspai,
321+
title={StatsPAI: The Causal Inference & Econometrics Toolkit for Python},
322+
author={Wang, Bryce},
323+
year={2025},
324+
url={https://github.com/brycewang-stanford/statspai},
325+
version={0.6.2}
326+
}
327+
```
328+
329+
## 许可证
330+
331+
MIT 许可证。见 [LICENSE](LICENSE)。
332+
333+
---
334+
335+
[GitHub](https://github.com/brycewang-stanford/statspai) · [PyPI](https://pypi.org/project/StatsPAI/) · [使用指南](https://github.com/brycewang-stanford/statspai#quick-example) · [CoPaper.AI](https://copaper.ai)

0 commit comments

Comments
 (0)