sports-modeling-doctrine

体育建模准则

结果

在获取数据或拟合模型之前，先撰写建模章程。章程由用户拥有，是关于问题、目标、时间、评估方式和完成标准的唯一事实来源。

编写代码前，先确定科学约定：

• 要回答什么问题；
• 每一行代表什么；
• 在决策时点可以知道什么；
• 什么基线可作为价值的证据；
• 如何在时间外评估成功与否；
• 什么结果会导致接受、修改或停止。

如果未明确这些字段，就不要拟合模型。

何时使用此技能

在开始或重新界定体育分析、确定“好”的标准、审查结果是否可评估，或防止探索性工作悄然演变为预测性声明时使用。

完成章程后，仅使用相关的专门技能：用于数据获取的公开来源加载器、用于理解数据的 eda-sports、用于构建时间安全预测变量的 feature-rules、用于参考模型的 baseline-models，以及相关的统计、预测、评级、模拟或验证技能。

问题类型

类型	核心问题	所需证据	常见的过度推断
描述性	发生了什么？	覆盖范围、分母、不确定性	将样本视为涵盖所有时期／总体
解释性	哪些因素相关？	设计、效应、不确定性、混杂因素限制	使用因果措辞
预测性	时间 T 之后会发生什么？	时间安全的输入和有序留出集	将系数解释为原因
因果性	干预后会发生什么变化？	识别策略和假设	仅依靠预测
排名	截至 T 谁最强？	未来效用、赛程背景、排名稳定性	将点估计排名视为确定结果
模拟	根据假设会出现怎样的分布？	经校准的输入和敏感性分析	将模拟精度报告为观测事实

不要混淆解释性成功与预测性成功。稳定的相关性未必能改善预测，而有用的预测变量也未必能确定因果机制。

章程工作流

1. 用一句话写明问题。
2. 指明运动项目、赛事、总体、时期和排除项。
3. 定义数据粒度：比赛、球队－比赛、球员－比赛、控球回合、比赛回合、投球或其他。
4. 使用上表对分析类型进行分类。
5. 对于预测、排名或前瞻性模拟工作，准确定义决策时点 T 和预测范围。
6. 定义目标或估计量、单位、标签规则，以及平局或结果缺失时的处理方式。
7. 记录基础发生率、零假设期望或现行流程。
8. 至少指定一个朴素基线和一个强而简单的基线。
9. 在拟合前锁定主要指标及其方向。
10. 选择遵循事件、赛季和数据可用时间顺序的验证方法。
11. 定义数据要求、最低覆盖范围和来源标准。
12. 写明接受、失败、修改和停止条件。
13. 记录范围外的决策和不支持的用途。

数据粒度与决策时间约定

对于每个拟使用的字段，都要能够回答：

row grain: <what one row represents>
entity/event key: <natural key>
decision time T: <timestamp or event boundary>
forecast horizon: <what future interval is predicted>
feature available by T: <yes/no and source timestamp>
target observed after T: <yes/no>
paired/dependent rows: <shared games, players, series, seasons>

体育数据中经常包含成对的球队－比赛行、赛后摘要、修订后的伤病报告、赛季结束后的汇总数据，以及在赛事结束后更新的评级。列名不能证明数据当时可用。请定义截至时点规则。

基线阶梯

级别	示例	用途
零模型	训练集中的固定发生率或历史均值	证明模型优于不区分情况的做法
结构型	场地指标、先前排名，或按背景划分的联赛平均值	捕捉显而易见的领域结构
强而简单	滞后状态、简单评级，或正则化线性／逻辑回归模型	检验复杂度是否值得其成本
现行模型	当前实际使用的预测或公开参考	衡量实际替代价值

在调整候选模型前，锁定基线定义、训练窗口和缺失数据处理方式。所有模型都必须在完全相同的留出行上评分。

指标默认值

目标	主要候选指标	基线	重要的次要证据
二元结果	对数损失、Brier 分数	流行率、场馆／简单评分	校准情况和各折表现差异
分差／连续值	MAE、RMSE	历史均值或简单评分	残差分布和区间覆盖率
计数	Poisson 偏差、MAE	历史计数均值	离散程度和零值表现
事件发生时间	合适的生存评分／一致性指数	简单生存估计	按时间跨度划分的校准情况
排名	与未来结果的相关性或效用	先前排名／评分	排名稳定性和不确定性
模拟	分布评分或覆盖率	简单经验分布	对假设的敏感性

对于概率预测，仅有准确率很少足够。应让指标与决策相匹配，明确指标的方向，并且仅在真正留出的数据上计算。

验证默认值

按时间排序的体育赛事通常需要扩展窗口或滚动起点验证。默认的赛季前向验证设计是：用 s 赛季之前的赛季训练，并在 s 赛季评估。当某项运动没有明确的赛季划分时，应按赛事时间切分，并在标签／特征存在重叠时明确设置间隔或封锁期。

