PTrade 行情获取：get_history 中 include 参数的实战应用

在 PTrade 策略交易系统中，调用 get_history 函数时，若希望获取的数据包含当前正在进行的这一分钟或这一天（即尚未走完的 K 线），需要设置参数 include=True。

以下是详细的设置方法和说明：

1. 参数设置

get_history 函数中控制是否包含当前数据的参数是 include。

• include=False (默认值)：
  • 获取的是过去 count 个已完成周期的 K 线数据。
  • 不包含当前正在进行的这一根 K 线。
• include=True：
  • 获取的数据包含当前正在进行的周期数据。
  • 返回的总长度仍然是 count，由 count - 1 个已完成的历史周期 + 1 个当前的实时周期组成。

2. 代码示例

假设当前策略运行在分钟级别或日线级别，以下代码展示了如何获取包含当前周期的数据：

def handle_data(context, data):
    # 示例 1：获取过去 5 分钟的数据，包含当前这一分钟（实时变动）
    # 假设当前时间是 09:35，返回的数据包含 09:31, 09:32, 09:33, 09:34 以及 09:35(当前)
    m_data = get_history(count=5, frequency='1m', field='close', security_list='600570.SS', include=True)
    log.info("分钟线数据（含当前）：\n%s" % m_data)

    # 示例 2：获取过去 5 天的数据，包含今天（实时变动）
    # 返回的数据包含前 4 个交易日的收盘价 + 今天的最新价
    d_data = get_history(count=5, frequency='1d', field='close', security_list='600570.SS', include=True)
    log.info("日线数据（含当前）：\n%s" % d_data)

3. 注意事项

1. 数据实时性：当 include=True 时，返回序列的最后一个数据点（即当前周期）是实时变动的。在分钟回测或实盘中，它代表当前时刻的最新价（Snapshot）；在日线回测中，如果在盘中调用，它代表截至当前时刻的日内最新价。
2. 未来函数风险：在日线级别回测中，如果在 handle_data（通常在收盘时运行）之前调用（例如在 before_trading_start 或盘中定时任务），且使用了 include=True 获取日线数据，可能会获取到当天的收盘价（取决于回测引擎的撮合机制），这可能导致“未来函数”问题。建议在盘中决策时，谨慎使用包含当天的日线数据，除非你明确知道自己在做盘中实时撮合。
3. 数据长度：设置 include=True 不会增加返回数据的总条数。例如 count=5，你依然只会得到 5 条数据，只是时间窗口向后平移了一个单位。

Q&A

Q: get_history 的 include 参数默认值是什么？
A: 默认值是 False，即默认只返回过去已完成的历史 K 线数据，不包含当前正在进行的周期。

Q: 如果我在 9:30:30 调用 get_history(1, '1m', include=True)，会返回什么？
A: 会返回当前 9:30 这根分钟线的实时数据（即 9:30:00 到 9:30:30 之间生成的 K 线数据），该数据在 9:31:00 之前会随着行情推送不断变化。

Q: include=True 对 get_price 函数也有效吗？
A: 无效。get_price 函数主要用于获取指定时间段的历史数据，它没有 include 参数。如果需要包含当前数据，请使用 get_history。