Key Concepts
Event Handlers
Data Events
public override void OnData(Slice slice) { if (slice.ContainsKey(_symbol)) { var myData = slice[_symbol]; } }
def OnData(self, slice: Slice) -> None: if slice.ContainsKey(self.symbol): my_data = slice[self.symbol]
The OnData
method is the primary event handler for receiving financial data events to your algorithm. It is triggered sequentially at the point in time the data is available; in backtesting and live. For daily data this means the event is processed at midnight in backtesting or 6am the following day in live trading.
All data for a given moment of time is grouped in a single event, including custom data types. This data is passed with the Slice object.
When fill-forward is enabled for your asset, the OnData event handler will be called regularly even if there was no new data. This is the default behavior.
In backtesting, if your algorithm takes a long time to process a slice, the following slice objects queue up and the next event triggers when your algorithm finishes processing the current slice. In live trading, if your algorithm takes longer to process the current slice than the time period that the slice spans, the next event triggers when your algorithm finishes processing the current slice, but the slice of the following event is the most recent slice. For example, say your algorithm consumes second resolution Crypto data but it takes your algorithm 3.5 seconds to process each slice. In backtesting, you'll get every slice. In live trading, if you deploy at 12:00:00 AM Coordinated Universal Time (UTC), you'll get the first slice at 12:00:01 AM UTC (spanning 12:00:00 AM UTC to 12:00:01 AM UTC) and you'll get the second slice at 12:00:04.5 AM UTC (roughly spanning 12:00:03 AM UTC to 12:00:04 AM UTC).
To perform intensive computation before the market opens, use a Scheduled Event or the Train method.
For more information on the Slice
object and OnData event, see Handling Data.
Securities Changed Event
public override void OnSecuritiesChanged(SecurityChanges changes) { foreach (var security in changes.AddedSecurities) { Debug($"{Time}: Added {security.Symbol}"); } foreach (var security in changes.RemovedSecurities) { Debug($"{Time}: Removed {security.Symbol}"); if (security.Invested) { Liquidate(security.Symbol, "Removed from Universe"); } } }
def OnSecuritiesChanged(self, changes: SecurityChanges) -> None: for security in changes.AddedSecurities: self.Debug(f"{self.Time}: Added {security.Symbol}") for security in changes.RemovedSecurities: self.Debug(f"{self.Time}: Removed {security.Symbol}") if security.Invested: self.Liquidate(security.Symbol, "Removed from Universe")
The OnSecuritiesChanged
event notifies the algorithm when assets are added or removed from the universe. This can be due to changes in the Universe constituents, or an explicit call to the RemoveSecurity method.
The event is triggered immediately when the asset is removed from the universe; however the data feed for the asset may remain active if the algorithm has open orders.
For more information, see how to use Security Changed Events.
Order Events
public override void OnOrderEvent(OrderEvent orderEvent) { var order = Transactions.GetOrderById(orderEvent.OrderId); if (orderEvent.Status == OrderStatus.Filled) { Debug($"{Time}: {order.Type}: {orderEvent}"); } } public override void OnAssignmentOrderEvent(OrderEvent assignmentEvent) { Log(assignmentEvent.ToString()); }
def OnOrderEvent(self, orderEvent: OrderEvent) -> None: order = self.Transactions.GetOrderById(orderEvent.OrderId) if orderEvent.Status == OrderStatus.Filled: self.Debug(f"{self.Time}: {order.Type}: {orderEvent}") def OnAssignmentOrderEvent(self, assignmentEvent: OrderEvent) -> None: self.Log(str(assignmentEvent))
The OnOrderEvent
method notifies the algorithm of new orders, and changes in the order status such as fill events and cancelations. For options assignment events there is a dedicated event handler OnAssignmentOrderEvent
.
In backtesting order events are triggered synchronously after the main data events. In live trading, order events are asynchronously as they occur. To avoid infinite loops, we recommend not to place orders in the OnOrderEvent.
For more information, see how to use Order Events.
Brokerage Events
public override void OnBrokerageMessage(BrokerageMessageEvent message) { if (message.Type== BrokerageMessageType.Reconnect) { Log($"{Time}: {message.Type}: Message: {message.Message}"); } } public override void OnBrokerageDisconnect() { Log($"Brokerage disconnection detected at {Time}."); }
def OnBrokerageMessage(self, message: BrokerageMessageEvent) -> None: if message.Type == BrokerageMessageType.Reconnect: self.Log(f"{self.Time}: {message.Type}: Message: {message.Message}") def OnBrokerageDisconnect(self) -> None: self.Log("Brokerage disconnection detected")
The OnBrokerageDisconnect
and OnBrokerageReconnect
event handlers pass information to the algorithm about the brokerage connection status. This can be helpful for considering when to place a trade when a brokerage API is unreliable or under maintenance. The OnBrokerageMessage
event handler provides information from the brokerages, including the disconnect and reconnect messages. Message content varies with each brokerage.
Brokerage events are triggered asynchronously in live trading, and are not created in backtesting.
Margin Call Events
public override void OnMarginCall(Listrequests) { foreach (var orderRequest in requests) { } } public override void OnBrokerageDisconnect() { Log($"Brokerage disconnection detected at {Time}."); }
def OnMarginCall(self, requests): -> List[SubmitOrderRequest]: # Modify order requests to choose what to liquidate. return requests def OnMarginCallWarning()(self) -> None: self.Log("Margin call warning, 5% margin remaining")
The OnMarginCallWarning
and OnMarginCall
event handlers provide information and control over how to reduce algorithm leverage when performance is poor.
The OnMarginCallWarning
method is called when there is less than 5% margin remaining, this gives you an opportunity to reduce leverage before an official margin call is performed by the brokerage. The OnMarginCall
event handler is passed a list of SubmitOrderRequest
objects which will be executed on exiting the method.
Margin events are called before the data events are processed.
The following demonstration demonstration processes suggested orders and modifies the qualities to liquidate more than necessary and prevent a second margin call. For more information, see how to handle Margin Calls.
Warmup Finished Event
public override void OnWarmupFinished() { // Done warming up }
def OnWarmupFinished(self) -> None: pass # Done warming up
The OnWarmupFinished
event handler is triggered after initialization, and warm up is complete. This event signals that the initialization of the algorithm is complete.
For more information, see how to use Warm Up to prepare your algorithm.
End Of Algorithm Events
def OnEndOfAlgorithm(self) -> None: self.Debug("Algorithm done")
public override void OnEndOfAlgorithm() { Debug("Algorithm done"); }
The OnEndOfAlgorithm
event handler is when the algorithm has finished executing as its final step. This is helpful for performing final analysis, or saving algorithm state.
Event Flow
When you deploy an algorithm, LEAN first calls the Initialize method. In live mode, the engine loads your holdings and open orders from your brokerage account to add data subscriptions and populate the Securities
, Portfolio
, and Transactions
objects. LEAN receives the data from the subscriptions, synchronizes the data to create a timeslice, and then performs the following steps. Your algorithm can spend up to 10 minutes on each timeslice unless you call the Train method.
- If it's a backtest, check if there are Scheduled Events in the past that didn't fire because there was no data between the previous slice and the current slice. LEAN automatically creates a Scheduled Event to call the
OnEndOfDay
method at the end of each day. - Update the algorithm time.
- Update the
CurrentSlice
. - Cancel all open orders for securities that changed their ticker.
- Add a
Security
object to theSecurities
collection for each new security in the universe. - Update the
Security
objects with the latest data. - Update the
Cash
objects in the CashBook with the latest data. - Process fill models for non-market orders.
- Submit market on open orders to liquidate Equity Option contracts if the underlying Equity has a split warning.
- Process margin calls.
- If it's time to settle unsettled cash, perform settlement.
- Call the OnSecuritiesChanged method with the latest security changes.
- Apply dividends to the portfolio.
- For securities that have a split warning, update their portfolio holdings and adjust their open orders to account for the split.
- Update consolidators with the latest data.
- Pass custom data to the
OnData
method. - Pass
Dividends
to theOnData
method. - Pass
Splits
to theOnData
method. - Pass
Delistings
to theOnData
method. - Pass
TradeBars
to theOnData
method. - Pass
QuoteBars
to theOnData
method. - Pass
OptionChains
to theOnData
method. - Pass
Ticks
to theOnData
method. - Pass the
Slice
to theOnData
method. - Perform universe selection.
- Pass the
Slice
to theUpdate
method of each Alpha model. - Pass the
Insight
objects from the Alpha model to the Portfolio Construction model. - Pass the
PortfolioTarget
objects from the Portfolio Construction model to each Risk Management model. - Pass the risk-adjusted
PortfolioTarget
objects from the Risk Management models to the Execution model.
In live mode, Scheduled Events occur in a separate thread from the algorithm manager, so they run at the correct time.
When your algorithm stops executing, LEAN calls the OnEndOfAlgorithm
method.