validation-design

検証設計

成果物

実際の予測プロセスを再現する、評価憲章とフォールド表を作成します。スポーツデータは時間の経過とともに変化します。選手名簿、ルール、戦術、対戦相手、スケジュール、データ収集システムが変わるため、ランダムな行分割が誠実なデフォルトになることはほとんどありません。

フォールドの構成を選ぶ際は分割パターン、メトリクスを固定する前にメトリクス固定ガイド、最終設計レビューではアンチパターンを確認してください。

このスキルを使用する場面

次の場合に使用します。

• 学習前にフォールド、メトリクス、ベースライン、実施可否のルールを固定する場合。
• ランダムな K-fold を、シーズン単位またはローリング起点のウォークフォワードに置き換える場合。
• チーム・試合パネルまたは反復イベントのエンバーゴ／グループ化を定義する場合。
• スポーツモデルを誠実に検証する方法についてユーザーから尋ねられた場合。

次の代替として、このスキルを使用しないでください。

• 特徴量行列のリーケージレビュー → leakage-audit
• 憲章の固定後に候補モデルを学習すること → baseline-models / predictive-modeling
• 確率の信頼性診断 → calibration-check

必要なこと	代わりに使用するもの
特徴量の適法性	feature-rules
リーケージの判定	leakage-audit
ベースラインの段階的評価	baseline-models

憲章：学習前に固定する

次の項目を記録します。

• 問い、ターゲット、行の粒度、予測判断時刻 T、対象となる母集団。
• 時系列分割の単位と、曖昧さのない並べ替え順。
• 対応する視点、反復イベント、エンティティ、シーズン、シリーズのグループ化。
• 最低限の学習履歴、拡大型またはスライディングウィンドウ、およびその理由。
• ラベルまたはソースの確定に基づくギャップ／エンバーゴ。
• 主指標、二次診断、ベースライン、実務上の成功基準。
• チューニングの境界、早期停止に使用するデータ、最後まで未使用にするホールドアウト。
• リーケージチェック、フォールドごとのレポート、失敗条件、許可する再実行。

結果を確認した後で憲章を変更する場合は、新しい評価バージョンを作成し、以前の結果には探索的と明記してください。

デフォルトのプロトコル

1. ファイル内の順序ではなく、情報を利用可能になった時刻に基づいて観測を並べます。
2. 公開遅延とエンバーゴを含め、学習データをテストデータより厳密に前の期間に限定します。
3. 候補の学習前に、主指標とベースラインをそれぞれ 1 つ選びます。
4. 各ブロックに十分なイベントがある場合は、シーズン／大会単位のウォークフォワードを使用します。
5. シーズン単位のブロックが粗すぎる場合、予測頻度が高いデータには、より細かなローリング起点のフォールドを使用します。
6. すべての変換の学習とハイパーパラメーターのチューニングは、過去の学習データだけを使用して行います。
7. 固定した候補について、各外側テストフォールドを 1 回だけスコアリングします。
8. 全体の平均値だけでなく、フォールド単位の結果、ばらつき、失敗、ベースラインとの差を報告します。
9. 特徴量ファミリーと候補を固定するまで、最終ホールドアウトを保持します。

分割パターン

シーズン単位のウォークフォワード

train through 2020 -> test 2021
train through 2021 -> test 2022
train through 2022 -> test 2023

これはシーズン制のリーグに適した強力なデフォルトです。各テストシーズンには、対象となる行が十分にあり、前のシーズンは最低履歴のルールを満たしている必要があります。

拡大型とスライディング型

ウィンドウ	学習データ	適している状況
拡大型	テストより前の対象履歴すべて	プロセスが安定している場合、データが乏しい場合
スライディング型	直近 K ブロック	レジームの変化／ルール変更が記録されている場合

最終ホールドアウトで最適化せずに K を選択します。各ウィンドウで除外される行／エンティティの数を報告します。

