3. HistoryPanel

この章では、HistoryPanel を紹介します。DataType の理解を基に、複数のターゲット、メトリクス、および同じタイムラインからの履歴データを 1 つの「パネル」に統合し、それを戦略調査、バックテストの準備、視覚化全体で再利用する方法を示します。この章を読むのに、ローカルデータソースを事前に読む必要はありませんが、ローカルデータソースにまだデータを設定していない場合は、get_history_data を使用してデータを取得する前に、ダウンロードと構成を完了してください。

前の章では、qteasy が DataType を使用して、「データテーブルの生の列」を戦略とバックテストで直接使用できる情報に抽象化していることを見ました。この情報を、複数のターゲットとさまざまなデータ型 (OHLC、ボリューム、MACD など) を含む同じタイムラインに 位置合わせする必要がある場合、複数の DataFrames を手動で連結すると、エラーが発生しやすくなるだけでなく、ストラテジーコードとビジュアライゼーションコードの間で同じデータ構造を再利用することも妨げられます。

HistoryPanel は、このシナリオ用に設計されたコンテナです。内部的には、shares × index × htypes の 3 次元構造にデータを編成します。これにより、統合インターフェイスを使用してシェアやメトリクスをスライスおよびフィルタリングし、後続のバックテスト、戦略ロジック、またはプロットで同じオブジェクトを再利用できます。ほとんどのユーザーは、パネルが内部でローカルデータソースとどのように対話するかを心配する必要はありません。 get_history_data などの使い慣れたワークフローを通じて HistoryPanel を取得した後、それを「時間調整された、複数共有、複数メトリクスのデータセット」として使用できます。

この章では、HistoryPanel の中心的な概念と一般的な使用法について説明します。 次の章 HistoryPanel Visualization はこれに基づいて、hp.plot() を使用して同じパネルを静的グラフまたは対話型グラフとして直接プロットする方法を紹介します。一般的なパスとの混乱を避けるために、下位レベルのデータ取得 API 機能は API リファレンス に簡単にリストされています。

3.1. 中心概念: 3D 構造と `shape`

HistoryPanel は、メモリ内の 3 次元の numpy.ndarray に対応し、次の 3 つの軸を持ちます。

軸	意味	共通のプロパティ
0次元	対象（銘柄コード等）	`shares`, `level_count`
1次元	時間 (歴史的な日付または瞬間)	`hdates`, `row_count`
2次元	データ型 (`open`、`close`、`vol` など)	`htypes`, `column_count`

shape は、上記と同じ順序で (ターゲットの数、期間、データ型の数) を返します。これは次のように理解できます。「時間 × メトリック」の多数の 2 次元テーブルが ターゲット 方向に積み重ねられています。同じパネル内で、ターゲットと指標は時間的に調整されます。

シングルインデックス幅のテーブル DataFrame (行は時間、列はインデックス) と比較して、HistoryPanel は マルチインデックス を 0 番目の次元に明示的に配置します。これにより、複数の MultiIndex 列を維持する必要がなく、バッチ操作とインデックスベースのスライスが容易になります。

(説明図:「3D ブロック」は、L 層インデックス × R 行時間 × C 列インデックスとして理解できます。必要に応じて、後のバージョンで図を追加できます。)

3.2. HistoryPanelの入手方法

推奨されるアプローチは **qt.get_history_data(..., as_data_frame=False) を使用することです。必要なデータがローカルデータソースですでに利用可能であると仮定すると、htype_names (DataType の命名と一致しています。前の章を参照) を shares、時間範囲、または rows とともに指定することで、調整された HistoryPanel を取得できます。

デフォルトでは、get_history_data は as_data_frame を True に設定し、インデックスごとにグループ化された dict[str, DataFrame] を返します。これは、単一インデックスデータをすばやく表示するのに適しています。 3D パネルが必要な場合は、必ず as_data_frame=False を渡してください。 完全なパラメーター、頻度、重み付け情報については、履歴データ API を参照してください。

以下の例は ネットワークに依存せず、小さな配列を使用してパネルを構築しているため、shape とラベルが理解しやすくなっています。実際の作業では、代わりに get_history_data を使用してローカルデータソースからデータを設定できます。

import numpy as np
import pandas as pd
from qteasy import HistoryPanel

