Fin Experiment Design

python -m scripts.core.empirical_package questions
python -m scripts.core.empirical_package scaffold --mode core --unit firm
python -m scripts.core.empirical_package audit output/fin-refinement/empirical_package.json

python -m scripts.research_framework.enhanced_pipeline --topic "..." --mechanism 渠道列名

# scripts/research_framework/modern_did.py
from modern_did import ModernDiDEngine, DiDEstimationResult

# scripts/research_framework/robustness_runner.py
from robustness_runner import RobustnessRunner, RobustnessReport

# scripts/research_framework/iv_panel.py
from iv_panel import IVPanel

# scripts/research_framework/rdd.py
from rdd import RDDEngine

样本是否包含处理组/对照组？
│
├── 是 → 政策/处理时点是否单一？
│   ├── 是 → 经典 2×2 DID
│   │   ├── 单一处理队列 → 标准 DID (Angrist & Pischke 2009)
│   │   └── 多处理队列 → Callaway-SantAnna (QJE 2021) [推荐]
│   │       或 Sun-Abraham (REStud 2021)
│   │       或 Borusyak-Jaravel-Spinks (REStud 2024)
│   │       或 Gardner (2022) shock-free
│   │
│   └── 否 → 合成控制法 (Abadie et al. 2010)
│       或 合成 DID (Arkhangelsky et al. 2021)
│
└── 否 → 处理变量是否为连续型？
    ├── 是 → 断点回归 (RDD)
    │   ├── 精确 RDD
    │   └── 模糊 RDD (含 IV)
    │
    └── 否 → 工具变量法
        ├── 弱 IV 检验: Kleibergen-Paap rk F statistic
        └── 面板 GMM: Arellano-Bond / Blundell-Bond

## 处理组定义

| 标准 | 具体定义 | 数据来源 |
|------|----------|----------|
| 行业标准 | 属于 [具体行业代码] | CSMAR / Wind |
| 规模标准 | 总资产 > [阈值] 亿元 | CSMAR / Wind |
| 所有制标准 | 国有企业 / 民营企业 | CSMAR |
| 地区标准 | 位于 [省份/城市] | CSMAR |

## 对照组定义

对照组选择原则：
1. **行业匹配**：与处理组同行业
2. **规模相近**：与处理组规模相近（±20%）
3. **时间匹配**：同期上市
4. **排除标准**：剔除金融公司、ST公司、退市公司

## 时间窗口

| 阶段 | 时间范围 | 说明 |
|------|----------|------|
| 政策前期 | [YYYY-Q1] - [YYYY-Q4] | 平行趋势检验 |
| 政策当期 | [YYYY-Q1] | 政策实施时点 |
| 政策后期 | [YYYY-Q1] - [YYYY-Q4] | 长期效应分析 |

最小时间窗口：政策前后各 3 年
推荐时间窗口：政策前后各 5 年

# 变量定义表

## 被解释变量（Y）

| 变量名 | 中文名 | 定义 | 计算方式 | 数据来源 | 频率 | 预期符号 |
|--------|--------|------|----------|----------|------|----------|
| y_main | [主变量] | [经济学定义] | [计算公式] | [来源] | Annual | +/- |
| y_robust1 | [稳健性变量1] | ... | ... | ... | ... | +/- |
| y_robust2 | [稳健性变量2] | ... | ... | ... | ... | +/- |

## 核心解释变量（X）

| 变量名 | 中文名 | 定义 | 计算方式 | 数据来源 | 频率 | 预期方向 |
|--------|--------|------|----------|----------|------|----------|
| treat | 处理变量 | Treatment×Post | 虚拟变量 | 政策数据库 | - | + |
| treat_intensity | 处理强度 | [定义] | [计算] | 政策数据库 | Annual | + |
| x_main | [核心变量] | [定义] | [计算] | [来源] | ... | +/- |

## 控制变量

### 公司层面

