1. qteasy 全体的なアーキテクチャと設計アプローチ

1.1. 1. 引言：为什么需要从“架构”理解 qteasy

qteasy は、ローカライズされた再現可能な定量取引ツールキットです。ユーザー ガイドや API ドキュメントを超えて、システム アーキテクチャ と 設計理論的根拠 の観点からモジュールがどのように階層化され、連携するかを理解することは、インターフェイスをより正確に使用し、問題をトラブルシューティングし、カスタム戦略やデータを拡張する際の迂回路を回避するのに役立ちます。この章では、qteasy のアーキテクチャと 3 つの主要な設計スレッドの全体的な概要を説明します。後続の章では各モジュールについて詳しく説明します。

1.2. 2. 三条设计主线（简述）

2.1 データ: 「生のテーブル」から「型付き情報」へ (DataType)

生の市場データ、財務データ、およびその他のデータが取得されてクリーンアップされた後、統合されたテーブル スキーマを使用して DataSource (ファイルまたはデータベース) に保存されます。 qteasy では、ストラテジーがこれらのテーブルを直接読み書きすることはできません。代わりに、「戦略で使用できる情報」を DataType (一意の dtype_id に対応する名前、頻度、資産タイプなどで構成される) に抽象化します。戦略は、必要な DataType と必要な履歴ウィンドウ (window_length) の長さを宣言するだけです。実行時に、エンジンは宣言に従って DataSource からデータを取得し、データ ウィンドウに編成して、ストラテジに挿入します。その目的には、バックテストとライブ取引に同じデータビューを使用すること、ストラテジーインターフェイスを統合すること、メカニズムレベルでの「先読みバイアス」を防止することが含まれます（ストラテジーは各タイムステップでエンジンによって注入された過去のデータのみを確認できます）。

2.2 戦略: 4 つの主要な要素と統合された Realize()

概念的には、戦略には 4 つのカテゴリの要素が含まれます。

  • 実行タイミング: 実行するタイミングと頻度 (例: 毎日の市場終了時) — qteasy 2.0 では、これはストラテジー クラス内にハードコーディングされず、ストラテジーの グループ によって管理されます。

  • 必須データ: 必要な DataType、ウィンドウの長さ (data_types、window_length など)。ストラテジの初期化中に宣言されます。

  • 調整可能なパラメーター: パラメーター によって定義され、set_parameter などを介して実行前に設定されます。最適化中に、オプティマイザーはパラメーター空間を検索します。

  • ロジック: パラメーターなしの realize() によって実装されます。メソッド内で、get_pars() と get_data(dtype_id) を使用して現在のステップのパラメーターとデータを取得し、取引シグナルを計算して返します。

一貫した動作を保証するために、同じ realize() がバックテストとライブ取引の両方で再利用されます。

2.3 実行: Operator とグループ、タイムステップによる駆動、統合された run(config)

Operator は、ストラテジのコンテナと実行のエントリ ポイントの両方です。複数の Group を保持し、各グループは同じ run_freq と run_timing (および signal_type と Blender) を持つストラテジのセットです。 group_timing_table は、各タイム ステップでどのグループを実行する必要があるかを示す「タイム ステップ × グループ」テーブルです。シングルステップのワークフローは次のように要約できます: 現在のステップのテーブルを検索して実行するグ​​ループを取得 → それらのグループの各戦略のデータ ウィンドウを準備して挿入 → 各戦略の generate() (内部で realize() を呼び出します) を呼び出します → グループの ブレンダー を使用してグループ内の信号をブレンドします → そのステップのマージされた信号を取得します。バックテスト、ライブ取引、最適化はすべて、「group_timing_table に従って Operator を段階的に実行する」という同じメカニズムに基づいています。違いは、データ ソース (ヒストリカル vs リアルタイム) と結果処理 (シミュレートされた約定 vs 実際の注文 vs パラメーター検索) のみです。

2.4 視覚化: HistoryPanel およびマルチバックエンド チャート

データと実行に加えて、qteasy は HistoryPanel ベースの視覚化スタック を提供します。

  • 3D データ コンテナ (shares × hdates × htypes) として、HistoryPanel は、get_history_data の自然な戻り値であり、視覚化の前提条件となるデータ構造でもあります。

  • HistoryPanel.plot(...) は、統合されたプロットのエントリ ポイントです。 htypes とsharesに基づいて適切なチャートタイプ（ローソク足、出来高、MACD、折れ線チャートなど）を自動的に選択し、バックエンドに依存しないチャート仕様を生成します。

  • 静的バックエンド (matplotlib) と対話型バックエンド (Plotly) は、同じ仕様セットに基づいてチャートをレンダリングし、配色、レイアウト、セマンティクスにおける静的ビューと対話型ビューの間の一貫性を確保します。

  • qt.candle(...) などの上位層 API は、「データの取得 → HistoryPanel の構築 → hp.plot() の呼び出し」の単なるラッパーです。

このようにして、視覚化ロジックがデータ取得やバックテスト エンジンから切り離され、独立して進化してテストすることが容易になります。

1.3. 3. 总体架构图（三层）

