Options Models
Assignment
Introduction
If you sell an Option in a backtest, an assignment model can simulate an Option exercise order on behalf of the buyer and assign you to complete the requirements of the contract.
Set Models
To set the assignment model of an Option, call the set_option_assignment_model
method of the Option
object inside a security initializer.
class BrokerageModelExampleAlgorithm(QCAlgorithm): def initialize(self) -> None: # In the Initialize method, set the security initializer to seed initial the prices and models of assets. self.set_security_initializer(MySecurityInitializer(self.brokerage_model, FuncSecuritySeeder(self.get_last_known_prices))) # Outside of the algorithm class class MySecurityInitializer(BrokerageModelSecurityInitializer): def __init__(self, brokerage_model: IBrokerageModel, security_seeder: ISecuritySeeder) -> None: super().__init__(brokerage_model, security_seeder) def initialize(self, security: Security) -> None: # First, call the superclass definition. # This method sets the reality models of each security using the default reality models of the brokerage model. super().initialize(security) # Next, overwrite the assignment model if security.Type == SecurityType.OPTION: # Option type security.set_option_assignment_model(DefaultOptionAssignmentModel())
Default Behavior
The default Option assignment model is the DefaultOptionAssignmentModel
. The DefaultOptionAssignmentModel
scans your portfolio every hour. It considers exercising American-style Options if they are within 4 days of their expiration and it considers exercising European-style Options on their day of expiration. If you have sold an Option that's 5% in-the-money and the Option exercise order is profitable after the cost of fees, this model exercises the Option.
To view the implementation of this model, see the LEAN GitHub repository.
Model Structure
Option assignment models should extend the NullOptionAssignmentModel
class. Extensions of the NullOptionAssignmentModel
class must implement the get_assignment
method, which automatically fires at the top of each hour and returns the Option assignments to generate.
class CustomOptionAssignmentModelExampleAlgorithm(QCAlgorithm): def initialize(self) -> None: security = self.add_option("SPY") # Set custom option assignment model for mimicking specific Brokerage most realistic actions security.set_option_assignment_model(MyOptionAssignmentModel()) # Define the custom Option assignment model outside of the algorithm class MyOptionAssignmentModel(NullOptionAssignmentModel): def get_assignment(self, parameters: OptionAssignmentParameters) -> OptionAssignmentResult: option = parameters.option # Check if the contract is ITM if option.right == OptionRight.CALL and option.underlying.price > option.strike_price or option.right == OptionRight.PUT and option.underlying.price < option.strike_price: return OptionAssignmentResult(option.holdings.absolute_quantity, "MyTag") return OptionAssignmentResult.NULL
For a full example algorithm, see this backtest .
The OptionAssignmentParameters
object has the following members:
To exercise the Option, return an OptionAssignmentResult
with a positive quantity. Otherwise, return OptionAssignmentResult.Null
. The OptionAssignmentResult
constructor accepts the following arguments:
Argument | Data Type | Description | Default Value |
---|---|---|---|
quantity | float | The quantity to assign | |
tag | str | The order tag to use |
Examples
The following examples demonstrate some common practices for handling Option assignment.
Example 1: Liquidate After Assignment
The following algorithm trades a
short straddle strategy
on ATM SPY Options that expire within seven days.
To capitalize the cash profit, it liquidates the underlying assigned Equity position in the
on_assignment_order_event
method.
class OptionAssignmentAlgorithm(QCAlgorithm): def initialize(self) -> None: self.set_start_date(2024, 4, 1) self.set_end_date(2024, 5, 1) # Add SPY Options data for trading. self._option = self.add_option("SPY") # Filter for the 2 ATM contracts that expire in 7 days to form a straddle. self._option.set_filter(lambda universe: universe.include_weeklys().straddle(7)) def on_data(self, slice: Slice) -> None: # Get the current Option chain. chain = slice.option_chains.get(self._option.symbol) # Open a new position if we're not already invested. if chain and not self.portfolio.invested: # Select the strike and expiry of the contracts. strike = list(chain)[0].strike expiry = list(chain)[0].expiry # Open the straddle position. option_strategy = OptionStrategies.short_straddle(self._option.symbol, strike, expiry) self.buy(option_strategy, 2) def on_assignment_order_event(self, assignment_event: OrderEvent) -> None: # Liquidate the assigned SPY position. self.market_order( assignment_event.symbol.underlying, -assignment_event.quantity * self._option.symbol_properties.contract_multiplier )
Example 2: Wheel Strategy
The following algorithm demonstrates a wheel Option strategy . The strategy is split into separate parts to generate consistent income: selling puts and selling covered call.
class WheelStrategyAlgorithm(QCAlgorithm): # Define the OTM threshold. A greater value means lower risk of assignment but lower premiums to collect. _otm_threshold = 0.05 def initialize(self): self.set_start_date(2020, 6, 1) self.set_end_date(2021, 6, 1) self.set_cash(1000000) # Seed the initial price of the each new security so we can add and trade contracts in the same time step. self.set_security_initializer( BrokerageModelSecurityInitializer(self.brokerage_model, FuncSecuritySeeder(self.get_last_known_prices)) ) # Add SPY data for trading. Use raw data normalization mode to enable fair strike price comparison. self._equity = self.add_equity("SPY", data_normalization_mode=DataNormalizationMode.RAW) def _get_target_contract(self, right: OptionRight, target_price: float) -> Symbol: # Get the Option chain. chain = self.option_chain(self._equity.symbol, flatten=True).data_frame # Select the contracts that are first to expire after 30 days since they have greater premiums and theta # to collect. expiry_threshold = self.time + timedelta(30) expiry = chain[chain.expiry > expiry_threshold].expiry.min() # Select the OTM Option contract to start the wheel or covered call. symbol = chain[ (chain.expiry == expiry) & (chain.right == right) & (chain.strike <= target_price if right == OptionRight.PUT else chain.strike >= target_price) ].sort_values('strike', ascending=right == OptionRight.CALL).index[0] # Add the Option contract to the algorithm. return self.add_option_contract(symbol).symbol def on_data(self, slice: Slice) -> None: # Start the wheel by selling the OTM put. if not self.portfolio.invested and self.is_market_open(self._equity.symbol): symbol = self._get_target_contract(OptionRight.PUT, self._equity.price * (1-self._otm_threshold)) self.set_holdings(symbol, -0.2) def on_assignment_order_event(self, assignment_event: OrderEvent) -> None: # After the put is assigned, look for an OTM call to form a covered call with the assigned underlying # position. symbol = self._get_target_contract(OptionRight.CALL, self._equity.price * (1+self._otm_threshold)) self.market_order(symbol, -self._equity.holdings.quantity / 100)
Other Examples
For more examples, see the following algorithms: