Universe Selection
Futures Universes
Future Universe Selection
The FutureUniverseSelectionModel
selects all the contracts for a set of Futures you specify. To use this model, provide a refreshInterval
and a selector function. The refreshInterval
defines how frequently LEAN calls the selector function. The selector function receives a
DateTime
datetime
object that represents the current Coordinated Universal Time (UTC) and returns a list of Symbol
objects. The Symbol
objects you return from the selector function are the Futures of the universe.
UniverseSettings.Asynchronous = true; AddUniverseSelection( new FutureUniverseSelectionModel( TimeSpan.FromDays(1), _ => new List<Symbol> {{ QuantConnect.Symbol.Create(Futures.Indices.SP500EMini, SecurityType.Future, Market.CME) }} ) );
from Selection.FutureUniverseSelectionModel import FutureUniverseSelectionModel self.universe_settings.asynchronous = True self.add_universe_selection( FutureUniverseSelectionModel( timedelta(1), lambda _: [Symbol.create(Futures.Indices.SP500E_MINI, SecurityType.FUTURE, Market.CME)] ) )
The following table describes the arguments the model accepts:
Argument | Data Type | Description | Default Value |
---|---|---|---|
refreshInterval | TimeSpan timedelta | Time interval between universe refreshes | |
futureChainSymbolSelector | Func<DateTime, IEnumerable<Symbol>> Callable[[datetime], List[Symbol]] | A function that selects the Future symbols for a given Coordinated Universal Time (UTC). To view the supported assets in the US Futures dataset, see Supported Assets. | |
universeSettings universe_settings | UniverseSettings | The universe settings. If you don't provide an argument, the model uses the algorithm.UniverseSettings algorithm.universe_settings by default. | null None |
The following example shows how to define the Future chain Symbol selector as an isolated method:
public override void Initialize() { AddUniverseSelection( new FutureUniverseSelectionModel(TimeSpan.FromDays(1), SelectFutureChainSymbols) ); } private static IEnumerable<Symbol> SelectFutureChainSymbols(DateTime utcTime) { return new[] { QuantConnect.Symbol.Create(Futures.Indices.SP500EMini, SecurityType.Future, Market.CME), QuantConnect.Symbol.Create(Futures.Metals.Gold, SecurityType.Future, Market.COMEX) }; }
from Selection.FutureUniverseSelectionModel import FutureUniverseSelectionModel def initialize(self) -> None: self.set_universe_selection( FutureUniverseSelectionModel(timedelta(days=1), self.select_future_chain_symbols) ) def select_future_chain_symbols(self, utc_time: datetime) -> List[Symbol]: return [ Symbol.create(Futures.Indices.SP500E_MINI, SecurityType.FUTURE, Market.CME), Symbol.create(Futures.Metals.GOLD, SecurityType.FUTURE, Market.COMEX) ]
This model uses the default Future contract filter, which doesn't select any Futures contracts. To use a different filter, subclass the FutureUniverseSelectionModel
and define a Filter
method. The Filter
method accepts and returns a FutureFilterUniverse
object to select the Futures contracts. The following table describes the filter methods of the FutureFilterUniverse
class:
Method | Description |
---|---|
StandardsOnly() standards_only() | Selects standard contracts |
IncludeWeeklys() include_weeklys() | Selects non-standard weekly contracts |
WeeklysOnly() weeklys_only() | Selects weekly contracts |
FrontMonth() front_month() | Selects the front month contract |
BackMonths() back_months() | Selects the non-front month contracts |
BackMonth() back_month() | Selects the back month contracts |
Expiration(TimeSpan minExpiry, TimeSpan maxExpiry) expiration(min_expiry: timedelta, max_expiry: timedelta) | Selects contracts that expire within a range of dates relative to the current day |
Expiration(int minExpiryDays, int maxExpiryDays) expiration(min_expiry_days: int, max_expiry_days: int) | Selects contracts that expire within a range of dates relative to the current day |
Contracts(IEnumerable<Symbol> contracts) contracts(contracts: List[Symbol]) | Selects a list of contracts |
Contracts(Func<IEnumerable<Symbol>, IEnumerable< Symbol>> contractSelector) contracts(contractSelector: Callable[[List[Symbol]], List[Symbol]]) | Selects contracts that a selector function selects |
The contract filter runs at the first time step of each day.
To move the Future chain Symbol selector and the contract selection function outside of the algorithm class, create a universe selection model that inherits the FundamentalUniverseSelectionModel class and override its Select method.
// In Initialize UniverseSettings.Asynchronous = true; AddUniverseSelection(new FrontMonthFutureUniverseSelectionModel()); // Outside of the algorithm class class FrontMonthFutureUniverseSelectionModel : FutureUniverseSelectionModel { public FrontMonthFutureUniverseSelectionModel() : base(TimeSpan.FromDays(1), SelectFutureChainSymbols) {} private static IEnumerable<Symbol> SelectFutureChainSymbols(DateTime utcTime) { return new List<Symbol> { QuantConnect.Symbol.Create(Futures.Indices.SP500EMini, SecurityType.Future, Market.CME), QuantConnect.Symbol.Create(Futures.Metals.Gold, SecurityType.Future, Market.COMEX) }; } protected override FutureFilterUniverse Filter(FutureFilterUniverse filter) { return filter.FrontMonth(); } }
from Selection.FutureUniverseSelectionModel import FutureUniverseSelectionModel # In Initialize self.UniverseSettings.Asynchronous = True self.AddUniverseSelection(FrontMonthFutureUniverseSelectionModel()) # Outside of the algorithm class class FrontMonthFutureUniverseSelectionModel(FutureUniverseSelectionModel): def __init__(self) -> None: super().__init__(timedelta(1), self.select_future_chain_symbols) def select_future_chain_symbols(self, utc_time: datetime) -> List[Symbol]: return [ Symbol.Create(Futures.Indices.SP500EMini, SecurityType.Future, Market.CME), Symbol.Create(Futures.Metals.Gold, SecurityType.Future, Market.COMEX) ] def Filter(self, filter: FutureFilterUniverse) -> FutureFilterUniverse: return filter.FrontMonth()
Some of the preceding filter methods only set an internal enumeration in the FutureFilterUniverse
that it uses later on in the filter process. This subset of filter methods don't immediately reduce the number of contract Symbol
objects in the FutureFilterUniverse
.
The AddUniverseSelection
method doesn't return a Future
object like the AddFuture method.
The Future
object contains Symbol
and Mapped
mapped
properties, which reference the continuous contract and the currently selected contract in the continuous contract series, respectively.
To get the Future
object, define the OnSecuritiesChanged
on_securities_changed
method in your algorithm class or framework models and check the result of the IsCanonical
method.
public override void OnSecuritiesChanged(QCAlgorithm algorithm, SecurityChanges changes) { foreach (var security in changes.AddedSecurities) { if (security.Symbol.IsCanonical()) { _future = security as Future; } } }
def on_securities_changed(self, algorithm: QCAlgorithm, changes: SecurityChanges) -> None: for security in changes.added_securities: if security.Symbol.IsCanonical(): self.future = security
To view the implementation of this model, see the LEAN GitHub repositoryLEAN GitHub repository.
Open Interest Future Universe Selection
The OpenInterestFutureUniverseSelectionModel
is an extension of the FutureUniverseSelectionModel
that selects the contract with the greatest open interest on a daily basis.
UniverseSettings.Asynchronous = true; AddUniverseSelection( new OpenInterestFutureUniverseSelectionModel( this, utcTime => new[] { QuantConnect.Symbol.Create(Futures.Indices.SP500EMini, SecurityType.Future, Market.CME) } ) );
self.universe_settings.asynchronous = True self.add_universe_selection( OpenInterestFutureUniverseSelectionModel( self, lambda utc_time: [Symbol.create(Futures.Indices.SP500E_MINI, SecurityType.FUTURE, Market.CME)] ) )
The following table describes the arguments the model accepts:
Argument | Data Type | Description | Default Value |
---|---|---|---|
algorithm | IAlgorithm | Algorithm | |
futureChainSymbolSelector |
Func<DateTime, IEnumerable<Symbol>>
Callable[[datetime], List[Symbol]] | A function that selects the Future symbols for a given Coordinated Universal Time (UTC). To view the supported assets in the US Futures dataset, see Supported Assets. | |
chainContractsLookupLimit |
int?
int/NoneType | Limit on how many contracts to query for open interest | 6 |
resultsLimit |
int?
int/NoneType | Limit on how many contracts will be part of the universe | 1 |
The following example shows how to define the Future chain Symbol selector as an isolated method:
public override void Initialize() { UniverseSettings.Asynchronous = true; AddUniverseSelection( new OpenInterestFutureUniverseSelectionModel(this, SelectFutureChainSymbols) ); } private static IEnumerable<Symbol> SelectFutureChainSymbols(DateTime utcTime) { return new[] { QuantConnect.Symbol.Create(Futures.Indices.SP500EMini, SecurityType.Future, Market.CME), QuantConnect.Symbol.Create(Futures.Metals.Gold, SecurityType.Future, Market.COMEX) }; }
def initialize(self) -> None: self.universe_settings.asynchronous = True self.add_universe_selection( OpenInterestFutureUniverseSelectionModel(self, self.select_future_chain_symbols) ) def select_future_chain_symbols(self, utc_time: datetime) -> List[Symbol]: return [ Symbol.create(Futures.Indices.SP500E_MINI, SecurityType.FUTURE, Market.CME), Symbol.create(Futures.Metals.GOLD, SecurityType.FUTURE, Market.COMEX) ]
To move the Future chain Symbol selector outside of the algorithm class, create a universe selection model that inherits the OpenInterestFutureUniverseSelectionModel
class.
// In Initialize UniverseSettings.Asynchronous = true; AddUniverseSelection(new GoldOpenInterestFutureUniverseSelectionModel(this)); // Outside of the algorithm class class GoldOpenInterestFutureUniverseSelectionModel : OpenInterestFutureUniverseSelectionModel { public GoldOpenInterestFutureUniverseSelectionModel(QCAlgorithm algorithm, int? chainContractsLookupLimit = 6, int? resultsLimit = 1) : base(algorithm, SelectFutureChainSymbols, chainContractsLookupLimit, resultsLimit) {} private static IEnumerable<Symbol> SelectFutureChainSymbols(DateTime utcTime) { return new List<Symbol> { QuantConnect.Symbol.Create(Futures.Metals.Gold, SecurityType.Future, Market.COMEX) }; } }
# In Initialize self.UniverseSettings.Asynchronous = True self.AddUniverseSelection(GoldOpenInterestFutureUniverseSelectionModel(self)) # Outside of the algorithm class class GoldOpenInterestFutureUniverseSelectionModel(OpenInterestFutureUniverseSelectionModel): def __init__(self, algorithm: QCAlgorithm, chainContractsLookupLimit: int = 6, resultsLimit: int = 1): super().__init__(algorithm, self.select_future_chain_symbols, chainContractsLookupLimit, resultsLimit) def select_future_chain_symbols(self, utcTime: datetime) -> List[Symbol]: return [Symbol.Create(Futures.Metals.Gold, SecurityType.Future, Market.COMEX)]
The AddUniverseSelection
method doesn't return a Future
object like the AddFuture method.
The Future
object contains Symbol
and Mapped
mapped
properties, which reference the continuous contract and the currently selected contract in the continuous contract series, respectively.
To get the Future
object, define the OnSecuritiesChanged
on_securities_changed
method in your algorithm class or framework models and check the result of the IsCanonical
method.
public override void OnSecuritiesChanged(QCAlgorithm algorithm, SecurityChanges changes) { foreach (var security in changes.AddedSecurities) { if (security.Symbol.IsCanonical()) { _future = security as Future; } } }
def on_securities_changed(self, algorithm: QCAlgorithm, changes: SecurityChanges) -> None: for security in changes.added_securities: if security.Symbol.IsCanonical(): self.future = security
To view the implementation of this model, see the LEAN GitHub repository.