qteasy は、以下の図 (テキスト版) に示すように、責任に応じて 3 つの層に分けることができます。

flowchart TB subgraph dataLayer [数据层] DS[DataSource] Tables[数据表] DT[DataType / dtype_id] GHD[get_history_data] HP[HistoryPanel] DS --> Tables Tables --> DT DT --> GHD GHD --> HP end subgraph strategyLayer [策略层] BS[BaseStrategy 及子类] PAR[Parameter] DTL[data_types / window_length] BS --> PAR BS --> DTL HP --> BS end subgraph runLayer [运行层] OP[Operator] GR[Group] GTT[group_timing_table] BL[blender] BT[Backtester] TR[Trader] OPR[Optimizer] OP --> GR OP --> GTT GR --> BL OP --> BT OP --> TR OP --> OPR end subgraph vizLayer [可视化层] HPPlot[HistoryPanel.plot] SpecBuilder[图表规格/布局] StaticBackend[静态后端(matplotlib)] InteractiveBackend[交互后端(Plotly)] HP --> HPPlot HPPlot --> SpecBuilder SpecBuilder --> StaticBackend SpecBuilder --> InteractiveBackend end dataLayer --> strategyLayer strategyLayer --> runLayer dataLayer --> vizLayer

  • データ レイヤー: DataSource、データ テーブル、DataType、および外部向きの get_history_data / HistoryPanel は、ストラテジー レイヤーとランタイム レイヤーに「タイプ別、ウィンドウ別」の履歴情報を提供します。

  • 戦略層: BaseStrategy とそのサブクラス (RuleIterator、FactorSorter、GeneralStg など)、パラメーター、data_types / window_length、要件の宣言と Realize() の実装を担当します。

  • ランタイム レイヤー: Operator、グループ、group_timing_table、ブレンダー、および Backtester / Trader / オプティマイザー。時間の経過とともに戦略を推進し、シグナルを集約し、バックテスト / ライブ トレード / 最適化を実行します。

1.4. 4. 核心对象关系图

flowchart LR subgraph operator [Operator] G1[Group A] G2[Group B] end G1 --> S1[Strategy 1] G1 --> S2[Strategy 2] G2 --> S3[Strategy 3] S1 --> DT[DataType] S1 --> PAR[Parameter] S2 --> DT S2 --> PAR S3 --> DT S3 --> PAR OP_RUN[op.run] CFG[config] DSRC[datasource] OP_RUN --> operator CFG --> OP_RUN DSRC --> OP_RUN

  • Operator には複数のグループが含まれており、各グループには複数の戦略が含まれています。

  • 各ストラテジーは、依存する DataType (および window_length) を宣言し、パラメーターを介して調整可能なパラメーターを定義します。

  • エントリ ポイントは op.run(config, datasource, logger) で、構成とデータソースによって駆動されます。

1.5. 5. 数据与信号的大致流向

データソースから戦略、バックテスト/ライブ取引/最適化に至るまで、全体的なフローは次のように簡略化できます。

sequenceDiagram participant User participant DataSource participant Operator participant Strategy participant Backtester User->>Operator: qt.run(op, mode=1/0/2, ...) Operator->>DataSource: 按策略声明请求历史/实时数据 DataSource-->>Operator: 数据窗口 loop 每个时间步 Operator->>Strategy: 注入数据窗口，调用 realize() Strategy-->>Operator: 信号 Operator->>Operator: blender 混合 end Operator-->>Backtester: 信号序列（回测时） Backtester-->>User: 资金曲线、绩效等

  • ユーザーは、qt.run(op, mode=...) を介してバックテスト (1)、ライブ取引 (0)、または最適化 (2) を入力します。

  • 設定とストラテジの宣言に基づいて、Operator は DataSource にデータを要求し、group_timing_table に従ってステップごとにストラテジを呼び出し、信号をブレンドします。

  • バックテストでは、シミュレーションされたフィルと評価のために信号シーケンスが Backtester に渡されます。ライブ取引では、執行のためにTrader/ブローカーに渡されます。最適化では、オプティマイザーはバックテストを複数回実行し、結果を集計します。

1.6. 6. 本系列各章与教程、API、示例的阅读顺序建议

  • このシリーズ (アーキテクチャとデザイン): 最初にこの章 (00) と コア概念の概要 を読んでから、必要に応じて データ レイヤー、戦略におけるデータ、[Operator およびグループ、戦略の実行とパラメーター、バックテスト/ライブ取引/最適化 を使用して、全体像を構築します。

  • ユーザー ガイド: 「実践的な」ステップバイステップの操作に焦点を当てています。アーキテクチャを理解した後、特定のタスク (データのダウンロード、戦略の作成、バックテストの実行など) を完了するために、必要に応じて選択的に読むのに適しています。

  • 過去の財務データをダウンロードして管理、API リファレンス: データ構成、インターフェイス パラメーター、および戻り値を検索するために使用されます。このシリーズでは「構造とメカニズム」のみを取り上げており、API ドキュメントに代わるものではありません。

  • 例: チュートリアルおよびこのシリーズと一緒に使用できる完全な実行可能な例を提供します。