仮説駆動型モデル開発

Allora ネットワーク向けの金融予測モデル作成をビルダーにガイドしています。このアプローチは仮説駆動型です。ビルダーは予測対象とそれを駆動する理論から始まり、その後のあらゆる決定がその理論から流れ出します。

このスキルは完全で実行可能なパイプラインを生成します。計画ではなく、疑似コードでもなく、データを読み込み、特徴を生成し、モデルを学習し、検証し、結果を報告する実行可能なコードです。

方法論

このワークフローは 方法論 で説明されている9つの原則を実装しています。完全な根拠は当該ドキュメントをお読みください。簡潔には:

1. 物理学優先の特徴エンジニアリング — 推定目標を中心に組織された特徴
2. 予測期間適応型パラメータ化 — すべての期間は予測期間から導出
3. アーキテクチャによるルックアヘッド防止 — 開発者の規律ではなく構造的安全装置
4. 3段階分離 — 最適化、評価、デプロイ（二重評価なし）
5. 損失関数をモデリング決定として — 信念をエンコード、事後考察ではない
6. マルチしきい値信号検証 — 同時独立品質ゲート
7. オプティマイザーゲーミング防止 — val=test パリティ、一定のテストカバレッジ
8. 設定駆動型実験 — 仕様はコードではなくデータ
9. 問題分解 — 有益な場合は予測をサブ問題に分解

検証アーキテクチャの詳細は 検証フレームワーク にあります。特徴エンジニアリングパターンは 特徴エンジニアリング にあります。損失関数設計は 損失設計 で説明されています。

---

エントリーポイント

ビルダーとの会話を以下の質問から始めます:

何を予測し、なぜか?

具体的には:

1. 予測対象は何か? (例: 将来リターン、ボラティリティ、ファンディングレート、スプレッド、センチメントスコア)
2. 予測期間は? (例: 1時間、8時間、1日、1週間)
3. 資産または商品は?
4. 仮説は何か — この対象が予測可能だと思う理由、およびそれを駆動する要因は何か?

ビルダーの回答がその後のすべてを決定します。4つすべてに対して明確な回答を得るまで進めないでください。

---

ガイド付きワークフロー

ステップ1: 予測問題を定義する

ビルダーの回答から以下を確立します:

• 対象変数。 正確に予測される量。正確に: 「次の H 期間のログリターン」は「価格方向」や「ベンチマーク相対的なエクセスリターン」とは異なります。対象定義は損失関数が最適化する内容と適切な検証メトリクスを決定します。

• 予測期間 H。 データのネイティブ時間単位で。パイプラインのすべての時間パラメータはこの値から導出されます（原則2）。

• データソース。 どのデータが利用可能か? 価格/取引量（どの取引所、どのペア）、オンチェーンデータ、代替データ、ソーシャルデータ? データソースは構成可能な特徴を制限します。

• 仮説の形式化。 ビルダーの理論をテスト可能なクレームに変換します。「モメンタムがリターンを予測すると思う」は「過去約0.5H～2H期間の短期価格トレンドが次の H 期間のリターンについての情報を持つ」となります。この形式化は特徴が果たすべき推定目標を明らかにします。

このステップの出力: ビルダーが確認する構造化問題定義。

チェックポイント1

進める前にビルダーと確認してください:

• 対象変数は正確に定義されているか?
• 予測期間は具体的か（特定の時間単位での特定の数値）?
• データソースは特定され、アクセス可能か?
• 仮説は、どの特徴を構築するかを示唆するのに十分に具体的か?

---

ステップ2: 推定目標を特定する

このステップはビルダーの仮説を構造化された一連の推定目標に翻訳します — 特徴が推定する経済的または物理的量です（原則1: 物理学優先の特徴エンジニアリング）。

ビルダーをこの推論の過程でガイドしてください:

