calibration-check

キャリブレーションチェック（スポーツ）

概要

モデルがチームの順位付けに優れていても、キャリブレーションが不十分なことがあります。モデルが30％と予測した場合、そのうち約30％が的中するはずです。

このスキルでは、スポーツモデルの確率の信頼性を測定し、評価の出所、不確実性、セグメントの安定性に基づいて、人間が確認した判定を行えるようにします。

識別性能の指標（AUC、精度）は、キャリブレーションの代わりにはなりません。

---

このスキルを使う場面

次の場合に使用します：

• モデルが勝利またはイベントの確率を出力する
• ユーザーが確率の確信度や信頼性について尋ねている
• 確率モデルをウォークフォワード評価した後
• 確率の数値を引用する結果を書く前
• 未補正の確率と再キャリブレーション済みの確率を比較する
• スポーツや大会に固有の確率アーティファクトを扱う

次の場合は使用しないでください：

必要なこと	代わりに使うもの
確率的な解釈を伴わない、純粋な順位付けタスク	ranking/eval スキル
確率出力がなく、ハードラベルのみを扱う	分類指標のみ
分割を一から設計する	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. ブライアスコア（必要に応じて信頼度／解像度に分解）
4. 対数損失 — 識別性能とキャリブレーションを総合的に評価する指標。ECE の代わりにはなりません
5. セグメント別キャリブレーション — シーズン別、ホーム／アウェー別、確率の裾野別
6. シャープネス — 確率に情報量があり、すべてが約0.5になっていないか

ECE、ブライアスコア、対数損失、シャープネスを解釈する際は、calibration_metrics.md を参照してください。ビンの境界や最小件数を決める前に、binning.md を参照してください。Platt スケーリング、アイソトニック回帰、その他の確率補正を適用する前に、recalibration.md を参照してください。

---

ワークフロー

1. 予測が時間的に安全な分割／ウォークフォワード分割から得られたことを確認します。
2. 確率が [0, 1] の範囲内にあることを検証し、除外した各行を記録します。
3. ビン分け方法（固定幅または分位数）を事前に決めます。
4. 曲線、ECE、ブライアスコア、対数損失を計算します。
5. シーズン別および確率の裾野別に分けて分析します。
6. 判定を下します（下表を参照）。
7. 再キャリブレーションする場合は、入れ子型／学習データ内での適切な方法に限ります。最終テストフォールドでアイソトニック回帰を学習し、それを検証済みとすることは決して避けてください。
8. キャリブレーションレポートを実験ログ／結果の報告書に記載します。

---

判定基準

判定	意味
well-calibrated	確率を引用するうえで、信頼性が許容できる
usable-with-caveats	一部にキャリブレーションの不備がある。開示する、または適切に再キャリブレーションする
poorly-calibrated	確率の数値を確率として信頼できない
invalid-eval	データリーク／分割の問題があり、判定できない

これらの判定は、単一の ECE 閾値ではなく、方法論全体に対するものです。判定を下す前に、予測が実際にホールドアウトされ、ウォークフォワードで得られたものかを確認し、不確実性とデータが入っているビンの件数を調べ、シーズンやフォールドを比較し、判断に関わるセグメントを確認して、予測の出所を記録してください。確率が信頼できることを示す普遍的な ECE の閾値はありません。

未使用の予測アーティファクトで実行する

入力には、評価対象の判断ごとに1行、二値の結果、および[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

1試合につきホーム側の視点が1つだけ実際の評価単位となる対称なチームゲームのアーティファクトでは、--filter-col is_home --filter-value 1を使用してください。1つのイベントについて両側を二重にカウントしないでください。

calibration_report.pyは、ブライアースコア、対数損失、ECE、信頼度ビンの件数、行の集計、任意のグループ別指標、および保守的なmanual-review-requiredヘルパー判定を返します。このスクリプトでは、未使用データ由来であることを証明したり、プール後のECEが良好だからといってwell-calibratedにしたりすることはできません。分析者は、上記の判定基準を適用する必要があります。segment_calibration.pyは、全行、カテゴリ別セグメント、確率の端の範囲の指標、およびデータの少ないビンの件数を出力します。

---

ビニングのガイダンス

戦略	使用する場面
等幅ビン（0～1を10分割）	スポーツの勝率のデフォルト
分位点ビン	確率が狭い範囲に集中している場合
端に注目（0～0.2、0.8～1.0）	判断が極端な範囲に集中している場合

必ずビンごとの件数を報告してください。空のビンは証拠にはなりません。

---

再較正のルール

許可

• Platt scaling／isotonic fitはトレーニングフォールド内のみで行い、テストフォールドに適用する
• ネストされたウォークフォワード再較正

禁止

• 最終テストのラベルでisotonicを学習し、それを検証済みと称する
• 結果を見た後で確率を手作業で編集する

再較正後は、真のフォワードフォールドでECE／ブライアースコアを再度報告してください。

---

厳守事項

1. ネスト処理について明示せずに、同じモデルの学習に使った行で較正を評価しないでください。
2. 較正を確認せずに、生のスコアを確率として提示しないでください。
3. プール後の「問題なさそう」という結果の陰に、セグメントの失敗を隠さないでください。
4. ビンごとのサンプル数が極めて少ない場合は、その旨を明記してください。ビンの幅を広げるか、主張の強さを抑えてください。
5. 正解率は較正ではありません。
6. データリークにより無効となった評価を「well-calibrated」とすることはできません。

---

よくあるアンチパターン

• 「56%正解したので、較正されています」
• サンプル数の記載がない信頼度プロットが1つだけ
• ホールドアウトデータでの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／ブライアースコア／対数損失を報告した
• ビンごとの件数またはセグメントに関する注記を記載した
• 判定を示した
• アクションを明記した

---

実例

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／ブライアースコア／対数損失の定義
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

---