社科实证分析·通用版
> 免费 | 纯 Python | 离线 | 本科/硕士论文适用
⚠️ 重要说明：
- ✅ 支持：OLS、面板固定效应、logit、probit、poisson、2×2 DID
- ✅ 新增：HTML 交互式报告 + 诊断图表可视化
- ❌ 不支持：交错 DID（多地多时点，请用付费版）
- 📊 数据限制：≤ 10,000 行，≤ 50 列
- 📄 输出格式：HTML 报告（主要） + CSV 表格 + Markdown + JSON
快速开始（3 分钟上手）
1. 最简单：跑个回归（HTML 报告）
python cli.py --csv data.csv --y 收入 --x "教育 经验" --format html
输出：HTML 交互式报告（含系数表、诊断图表、显著性、R²）
2. 面板数据：固定效应
python cli.py --model fe --csv panel.csv --y wage --x education --id worker_id --time year
输出：双向固定效应 + 组内 R²
3. 政策评估：2×2 DID（★ 新增）
python cli.py --model did --csv policy.csv --y outcome --x policy \
--id city_id --time year --treat treated --post post_2020
输出：DID 系数 + 平行趋势检验 + 事件研究图
4. 二元选择：Logit
python cli.py --model logit --csv survey.csv --y purchase --x "price quality"
输出：Logit 系数 + Pseudo R² + 预测准确率
5. 不确定用哪个？让 AI 建议
python cli.py --csv data.csv --y outcome --x predictors --suggest
输出：根据数据特征推荐模型
✨ v1.0.5 新增功能
HTML 交互式报告
- 📊 专业设计：现代化界面，渐变色头部，响应式布局
- 📈 诊断图表：自动生成 VIF 柱状图、残差诊断、系数森林图、事件研究图
- 📝 使用建议：嵌入解读提示和方法说明
- 💾 单文件输出：图表 base64 嵌入，可直接分享
使用方法：
# OLS HTML 报告
python ols_cli.py --csv data.csv --y outcome --x "x1 x2 x3" --format html --outdir ./output
# DID HTML 报告
python did_cli.py --csv policy.csv --y outcome --did did_var \
--id city_id --time year --policy-year 2020 --outdir ./output
包含内容：
1. 核心结果汇总（R²、N、系数、显著性）
2. 系数表格（带星号 //**）
3. 系数森林图（置信区间可视化）
4. 残差诊断图（4合1：残差vs拟合值、QQ图、标准化残差、直方图）
5. VIF 诊断图（真实计算，颜色编码）
6. 使用建议和解读提示
诊断可视化
- ✅ VIF 真实计算：准确检测多重共线性
- ✅ 残差诊断：4合1图，全面检查假设
- ✅ 系数可视化：森林图展示置信区间
- ✅ 事件研究图：DID 平行趋势可视化
DID 独立 CLI
- ✅ 完整分析：2×2 DID + 平行趋势检验 + 事件研究
- ✅ 自动解读：DID 系数含义、显著性、平行趋势状态
- ✅ 方法说明：模型设定、关键假设、使用建议
- ✅ HTML 报告：专业格式，论文可用
可选依赖
- matplotlib >= 3.0（用于生成诊断图表）
- 安装：
pip install matplotlib - 无 matplotlib 时自动降级为 JSON/CSV 输出
何时使用这个 Skill
当你有一份社科数据（CSV 或 Excel），想快速跑通 OLS / 面板固定效应 / logit / probit / poisson / 基础 DID，生成一份带系数表、诊断、图表的实证分析报告时，用这个 skill。
典型场景
- "帮我评估 2020 年政策对城市 GDP 的影响（DID 分析）"
- "这份面板数据能做固定效应回归吗？控制城市和年份"
- "跑个 logit，看看哪些因素影响用户是否购买"
- "帮我做基础的实证分析，我有因变量 Y 和解释变量 X1、X2"
- "分析专利数量的影响因素（泊松回归）"
❌ 不适用场景
功能限制：
- ❌ 交错 DID（多地多时点政策，需要付费版）
- ❌ Stata 特定命令（reghdfe、ivreg2）
- ❌ 高级方法：工具变量（IV）、断点回归（RD）、PSM
- ❌ 复现他人的 do-file 或审计代码
- ❌ SSCI 二区审稿标准的自检报告
数据限制：
- ❌ 超过 10,000 行 或 50 列（会自动拒绝）
- ❌ 非结构化数据（文本、图像）
- ❌ 时间序列（需要特殊处理）
💡 如何判断：运行 --suggest 会自动告诉你适不适合
输入
必需
--input <file.csv>或<file.xlsx>：数据文件--y <列名>：因变量--x <列名,列名>：核心解释变量（逗号分隔）
可选
--model <ols|fe|logit|probit|poisson|did>：模型类型，默认ols--controls <列名,列名>：控制变量--id <列名>：个体 ID（FE/DID 必填）--time <列名>：时间变量（可选，用于双向 FE 或事件研究）--treat <列名>：处理组标识（DID 必填，0/1）--post <列名>：政策后标识（DID 必填，0/1）--event-window <-3,4>：事件研究窗口--cluster <列名>：聚类标准误（默认 FE/DID 用--id）--outdir <目录>：输出目录，默认./output--format <html,csv,md,json>：输出格式，默认全出--describe-only：只做数据体检，不建模
约束
- 数据行数 ≤ 10,000
- 列数 ≤ 50
- 纯数值/分类变量；日期需预处理成年份
- 缺失值自动删除（listwise）
输出格式（默认生成 4 种）
📊 1. HTML 报告（★ 主要输出，推荐）
文件：output/report.html
内容：
- ✅ 数据概览：行数、列数、缺失值统计
- ✅ 系数表：带星号、置信区间、格式化数字
- ✅ 诊断图表：
- OLS: VIF 柱状图、残差 QQ 图、异方差检验
- FE: 组内/组间变异、固定效应数量
- Logit: 预测概率分布、混淆矩阵
- ✅ 解读提示：每个指标的含义和阈值
优势：
- 浏览器直接打开，最直观
- 适合非技术人员
- 可直接截图放入报告
📋 2. CSV 表格（Excel 友好）
文件：
- output/coefficients.csv：系数表
- output/diagnostics.csv：诊断统计
用途：
- 直接在 Excel 打开
- 复制粘贴到论文表格
- 与其他结果合并
📝 3. Markdown（论文初稿）
文件：output/report.md
内容：纯文本格式的完整报告
用途：
- 复制到 Word/LaTeX
- 作为论文方法部分的草稿
- 版本控制友好
🔧 4. JSON（程序接口，可选）
文件：output/results.json
说明：
- ⚠️ 不是给人看的，是给程序用的
- 包含所有数值的机器可读格式
- 如果你不写代码，忽略这个文件
什么时候需要：
- 批量处理多个模型
- 与其他分析工具对接
- 自动化报告生成
💡 推荐工作流：
1. 运行命令 → 查看 report.html 了解结果
2. 需要表格 → 打开 coefficients.csv 复制到 Excel
3. 写论文 → 参考 report.md 撰写方法部分
示例
基础 DID
python cli.py \
--model fe \
--csv policy_data.csv \
--y gdp \
--x "policy population investment" \
--fe "city year" \
--cluster city
说明：
- DID 作为固定效应的特例，通过交互项 policy = treat × post 实现
- 系数解读：policy 的系数即为处理效应（ATT）
- 需检验平行趋势假设（事前趋势）
面板固定效应
python cli.py \
--model fe \
--csv panel.xlsx \
--y wage \
--x "education experience" \
--fe "worker_id year" \
--cluster worker_id
输出：
- 双向固定效应（个体 + 时间）
- 聚类稳健标准误
- Within R² 和 F 检验
Logit 二元选择
python cli.py \
--model logit \
--csv survey.csv \
--y purchase \
--x "price quality brand"
Poisson 计数回归
python cli.py \
--model poisson \
--csv patent_data.csv \
--y patent_count \
--x "rd_investment firm_size"
方法论说明
OLS（普通最小二乘）
模型：Y = Xβ + ε
假设：
- 线性关系
- 误差独立同分布
- 无完全多重共线性
- 误差与自变量不相关
适用：连续因变量、横截面数据
输出：
- 系数估计（β）
- HC1 稳健标准误
- R²、调整 R²
- VIF（多重共线性检验）
FE（固定效应）
模型：Y_it = α_i + X_it·β + ε_it
核心思想：吸收个体/时间不变的特征（α_i）
适用：
- 面板数据（多个个体、多个时期）
- 需要控制个体异质性
- 关注时间内变化的效应
输出：
- 组内（within）估计量
- 聚类标准误（默认聚类到个体）
- 固定效应 F 检验
Logit / Probit（二元选择）
Logit 模型：P(Y=1|X) = 1 / (1 + e^(-Xβ))
Probit 模型：P(Y=1|X) = Φ(Xβ)，Φ 为标准正态 CDF
适用：二元因变量（0/1，是/否）
解读：
- 系数不能直接解释为边际效应
- 正系数 → 增加 Y=1 的概率
- 负系数 → 降低 Y=1 的概率
输出：
- 系数估计
- Pseudo R²（McFadden）
- 预测准确率
Poisson（泊松回归）
模型：E(Y|X) = e^(Xβ)
适用：计数因变量（专利数、发文量、事件次数）
假设：均值 = 方差（等离散）
注意：
- 如果过度离散（方差 > 均值），使用 --nbreg（负二项）
- 系数解释：e^β - 1 = X 增加 1 单位时 Y 的百分比变化
DID（双重差分）
模型：Y = β₀ + β₁·treat + β₂·post + β₃·(treat×post) + ε
核心假设：平行趋势（处理前，处理组和对照组趋势相同）
β₃ 解释：处理效应（ATT）
检验：
- 平行趋势：事前系数联合检验
- 事件研究：估计每个时期的处理效应
- 安慰剂检验：假装政策提前实施
常见问题（FAQ）
Q1：什么时候用 OLS，什么时候用 FE？
OLS：
- 横截面数据（一次调查）
- 个体间比较
- 示例：不同城市的 GDP 与教育水平
FE：
- 面板数据（多年观测）
- 需要控制个体固定特征
- 示例：同一城市多年 GDP 变化
Q2：DID 的平行趋势假设如何检验？
方法 1：事件研究图
--event-window -3,4
- 观察政策前系数是否显著（应不显著）
- 事前趋势越平行越好
方法 2：联合检验
- 输出会自动报告事前系数的 F 检验
- p > 0.05 → 通过平行趋势检验
Q3：标准误选择：稳健、聚类还是普通？
横截面数据：
- 使用 HC1 稳健标准误（默认）
- 应对异方差
面板数据：
- 聚类到个体（--cluster id）
- 应对个体内相关
DID：
- 聚类到处理单元（通常是地区/企业）
- 应对组内相关
Q4：出现"完全分离"（perfect separation）怎么办？
原因：Logit/Probit 中，某个自变量完全预测因变量
解决：
1. 检查数据：是否有常量列
2. 增加样本量
3. 考虑用 OLS（线性概率模型）
Q5：VIF（方差膨胀因子）多高算高？
阈值：
- VIF < 5：可接受
- 5 < VIF < 10：需注意
- VIF > 10：严重多重共线性
解决：
- 删除高度相关的变量
- 使用主成分分析
- 使用岭回归（付费版）
Q6：什么情况需要用付费版？
需要高级方法：
- 工具变量（IV）：处理内生性
- 断点回归（RD）：政策断点评估
- 倾向得分匹配（PSM）：选择偏误
- 交错 DID：多地多时点政策
需要 Stata：
- reghdfe（高维固定效应）
- ivreg2（工具变量）
- did_multiplegt（交错 DID）
需要复现审计：
- 自动读取他人 do-file
- 判定依赖和可行性
- 生成复现状态卡
🆘 遇到问题？统一排查指南
报错：找不到列名
❌ 找不到列：wrong_column
原因：列名拼写错误或不存在
解决：
1. 查看错误提示中的"可用列"列表
2. 复制粘贴列名（避免手打错误）
3. 注意大小写和空格
报错：数据类型不匹配
❌ 列 'outcome' 不是二元变量（0/1）
原因：Logit/Probit 要求因变量是 0/1
解决：
1. 检查因变量值：print(data['outcome'].unique())
2. 转换为 0/1：data['outcome'] = (data['outcome'] == '是').astype(int)
3. 或改用 OLS 线性概率模型
报错：回归失败（秩亏）
❌ 回归失败：rank deficient at column 3
原因：完全多重共线性（某变量是其他变量的线性组合）
解决：
1. 检查是否有常数列：data.describe()
2. 检查高度相关变量：运行后查看 VIF
3. 删除冗余变量
4. 使用 --suggest 查看建议
警告：样本量过小
⚠️ 样本量较小（n=25，建议 ≥ 30）
影响：结果可能不稳定，p 值不可靠
建议：
1. 增加样本量（推荐 ≥ 100）
2. 谨慎解释结果
3. 报告时说明样本量限制
警告：缺失值
⚠️ 检测到缺失值：gdp_pc: 5 个 (0.5%)
处理：自动删除包含缺失值的行（listwise deletion）
注意：
- 如果缺失过多（> 10%），考虑插补
- 检查缺失是否有规律（可能导致选择偏误）
输出格式问题
问题：JSON 格式看不懂
解决：
- 主要看 HTML：output/report.html（浏览器打开）
- Excel 用户：output/coefficients.csv（直接打开）
- 论文初稿：output/report.md（复制粘贴）
- JSON 是给程序用的，不是给人看的
数据超限
❌ 数据行数超过 10,000 行限制
解决：
1. 抽样：data.sample(10000)
2. 使用付费版（支持大数据）
3. 分组分析
还是不行？
- 使用
--suggest检查数据是否适合 - 查看完整错误信息（不要只看第一行）
- 在 SkillHub 评论区描述问题（附上错误信息）
输出解读指南
系数星号含义
***p < 0.01（1% 显著性）**p < 0.05（5% 显著性）*p < 0.10（10% 显著性）
R² 和 Pseudo R²
OLS R²：
- 0.3-0.5：社科常见水平
- > 0.7：较高拟合度
Logit Pseudo R²：
- 0.2-0.4：较好拟合
- 不能与 OLS R² 直接比较
p 值解读
- p < 0.05：统计显著（拒绝零假设）
- p > 0.05：不显著（不能拒绝零假设）
- 注意：显著 ≠ 重要，需结合系数大小和实际意义
限制与建议
当前限制
- 数据规模：≤ 10,000 行（大数据用付费版 Stata）
- 基础 DID：只支持 2×2 设计；交错 DID（多地多时点）需付费版
- 无高级方法：IV/RD/PSM/合成控制需付费版
- 报告是初稿：给出系数和诊断，识别策略需自行撰写
使用建议
- 先描述性统计：使用
--describe-only了解数据 - 检查假设：查看诊断报告（VIF、异方差、平行趋势）
- 稳健性检验：
- 更换控制变量
- 子样本分析
- 更换标准误类型 - 结果解读：结合系数大小、显著性和实际意义
技术规格
- 编程语言：纯 Python（无第三方依赖）
- 核心算法：QR 分解、IRLS（迭代加权最小二乘）
- 数值稳定性：秩亏检测、条件数监控
- 可重复性：确定性算法，相同输入必得相同输出
- 安全性：无网络调用、无代码执行、所有输出转义
版本信息
- 当前版本：1.0.5
- 发布日期：2024-10-22
- 代码量：2,343 行（engine.py 728行 + 新增模块 1,500行 + CLI增强）
- 更新内容：
- v1.0.5: ✅ HTML 交互式报告 + 诊断图表可视化（VIF/残差/系数森林图/事件研究图）+ DID 独立 CLI + 进度条模块
- v1.0.4: 启用 2×2 DID 功能 + 扩展数据限制到 10,000 行
- v1.0.3: 明确能力边界、添加快速入门、统一错误处理页面
- v1.0.2: 友好错误提示、自动输入验证、模型选择建议
- v1.0.1: 补充方法论说明、FAQ
- v1.0.0: 首次发布，支持 OLS/FE/Logit/Probit/Poisson
升级到付费版
社科实证分析·专业版（敬请期待）
未来将提供以下功能：
- ✅ Stata 运行时（云端或本机）
- ✅ 高级方法：IV/RD/PSM/交错 DID/合成控制
- ✅ 复现审计：自动读取 do-file，判定可行性
- ✅ 顶刊对照：与 SSCI 论文 baseline 表格对比
- ✅ SSCI 审稿标准：稳健性检验建议、识别策略自检
使用交流：欢迎在 SkillHub 评论区交流使用心得
