PTrade API 进阶：get_history 中 include=True 的使用场景与风险

在 PTrade 的 get_history 函数中，include 参数是一个布尔值（bool），主要用于控制获取的数据结果中是否包含当前正在进行的周期（即尚未结束的 K 线）。

以下是详细的解释：

1. 参数定义

• 类型：bool (True / False)
• 默认值：False

2. 具体作用

当 include=False（默认情况）

• 含义：不包含当前周期的数据。
• 返回内容：返回截止到上一周期结束的历史 K 线数据。
• 应用场景：这是回测中最常用的设置，用于避免“未来函数”（Look-ahead bias）。
  • 日线策略：如果在 2023-10-27 盘中运行，获取的是截止到 2023-10-26（昨天）收盘的数据。
  • 分钟策略：如果在 10:30:05 运行（获取 1 分钟线），获取的是截止到 10:29 分的那根已走完的 K 线。

当 include=True

• 含义：包含当前周期的数据。
• 返回内容：返回的数据中，最后一条是当前正在进行中的 K 线。
• 数据特性：对于这根未完成的 K 线：
  • open：当前周期的开盘价。
  • high / low：当前周期截至目前的最高/最低价。
  • close：当前时刻的最新价格（即实时价）。
  • volume：当前周期截至目前的成交量。
• 应用场景：
  • 需要根据盘中实时价格与历史均线进行比较时。
  • 在盘中实时计算动态指标时。
  • 注意：在回测中使用 include=True 可能会导致策略利用了收盘价（其实是当前价）进行决策，从而产生未来函数效应，需谨慎使用。

3. 举例说明

假设当前时间是 2023年10月27日 14:00，策略频率为日线 (1d)，我们要获取 count=5 条数据：

• get_history(5, ..., include=False)：

  • 返回：10月23日、24日、25日、26日、26日（共5条，最后一条是昨天收盘数据）。
  • 数据是固定的，不会随盘中波动变化。

• get_history(5, ..., include=True)：

  • 返回：10月23日、24日、25日、26日、27日（共5条，最后一条是今天的实时数据）。
  • 最后一条数据的 close 字段会随着 14:00 之后的股价波动而不断变化，直到 15:00 收盘固定下来。

Q&A

Q: 在编写回测策略时，一般推荐将 include 设置为 True 还是 False？
A: 在大多数回测场景下，推荐保持默认值 False。因为回测通常基于已完成的历史数据进行逻辑判断。如果设置为 True，策略可能会在 K 线未走完时就利用了该 K 线的信息，导致回测结果虚高（未来函数）。除非你的策略逻辑明确需要使用“当前最新价”与历史数据混合计算，否则应使用 False。

Q: 如果我想获取当前的最新价格，应该用 get_history(include=True) 还是 get_snapshot?
A: 如果仅仅是为了获取当前的最新价格（Last Price），建议使用 get_snapshot(security) 或 get_price（在某些上下文中）。get_snapshot 是专门用于获取高频切片/快照数据的，效率更高且包含买卖档口信息。get_history(include=True) 更适合需要将当前价格拼接到历史序列中进行连贯计算（如计算包含今日价格的 5 日均线）的场景。

Q: include 参数对 count（数据条数）有影响吗？
A: count 始终代表返回的数据总条数。

• 如果 include=False，返回的是过去完整的 count 条。
• 如果 include=True，返回的是过去完整的 count-1 条 + 当前未完成的 1 条。总数依然是 count。