如何在 JoinQuant 中将 context.portfolio.positions 转换为 DataFrame 并查看列名？

在 JoinQuant (聚宽) 平台中，context.portfolio.positions 是一个字典（dict），其键（key）是标的代码（如 '000001.XSHE'），值（value）是对应的 Position（持仓）对象。

1. 直接转换的误区

如果您直接使用 pd.DataFrame([context.portfolio.positions])，由于传入的是一个包含单个字典的列表，Pandas 会将字典的键（标的代码）作为列名，而将值（Position 对象本身）作为该列对应的值。这通常不是我们想要的结果，因为我们无法直观地看到持仓的具体数据（如持仓量、成本等）。

2. 正确的转换方法

为了得到一个包含各项持仓指标的 DataFrame，我们需要遍历 context.portfolio.positions，提取出 Position 对象的各个属性，然后再转换为 DataFrame。代码如下：

import pandas as pd

def get_positions_df(context):
    positions = context.portfolio.positions
    if not positions:
        return pd.DataFrame() # 如果没有持仓，返回空 DataFrame
    
    pos_list = []
    for code, pos in positions.items():
        pos_dict = {
            'security': pos.security,               # 标的代码
            'price': pos.price,                     # 最新行情价格
            'acc_avg_cost': pos.acc_avg_cost,       # 累计的持仓成本
            'avg_cost': pos.avg_cost,               # 当前持仓成本
            'hold_cost': pos.hold_cost,             # 当日持仓成本
            'init_time': pos.init_time,             # 建仓时间
            'transact_time': pos.transact_time,     # 最后交易时间
            'locked_amount': pos.locked_amount,     # 挂单冻结仓位
            'total_amount': pos.total_amount,       # 总仓位
            'closeable_amount': pos.closeable_amount, # 可卖出的仓位
            'today_amount': pos.today_amount,       # 今天开的仓位
            'value': pos.value,                     # 标的价值
            'side': pos.side,                       # 多/空方向 ('long' or 'short')
            'pindex': pos.pindex                    # 仓位索引
        }
        pos_list.append(pos_dict)
        
    df = pd.DataFrame(pos_list)
    return df

3. 各列的名称及含义

使用上述正确方法转换后，DataFrame 的各列名称即为 Position 对象的属性名，具体含义如下：

• security: 标的代码（如 '000001.XSHE'）
• price: 最新行情价格
• acc_avg_cost: 累计的持仓成本（清仓/减仓时也会更新，包含历史盈亏）
• avg_cost: 当前持仓成本（仅在开仓/加仓时更新）
• hold_cost: 当日持仓成本
• init_time: 建仓时间（datetime.datetime 格式）
• transact_time: 最后交易时间（datetime.datetime 格式）
• locked_amount: 挂单冻结仓位
• total_amount: 总仓位（不包含挂单冻结仓位）
• closeable_amount: 可卖出的仓位
• today_amount: 今天开的仓位
• value: 标的价值（最新价 * 总仓位 * 乘数）
• side: 仓位方向（'long' 为多仓，'short' 为空仓）
• pindex: 子账户（仓位）索引

4. 如何查看 DataFrame 的列名

在获取到 DataFrame 后，您可以通过以下 Pandas 内置方法查看列名：

df = get_positions_df(context)

# 方法一：直接打印 columns 属性
print(df.columns)

# 方法二：转换为列表形式查看（推荐，更直观）
print(df.columns.tolist())

# 方法三：查看 DataFrame 的基本信息（包含列名、非空值数量、数据类型）
df.info()

通过这种方式，您可以非常方便地在策略日志或研究环境中分析当前的持仓明细。