3. HistoryPanel（歷史數據面板）

本章介紹 HistoryPanel：在已理解 DataType 的前提下，如何把多標的、多指標、同一時間軸上的歷史數據收攏爲一塊「面板」，並在策略研究、回測準備與可視化之間複用。閱讀本章無需先讀本地數據源 DataSource，但若尚未向本地數據源填充數據，請先完成下載與配置後再使用 get_history_data 取數。

在上一章中，我們已經看到，qteasy 用 DataType 把「數據表裏的原始列」抽象成策略與回測可以直接消費的資訊。當這些資訊需要在時間上與多隻標的、多種數據類型（例如 OHLC、成交量、MACD 等）對齊到同一套時間軸上時，如果仍靠手工拼接多個 DataFrame，既容易出錯，也不利於策略代碼與可視化代碼複用同一套數據結構。

HistoryPanel（歷史數據面板） 正是爲這一場景準備的容器：它在內部把數據組織爲 標的（shares）× 時間（index）× 數據類型（htypes） 三維結構，讓你可以用統一的接口做切片、篩選標的或指標，並在後續 回測、策略邏輯或繪圖 中沿用同一份對象。對大多數用戶來說，你並不需要關心面板在內部如何與本地數據源交互；通過熟悉的 get_history_data 等工作流拿到 HistoryPanel 之後，就可以把它當作「時間上對齊好的、可多標的、多指標的一塊數據整體」來使用。

本章說明 HistoryPanel 的核心概念與常見用法；下一章 HistoryPanel 可視化 在此基礎上介紹如何 hp.plot() 將同一塊麪板直接畫成靜態圖或交互圖。更底層的取數 API 分工，僅在 API 參考 中擇要列出，以免與日常路徑混淆。

3.1. 核心概念：三維結構與 `shape`

HistoryPanel 在內存中對應一個三維 numpy.ndarray，三條軸依次爲：

軸	含義	常用屬性
第 0 維	標的（證券代碼等）	`shares`、`level_count`
第 1 維	時間（歷史日期或時刻）	`hdates`、`row_count`
第 2 維	數據類型（如 `open`、`close`、`vol`）	`htypes`、`column_count`

shape 返回 (標的數, 時間長度, 數據類型數)，與上面順序一致。可以把它理解爲：許多張「時間 × 指標」的二維表，在標的方向上再疊一層；同一面板內，各標的、各指標在時間上是對齊的。

與單標的寬表 DataFrame（行是時間、列是指標）相比，HistoryPanel 把 多標的 明確放在第 0 維，便於批量運算與按標的切片，而不必維護多層 MultiIndex 列。

（示意圖：可將「三維塊」理解爲 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]，適合快速查看單標的；需要三維面板時，務必傳入 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 中的粒度一致（日頻、日內等）。
按行號區間：isegment(start_index, end_index)，與 Python 切片類似，適用於按位置截取。
最近若干行：head(n) / tail(n)。
按標的與/或指標名篩選：slice(shares='A, B', htypes='close, vol')，字符串或列表均可。

單標的、多指標繼續用 pandas 分析時，可用 to_share_frame(share) 得到該標的的 DataFrame（時間爲索引，列爲 htypes）。多標的導出還可參見 API 文檔中的 to_df_dict 等說明。

Operator 與回測流程中，歷史數據往往在策略運行調度階段按組注入；具體參數與時間表配置見 「創建並操作交易策略」 相關章節。此處只需建立印象：策略與可視化都可以圍繞同一塊 HistoryPanel（或其切片）展開，從而減少「一份數據、多種形狀」的重複整理。

3.4. 指標與列擴展（`kline` 等）

在已有價格類 htypes 的基礎上，可以通過 hp.kline 訪問器調用均線、MACD、布林帶等常見派生列。這類方法通常返回新的 HistoryPanel：在第三維上追加指標列，不原地修改原對象，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() 做靜態或交互制圖。
本地數據未就緒時，請先閱讀 本地數據源 DataSource 與 數據拉取與渠道。