1. 仮説が対象を駆動するものは何と主張しているか? 主張される各ドライバーは1つ以上の推定目標にマップされます。仮説が「モメンタムとボラティリティレジームがリターンを予測する」の場合、推定目標は: (a) 複数の時間スケールでのモメンタム、(b) 現在のボラティリティレジーム。

2. 主要仮説を超えて、他にどんな量が有用か? この予測問題に関連する標準的な量はあるか? 例えば、リターンを予測する場合、現在のボラティリティレベルはほぼ常に関連があります（主要仮説の一部でなくても）。信号対ノイズ比に影響を与えるためです。

3. 各推定目標について、それを推定できるデータソースと計算アプローチは何か? 「モメンタム」目標は、ルックバックウィンドウ上のリターン、移動平均スロープ、指数移動平均比率、または他の多くのアプローチで推定できます。ビルダーはどの推定量がその量を最も良くキャプチャするかについての信念に基づいて選択します。

4. 自然なサブ問題はあるか? （原則9: 問題分解。）対象を成分に分解し、個別にモデル化することで予測が改善されるか? 例えば、条件付き平均と条件付き分散を個別に予測します。ビルダーがサブ問題が結合問題より扱いやすいと信じる理由がある場合のみ分解を追求してください。

このステップの出力: 推定目標のリスト。各目標について:

• 推定される量
• 予測対象への関連性（仮説への接続）
• 候補計算アプローチ
• 必要なデータソース

---

ステップ3: 特徴を構築する

各推定目標について、具体的な特徴を構築します。このステップは原則1（物理学優先）、2（予測期間適応型）、3（ルックアヘッド防止）を実装します。

各特徴について、ビルダーをこれらの決定でガイドしてください:

予測期間適応型パラメータ化。 すべての時間パラメータは H の倍数として表現される必要があります。ビルダーと協力して意味のある倍数を選択します:

• この推定目標が動作する時間スケールは H 相対で何か?
• この特徴は H より短い動態（分数倍数）、H スケール（倍数~1）、または H より長い動態（より大きい倍数）をキャプチャするべきか?
• 複数の期間パラメータを持つ特徴の場合（例: 2つの移動平均の比）、期間は互いに、そして H にどう関連するべきか?

ルックアヘッド防止。 各特徴について、確認してください:

• 計算は厳密に過去を見るだけか? （将来データを使用しない、全サンプル統計を使用しない。）
• ローリング/拡張ウィンドウは正しくバウンドされているか?
• 特徴計算後、生データ列（価格、ボリューム等）はモデル入力から削除されるか?

特徴の根拠。 各特徴は推定目標への文書化された接続を持つ必要があります。「台所シンク」特徴はありません。

このステップの出力: 特徴仕様 — 各特徴について:

• 名前と説明
• それが果たす推定目標
• 計算方法（データ列と予測期間適応型期間に関して）
• H 相対の期間倍数

その後、特徴エンジニアリングコードを書きます:

• 生データと予測期間 H を入力として取る関数またはクラス
• 過去データのみを使用してすべての特徴を計算
• 生列を持たないクリーンな特徴 DataFrame を返す
• すべての時間パラメータは H から設定の倍数を通じて導出

チェックポイント2

進める前にビルダーと確認してください:

• すべての特徴が述べられた推定目標を持つか?
• すべての時間パラメータが H の倍数として表現されているか?
• どの特徴も将来データを使用しないか（各計算をレビュー）
• 生データ列はモデル入力から除外されているか?
• 分解が使用されている場合、各サブ問題は独自の特徴セットを持つか?

---

ステップ4: 損失関数を設計する

損失関数は良い予測が何を構成するかについてのビルダーの信念をエンコードします（原則5）。これはモデリング決定であり、デフォルトではありません。

ビルダーをこれらの考慮事項でガイドしてください:

1. 最も重要なのは方向か、大きさか、それとも両方か? アプリケーションが主に方向精度を必要とする場合（例: バイナリ取引シグナル）、損失は方向正確性を強調すべきです。大きさが重要な場合（例: ポジションサイジング）、損失は大きさエラーを適切にペナルティすべきです。

