ptrade 平台 get_history 函数的 include 参数有什么作用？

在 ptrade 量化交易平台中，get_history 函数是获取历史行情 K 线数据的核心接口。其中，include 参数在决定获取的数据时间范围时起着至关重要的作用。

include 参数详解

• 参数含义：用于指定获取的历史数据中是否包含当前周期的数据。
• 数据类型：布尔值 (bool)。
• 可选值：
  • True：包含当前周期的数据。
  • False：不包含当前周期的数据。
• 默认值：False（如果不显式传入该参数，系统默认不包含当前周期）。

什么是“当前周期”？

“当前周期”取决于你调用 get_history 时传入的 frequency（K线周期）参数以及策略运行的当前时间：

1. 日线级别 (frequency='1d')：
   • 如果当前是 2023年10月10日，include=True 会将 10月10日 当天的 K 线数据包含在返回结果中（如果是盘中调用，返回的可能是截至调用时刻的未走完的 K 线数据）。
   • include=False 则只会返回到 2023年10月9日（上一交易日）及之前的 K 线数据。
2. 分钟级别 (frequency='1m')：
   • 如果当前时间是 10:05，include=True 会包含 10:04-10:05 这一分钟的 K 线。
   • include=False 则只会返回到 10:04 结束的 K 线。

代码示例

def initialize(context):
    g.security = '600570.SS'
    set_universe(g.security)

def handle_data(context, data):
    # 示例 1：不包含当前周期（默认情况）
    # 获取过去 5 天的收盘价，不包括今天
    history_exclude = get_history(5, '1d', 'close', security_list=g.security, include=False)
    log.info('不包含今天的历史数据：\n%s' % history_exclude)

    # 示例 2：包含当前周期
    # 获取过去 5 天的收盘价，包括今天（如果是盘中，今天的收盘价即为最新价）
    history_include = get_history(5, '1d', 'close', security_list=g.security, include=True)
    log.info('包含今天的历史数据：\n%s' % history_include)

使用建议与注意事项

1. 避免未来函数：在回测中，如果你在盘中（如 handle_data）使用 include=True 获取日线数据，可能会提前获取到当天的收盘价，从而引入“未来函数”，导致回测结果失真。通常建议在日线策略中使用默认的 include=False。
2. 实时计算需求：在实盘交易中，如果你需要结合当前的最新价格来计算某些技术指标（如实时的均线），可以将 include=True，此时当前周期的 close 价格通常代表最新的快照价格。
3. 数据对齐：无论 include 是 True 还是 False，get_history 返回的数据条数始终由 count 参数决定。例如 count=5，include=False 返回 T-5 到 T-1 的 5 条数据；include=True 返回 T-4 到 T 的 5 条数据。