calibration-check

校准检查（体育）

概述

模型可以很好地为球队排名，但仍可能校准不佳。如果模型给出的概率是 30%， 那么大约 30% 的此类情况应当命中。

此技能用于衡量体育模型的概率可靠性，并支持基于评估溯源、不确定性和 分段稳定性的人工审核结论。

区分度指标（AUC、准确率）不能替代校准。

---

何时使用此技能

适用于以下情况：

• 模型输出胜率／事件概率
• 用户询问概率有多可信／可靠
• 概率模型完成滚动评估后
• 撰写引用概率数值的结果之前
• 比较原始概率与重新校准后的概率
• 针对特定体育项目和赛事的概率产物

以下情况不要使用：

需求	请改用
不涉及概率解释的纯排名任务	排名／评估技能
仅有硬标签、没有概率输出	仅使用分类指标
从头设计数据划分	validation-design
特征合法性审查	leakage-audit
仅预测分差、没有概率的模型	MAE/RMSE 报告

---

安装

捆绑脚本需要 pandas：

python -m pip install pandas

Parquet 输入还需要 pyarrow 或 fastparquet。两个脚本都接受 CSV、 Parquet、JSON、JSONL 和 NDJSON，并且无需导入 pandas 即可使用 --help。

---

衡量内容

1. 可靠性／校准曲线 — 将预测概率分箱并与观测频率比较
2. 期望校准误差（ECE）
3. Brier 分数（必要时进行可靠性／分辨率分解）
4. 对数损失 — 同时体现区分度和校准；不能替代 ECE
5. 分段校准 — 按赛季、主／客场、概率尾部划分
6. 锐度 — 概率是否具有信息量，而非都接近 0.5？

解读 ECE、Brier 分数、对数损失或锐度时，请阅读 calibration_metrics.md。选择分箱边界 或最小计数前，请阅读 binning.md。拟合 Platt、等距回归 或其他概率校正方法前，请阅读 recalibration.md。

---

工作流

1. 确认预测来自时间安全／滚动交叉验证折。
2. 验证概率位于 [0, 1] 范围内；统计所有排除的行。
3. 预先声明分箱方式（固定宽度或分位数）。
4. 计算曲线、ECE、Brier 分数和对数损失。
5. 按赛季和概率尾部切片分析。
6. 给出结论（见下表）。
7. 如需重新校准，只能使用嵌套／训练集内的适当方法——绝不能在最终测试折上拟合等距回归后就称其已通过验证。
8. 将校准报告写入实验日志／结果说明。

---

结论等级

结论	含义
well-calibrated	可靠性足以支持引用概率
usable-with-caveats	存在一定校准偏差；应披露和／或以适当方式重新校准
poorly-calibrated	概率数值不值得作为概率信任
invalid-eval	泄漏／划分问题导致无法作出判断

这些结论依据的是完整方法，而非单一的 ECE 阈值。 给出结论前，请确认预测确实来自留出数据且采用滚动评估，检查不确定性和非空分箱的计数，比较不同赛季或折，检查与决策相关的分段，并记录预测来源。 不存在能证明概率可信的通用 ECE 截止值。

在留出集预测产物上运行

输入必须包含每个评估决策对应的一行、一个二元结果，以及一个介于 [0, 1] 之间的概率。

本工具包基线辅助程序推荐的可移植名称：

• 结果：y_true
• 概率：p_pred（也会输出为 logistic_probability）

# After baseline-models/scripts/run_baselines.py --predictions-out ...
python /path/to/calibration-check/scripts/calibration_report.py \
  --input baseline-predictions.csv --target y_true --probability p_pred \
  --group-col season --bins 10 --out calibration.json

python /path/to/calibration-check/scripts/calibration_report.py \
  --input predictions.csv --target won --probability win_probability \
  --group-col season --bins 10 --out calibration.json

python /path/to/calibration-check/scripts/segment_calibration.py \
  --input predictions.csv --target won --probability win_probability \
  --segment-col is_home

