leakage-audit

漏洩監査

目標と基本方針

パイプラインが時間的に安全であることが証明されるまでは、漏洩があるものと想定します。敵対的な視点で証拠に基づいた判定を行い、汚染されたフィールド、影響を受ける主張、必要な修正、再テストの条件を示します。判定は CLEAN、REVIEW REQUIRED、NOT CLEAN のいずれかです。 高い指標値は、データがクリーンである証拠にはなりません。

このスキルを使う場面

次のような場合に使用します。

• バックテストや「良好な」指標を初めて信頼しようとするとき。
• モデリングの前、または不自然に強い結果が出た後に、特徴量テーブルをレビューするとき。
• ターゲットの別名、結合、シフト、前処理、分割設計を監査するとき。
• ユーザーが、モデルの性能が良すぎる、または結果が予想外だと言ったとき。

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

• 適法な特徴量をゼロから設計する → feature-rules
• フォールドと指標を設計する → validation-design
• パネルデータの初回 EDA を行う → eda-sports

必要な作業	参照先
特徴量の構築ルール	feature-rules
フォールド／指標の基準	validation-design
クリーンな設計後の確率の信頼性	calibration-check

監査の基準を固定する

相関や指標を調べる前に、ターゲット、行の粒度、正確な予測判断時点 T、対象となる母集団、データソースの公開／改訂ポリシー、意図する検証分割を明記します。T が曖昧な場合、監査に合格することはできません。

すべての監査で監査チェックリストを使用します。障害モードを追跡するときは漏洩パターンカタログを参照し、性能や結合に不自然な点がある場合はケーススタディを参照します。

監査の手順

1. ターゲットのソースまでたどり、別名、変換、代理変数、重複ラベルを特定します。
2. すべての候補特徴量、元データソース、イベント／公開／改訂時刻、および T 時点での利用可能性を一覧化します。
3. 時系列変換で、安定したソートと shift-before-roll/expand が行われているかを確認します。
4. 対戦相手、ロスター、負傷、レーティング、天候、価格、スケジュールの結合を追跡します。
5. 前処理、選択、エンコード、チューニングがトレーニング行のみを使って適合されていることを確認します。
6. 検証が時間を前に進める形で行われ、関連する行が同じ分割に保たれていることを確認します。
7. 自動の行列ヒューリスティクスを実行し、検出されたすべての項目を手動で調査します。
8. 不審な行と性能の急上昇を、元データから再現します。
9. 判定を下し、修正と再実行が完了するまで、根拠のない主張を保留します。

漏洩カタログ

パターン	例	確認する証拠	修正
ターゲットの別名	won、マージンの符号、最終順位	系譜、完全または近似した相関	入力から削除する
同一イベントの汚染	現在のスコア、EPA、ボックススコアの合計値	ソース／イベントのタイムスタンプ	ターゲット専用にするか、T を再定義する
シフトされていない履歴	現在の結果を含むローリング平均	変換の順序と境界行	シフトしてから集計する
シーズン間の混入	第 2 週でシーズン最終平均を使用	スナップショット／公開ポリシー	過去の値を累積して使用する
対戦相手情報の汚染	対戦相手の合計値に対象試合が含まれる	結合の追跡と対応する行	安全な対戦相手の事前情報を結合する
改訂による漏洩	過去の予測に訂正済み統計を使用	公開／改訂タイムスタンプ	公開時点のデータ版を再構築する
ランダムな行分割	トレーニングに未来の試合が含まれる	フォールドの日付範囲	時系列の前進のみで分割する
グループ漏洩	同一試合の視点別データが別々に分割される	試合／エンティティの所属	関連する行をグループ化する
前処理の漏洩	スケーラー／エンコーダーを全データで適合	適合済みオブジェクトの系譜	トレーニングフォールドで適合する
チューニングの漏洩	最終フォールドがハイパーパラメーターに影響	実験履歴	ネストしたチューニング／未使用のホールドアウトを使う
重複による漏洩	同一イベントまたは選手が両方に出現	ハッシュとキー	分割前に重複排除／グループ化する

手動レビュー

ターゲットと時刻

• 定義上、ターゲットは T より後のものですか。また、中止／引き分け／未完了のイベントは適切に処理されていますか？
• 予測タイムスタンプは、仮定ではなく保存または再構築されていますか？
• どのプロバイダーフィールドが改訂されますか。また、どの過去時点のデータ版を使用しますか？
• 特徴量名に問題がなくても、元のテーブルがイベント後のデータである可能性はありませんか？

変換

ordered = df.sort_values(["team", "event_time", "game_id"])
expected = ordered.groupby("team")["won"].transform(
    lambda s: s.shift(1).expanding(min_periods=1).mean()
)
assert expected.equals(ordered["pre_win_pct"])

ソートの同順位の処理、リセット境界、オフシーズンの持ち越し、最小期間、最初のエンティティイベントに説明のつかない経験的事前値がないかを確認してください。将来の摂動テストでは、後の結果を変更しても前の特徴量が変わらないことを証明してください。

結合

結合ごとに、左側と右側の粒度、キー、想定カーディナリティ、公開時刻の条件、不一致率、重複率、保持するフィールドを記録してください。as-of 結合は過去を参照するものであり、right_published_at <= T を満たす必要があります。表示名による結合や、気づかれないまま発生する多対多の展開は、解決されるまで監査上の不合格です。対戦相手の特徴量は、対戦相手自身のイベント前の行と一致する必要があります。

分割と前処理

