statsmodels

Statsmodels：统计建模与计量经济学

概述

Statsmodels 是 Python 中首屈一指的统计建模库，提供涵盖广泛统计方法的估计、推断和诊断工具。无论是简单线性回归，还是复杂的时间序列模型和计量经济学分析，都可以使用此技能进行严谨的统计分析。

当前兼容性

示例面向 statsmodels 0.14.6，该版本于 2025 年 12 月 5 日发布。为确保环境可复现，请固定主要软件包版本：

uv pip install statsmodels==0.14.6

使用 statsmodels.api 和 statsmodels.formula.api 进行稳定的高层级导入；当示例需要 HurdleCountModel 等较新或专用类时，则直接导入相应模块。

适用场景

在以下情况下应使用此技能：

• 拟合回归模型（OLS、WLS、GLS、分位数回归）
• 执行广义线性建模（逻辑回归、Poisson、Gamma 等）
• 分析离散结果（二元、多项、计数、有序）
• 进行时间序列分析（ARIMA、SARIMAX、VAR、预测）
• 运行统计检验和诊断
• 检验模型假设（异方差、自相关、正态性）
• 检测异常值和高影响观测值
• 比较模型（AIC/BIC、似然比检验）
• 估计因果效应
• 生成可直接用于发表的统计表格和推断结果

快速入门、功能与模型选择

• references/quick_start_guide.md：OLS、逻辑回归、ARIMA 和 GLM 的简明示例，以及如何阅读摘要。
• references/modeling_capabilities.md：线性模型、GLM、离散选择、时间序列，以及统计检验和诊断。
• references/model_selection.md：R 风格的公式 API 和模型比较。
• 各主题详情：references/linear_models.md、 references/glm.md、 references/discrete_choice.md、 references/time_series.md 和 references/stats_diagnostics.md。

statsmodels 用于推断——标准误、置信区间和假设检验。当目标是预测，且无需解释系数时，应选择 scikit-learn。

最佳实践

数据准备

1. 始终添加常数项：除非要排除截距，否则使用 sm.add_constant()
2. 检查缺失值：拟合前进行处理或插补
3. 按需缩放：有助于收敛和解释（但树模型不需要）
4. 编码分类变量：使用公式 API 或手动进行虚拟变量编码

模型构建

1. 从简单模型开始：先建立基础模型，再按需增加复杂度
2. 检查假设：检验残差、异方差和自相关
3. 使用合适的模型：根据结果类型选择模型（二元→Logit，计数→Poisson）
4. 考虑替代方案：若假设不成立，则使用稳健方法或其他模型

推断

1. 报告效应量：不要只报告 p 值
2. 使用稳健标准误：存在异方差或聚类时使用
3. 多重比较：检验多个假设时进行校正
4. 置信区间：始终与点估计一并报告

模型评估

1. 检查残差：绘制残差与拟合值图、Q-Q 图
2. 影响诊断：识别并调查高影响观测值
3. 样本外验证：在留出集上测试或进行交叉验证
4. 比较模型：非嵌套模型使用 AIC/BIC，嵌套模型使用 LR 检验

报告

1. 提供全面摘要：使用 .summary() 获取详细输出
2. 记录决策：注明变换方式和排除的观测值
3. 谨慎解读：考虑链接函数（例如，log 链接对应 exp(β)）
4. 可视化：绘制预测值、置信区间和诊断图

常见工作流

工作流 1：线性回归分析

1. 探索数据（绘图、描述性统计）
2. 拟合初始 OLS 模型
3. 检查残差诊断
4. 检验异方差和自相关
5. 检查多重共线性（VIF）
6. 识别有影响力的观测值
7. 如有需要，使用稳健标准误重新拟合
8. 解读系数和推断结果
9. 在留出集上验证，或通过交叉验证（CV）验证

工作流 2：二元分类

1. 拟合逻辑回归（Logit）
2. 检查收敛问题
3. 解读优势比
4. 计算边际效应
5. 评估分类性能（AUC、混淆矩阵）
6. 检查有影响力的观测值
7. 与替代模型（Probit）比较
8. 在测试集上验证预测结果

工作流 3：计数数据分析

1. 拟合泊松回归
2. 检查过度离散
3. 如果存在过度离散，则拟合负二项回归
4. 检查零值过多的情况（考虑 ZIP/ZINB）
5. 解读率比
6. 评估拟合优度
7. 通过 AIC 比较模型
8. 验证预测结果

工作流 4：时间序列预测

1. 绘制序列图，检查趋势/季节性
2. 检验平稳性（ADF、KPSS）
3. 对非平稳序列进行差分
4. 根据 ACF/PACF 确定 p、q
5. 拟合 ARIMA 或 SARIMAX
6. 检查残差诊断（Ljung-Box）
7. 生成带置信区间的预测
8. 在测试集上评估预测准确性

参考文档

此技能包含全面的参考文件，提供详细指导：

references/linear_models.md

线性回归模型的详细介绍，包括：

