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