sports-modeling-doctrine

スポーツモデリングの指針

目標

データを取得したりモデルを適合したりする前に、モデリング憲章を作成してください。憲章は、問い、目的変数、タイミング、評価、完了の定義について、ユーザーが管理する信頼できる情報源です。

コードを書く前に、科学的な取り決めを確定してください。

• どのような問いに答えるのか。
• 1 行が何を表すのか。
• 意思決定時点で何が分かっているのか。
• 価値を示す証拠として何をベースラインとするのか。
• 時間外での成功をどのように測定するのか。
• どの結果をもって採用、修正、または中止とするのか。

これらの項目が明記されていない場合は、モデルを適合しないでください。

このスキルを使う場面

スポーツ分析を始めるとき、または分析の枠組みを見直すとき、「良い」とは何かを決めるとき、結果が評価可能かどうかを確認するとき、あるいは探索的な作業がいつの間にか予測上の主張になるのを防ぐときに使ってください。

憲章の作成後は、関連する専門スキルのみを使ってください。データ取得には公開ソースローダー、データ理解には eda-sports、時間的に安全な予測子には feature-rules、参照モデルには baseline-models、統計、予測、レーティング、シミュレーション、検証には関連するスキルを使います。

問いの種類

種類	中心となる問い	必要な証拠	よくある過剰解釈
記述	何が起きたのか。	カバレッジ、分母、不確実性	サンプルをあらゆる時代・母集団に当てはめる
説明	何と関連しているのか。	研究デザイン、効果、不確実性、交絡に関する限界	因果関係を示す表現
予測	時点 T より後に何が起きるのか。	時間的に安全な入力と順序を守ったホールドアウト	係数を原因として説明する
因果	介入によって何が変わるのか。	識別戦略と仮定	予測だけを使う
ランキング	時点 T において最も強いのは誰か。	将来の有用性、日程の文脈、順位の安定性	点推定の順位を確実なものとして扱う
シミュレーション	仮定に基づくと、どのような分布になるのか。	キャリブレーションされた入力と感度分析	シミュレーション上の精度を観測された事実として報告する

説明における成功と予測における成功を混同しないでください。安定した関連性が予測を改善するとは限りません。また、有用な予測子が因果メカニズムを特定するとは限りません。

憲章の作成手順

1. 問いを 1 文で書きます。
2. スポーツ、競技、母集団、対象時代、除外条件を明記します。
3. 粒度を定義します。試合、チームと試合の組み合わせ、選手と試合の組み合わせ、ポゼッション、プレー、投球、その他のいずれかを指定します。
4. 上の表を使って分析の種類を分類します。
5. 予測、ランキング、または前向きなシミュレーションでは、意思決定時点 T と予測期間を厳密に定義します。
6. 目的変数または推定対象、単位、ラベルの規則、引き分けや結果の欠損値の扱いを定義します。
7. 基準発生率、帰無期待値、または現行プロセスを記録します。
8. 単純なベースラインを少なくとも 1 つ、強力な単純ベースラインを少なくとも 1 つ明記します。
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	過去の平均値または単純レーティング	残差分布と区間カバレッジ
カウント	ポアソン逸脱度、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

NFL、NBA、MLBの簡潔なパターンをさらに見るには、references/charter_examples.mdを参照してください。

必須事項と完全性のルール

1. 時系列が重要です。イベントのランダムなシャッフルには、明示的な正当化が必要です。
2. 将来予測を主張する場合、特徴量は時点 T で利用可能なものでなければなりません。
3. 候補モデルを評価する前に、ベースラインを定義してください。
4. テストフォールドを確認する前に、主要メトリクスを固定してください。
5. 粒度を変更する場合は、集約方法とキーの検証を明示してください。
6. 候補モデルとベースラインには、同一のホールドアウト対象集団を使用してください。
7. 失敗や改善なしという結果も、有効な結果として記録してください。
8. 強い主張には、リーク監査と誠実な不確実性の提示が必要です。
9. 公開データを使っても、出所、ライセンス、スナップショットの管理責任がなくなるわけではありません。
10. 好ましい結果が出た後に、対象範囲をひそかに広げてはいけません。
11. チャーターの要件を満たす、最もシンプルなモデルを使用してください。
12. 意思決定と成果物は、消えてしまうチャットの外に記録してください。

アンチパターン

• 意思決定を定義する前にアルゴリズムを選ぶ。
• 利用可能時刻を記録せず、特徴量を無秩序に詰め込む。
• 好調な1シーズンだけで「汎化」と呼ぶ。
• ホールドアウトの結果を見た後で主要メトリクスを変更する。
• チームと試合の各行を、独立した試合として扱う。
• スケジュールやルールが異なるスポーツ間で、同じ仮定をそのまま使う。
• テスト期間を把握した後もチューニングを続ける。
• 複雑なモデルがヌルモデルには勝っても、強力でシンプルなベースラインには勝っていないのに、成功を宣言する。
• キャリブレーション計画なしに確率を出す。

ヘルパー

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 — ポータブルな憲章作成ツール。