• OLS、WLS、GLS、GLSAR、分位数回归
• 混合效应模型
• 递归回归和滚动回归
• 全面的诊断（异方差、自相关、多重共线性）
• 影响统计量和离群值检测
• 稳健标准误（HC、HAC、聚类）
• 假设检验和模型比较

references/glm.md

广义线性模型完整指南：

• 所有分布族（二项分布、泊松分布、伽马分布等）
• 链接函数及其适用场景
• 模型拟合和解读
• 伪 R 平方和拟合优度
• 诊断和残差分析
• 应用（逻辑回归、泊松回归、伽马回归）

references/discrete_choice.md

离散结果模型综合指南：

• 二元模型（Logit、Probit）
• 多项模型（MNLogit、Conditional Logit）
• 计数模型（泊松、负二项、零膨胀、门槛模型）
• 有序模型
• 边际效应和解读
• 模型诊断和比较

references/time_series.md

深入的时间序列分析指南：

• 单变量模型（AR、ARIMA、SARIMAX、指数平滑）
• 多变量模型（VAR、VARMAX、动态因子）
• 状态空间模型
• 平稳性检验和诊断
• 预测方法和评估
• 格兰杰因果关系、IRF、FEVD

references/stats_diagnostics.md

全面的统计检验和诊断：

• 残差诊断（自相关、异方差、正态性）
• 影响和离群值检测
• 假设检验（参数和非参数）
• 方差分析和事后检验
• 多重比较校正
• 稳健协方差矩阵
• 功效分析和效应量

参考时机：

• 需要详细的参数说明
• 在相似模型之间进行选择
• 排查收敛或诊断问题
• 理解特定检验统计量
• 查找高级功能的代码示例

搜索模式：

# Find information about specific models
rg "Quantile Regression" references/

# Find diagnostic tests
rg "Breusch-Pagan" references/stats_diagnostics.md

# Find time series guidance
rg "SARIMAX" references/time_series.md

常见陷阱及规避方法

1. 忘记常数项：除非不需要截距项，否则始终使用 sm.add_constant()
2. 忽略假设：检查残差、异方差和自相关
3. 因变量类型与模型不匹配：二元变量→Logit/Probit，计数变量→Poisson/NB，而非 OLS
4. 未检查收敛情况：留意优化警告
5. 误解系数：记住链接函数（log、logit 等）
6. 在过度离散时使用 Poisson：检查离散程度，必要时使用负二项模型
7. 未使用稳健标准误：存在异方差或聚类时使用
8. 过拟合：相对于样本量，参数过多
9. 数据泄漏：在测试数据上拟合，或使用未来信息
10. 未验证预测结果：始终检查样本外表现
11. 比较非嵌套模型：使用 AIC/BIC，而非 LR 检验
12. 忽略有影响力的观测值：检查 Cook 距离和杠杆值
13. 多重检验：检验多个假设时校正 p 值
14. 未对时间序列做差分：在非平稳数据上拟合 ARIMA
15. 混淆预测区间与置信区间：预测区间更宽

获取帮助

详细文档和示例：

• 官方文档：https://www.statsmodels.org/stable/
• 用户指南：https://www.statsmodels.org/stable/user-guide.html
• 示例：https://www.statsmodels.org/stable/examples/index.html
• API 参考：https://www.statsmodels.org/stable/api.html

Agent 操作流程

1. 检查环境。 确认 Python 环境和库版本（python -c "import pkg; print(pkg.__version__)"），并检查数据的形状、类型和缺失值。
2. 明确输入。 从数据或用户处确认格式、标识符和参数。对于任何会影响结果的值，应先询问，而非猜测。
3. 先运行小规模版本。 先在样本或单个折上运行，并检查运行时间和内存。
4. 根据上述说明和参考资料执行完整任务。
5. 验证结果。 使用留出数据、固定随机种子和适当的指标；检查是否存在数据泄漏；报告不确定性（置信区间、不同随机种子的标准差）。
6. 报告。 说明运行内容（版本、命令、参数）、检查内容以及仍不确定的事项。

如果发生这种情况	请这样做
内存不足或执行过慢	对数据进行子采样，使用分块或惰性计算，或缩小模型规模，并告知用户所做的更改。
当前安装的版本中缺少这些说明里提到的函数、标志或端点	查阅已安装版本自身的文档（help()、--help、官方文档），调整方案并告知用户。切勿编造 API。
必需的输入、标识符或参数存在歧义	询问用户，或在运行前明确说明所做的假设。

诚信准则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 切勿报告本次会话中未计算的指标；应展示生成每个数值的代码路径。
• 将此处与特定版本相关的细节视为可能已过时：请对照已安装版本的官方文档进行确认。
• 对于需要付费、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须先征得用户同意。

相关技能

• statistical-analysis：面向研究数据的引导式统计分析——检验选择、假设检查、效应量、功效分析、贝叶斯替代方法等。
• timesfm-forecasting：使用 Google 的 TimesFM 基础模型进行零样本时间序列预测。
• aeon：用于时间序列机器学习任务，包括分类、回归、聚类、预测、异常检测等。