跳转至

第4章 QCAlgorithm 基础

本章详细介绍 Lean 策略的核心类 QCAlgorithm,包括算法生命周期、基本配置和证券管理。

4.1 QCAlgorithm 类概览

QCAlgorithm 是所有 Lean 策略的基类,提供了完整的 API 来构建交易策略。

from AlgorithmImports import *

class MyStrategy(QCAlgorithm):
    """
    所有策略都必须继承 QCAlgorithm
    """
    pass

4.2 算法生命周期

4.2.1 方法调用顺序

启动
 │
 ├─> Initialize()          # 只调用一次,初始化设置
 │
 ├─> OnData()              # 每个数据点调用,主逻辑
 │    └─> 循环调用...
 │
 ├─> OnEndOfDay()          # 每日收盘时调用
 │
 └─> OnEndOfAlgorithm()    # 算法结束时调用一次

4.2.2 完整生命周期示例

from AlgorithmImports import *

class LifeCycleDemoAlgorithm(QCAlgorithm):

    def Initialize(self):
        """初始化:只调用一次"""
        self.SetStartDate(2023, 1, 1)
        self.SetEndDate(2023, 1, 31)
        self.SetCash(100000)

        self.AddEquity("SPY", Resolution.Daily)

        # 自定义变量
        self.data_count = 0
        self.day_count = 0

        self.Debug("=== Initialize Complete ===")

    def OnData(self, data):
        """每个数据点调用"""
        self.data_count += 1

        # 第一次调用
        if self.data_count == 1:
            self.Debug("=== First OnData Call ===")

    def OnEndOfDay(self, symbol):
        """每个证券每日收盘时调用"""
        if symbol == next(iter(self.Securities.Keys)):
            self.day_count += 1
            self.Debug(f"=== End of Day {self.day_count} ===")

    def OnEndOfAlgorithm(self):
        """算法结束时调用"""
        self.Debug("=== Algorithm Ended ===")
        self.Debug(f"Total OnData calls: {self.data_count}")
        self.Debug(f"Total trading days: {self.day_count}")

4.3 基本配置方法

4.3.1 时间设置

def Initialize(self):
    # 方式1:单独设置
    self.SetStartDate(2023, 1, 1)     # 年, 月, 日
    self.SetEndDate(2023, 12, 31)      # 年, 月, 日

    # 方式2:使用 DateTime
    from datetime import datetime
    self.SetStartDate(datetime(2023, 1, 1))
    self.SetEndDate(datetime(2023, 12, 31))

4.3.2 资金设置

def Initialize(self):
    # 设置初始资金
    self.SetCash(100000)              # $100,000

    # 设置账户货币
    self.SetAccountCurrency("USD")    # 默认 USD

    # 设置不同货币的初始资金
    self.SetCash("EUR", 50000)        # €50,000

4.3.3 Benchmark 设置

def Initialize(self):
    # 设置基准
    self.SetBenchmark("SPY")

    # 自定义 benchmark(lambda 的参数是时间 DateTime,返回该时刻的基准价格)
    self.SetBenchmark(lambda t: self.Securities["SPY"].Price)

4.4 添加证券

4.4.1 股票 (Equity)

def Initialize(self):
    # 基本用法
    spy = self.AddEquity("SPY", Resolution.Daily)

    # 获取 Symbol 对象
    self.spy_symbol = spy.Symbol

    # 设置正常数据
    spy.SetDataNormalizationMode(DataNormalizationMode.Adjusted)

    # fillForward:数据缺失时用前值填充;extendedMarketHours:包含盘前盘后
    # 注意:这两个选项通过 AddEquity 的参数设置,Security 对象没有对应方法
    spy = self.AddEquity("SPY", Resolution.Daily, fillForward=True)          # 延迟填充数据
    spy = self.AddEquity("SPY", Resolution.Daily, extendedMarketHours=True)  # 包含盘前盘后

4.4.2 外汇 (Forex)