シーズン内のローリング起点

train through week 6 -> test week 7
train through week 7 -> test week 8

高頻度のラベルや運用上の再学習に使用します。特徴量には引き続きシフト／時点基準の構築が必要です。時間分割では、リーケージのある行列を修正できません。

エンバーゴと利用可能性のギャップ

ラベルの確定やソースの公開がイベント後になる場合、直近の学習イベントをすぐに利用できないことがあります。任意の数ではなく、実際の最大利用可能遅延からギャップを設定します。延期されたイベントや改訂によってギャップを延長するかどうかを記録してください。

グループ化とパネル

チーム競技のパネルでは、1つの試合につき通常2行あります。関連する視点は同じフォールドにまとめ、チーム行の精度を2倍にしたものを独立した試合予測精度として扱わないでください。選手イベントの行は、ラインアップ、試合、またはシリーズの影響を共有する場合があります。主張に基づいてグループ化を選択してください。時系列が最優先の場合、エンティティによるグループ化で将来の行が誤って学習データに入らないようにしてください。

ネストされたチューニング

Outer test block S
  Inner chronological folds inside blocks < S choose configuration
  Refit chosen configuration on all eligible data < S
  Score S once

早期停止はチューニングです。外側のテストフォールドではなく、学習期間内の検証スライスが必要です。

メトリクスの固定

タスク	主な候補	副次的な診断指標
勝率	対数損失	Brier、較正／ECE、精度
マージン／値	MAE	RMSE、バイアス、残差のスライス
カウント／率	偏差またはMAE	率の較正、ゼロの挙動
ランキング	将来期間のSpearman	ペアワイズ精度、安定性

精度だけでは確率の品質を考慮できません。RMSEはMAEよりも大きな誤差を重く評価します。意思決定における損失とターゲットの意味に基づいて選び、方向、集計、重み付け、予測の欠損、同順位の扱いを明示してください。

すべての候補について、同じ行とフォールドを使って、単純なベースラインとドメインに関連するベースラインを用意してください。例として、学習データの定数率／平均、ホーム指標、直近の値／評価、またはその他のシンプルで妥当な比較対象があります。

フォールド構築の診断

for fold in folds:
    train = df.loc[fold.train]
    test = df.loc[fold.test]
    assert train["event_time"].max() < test["event_time"].min()
    assert set(train["game_id"]).isdisjoint(set(test["game_id"]))

各フォールドについて、学習／テスト期間、行数、イベント数、エンティティ数、ターゲットの基準率、除外行数、利用可能性ギャップ、必須列の欠損値を記録してください。短縮されたシーズン、拡張期、ポストシーズン、またはソースの変更が結果を左右していないかを確認してください。

単独で使えるヘルパー

ユーザーが所有するCSV、Parquet、JSON、JSONL、またはNDJSONから、拡張ウォークフォワードのフォールドサイズを出力します。このヘルパーにはpandasが必要です。指定されたすべての列を検証し、異なる分割値をソートします。また、順序付け可能な任意のシーズン／日付／グループ列を受け付けます。

python /path/to/validation-design/scripts/print_folds.py \
  --input modeling_table.csv --split-col season \
  --required-cols won,is_home,rating_diff --min-train-groups 2

python /path/to/validation-design/scripts/write_charter.py \
  --out data/validation_charter.md

--min-train-groupsのデフォルトは2です。 つまり、最初のNグループは学習専用の履歴となり、テストフォールドには一度も含まれません。シーズンが2022, 2023, 2024の場合の例：

• デフォルトの2 → テストフォールドは1つ：2024（学習データは2022+2023）
• 1 → テストフォールドは2つ：2023と2024

このヘルパーは、CSVテーブルの前に、予定されているテストフォールドをstderrに出力します。評価対象の行を一致させるため、baseline-models／predictive-modelingヘルパーを呼び出す際も同じ設定を使用してください。