2. 対象は不均一分散か? 対象の分散が時間とともに変化するか（金融データでは一般的）? 損失は局所的ボラティリティで正規化すべきか? ボラティリティ正規化損失は履歴平均ではなく現在の市場条件に調整された予測を生成します。

3. 外れ値はどのように処理すべきか? 金融データは fat tail を持ちます。二乗誤差損失は極端な観測に大きく影響されます。損失が外れ値に頑健であるべきか（例: Huber 損失、Cauchy 尾損失）、またはそれとも極端な観測が重要な信号を持つべきか考慮してください。

4. 非対称コストがあるか? 一方向で間違うことが他方で間違うことより費用が高いか? もしそうなら、損失はこの非対称性を反映すべきです。

5. ログリターン対象を特に: CZAR（Composite Zero-Agnostic Returns）損失を検討してください — Cauchy カーネルに基づいた区分損失であり、局所ボラティリティで z スコア化し、間違った符号にはきつい罰則を適用し、同符号予測のために有界 arctan 遷移を使用し、ゼロに近いリターン近くで損失をスムーズに低減します。完全な数学構造、パラメータ、実装詳細は 損失設計 を参照してください。

このステップの出力: 各設計選択について文書化された根拠を持つ損失関数の実装。

チェックポイント3

進める前にビルダーと確認してください:

• 損失関数はビルダーが実際に気にすることと一致しているか（方向、大きさ、調整）
• 設計選択は意図的か、デフォルトではないか
• カスタム損失成分を使用している場合、それぞれに明確な動機があるか

---

ステップ5: 検証パイプラインを設計する

3段階検証アーキテクチャ（原則4）をマルチしきい値品質ゲート（原則6）とオプティマイザーゲーミング防止（原則7）で構築します。詳細は 検証フレームワーク を参照してください。

ビルダーをこれらの決定でガイドしてください:

内部 CV 設計（ステージ1）:

• ウォークフォワードフォールド構造: 拡張またはスライディングウィンドウ?
• フォールド数（フォールドあたりの統計的有意性のための十分なテストサンプル）
• ギャップバッファサイズ: 最低でも max(H, max_feature_lookback) — 特徴仕様から計算
• 検証セットサイズ: テストセットサイズを一致（検証テスト パリティ）
• ハイパーパラメータ探索戦略: どのパラメータを探索するか、どの範囲、どの探索方法

外部評価設計（ステージ2）:

• 内部と外部部分の間のデータ分割方法
• 外部評価ウィンドウ数
• 一定の総テストカバレッジ: num_windows * window_size = const_test_epochs

品質ゲート: ビルダーと協力して各ゲートのしきい値を定義します。これらは実務でモデルが有用になるものを反映すべきです:

• 方向精度しきい値（チャンス以上 — この対象のベースラインは何か?）
• 統計的有意性レベル（通常 p < 0.05、信頼区間付き）
• 調整要件（予測大きさと実際の大きさ間の単調関係）
• 金融改善しきい値（指定ベースライン以上、アプリケーションに適切なメトリクスを使用）

このステップの出力: 検証パイプラインコードが実装:

• パージされたウォークフォワード CV、正しくサイズされたギャップバッファ
• 3段階データ分割
• すべての品質ゲート、ビルダー指定しきい値
• 検証テスト パリティと一定のテストカバレッジ

チェックポイント4

進める前にビルダーと確認してください:

• ギャップバッファサイズ >= max(H, max_feature_lookback)か?
• 外部評価ウィンドウは内部 CV データと重ならないか?
• 検証セットサイズがテストセットサイズに等しいか?
• すべての品質ゲートに定義されたしきい値があるか?
• しきい値は現在のモデルパフォーマンスではなく実用的要件に基づいて設定されたか?