def Initialize(self):
    # 添加外汇对
    eurusd = self.AddForex("EURUSD", Resolution.Hour)

    # 添加多个外汇对
    forex_pairs = ["EURUSD", "GBPUSD", "USDJPY", "USDCHF"]
    for pair in forex_pairs:
        self.AddForex(pair, Resolution.Hour)

4.4.3 加密货币 (Crypto)

def Initialize(self):
    # 添加加密货币
    btc = self.AddCrypto("BTCUSD", Resolution.Minute)

    # 设置市场
    self.AddCrypto("ETHUSD", Resolution.Minute, Market.GDAX)

    # 常见加密货币交易所
    # - Bitfinex
    # - GDAX (Coinbase)
    # - Binance
    # - Kraken

4.4.4 期货 (Future)

def Initialize(self):
    # 添加期货
    es = self.AddFuture("ES", Resolution.Minute)

    # 设置过滤器
    es.SetFilter(
        lambda universe: universe
            .FrontMonth()  # 最近月份
            .Expiration(timedelta(0), timedelta(days=7))  # 7天后到期
    )

    # 添加黄金期货
    gc = self.AddFuture("GC", Resolution.Minute)
    gc.SetFilter(timedelta(0), timedelta(days=180))  # 到期时间在 0~180 天之间的合约

4.4.5 期权 (Option)

def Initialize(self):
    # 添加期权
    spy_option = self.AddOption("SPY", Resolution.Minute)

    # 设置期权链过滤器
    spy_option.SetFilter(-2, 2,  # 行权价范围:平价±2档
                        timedelta(0),   # 最短到期:今天
                        timedelta(30))  # 最长到期:30天

    # 获取期权链
    self.option_symbol = spy_option.Symbol

4.5 数据分辨率

4.5.1 分辨类型

分辨率 说明 适用场景
Tick 逐笔数据 高频交易、详细分析
Second 秒级 日内交易
Minute 分钟级 日内交易
Hour 小时级 中长期策略
Daily 日级 长期策略

4.5.2 分辨率使用示例

def Initialize(self):
    # 同一证券可以有不同分辨率
    self.AddEquity("SPY", Resolution.Daily)      # 日线
    self.AddEquity("SPY", Resolution.Hour)       # 小时线

    # 自定义数据订阅
    self.AddEquity("AAPL", Resolution.Minute, Market.USA)

    # 使用 Consolidator 降低数据频率
    # 注意:CalendarType 已过时(应使用 Calendar),且只有 Weekly/Monthly,
    # 没有 Hourly(小时线合并请用 Resolution.Hour)
    self.Consolidate("SPY", Calendar.Weekly, self.WeeklyBarHandler)

def WeeklyBarHandler(self, bar):
    """周线数据处理"""
    self.Debug(f"Weekly close: {bar.Close}")

4.6 Securities 对象

4.6.1 访问证券信息

def OnData(self, data):
    # 获取证券对象
    spy_security = self.Securities["SPY"]

    # 当前价格
    price = spy_security.Price

    # 买入价/卖出价
    bid = spy_security.BidPrice
    ask = spy_security.AskPrice

    # 最后交易时间
    last_time = spy_security.LocalTime

    self.Debug(f"SPY Price: {price}, Bid: {bid}, Ask: {ask}")

4.6.2 证券属性

def OnData(self, data):
    security = self.Securities["SPY"]

    # 基本信息
    symbol = security.Symbol           # Symbol 对象
    price = security.Price             # 当前价格
    volume = security.Volume           # 成交量

    # 价格数据
    open_price = security.Open         # 开盘价
    high_price = security.High         # 最高价
    low_price = security.Low           # 最低价
    close_price = security.Close       # 收盘价

    # 交易相关
    bid_price = security.BidPrice      # 买入价
    ask_price = security.AskPrice      # 卖出价
    bid_size = security.BidSize        # 买入量
    ask_size = security.AskSize        # 卖出量

    # 数据状态
    has_data = security.HasData        # 是否有数据
    is_trading = security.IsTradable   # 是否可交易

4.7 常用工具方法

4.7.1 时间相关

