ml-experiment-standards

ML 実験標準

目的：すべての ML ジョブ（迅速なプロトタイプを含む）は、再現可能で、 リークがなく、指標によって正当化されること。これらは任意の仕上げでは ありません。省略した項目はたいてい「本番環境でモデルが崩壊した」あるいは 「結果が再現しなかった」という形で返ってきます。

1. EDA を最初に行う

モデルに着手する前に、以下を作成して提示します：分布、欠損率、 外れ値、ターゲットのバランス、顕著な相関。指標と損失の選択は この情報に依存します。EDA なしのモデル推奨は推測にすぎません。

2. リーク監査

すべての分割の判断において、明示的に答え（そしてその答えをコードの コメントとして書きます）：「訓練セットは、いずれかのテストサンプルに ついての間接的な情報を含んでいないか？」

データ種別	正しい分割	理由
独立したサンプル	層化 k 分割	クラス比率を保つ
時系列	TimeSeriesSplit / ウォークフォワード	未来が過去に漏れてはならない
空間データ	空間ブロック CV — references/spatial-cv-protocol.md を参照	近傍はほぼ重複である
グループ化されたデータ（患者、区画、シーン）	GroupKFold	グループが分割をまたいではならない

• スケーラー／エンコーダー／補完器は訓練データのみで fit します。クリーンな方法は sklearn.pipeline.Pipeline です — これなら CV が構造上正しく fit します。
• ターゲット由来の特徴量（ターゲットエンコーディングなど）は アウトオブフォールドで計算しなければならず、そうであることを示す必要があります。

references/spatial-cv-protocol.md にある空間プロトコルは、このリポジトリにとって 唯一の正典となる情報源です — 他のスキルはここにリンクします。再掲しないでください。

3. 指標の選択 — 正当化すること

決してデフォルトで指標を選ばないでください。一文の根拠を書きます：

• 不均衡クラス → F1 / AUC-PR、精度ではない（精度は 多数派クラスの暗記を報酬として与えます）。
• セグメンテーション → IoU/Dice（ピクセル精度は背景によって水増しされます）。
• 回帰 → RMSE（大きな誤差に敏感）対 MAE（頑健）対 R² （説明された分散）— ユースケースから正当化します。
• すべての点推定には不確実性を付けます：ブートストラップ CI または CV フォールド全体の平均 ± 標準偏差。単一の数値は、差がシグナルなのか ノイズなのかを隠します。

4. 再現性の骨組み

すべての訓練スクリプトはこの形に従います（スクリプト優先。ノートブックの 魔法は使いません）：

"""Experiment: <name>. Goal and success criterion: <one sentence>."""
from dataclasses import dataclass, asdict
import json, random
import numpy as np

@dataclass
class Config:
    seed: int = 42
    lr: float = 1e-3
    batch_size: int = 32
    epochs: int = 100
    patience: int = 10  # early stopping

def set_seed(seed: int) -> None:
    random.seed(seed)
    np.random.seed(seed)
    # if torch: torch.manual_seed(seed); torch.cuda.manual_seed_all(seed)

def main(cfg: Config) -> None:
    set_seed(cfg.seed)
    ...  # data -> split -> pipeline -> train -> evaluate
    with open("runs/run_meta.json", "w", encoding="utf-8") as f:
        json.dump({"config": asdict(cfg), "metrics": metrics}, f, indent=2)

if __name__ == "__main__":
    main(Config())

• 設定は dataclass／YAML に置き、決してハードコードしません — スイープと実行の 比較がこれに依存します。
• ライブラリのバージョンを固定します（pip freeze > requirements.txt）。
• 利用可能な場合は MLflow/W&B を使います。上記の JSON ログが最低限です。

5. 深層学習の追加事項

• 損失の根拠：不均衡セグメンテーションには Dice／Dice+CE。その理由を書きます。 Focal は比較した後にのみ — 無条件の勝利ではありません。
• 拡張の根拠：どの変換が問題の物理的特性を尊重するかを述べます （向きに依存するタスクでは一部の回転が禁止されます。 マルチスペクトルでは単純な色のジッターが禁止されます）。
• 過学習の制御：patience 付きの早期停止 + レポートに訓練／検証 曲線。曲線がなければ「モデルは良好」とは言えません。
• 容量の順序：まず小さなモデル + 単純なベースライン（ロジスティック 回帰、RF）。ベースラインを超えられない深層モデルはデータの 問題であり、アーキテクチャの問題ではありません。
• EO 固有のチッピング／推論の詳細 → geo-deep-learning。

6. システムコンテキスト（MLOps）

すべてのモデルをそのチェーンの中で一段落で位置づけます：データソース → クリーニング → 特徴量／バージョニング → 訓練 → 評価 → デプロイ （バッチ／リアルタイム）→ モニタリング（データ／モデルのドリフト）。プロトタイプで あっても、「このステップが本番環境で何になるか」を記します。

7. レポート形式

## Experiment: <name>
- Data: n=<>, split: <strategy + rationale>
- Baseline: <model> → <metric ± CI>
- Model: <model> → <metric ± CI>
- Leakage audit: <what was checked>
- Next step: <single recommendation>

差を報告するときは、統計的な誠実さを守ります：その差が フォールド間の標準偏差を超えないなら、「明確な差はない」と述べます — p ハッキングも、選択的な報告も行いません。

実行契約

• ワークフロー: 予測対象と意思決定での用途を定義し、ベースラインを確立し、リークを監査し、空間的に妥当な分割を作成し、再現可能に学習し、不確実性を定量化し、誤差とデプロイ適合性を検査します。
• 判断ルール: このスキルは予測モデルの実験にのみ適用します。推論には空間統計を、サンプリングされたサーフェスの推定にはジオスタティスティクスを用い、モデルを無理に当てはめずに記述的分析を行います。
• 検証プロトコル: クリーンな環境から再現し、フォールドまたはシードをまたいでベースラインと比較し、空間残差を検査し、分割の独立性を検証し、最終的な意思決定しきい値をテストします。
• 失敗モード: リーク、分割後の前処理、不適切なメトリクス、独立していないテスト単位、選択的な実行、または学習とサービングのスキューがある場合、アップリフトの主張を無効化します。
• 成果物: 実験設定、分割とシードのマニフェスト、不確実性を含むベースラインとモデルのメトリクス、リーク監査、誤差分析、アーティファクト、デプロイに関する注意事項。
• ソースの鮮度: バージョンに敏感な分割・メトリクス・再現性の API を使用する前に、信頼できるソースのレジストリを参照してください。