Skip to content

title: Chapter 4: QCAlgorithm Basics

Chapter 4: QCAlgorithm Basics

This chapter takes a detailed look at QCAlgorithm, the core class of Lean strategies, including the algorithm lifecycle, basic configuration, and security management.

4.1 QCAlgorithm Class Overview

QCAlgorithm is the base class of all Lean strategies and provides a complete API for building trading strategies.

from AlgorithmImports import *

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

4.2 Algorithm Lifecycle

4.2.1 Method Call Order

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

4.2.2 Full Lifecycle Example

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 Basic Configuration Methods

4.3.1 Time Settings

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 Cash Settings

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

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

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

4.3.3 Benchmark Settings

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

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

4.4 Adding Securities

4.4.1 Equities

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 Futures

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 Options

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 Data Resolution

4.5.1 Resolution Types

Resolution Description Best For
Tick Tick-by-tick data High-frequency trading, detailed analysis
Second Per-second Intraday trading
Minute Per-minute Intraday trading
Hour Per-hour Medium- to long-term strategies
Daily Per-day Long-term strategies

4.5.2 Resolution Usage Example

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 The Securities Object

4.6.1 Accessing Security Information

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 Security Properties

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 Common Utility Methods

4.7.1 Time

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 Debug Output

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 Math Utilities

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 Event Handling

4.8.1 Data Events

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 Order Events

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 Other Events

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 Complete Example: Multi-Timeframe Strategy

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}")