def OnData(self, data):
    # 当前时间
    now = self.Time

    # 时间判断
    is_weekend = self.Time.weekday() >= 5
    is_month_start = self.Time.day <= 3

    # 时间差计算
    from datetime import timedelta
    tomorrow = self.Time + timedelta(days=1)
    one_month_ago = self.Time - timedelta(days=30)

4.7.2 调试输出

def OnData(self, data):
    # Debug - 在回测/实盘中显示
    self.Debug("Debug message")

    # Log - 记录到日志
    self.Log("Log message")

    # Error - 错误信息
    self.Error("Error message")

    # 注意:QCAlgorithm 没有 Warn 方法,警告信息可用 self.Debug 或 self.Error 输出
    self.Debug("Warning message")

4.7.3 数学工具

def OnData(self, data):
    # 最小值/最大值
    min_val = min(1, 2, 3)
    max_val = max(1, 2, 3)

    # 绝对值
    abs_val = abs(-5)

    # 四舍五入
    rounded = round(3.14159, 2)

    # 幂运算
    squared = 2 ** 3

4.8 事件处理

4.8.1 数据事件

def OnData(self, data):
    """
    主数据处理函数
    data: Slice 对象,包含所有证券的数据
    """
    # 检查特定证券是否有数据
    if data.ContainsKey("SPY"):
        bar = data["SPY"]
        self.Debug(f"SPY: {bar.Close}")

    # 遍历所有数据
    for symbol, value in data.items():
        self.Debug(f"{symbol}: {value}")

4.8.2 订单事件

def OnOrderEvent(self, orderEvent):
    """
    订单状态变化时触发
    """
    orderId = orderEvent.OrderId
    status = orderEvent.Status
    symbol = orderEvent.Symbol

    if status == OrderStatus.Filled:
        self.Debug(f"Order {orderId} filled: {symbol}")
    elif status == OrderStatus.Canceled:
        self.Debug(f"Order {orderId} canceled: {symbol}")
    elif status == OrderStatus.Invalid:
        self.Debug(f"Order {orderId} invalid: {orderEvent.Message}")

4.8.3 其他事件

def OnDividends(self, dividends):
    """分红事件"""
    for dividend in dividends.Values:
        self.Debug(f"Dividend: {dividend.Symbol} - {dividend.Distribution}")

def OnSplits(self, splits):
    """拆股事件"""
    for split in splits.Values:
        self.Debug(f"Split: {split.Symbol} - {split.SplitFactor}")

def OnAssignmentOrderEvent(self, assignmentEvent):
    """期权行权事件"""
    self.Debug(f"Assignment: {assignmentEvent}")

def OnMarginCallWarning(self):
    """保证金警告"""
    self.Debug("Margin call warning!")

def OnDelistings(self, delistings):
    """退市事件"""
    for delisting in delistings.Values:
        self.Debug(f"Delisting: {delisting.Symbol}")

4.9 完整示例:多时间周期策略

from AlgorithmImports import *

class MultiTimeFrameAlgorithm(QCAlgorithm):

    def Initialize(self):
        self.SetStartDate(2020, 1, 1)
        self.SetEndDate(2023, 12, 31)
        self.SetCash(100000)

        # 添加日线和小时线
        self.daily = self.AddEquity("SPY", Resolution.Daily).Symbol
        self.hourly = self.AddEquity("SPY", Resolution.Hour).Symbol

        # 创建不同时间周期的指标
        self.daily_sma = self.SMA(self.daily, 50, Resolution.Daily)
        self.hourly_sma = self.SMA(self.hourly, 20, Resolution.Hour)

        # 每小时检查
        self.Consolidate("SPY", Resolution.Hour, self.HourlyBarHandler)

    def OnData(self, data):
        # 只用日线数据做决策
        if not self.daily_sma.IsReady:
            return

    def HourlyBarHandler(self, bar):
        """每小时调用"""
        if not self.hourly_sma.IsReady:
            return

        # 日线趋势向上 + 小时线回调
        if bar.Close > self.daily_sma.Current.Value:
            if bar.Close < self.hourly_sma.Current.Value:
                self.Debug(f"Buy signal at {bar.Time}")