各フォールドについて、宣言されたギャップ／エンバーゴのみを認めたうえで、train max time < test min time を証明してください。推定対象で必要な場合は、ペアとなるチーム・試合の行、同じイベントからの反復観測、その他の依存グループを同じ分割に含めてください。補完器、スケーラー、エンコーダー、特徴選択器、ターゲットエンコーダー、PCA、早期停止、ハイパーパラメーター検索は、訓練データのみを使用する必要があります。

過剰に良好な結果のトリガー

ほぼ完全な精度、あり得ないほど低い対数損失／誤差、単一特徴量の劇的な急上昇、訓練／テストの一致、またはドメインのベースラインをはるかに上回る結果が出た場合は、停止してください。評価する前に、ターゲットの別名、現在のイベントのフィールド、シフト、対戦相手との結合、重複、全データを使った前処理、テストフォールドでのチューニングを再確認してください。

自動ヘルパー

監査ヘルパーは、ユーザー所有の CSV、Parquet、JSON、JSONL、または NDJSON のテーブルを読み込み、pandas を必要とします。指定された列を検証し、名前、ターゲットとの完全一致、重複、ほぼ完全な相関に関するヒューリスティックを実行します。

python /path/to/leakage-audit/scripts/audit_pregame_features.py \
  --input modeling_table.csv --target won \
  --features pre_win_rate,rest_diff,rating_diff \
  --entity-col team --time-col event_time --out leakage.json

python /path/to/leakage-audit/scripts/write_audit_stub.py \
  --out data/leakage_audit.md

タスクで厳密に禁止する名前を指定するには、--banned を使用してください。最初のイベントの null 率チェックは、正当な事前値が最初のイベントに含まれる可能性があるため、常に REVIEW であり、PASS にはなりません。重複行とほぼ完全な相関も REVIEW です。疑わしいものではありますが、それだけで証拠にはなりません。禁止対象の特徴量、またはターゲットと同一の特徴量が直接見つかった場合、NOT CLEAN を返し、ステータス 2 になります。それ以外の場合、ヘルパーは REVIEW REQUIRED とステータス 1 を返します。ヒューリスティックだけで CLEAN が返ることはありません。CLEAN の判定を出せるのは、リネージ、変換、結合、分割、フォールド内での前処理について手動監査を完了した場合のみです。

終了コード（クラッシュではありません）

終了コード	判定	エージェントの対応
1	REVIEW REQUIRED	続行してください。 JSON を読み、手動監査を完了してください。これを重大な失敗として扱わないでください。
2	NOT CLEAN	修正して再テストするまで、予測に関する主張を中止してください。
0	未使用	ヒューリスティックが自動的に CLEAN を返すことはありません。

stderr にも exit=1 REVIEW REQUIRED... または exit=2 NOT CLEAN... が出力されるため、予備知識のないエージェントがレビューの通知をスクリプトの破損と誤解することはありません。

自動チェックでは、データソースの利用可能性、変換の正しさ、結合の方向、フォールドの範囲を証明できません。自動チェックはリネージとコードレビューを補完するものであり、それらに取って代わるものではありません。

診断例

シフトなしのローリング成績： 手動で再計算すると、行 i にその行自身の結果が含まれていることがわかります。NOT CLEAN と判定し、shift(1) を使って再構築し、すべての下流アーティファクトを再生成して、検証を再実行してください。

シーズン最終時点の効率指標を序盤の試合に使用： 値はシーズン内で一定で、後の試合を反映しています。過去のイベントに基づく、as-of の拡張統計に置き換えてください。最初の数週間を単に削除してはいけません。

正当な初回イベントの事前値： 最初の行に null でない評価値がありますが、リネージから、T より前に公開された固定のプレシーズン評価値であることがわかります。初期化とタイムスタンプを記録するまでは REVIEW REQUIRED のままとし、その後、この項目を合格にしてください。

特徴量に問題がないランダム K-fold： 特徴量チェックには合格していますが、将来のシーズンが訓練に含まれています。パイプラインは依然として NOT CLEAN です。フォールドを再設計し、報告済みのすべての指標を再計算してください。

判定ルール

判定	意味
CLEAN	完全なインベントリを確認済みで、未解決の違反やレビュー項目がありません
REVIEW REQUIRED	汚染が確認されていませんが、証拠または利用可能性が不十分です
NOT CLEAN	1 つ以上の特徴量、結合、変換、分割、またはチューニングの経路で禁止情報が使用されています

不確実な場合は CLEAN ではありません。固定マトリックスは再生成して再評価する必要があります。 スコアリング後に疑わしい列を削除しても、それ以前の指標は正当化されません。

監査レポートのテンプレート

Leakage audit
Sport / question / target / grain:
Decision time T and publication policy:
Data snapshot and feature count:
Validation and grouping rule:
Automated helper result / exit status:
Lineage and transform evidence reviewed:
Findings:
  1. [PASS | REVIEW | FAIL] item, evidence, affected scope
Contaminated fields/artifacts:
Required repairs and retests:
Remaining uncertainty:
Verdict: CLEAN | REVIEW REQUIRED | NOT CLEAN
Auditor / date:

整合性とリソースの振り分け

1. 誤って CLEAN とするより、誤って要レビューとする方を優先してください。指標から問題がないと推測してはなりません。
2. 監査のタイムラインの並べ替えは、構築時のものと正確に一致させてください。
3. 不正なテスト期間を削除したり、成功の定義を変更したりして、リークを修正してはなりません。
4. NOT CLEAN の場合、再構築して再テストするまで予測に関する主張を行えません。
5. 完了の確認には references/audit_checklist.md、分類体系には references/leakage_patterns.md、診断には references/case_studies.md を使用してください。
6. 修正には feature-rules、フォールドには validation-design を併用してください。