このヘルパーが出力するのは拡張グループフォールドの行数です。T、依存関係のグループ化、エンバーゴ、変換の適合、またはチューニングの分離は検証しません。設計を有効と判断する前に、これらを手動で確認してください。サポートされる順序値は、有限の数値、ISO形式の日付／タイムスタンプ、および2022-23、2022/23、2022-2023のような一般的な連続シーズン範囲です。これ以外のラベル（時系列順と辞書順が一致しないステージなど）には、明示的な数値の序数／日付フィールドが必要です。出力は、テストグループごとに1行を持つCSVです。

アンチパターン

アンチパターン	問題点	対処法
イベントにランダムなK分割交差検証を適用する	将来の構造が学習データに入る	前方向のみのフォールドを使う
全データでスケーラー／補完器を適合させる	テスト分布が漏洩する	フォールドごとのパイプラインを使う
外側のテストで早期停止する	テストデータがチューニング用になる	内側の検証スライスを使う
最終ホールドアウトを繰り返し確認する	適応的な過学習が起きる	固定して一度だけスコアを計算する
成績の悪いフォールドを削除する	選択バイアスが生じる	報告し、その状況を説明する
プールした平均値だけを報告する	不安定さが隠れる	フォールドごとの表とばらつきを示す
ベースラインがない	メトリクスの文脈が欠ける	妥当なベースラインを同じ条件で評価する
候補ごとに異なる行を使う	公平に比較できない	共通の対象サンプルを使う／開示する
チーム行の指標を試合精度と呼ぶ	対応する行を二重に数える	ホーム側のみを使うか、試合単位で集計する

レポート用の表と判定基準

fold | train_period | test_period | train_n | test_n | baseline_primary |
candidate_primary | gap | secondary_metrics | exclusions | failures

各フォールドの平均とばらつきを報告しつつ、個々のフォールドの結果も残してください。フォールドを行数で重み付けする方法と、フォールドを均等に平均する方法では、答える問いが異なります。どちらを主な方法とするか明記してください。主張の根拠とする場合は、キャリブレーションと関連するレジーム／エンティティごとのスライスも含めてください。成功基準には、固定した主指標、ベースラインとの差、フォールド間の十分な一貫性、そして譲れないリーク防止／キャリブレーションの制限を組み合わせてください。

憲章のテンプレート

Validation charter
Target / grain / decision time T / eligible population:
Split unit and ordering:
Grouping rule:
Minimum training history:
Window: expanding | sliding(K=)
Gap/embargo and availability rationale:
Primary metric definition:
Secondary diagnostics:
Baselines:
Inner tuning and early stopping:
Final untouched holdout:
Common evaluation rows:
Success / failure rule:
Required leakage checks:
Per-fold reporting and slice requirements:
Allowed reruns / versioning:

実例と完全性のルール

チーム対戦の勝率予測では、Tをキックオフに設定し、試合ごとに両方の視点をまとめ、2つの過去シーズンを使ってシーズン単位で順次分割し、各外側の訓練セット内で前処理の適合とチューニングを行います。主指標には対数損失を、二次指標にはブライアスコア／キャリブレーションを使用し、定率ベースラインとホーム指標ベースラインを比較して、各シーズンの結果をすべて報告します。試合レベルの主張には、単一の視点または試合単位の集計を使用してください。

1. 行、依存関係グループ、変換の適合、チューニングの情報が、未来から過去へ渡ることはありません。
2. 候補を試す前に指標と成功基準を固定し、結果の悪いフォールドも公開してください。
3. 候補と特徴量を固定するまで、最終ホールドアウトには手を付けないでください。
4. 設計には references/split_patterns.md、指標には references/metrics_lock.md、レビューには references/anti_patterns.md を使用してください。
5. feature-rules と leakage-audit を併用してください。フォールドがクリーンでも、安全でない特徴量の問題は修復できません。