| 变量名 | 中文名 | 定义 | 计算方式 | 数据来源 | 理由 |
|--------|--------|------|----------|----------|------|
| Size | 企业规模 | Ln(总资产) | Ln(总资产) | CSMAR/Wind | 规模效应 |
| Lev | 资产负债率 | 总负债/总资产 | 财务比率 | CSMAR/Wind | 资本结构 |
| ROA | 资产收益率 | 净利润/总资产 | 财务比率 | CSMAR/Wind | 盈利能力 |
| MB | 市值账面比 | 市值/账面价值 | 市场/账面 | CSMAR | 成长性 |
| Age | 企业年龄 | Ln(上市年限+1) | 年份计算 | CSMAR | 生命周期 |
| TOP1 | 股权集中度 | 第一大股东持股比例 | 持股比例 | CSMAR | 公司治理 |
| Dual | 两职合一 | 董事长兼总经理 | 虚拟变量 | CSMAR | 公司治理 |
| Board | 董事会规模 | 董事人数 | 人数 | CSMAR | 公司治理 |
| SOE | 所有制 | 国有企业 | 虚拟变量 | CSMAR | 所有制效应 |

### 宏观层面

| 变量名 | 中文名 | 定义 | 计算方式 | 数据来源 |
|--------|--------|------|----------|----------|
| GDP_g | GDP增速 | GDP同比增长率 | 同比 | 国家统计局 |
| M2_g | M2增速 | M2同比增长率 | 同比 | 央行 |
| CPI | 通胀率 | 消费者价格指数 | 同比 | 国家统计局 |
| HHI | 行业集中度 | Herfindahl 指数 | 计算 | CSMAR |

## 固定效应设置

| 固定效应 | 目的 | 是否加入 |
|----------|------|----------|
| 公司固定效应 (μᵢ) | 控制不随时间变化的个体异质性 | ✅ 必须 |
| 年度固定效应 (λₜ) | 控制共同时间趋势 | ✅ 必须 |
| 行业×年度 | 控制行业共同冲击 | ✅ 推荐 |
| 省份×年度 | 控制地区共同冲击 | ✅ 推荐 |
| 公司×行业趋势 | 控制公司特定趋势 | ⚠️ 可选 |

## 标准误聚类

| 聚类维度 | 理由 | 适用场景 |
|----------|------|----------|
| 公司层面 | 公司内观测相关 | 默认选项 |
| 公司×年度双维 | 既有个体内相关又有年间相关 | 标准做法 (CGM 2011) |
| 行业×年度 | 行业层面冲击相关 | 有明显行业效应时 |
| 省份×年度 | 省份层面冲击相关 | 地区政策研究 |

## 变量符号约定

```python
# Stata 变量命名规范
y_main = "innovation"           # 被解释变量
treat = "did"                    # DID 交互项
x_vars = ["size", "lev", "roa", "mb", "age", "top1", "dual", "board", "soe"]
macro_vars = ["gdp_g", "m2_g", "cpi"]
fe = "i.stock_code i.year"       # 固定效应
cluster = "stock_code"           # 聚类维度

---

# 阶段4：识别策略详细设计

## 4.1 DID 详细设计

### 平行趋势假设

**事件研究设计**（必须做）：
$$Y_{it} = \alpha + \sum_{k=-T}^{-2} \delta_k D_{it}^k + \sum_{k=0}^{K} \gamma_k D_{it}^k + \gamma \cdot X_{it} + \mu_i + \lambda_t + \varepsilon_{it}$$

其中 $D_{it}^k = Treatment_i \times 1(t = T_0 + k)$。

**平行趋势检验要点**：
- 政策前各期 ($k < 0$) 的系数 $\delta_k$ 应统计上不显著（置信区间包含0）
- 绘制 $\delta_k$ 的系数图（95%置信区间）
- 可使用 `modern_did.py` 的 `event_study_data()` 方法

### 交错 DID 特别注意事项

当存在多个处理时点时：

| 问题 | 解决方案 |
|------|----------|
| 不同处理时点导致处理状态定义不一致 | 使用 Callaway-SantAnna 组-时间 ATT |
| 早期处理组作为晚期处理组对照组 | Borusyak-Jaravel-Spinks 反事实推断 |
| 存在处理效应异质性 | Sun-Abraham 交互加权估计 |
| 处理效应随时间变化 | 事件研究 + 动态效应分解 |

### ModernDiDEngine 使用

```python
from modern_did import ModernDiDEngine

# 初始化
engine = ModernDiDEngine(
    df=data,
    y_var="innovation",           # 被解释变量
    treat_var="treatment",        # 处理组虚拟变量
    time_var="year",              # 时间变量
    unit_var="stock_code",        # 单位变量
    x_vars=["size", "lev", "roa", "mb", "age", "top1"],
    cluster_var="stock_code"      # 聚类变量
)