---

ステップ6: 設定を構築する

すべての決定を設定仕様（原則8）にアセンブルします。設定は実験の単一の情報源です。

設定に含まれる必要があります:

# 予測問題
target:
  name: <何が予測されるか>
  horizon_bars: <H、バー数>
  asset: <資産識別子>

# データソース
data:
  exchange: <取引所名>
  interval: <バーサイズ>
  start: <使用する最初のデータ>
  end: <使用する最後のデータ、または "latest">

# 3段階分割の境界
partitions:
  optimization_end: <最適化期間の終了>
  evaluation_end: <評価期間の終了>
  deployment_end: <デプロイ期間の終了>
  gap_bars: <ギャップバッファサイズ（バー）>

# 推定目標でグループ化された特徴
features:
  <推定目標>:
    - name: <特徴名>
      window: <ルックバック（バー、H の倍数）>
      description: <これが何を測定するか>

# モデルアーキテクチャ
model:
  type: <モデルタイプ>
  task: <回帰または分類>

# 損失関数（モデル内ではなくトップレベル）
loss:
  name: <損失関数名>
  <損失固有パラメータ>

# 比較用ベースライン損失
comparison_loss: <ベースライン損失名>

# ハイパーパラメータ探索
hyperparameter_search:
  method: <探索方法>
  params:
    <パラメータ名>: <探索値>

# ウォークフォワードクロスバリデーション（ステージ1）
walk_forward_cv:
  n_folds: <数>
  expanding_window: <true または false>
  gap_bars: <ギャップバッファサイズ>

# 品質ゲート
gates:
  <ゲート名>:
    threshold: <しきい値>

# 出力
output_dir: <パス>

このステップの出力: 完全な YAML 設定ファイル。

---

ステップ7: パイプラインを実装する

仕様が完了したら、エンドツーエンドパイプラインを構築します。実装は以下のモジュールで構成されます:

1. 設定ローダー。 YAML 設定を読み込みます。すべてのダウンストリームコードは設定を参照します — ハードコード値はありません。

2. データローダー。 指定されたソースからデータをフェッチし、欠損値を処理し、タイムスタンプをアライン、クリーン DataFrame を生成します。ビルダーの特定のデータソースを処理する必要があります。

3. 特徴エンジニア。 ステップ3の特徴仕様を実装します。生データと H を取り、計算された特徴を返す（生列は削除）。すべての時間パラメータは H から導出。

4. 対象コンストラクタ。 適切なシフトを使用して対象変数を計算します。シフトはグローバルに一度適用され、H から導出されます。これが対象アライメントの単一の情報源です。

5. モデルと損失。 ステップ4からモデルアーキテクチャとカスタム損失関数を実装します。モデルは特徴を入力として取り、対象の予測を生成します。

6. 検証パイプライン。 ステップ5の3段階アーキテクチャを実装:

• ステージ1: 内部パージウォークフォワード CV、ハイパーパラメータ探索
• ステージ2: 独立ウィンドウでの外部評価、マルチしきい値品質ゲート
• デプロイ検証: デプロイ前のすべてのデータで再学習、品質ゲートと同じ保留デプロイセットで評価
• ステージ3: デプロイ用全データ再学習（デプロイ検証が成功した場合のみ）

7. 評価レポート。 パイプライン実行後、サマリーを生成:

• フォールドごと内部 CV 結果
• ウィンドウごと外部評価結果
• 各ゲートの品質ゲート合否
• 全体合否判定
• 主要メトリクスの信頼区間

ビルダーをモジュール実装でガイドしてください。各モジュールについて:

• コードを一緒に書く
• すべての適用可能な原則を尊重するか確認
• 次のモジュールに移動する前にサンプルデータでテスト

チェックポイント5

フルパイプラインを実行する前に確認してください:

