Requesting Data
Individual Contracts
Introduction
The add_future_option_contract
method enables you to add an individual Option contract to your algorithm.
To check which contracts are currently available to add to your algorithm, use the option_chain
method.
If you want to subscribe to a set of contracts instead of individual contracts one-by-one, see Universes.
Create Subscriptions
Before you can subscribe to an Option contract, you must configure the underlying Future and get the contract Symbol
.
class BasicFutureOptionAlgorithm(QCAlgorithm): def initialize(self): self.set_start_date(2020, 1, 1) self._future = self.add_future( Futures.Indices.SP_500_E_MINI, extended_market_hours=True, data_mapping_mode=DataMappingMode.OPEN_INTEREST, data_normalization_mode=DataNormalizationMode.BACKWARDS_RATIO, contract_depth_offset=0 ) self._future.set_filter(0, 182) self._contract_symbol = None def on_data(self, data): if not self._contract_symbol: # Method 1: Add the desired option chain for the mapped contract self._contract_symbol = self._select_option_contract(self._future.mapped) self.add_future_option_contract(self._contract_symbol) # Method 2: Get all future contracts from the Future chain provider future_contract_symbol = list(self.futures_chain(self._future.symbol))[0].symbol symbol = self._select_option_contract(future_contract_symbol) self.add_future_option_contract(symbol) # Method 3: Iterate all Future chains to find the desired future options contracts for symbol, chain in data.future_chains.items(): expiry = min([contract.expiry for contract in chain]) future_contract = next(contract for contract in chain if contract.expiry == expiry) symbol = self._select_option_contract(future_contract.symbol) self.add_future_option_contract(symbol) def _select_option_contract(self, future_contract_symbol): chain = self.option_chain(future_contract_symbol, flatten=True).data_frame expiry = chain.expiry.min() return chain[ (chain.expiry == expiry) & (chain.right == OptionRight.CALL) ].sort_values('strike').index[-1]
Configure the Underlying Futures Contracts
In most cases, you should subscribe to the underlying Futures contract before you subscribe to a Futures Option contract.
self._future = self.add_future( Futures.Indices.SP_500_E_MINI, extended_market_hours=True, data_mapping_mode=DataMappingMode.OPEN_INTEREST, data_normalization_mode=DataNormalizationMode.BACKWARDS_RATIO, contract_depth_offset=0 )
To get a Symbol
of a specific Futures contract, use the mapped
property of the Future
object or the symbol
property of the FutureContract
objects in the Slice.future_chains
collection.
Get Contract Symbols
To subscribe to a Future Option contract, you need the contract Symbol
.
The preferred method to getting Option contract Symbol
objects is to use the option_chain
method.
This method returns an OptionChain
object, which represent an entire chain of Option contracts for a single underlying security.
You can even format the chain data into a DataFrame where each row in the DataFrame represents a single contract.
With the chain, sort and filter the data to find the specific contract(s) you want to trade.
# Get the contracts available to trade (in DataFrame format). chain = self.option_chain(future_contract_symbol, flatten=True).data_frame # Select a contract. expiry = chain.expiry.min() self._contract_symbol = chain[ # Select call contracts with the closest expiry. (chain.expiry == expiry) & (chain.right == OptionRight.CALL) # Select the contract with the lowest strike price. ].sort_values('strike').index[0]
Subscribe to Contracts
To create a Future Option contract subscription, pass the contract Symbol
to the add_future_option_contract
method. Save a reference to the contract symbol
so you can easily access the Option contract in the OptionChain that LEAN passes to the on_data
method. This method returns an Option
object. To override the default pricing model of the Option, set a pricing model.
option = self.add_future_option_contract(self._contract_symbol) option.price_model = OptionPriceModels.binomial_cox_ross_rubinstein()
Warm Up Contract Prices
If you subscribe to a Future Option contract with add_future_option_contract
, you'll need to wait until the next Slice
to receive data and trade the contract. To trade the contract in the same time step you subscribe to the contract, set the current price of the contract in a security initializer.
seeder = FuncSecuritySeeder(self.get_last_known_prices) self.set_security_initializer(BrokerageModelSecurityInitializer(self.brokerage_model, seeder))
Supported Assets
To view the supported assets in the US Future Options dataset, see the Supported Assets.
Resolutions
The following table shows the available resolutions and data formats for Future Option contract subscriptions:
Resolution | TradeBar | QuoteBar | Trade Tick | Quote Tick |
---|---|---|---|---|
TICK | ||||
SECOND | ||||
MINUTE | ![]() | ![]() | ||
HOUR | ![]() | ![]() | ||
DAILY | ![]() | ![]() |
There is only one resolution option, so you don't need to pass a resolution
argument to the add_future_option_contract
method.
self.add_future_option_contract(self._option_contract_symbol, Resolution.MINUTE)
To create custom resolution periods, see Consolidating Data.
Fill Forward
Fill forward means if there is no data point for the current slice, LEAN uses the previous data point. Fill forward is the default data setting. If you disable fill forward, you may get stale fills or you may see trade volume as zero.
To disable fill forward for a security, set the fill_forward
argument to false when you create the security subscription.
self.add_future_option_contract(self._option_contract_symbol, fill_forward=False)
Extended Market Hours
By default, your security subscriptions only cover regular trading hours. To subscribe to pre and post-market trading hours for a specific asset, enable the extended_market_hours
argument when you create the security subscription.
self.add_future_option_contract(self._option_contract_symbol, extended_market_hours=True)
You only receive extended market hours data if you create the subscription with minute, second, or tick resolution. If you create the subscription with daily or hourly resolution, the bars only reflect the regular trading hours.
To view the schedule of regular and extended market hours, see Market Hours.
Data Normalization
The data normalization mode doesn't affect the data that LEAN passes to on_data
or the data from history request. If you change the data normalization mode, it won't change the outcome.
Remove Subscriptions
To remove a contract subscription that you created with add_future_option_contract
, call the remove_option_contract
method. This method is an alias for remove_security
.
self.remove_option_contract(self._option_contract_symbol)
The remove_option_contract
method cancels your open orders for the contract and liquidates your holdings.
Helper Methods
The Option
object provides methods you can use for basic calculations. These methods require the underlying price. To get the Option
object and the Security
object for its underlying in any function, use the Option symbol
to access the value in the securities
object.
option = self.securities[self._option_contract_symbol] underlying = self.securities[self._option_contract_symbol.underlying] underlying_price = underlying.price
To get the Option payoff, call the get_pay_off
method.
pay_off = option.get_pay_off(underlying_price)
To get the Option intrinsic value, call the get_intrinsic_value
method.
intrinsic_value = option.get_intrinsic_value(underlying_price)
To get the Option out-of-the-money amount, call the out_of_the_money_amount
method.
otm_amount = option.out_of_the_money_amount(underlying_price)
To check whether the Option can be automatic exercised, call the is_auto_exercised
method.
is_auto_exercised = option.is_auto_exercised(underlying_price)