# 1. Callaway-SantAnna (推荐)
result_cs = engine.cs()
print(f"CS ATT: {result_cs.coef:.4f} (SE: {result_cs.se:.4f})")

# 2. Borusyak-Jaravel-Spinks
result_bjs = engine.bjs()
print(f"BJS ATT: {result_bjs.coef:.4f} (SE: {result_bjs.se:.4f})")

# 3. Sun-Abraham
result_sa = engine.sa()
print(f"SA ATT: {result_sa.coef:.4f} (SE: {result_sa.se:.4f})")

# 4. Goodman-Bacon 分解（诊断工具）
bacon_df = engine.bacon()
print(bacon_df)

# 5. 事件研究数据
event_study = engine.event_study_data(horizons=range(-5, 6))
engine.plot_event_study(estimator="cs", horizons=range(-5, 6), save_path="event_study.pdf")

# 6. Honest DiD (Rambachan-Roth 敏感性分析)
honest_result = engine.honest_did(m=0.5, delta_grid=None)
print(honest_result)

# 7. Wild Bootstrap
wild_result = engine.wild_bootstrap(n_boot=999, cluster_var="stock_code")
print(f"Wild Bootstrap ATT: {wild_result.coef:.4f} (p={wild_result.pval:.4f})")

from rdd import RDDEngine

# 初始化
rdd = RDDEngine(
    df=data,
    outcome="performance",        # 结果变量
    running="score",               # 跑分变量
    cutoff=0,                      # 断点位置
    treatment="treated"            # 处理变量
)

# 1. 带宽选择
bw_ik = rdd.bandwidth_ik()        # Imbens-Kalyanaraman 2012
bw_cct = rdd.bandwidth_cct()      # Calonico-Cattaneo-Titiunik 2014

# 2. 精确 RDD
sharp_result = rdd.sharp_rdd(bandwidth=bw_ik, kernel="triangular")

# 3. 模糊 RDD（需要工具变量）
fuzzy_result = rdd.fuzzy_rdd(instrument="fuzzy_inst", bandwidth=bw_ik)

# 4. McCrary 密度检验
mccrary = rdd.mccrary_test()
print(f"McCrary t-stat: {mccrary['t_stat']:.3f}, p-value: {mccrary['p_value']:.3f}")

# 5. 预先指定变量连续性检验
covariates = ["size", "lev", "age"]
for var in covariates:
    continuity_test = rdd.test_covariate_balance(var)
    print(f"{var}: p-value = {continuity_test['p_value']:.3f}")

from iv_panel import IVPanel

# 初始化
iv = IVPanel(
    df=data,
    y_var="innovation",            # 被解释变量
    instruments=["iv1", "iv2"],    # 工具变量列表
    x_vars=["size", "lev", "roa"]  # 外生控制变量
)

# 1. 第一阶段
first_stage = iv.first_stage()
print(f"First Stage F: {first_stage['f_stat']:.2f}")

# 2. 第二阶段
second_stage = iv.second_stage()
print(f"2SLS Coefficient: {second_stage['coef']:.4f}")

# 3. 弱工具变量检验
kp_f = iv.weak_instrument_test()
print(f"Kleibergen-Paap rk F: {kp_f:.2f}")  # > 10 表示非弱 IV

# 4. 过度识别检验（Sargan-Hansen）
overid = iv.overidentification_test()

# 5. 面板 GMM
gmm_result = iv.panel_gmm()

from synthetic_control import SyntheticControl

# 初始化
sc = SyntheticControl(
    df=data,
    treated_unit="treated_id",
    outcome_var="y",
    control_pool=["ctrl1", "ctrl2", "ctrl3", ...],
    time_var="year",
    treatment_time=2015
)

# 1. 合成控制
result = sc.fit()

# 2. 推断（置换检验）
placebo_results = sc.placebo_test(n_permutations=500)

# 3. 绘图
sc.plot(save_path="sc_results.pdf")

# 4. RMSPE 比率
rmspe_ratio = sc.rmspe_ratio()

# 合成 DID（Arkhangelsky et al. 2021）
from synthetic_did import SyntheticDID
sdid = SyntheticDID(
    df=data,
    treated_unit="treated_id",
    outcome_var="y",
    time_var="year",
    treatment_time=2015,
    control_pool=[...]
)
sdid_result = sdid.fit()