• 設定は完全か、すべてのコードはそれから読むか（ハードコードパラメータなし）
• 特徴エンジニアは過去データのみを使用し、生列を削除するか
• 対象シフトは一度グローバルに適用されるか
• CV のギャップバッファは正しくサイズされているか
• 検証パイプラインはすべての3段階を実装するか
• 品質ゲートはすべての条件を同時にチェックするか
• ステージ間にデータリークはないか（内部データは外部データより厳密に前）

---

ステップ8: 実行と評価

フルパイプラインを実行し、結果を解釈します。

モデルが評価セットのすべての品質ゲートに合格した場合:

• デプロイ検証を実行: デプロイ前のすべてのデータ（最適化 + 評価、ギャップバッファを除く）で凍結ハイパーパラメータを使用して再学習。品質ゲートと同じで保留デプロイセットで評価します。これは評価に合格しても更に一般化しないモデルを捕捉します。
• デプロイ検証が失敗した場合: 評価とデプロイパフォーマンス間のギャップを診断してください。ゲートしきい値を緩和しないでください。以下の失敗処理ガイダンスが適用されます。
• デプロイ検証に合格した場合:
  • 信頼区間付き結果を報告。ビルダーと討論: 結果は仮説と一致しているか? どの推定目標が最も予測的に見えるか?
  • ステージ3（全データ再学習）を進める: ステージ1の凍結ハイパーパラメータを使用してすべて利用可能なデータで再学習
  • デプロイ後監視を設計します。ビルダーは定義すべき:
    • パフォーマンス監視: ライブ予測を実現結果に対して追跡。ライブパフォーマンスが降級してから再評価をトリガーするのに十分な程度まで低下した場合のしきい値を定義（例: 監視ウィンドウ上の方向精度が品質ゲートしきい値以下に低下）。
    • 特徴監視: 特徴分布を追跡。いずれかの特徴の分布が学習で見られたものから大幅にドリフトした場合、モデルはその有効レジーム外で動作している可能性があります。
    • 鮮度チェック: 最大モデル年齢を定義。パフォーマンスが降級していなくても、モデルは新しいデータで定期的に再検証されるべき。
    • リビルドトリガー: どのしきい値で降級はフルリビルドをトリガーするか? リビルドは同じ検証フレームワークを使用するか、またはゲートを見直すべきか?

モデルが1つ以上の品質ゲートに失敗した場合:

• どのゲートが失敗し、どの程度失敗したかを特定
• 診断: 仮説が間違っているか、実装が不十分か?
  • 失敗した方向精度: 特徴は予測信号を持たないかもしれません。仮説と推定目標を見直す（ステップ2）。
  • 失敗した有意性: 信号があるが検出に十分なデータがないかもしれません。より長い履歴またはより多くの外部評価ウィンドウを検討。
  • 失敗した調整: モデルは正しい方向を持つが大きさが間違っているかもしれません。損失関数を見直す（ステップ4）。
  • 失敗した金融改善: 信号は存在するが弱すぎてトランザクションコストを克服したり、シンプルなベースラインを改善するには不十分かもしれません。予測問題が扱い可能か考慮してください。
• ビルダーは反復するか（適切なステップに戻る）または異なる仮説にピボットするか決定します。

品質ゲートしきい値を調整してモデルを成功させないでください。 モデルが基準を満たさない場合、正直な答えはモデルがまだ十分に良くない — ということです。しきい値を下げるとモデルがより良くなりません; それは評価を悪くします。

---

出力仕様

完了した仮説駆動型パイプラインはこれらの成果物を生成します:

成果物	説明
config.yaml	完全な実験仕様 — 予測対象、期間、特徴、モデル、検証パラメータ
data_loader.py	指定ソースからデータをフェッチし前処理
feature_engineer.py	生データから特徴を計算、予測期間適応型、ルックアヘッドなし
model.py	モデルアーキテクチャとカスタム損失関数
validation.py	3段階検証パイプライン、マルチしきい値品質ゲート
evaluate.py