11. HistoryPanel およびオプションの「FactorResearch」ヘルパー層 (評価結論)

この文書は、ロードマップの評価項目に答えます: IC/IR、分位数ポートフォリオのリターン、ロングショート曲線などの計算専用の、HistoryPanel (作業名 FactorResearch) の上に別の軽量 API 抽象化レイヤーを追加する必要がありますか?

11.1. 1. 当前能力边界（已满足的部分）

次の機能は、HistoryPanel および関連 API ですでにカバーされているため、車輪を再発明する必要はありません。

  • 因子列の生成: assign、__setitem__、returns、kline、apply_ta など。

  • 断面変換: rank、zscore(method='cs'|'ts');

  • 大まかなポートフォリオとベンチマーク: portfolio (均等加重/加重、groups、benchmark);

  • 研究指向の戻り表示: cum_return、normalize、および mask=;

  • 視覚化: plot および (M,L) マスクの強調表示。

  • 測定/分析ツールとの統合: to_df_dict、または手動で長い形式に再形成してから、pandas / statsmodels を使用します (チュートリアル 2.5 §11 を参照)。

「軽量化要素の調査 + 大まかな検証」という目的に向けて、上記は既に 完全な基盤 を形成しています。

11.2. 2. 若增加 FactorResearch 层，能解决什么？

典型的なラッパーには次のものが含まれます。

  • 因子列と戻り列 (またはラベル) を指定すると、期間ごとの IC、IC 平均/IR が出力されます。

  • 分位ポートフォリオの NAV またはリターン シリーズ (クロスセクションごとにバケット化)。

  • ロング/ショート ポートフォリオの時系列 (上部から下部を引いたもの)。

これらはすべて、ユーザー側の数十行で、または既存の rank / portfolio / values + pandas を使用する独立したモジュールで実装できます。ラッピングの価値は、安定した API、統一されたパラメーター規則、およびコピー＆ペーストのエラーの減少にあります。

11.3. 3. 结论（短期不引入类库级 FactorResearch）

結論: 現段階では、qteasy カーネルまたは HistoryPanel 上に FactorResearch クラス/サブモジュールを強制的に追加することはありません。

簡単な根拠:

  1. 明確な責任: HistoryPanel は、明示的な位置合わせ/リサンプリングを備えた 3D 研究コンテナとしてすでに位置づけられています。 IC/IR、クォンタイルポートフォリオなどは、より強力なリサーチワークフロー規約を備えた「分析レシピ」です。これらは、HP API の肥大化を避けるために、スタンドアロンのチュートリアル、サンプル、または将来のオプション パッケージに適しています。

  2. 誤った期待を避ける: スタンドアロン モジュールという名前を付けると、ユーザーはフレームワークにすでに「出版グレードの要素テスト」 (複数のテスト、サンプル分割、HAC 標準誤差など) が含まれていると簡単に思い込む可能性がありますが、実際にはユーザーは統計モデル側などで推論を行う必要があります。

  3. 中期的な「組み込み因子ライブラリ」 との関係: 最上位ロードマップの 組み込み因子ライブラリ (M2.1) が実装される場合、より自然なアプローチは 因子定義 + 登録 + FactorSorter/バックテストとの統合 になります。バッチ IC/階層化は、HistoryPanel インスタンス メソッドではなく、因子ライブラリに関する オプションのユーティリティ関数 にすることができます。

  4. メンテナンスコスト: IC には、フォワードリターンウィンドウ、取引停止、上場廃止、重み付け (価値重み付けと等重み付け) などの規則が必要です。パラメーターの組み合わせは多数あります。統一されたデータ契約がなければ、サポートコストが簡単に上昇する可能性があります。

11.4. 4. 若未来引入，建议形态（备忘）

コミュニティの需要が明らかな場合は、HistoryPanel メソッドではなく 独立モジュール (例: qteasy.research.factor_stats または外部 qteasy-research プロジェクト) を推奨します。

  • 入力: HistoryPanel または DataFrame + 列名 + 将来予測期間。

  • 出力: DataFrame / Series (オプションで補足として再プロット);

  • ドキュメント: Backtester の代替品ではないこと、および Fama–MacBeth / Newey–West が組み込まれていないことを明確に述べています (統計モデルにはまだエクスポートされています)。

その時点で、既存の HP テスト スタイルと一致する TDD と英語の ValueError コントラクトが付属している必要があります。

11.5. 5. 与教程的关系

実際のワークフローについては、チュートリアル 2.5: HistoryPanel を使用した履歴データの操作と分析 の §9 ～ §11 に従ってください。この設計ドキュメントは アーキテクチャ レベルの評価結果を記録するだけであり、ユーザーに必読の API サーフェスは追加されていません。