随机打乱行不是默认做法，因为这可能将未来的阵容、球队实力、赛程和特征信息混入训练集。应将同一场比赛分在一起，并在估计不确定性时考虑球队或球员的重复出现。

验收和停止规则

通常只有满足以下条件，预测候选方案才值得保留：

• 在平均主要指标上优于已锁定的基线；
• 在大多数符合条件的折上都有提升，或有合理的汇总结果；
• 通过时间安全性和数据泄漏检查；
• 当报告概率时，避免出现灾难性的校准问题；
• 在相关的时代、球队、球员或赛事切片中仍然有用；
• 其复杂度和维护负担是合理的。

对于解释性工作，要求效应方向稳定、不确定性表述诚实且结论范围有限。对于模拟，要求输入经过校准并进行敏感性分析。

设定验收规则时，请阅读 references/good_enough.md。当规则得到满足、失败条件使工作无效，或进一步增加复杂度无法带来实质性的留出数据价值时，就应停止。

章程架构

question
sport_and_competition
population_and_exclusions
grain_and_natural_key
analysis_type
decision_time_and_horizon
target_or_estimand
base_rate_or_null
naive_and_strong_baselines
primary_metric_and_direction
secondary_metrics
validation_design
data_requirements_and_provenance
uncertainty_plan
acceptance_rule
failure_and_stop_conditions
out_of_scope_and_prohibited_uses
required_artifacts

章程示例

赛前球队获胜概率

Question: Do venue and shifted form improve P(team wins)?
Sport/population: NFL completed regular-season games, 2018-2024
Grain: team-game; two paired rows per contest
Decision time: scheduled kickoff
Target: won; ties reported separately
Baselines: constant training prevalence; venue-only logistic
Primary metric: held-out log-loss, lower is better
Validation: season walk-forward; contest rows remain together
Acceptance: beat both baselines in mean and at least five of seven folds
Failure: any feature not provably available before kickoff
Out of scope: causal claims and wagering profitability

球员下一场比赛计数

Question: Predict a starter's strikeouts in the next start.
Grain: player-game
Decision time: first pitch
Target: strikeouts in that start
Baselines: trailing shifted mean; opponent strikeout-allowed mean
Primary metric: MAE
Validation: date walk-forward with player histories truncated at T
Cold start: separate rule and reporting slice

请阅读 references/charter_examples.md，了解更多简明的 NFL、NBA 和 MLB 模式。

不可妥协的要求和诚信规则

1. 时间顺序很重要；随机打乱赛事需要明确说明理由。
2. 对前瞻性主张而言，特征必须在 T 时点可用。
3. 必须先定义基线，再定义候选模型。
4. 查看测试折之前，必须锁定主要指标。
5. 粒度变更需要明确的聚合方式和键验证。
6. 候选方案和基线必须使用完全相同的留出样本。
7. 记录失败和未提升的结果，并将其视为有效结果。
8. 强主张需要经过数据泄漏审计，并诚实说明不确定性。
9. 公开数据并不能免除来源、许可或快照方面的责任。
10. 不得在出现有利结果后悄然扩大范围。
11. 使用满足章程要求的最简单模型。
12. 在临时聊天之外记录决策和产物。

反模式

• 在定义决策前就选择算法；
• 特征混杂，却没有可用时间戳；
• 把一个热门赛季称为“泛化”；
• 在看到留出结果后更改主要指标；
• 将每行球队—比赛记录都当作独立比赛；
• 对赛程或规则不同的运动照搬相同假设；
• 在熟悉测试窗口后仍继续调参；
• 复杂模型虽然胜过零模型，却未胜过强而简单的基线，就宣称获胜；
• 没有校准计划就生成概率。

Helper

python <path-to-sports-modeling-doctrine>/scripts/print_charter_template.py \
  --out data/modeling_charter.md

在数据采集或拟合之前，填写用户所有的模板。该助手不会替用户选择问题、基线或验收规则。

操作与交接规则

• 仅使用与章程相关的技能；每项技能都必须能够独立使用。
• 在采集、分析和报告步骤之间传递明确的用户所有制工件。
• 当有理据的范围决策发生变化时，及时更新章程。
• 应重新制定章程，而不是悄悄更改目标、粒度或决策时间。
• 如果无法确定时机、粒度、溯源或评估，请报告阻塞因素。

如需选择性地进行后续路由，请阅读 references/skill_path.md。这是决策辅助材料， 并非要求调用其中列出的每项技能。

输出约定

返回或保存已完成的章程，其中包含问题、类型、运动项目/人群、 粒度/键、决策时间、目标、基线、主要指标、验证、 不确定性、验收/失败规则、范围外用途和必需工件。 没有这份约定时，不要给出算法建议。

资源

• references/charter_examples.md — 阅读运动项目和特定目标的章程示例。
• references/good_enough.md — 定义验收、失败和停止规则时阅读。
• references/skill_path.md — 章程完成后，选择可选的专家交接时阅读。
• scripts/print_charter_template.py — 可移植的章程编写器。