Ptrade 平台 get_individual_entrust 获取的数据结构是什么？如何解析返回的 Panel 对象？

在 Ptrade 量化交易平台中，get_individual_entrust 接口用于获取当日的逐笔委托（Level2）行情数据。根据传入的参数 is_dict 以及 Python 环境版本的不同，该接口返回的数据结构会有所差异。以下是详细的数据结构解析及 Pandas Panel 对象的处理方法。

一、 get_individual_entrust 返回的数据结构

get_individual_entrust 主要有三种返回数据结构：

1. Dict 字典类型（当 is_dict=True 时）

这是官方推荐的高效获取方式，取数速度大幅提升。返回格式如下：

{
    "股票代码(str)": [[时间戳毫秒级, 价格, 委托数量, 委托编号, 委托方向, 委托类型], ...],
    "fields": ["business_time", "hq_px", "business_amount", "order_no", "business_direction", "trans_kind"]
}

2. DataFrame 类型（Python 3.11 环境，默认 is_dict=False）

返回一个 Pandas DataFrame，包含以下列：

• code: 代码 (str)
• business_time: 时间戳毫秒级 (int)
• hq_px: 价格 (float)
• business_amount: 委托数量 (int)
• order_no: 委托编号 (int)
• business_direction: 成交方向 (int)
• trans_kind: 委托类型 (int)

3. Pandas Panel 类型（Python 3.5 环境，默认 is_dict=False）

在较老的 Python 3.5 环境中，默认返回 Pandas Panel 对象。其三维结构如下：

• Items axis: 股票代码列表 (str)，例如 '000001.SZ'。
• Major_axis axis: 数据索引，通常为自然数列 (0, 1, 2...)。
• Minor_axis axis: 具体的字段信息，包含：
  • business_time: 时间戳毫秒级 (numpy.int64)
  • hq_px: 价格 (numpy.int64 / float)
  • business_amount: 委托数量 (numpy.int64)
  • order_no: 委托编号 (numpy.int64)
  • business_direction: 委托方向 (numpy.int64) —— 0:卖, 1:买, 2:借入, 3:出借
  • trans_kind: 委托类型 (numpy.int64) —— 1:市价, 2:限价, 3:本方最优

二、 如何解析 Pandas Panel 对象

如果你在 Python 3.5 环境下获取到了 Panel 对象，可以通过以下方式进行解析和提取数据：

示例代码：解析 Panel 对象

def initialize(context):
    g.security = ["000001.SZ", "000002.SZ"]
    set_universe(g.security)

def handle_data(context, data):
    # 获取股票池逐笔委托数据（Python 3.5 默认返回 Panel）
    entrust_panel = get_individual_entrust(g.security)
    
    if entrust_panel is not None:
        # 1. 获取特定股票的 DataFrame
        # 通过 Items axis (股票代码) 获取对应的 DataFrame
        df_000001 = entrust_panel["000001.SZ"]
        log.info("000001.SZ 的逐笔委托数据：\n%s" % df_000001)
        
        # 2. 提取特定字段
        # 从该股票的 DataFrame 中提取委托量 (business_amount)
        business_amount = df_000001["business_amount"]
        log.info("000001.SZ 的委托量序列：\n%s" % business_amount)
        
        # 3. 遍历最新的一笔委托
        if not df_000001.empty:
            latest_entrust = df_000001.iloc[0] # 假设 search_direction=1，第一条为最新
            log.info("最新委托价格: %s, 数量: %s, 方向: %s" % (
                latest_entrust['hq_px'], 
                latest_entrust['business_amount'],
                latest_entrust['business_direction']
            ))

三、 最佳实践建议

1. 优先使用 Dict 格式：无论是在 Python 3.5 还是 3.11 环境，强烈建议在调用时传入 is_dict=True（例如 get_individual_entrust(g.security, is_dict=True)）。字典格式的解析速度远快于 Panel 和 DataFrame，这对于处理高频的 Level2 逐笔数据至关重要。
2. 权限确认：逐笔委托数据属于 Level2 行情，调用此接口前请务必确认您的 Ptrade 账户已开通 L2 行情权限，否则接口将返回 None。
3. 数据量控制：通过 data_count 参数控制获取的数据条数（最大200条），避免单次请求数据量过大导致策略运行超时。