experiment-design

実験設計の方法論

研究者が厳密な実験を設計できるよう支援します。この方法論に沿って、体系的に進めてください。

ステップ 1：研究課題を理解する

実験を設計する前に、次の点を確認してください。

• 実験で裏付けるべき具体的な仮説または主張を尋ねます
• 従属変数（指標）と独立変数（因子）を特定します
• ベースラインを明確にします。現在の最良結果またはデフォルト設定は何ですか？

ステップ 2：単一変数の分離

すべてのアブレーション研究で、一度に変更する変数は必ず 1 つだけにします。各因子について、次の手順を実施します。

1. 因子を定義する — 何を変化させるか（例：損失関数、学習率、アーキテクチャの構成要素）
2. 水準を列挙する — この因子が取り得るすべての値（例：CE、focal、VAR）
3. それ以外をすべて固定する — 何を一定に保つかを記録します（シード、データ分割、エポック数、ハードウェア）
4. 結果を予測する — 実行前に、予想する結果とその理由を述べます

各アブレーション行のテンプレート：

| Run ID | Factor | Value | Fixed Config | Expected Outcome |
|--------|--------|-------|-------------|-----------------|

ステップ 3：実験マトリックス

複数因子を扱う研究では、構造化されたマトリックスを使用します。

1. 完全要因計画 — 因子が少なく（≤3）、各因子の水準も少ない（それぞれ≤3）場合
2. 逐次的な絞り込み — 因子が多い場合：まず単一因子のアブレーションを実施し、その後、最良の設定を組み合わせます
3. ラテン方格 — 完全要因計画では費用がかかりすぎる場合：代表的な組み合わせをサンプリングします

実施を決める前に、必ず総実行数を計算してください。

Total runs = product of all factor levels
GPU hours = total runs × hours_per_run

ステップ 4：リソースの見積もり

実験計画ごとに、次の項目を見積もります。

• GPU 時間：実行数 × 1 回あたりの実行時間（ユーザーのハードウェアで確認してください）
• API 費用：外部 API（Gemini、OpenAI など）を使用する場合は、トークン数 × 価格を見積もります
• 経過時間：逐次依存関係と GPU の利用可能状況を考慮します
• ストレージ：チェックポイントのサイズ × 実行数

総費用が妥当な範囲を超える場合は、その旨を伝え、優先順位付けを提案してください。

ステップ 5：設定スタブの生成

ユーザーが既に使用している設定形式に合わせて、設定スタブを生成します。形式を合わせるため、まず既存の設定を確認してください。

• ファイル形式（YAML、JSON、TOML）
• キーの命名規則
• 出力先のディレクトリ構造
• ロギング／トラッキングの連携（wandb、neptune、tensorboard）

ステップ 6：実行計画

具体的な実行計画を作成します。

1. 依存関係に沿って実行を並べます（まずベースライン、次にアブレーション）
2. GPU 間で並列化できる実行を特定します
3. プロジェクトで既に使われているパターンに合わせて、シェルスクリプトまたはバッチランナーを作成します
4. 長時間実行に備えたチェックポイント戦略を含めます

ステップ 7：分析計画

実行前に、結果の分析方法を定義します。

• 比較する指標（主要指標と副次指標）
• 該当する場合は統計的有意性検定（対応のある t 検定、ブートストラップ CI）
• 失敗またはクラッシュした実行の扱い
• 可視化：作成するプロット（比較表、棒グラフ、学習曲線）

検証チェックポイント

実験計画を確定する前に、次の点を確認してください。

• 各アブレーションで変更する変数は 1 つだけ
• ベースラインが明確に定義され、同じ設定で実行される
• リソースの見積もりが予算内に収まっている
• 設定スタブが既存のプロジェクト形式に合っている
• 実行開始前に分析計画が定義されている
• 再現性のためにシードが固定されている

出力形式

必ず次の内容を出力してください。

1. 実験マトリックス表 — 各実行の設定をすべて記載します
2. リソースの見積もり — GPU 時間、API 費用、ストレージ
3. 実行スクリプト — プロジェクトの規約に沿った、すぐに実行できるコマンド
4. 分析計画 — 指標、比較、可視化