# 2 只标的、4 个交易日、3 种数据类型 → shape (2, 4, 3)
values = np.array(
    [
        [[1.0, 1.1, 100], [1.2, 1.3, 110], [1.15, 1.2, 105], [1.25, 1.28, 120]],
        [[10.0, 10.5, 200], [10.2, 10.8, 210], [10.1, 10.4, 205], [10.3, 10.9, 215]],
    ],
    dtype=float,
)
hp = HistoryPanel(
    values=values,
    levels=['000001.SZ', '000002.SZ'],
    rows=pd.date_range('2025-01-02', periods=4, freq='B'),
    columns=['open', 'high', 'vol'],
)
print(hp.shape)          # (2, 4, 3)
print(hp.shares)         # 标的列表
print(hp.htypes)         # 数据类型列表

ローカル市場データがすでに利用可能な場合は、次のように変更できます。

import qteasy as qt

hp = qt.get_history_data(
    htype_names='open, high, low, close, vol',
    shares='000001.SZ',
    rows=60,
    as_data_frame=False,
)
print(hp.shape, hp.shares, hp.htypes)

3.3. 基本操作: 時間範囲、ターゲットおよびインジケーターのサブセット

次のメソッドは、データ取得セマンティクスを変更せずに、現在の焦点を絞り込みます。戻り値は依然として HistoryPanel です (空のパネルを除く)。

日付範囲別: segment(start_date, end_date)、閉じた範囲内のすべての時間行。日付は、hdates の粒度 (毎日の頻度、日中など) と一致させることができます。
行番号範囲別: Python スライスと同様の isegment(start_index, end_index) は、位置によるセグメントの抽出に適しています。
**最近の行: head(n) / tail(n)。
ターゲット名および/またはインジケーター名によるフィルター: slice(shares='A, B', htypes='close, vol')、文字列またはリストのいずれかを使用できます。

単一インデックスまたは複数インデックスのデータに対してパンダ分析を実行する場合、to_share_frame(share) を使用して、そのインデックスの DataFrame を取得できます (インデックスとして時刻、列として htypes を使用)。マルチインデックスデータのエクスポートの詳細については、to_df_dict の API ドキュメントおよびその他の関連ドキュメントを参照してください。

Operator およびバックテストプロセスでは、戦略実行のスケジューリングフェーズ中に履歴データがグループに注入されることがよくあります。特定のパラメータとスケジュール設定については、「トレーディング戦略の作成と運用」 の関連する章を参照してください。ここでは、次のことを確立するだけで十分です。 **戦略と視覚化は両方とも同じ HistoryPanel (またはそのスライス) ** を中心に展開でき、それによって「複数の形式の 1 つのデータセット」の繰り返しの編成が削減されます。

3.4. メトリクスと列拡張子 (`kline` など)

既存の価格クラス htypes を基盤として、hp.kline アクセサーを介して、移動平均、MACD、ボリンジャーバンドなどの一般的な派生列にアクセスできます。これらのメソッドは通常、新しい HistoryPanel を返します。元のオブジェクトを変更せず、インジケーター列を 3 番目の次元に追加し、shares と hdates を元のパネルと一致させます。新しいバージョンでは、調整された列名 (close|b など) は、kline、returns などの解析ロジックに合わせて調整されます。未加工の列名と調整された列名の両方がパネルに存在する場合は、HistoryPanel API の動作の説明を読むことをお勧めします。

ファクターベースの手法 (リターン、ボラティリティ、apply_ta など) のより完全な例は、チュートリアル HistoryPanel を使用して履歴データを操作および分析する にあります。

3.5. 概要と次のステップ

HistoryPanel は、(ターゲット × 時間 × データ型) の統合コンテナーを提供します。これは、複数のターゲット、複数のメトリクス、および時間調整を使用した調査およびバックテストの準備に適しています。
get_history_data(..., as_data_frame=False) 関数は、データフレームを取得するためによく使用されます。デフォルトでは、まず、DataType の命名と get_dtype_map() に関する前の章を読むことができます。
スライスとサブセット: segment / isegment / head / tail / slice;単一フレームをエクスポートしています: to_share_frame。
次の章 HistoryPanel 視覚化: hp.plot() を使用して静的プロットまたは対話型プロットを作成します。
ローカルデータの準備ができていない場合は、最初に ローカルデータソース と データの取得とチャネル をお読みください。