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 与 数据拉取与渠道。