如果每场比赛只采用主队视角作为实际评估单位，请对对称的球队比赛产物使用 --filter-col is_home --filter-value 1。不要对同一事件的双方重复计数。

calibration_report.py 返回 Brier 分数、对数损失、ECE、可靠性分箱计数、行数统计、可选的分组指标，以及保守的 manual-review-required 辅助判定。该脚本无法证明留出集来源，也无法将有利的汇总 ECE 转化为 well-calibrated；分析人员必须应用上述判定等级。segment_calibration.py 会输出全行、分类分段、概率尾部指标和稀疏分箱计数。

---

分箱指南

策略	适用场景
等宽分箱（10 个分箱，范围 0–1）	体育赛事胜率的默认选择
分位数分箱	概率集中在较窄范围内
尾部聚焦（0–0.2、0.8–1.0）	决策集中在极端区间

务必报告分箱计数。空分箱不能作为证据。

---

重新校准规则

允许

• 仅在训练折内拟合 Platt scaling / isotonic，并应用于测试折
• 嵌套式滚动前向重新校准

不允许

• 在最终测试标签上拟合 isotonic，并称其经过验证
• 查看结果后手动编辑概率

重新校准后，在真实的前向折上重新报告 ECE/Brier。

---

硬性约束

1. 未进行嵌套说明时，绝不可在用于拟合相同模型的训练行上评估校准度。
2. 未检查校准度时，绝不可将原始分数作为概率呈现。
3. 绝不可用汇总结果“看起来不错”来掩盖分段失效。
4. 如果每个分箱的样本量很小，请明确说明——扩大分箱范围或降低结论强度。
5. 准确率不等于校准度。
6. 存在泄漏问题的评估不能称为 well-calibrated。

---

反模式

• “正确率为 56%，所以校准良好”
• 没有样本量信息的可靠性图
• 留出集 isotonic 作秀
• 平均概率 ≈ 基准率，因此校准良好（这是必要条件，而非充分条件）
• 忽略 0.05 和 0.95 尾部
• 不考虑特定运动项目的校准情况，就引用 NBA/MLB 百分比

---

报告模板

Calibration report
Sport/model:
Eval: walk-forward seasons …
n:
Brier:
ECE (bins=…):
Log-loss:
Notes by season:
Tail behavior:
Verdict: well-calibrated | usable-with-caveats | poorly-calibrated | invalid-eval
Actions:
Reproduce:

---

输出要求

完成意味着：

• 使用了滚动前向概率
• 报告了 ECE/Brier/对数损失
• 提供了分箱计数或分段说明
• 给出了判定
• 说明了后续措施

---

示例

python /path/to/calibration-check/scripts/calibration_report.py \
  --input held-out-predictions.csv --target y_true \
  --probability logistic_probability --group-col season \
  --bins 10 --out calibration.json

python /path/to/calibration-check/scripts/segment_calibration.py \
  --input held-out-predictions.csv --target y_true \
  --probability logistic_probability --segment-col is_home

示例发现：接近 0.70 的预测落在稀疏分箱中，实际结果接近 0.60。根据不确定性，将尾部标记为不稳定或过度自信；不要根据少量行推断出持久性缺陷。

---

随附资源

references/

文件	内容
calibration_metrics.md	ECE/Brier/对数损失定义
binning.md	分箱策略说明
recalibration.md	允许的重新校准模式

scripts/

文件	内容
calibration_report.py	针对所提供预测行生成描述性校准 JSON；必须在外部验证来源
segment_calibration.py	主队/客队和尾部分段

---

相关技能

需求	技能
验证设计	validation-design
预测模型	predictive-modeling
统计模型	statistical-modeling
结果撰写	results-reporting
模型卡	model-card

---

快速命令卡

python /path/to/calibration-check/scripts/calibration_report.py \
  --input predictions.csv --target won --probability win_probability \
  --group-col season --bins 10 --out calibration.json

python /path/to/calibration-check/scripts/segment_calibration.py \
  --input predictions.csv --target won --probability win_probability \
  --segment-col is_home

---