Universe Selection
Universe Settings
Resolution
The Resolution
resolution
setting defines the time period of the asset data. The Resolution
enumeration has the following members:
To view which resolutions are available for the asset class of your universe, follow these steps:
- Open the Asset Classes documentation page.
- Click an asset class.
- Click .
- On the Requesting Data page, in the table of contents, click .
The default value is Resolution.Minute
Resolution.MINUTE
. To change the resolution, in the Initialize method,
adjust the algorithm's UniverseSettings
before you create the Universe Selection model.
// Set universe settings to subscribe to daily data and select SPY ETF constituents as the trading universe. UniverseSettings.Resolution = Resolution.Daily; AddUniverseSelection(new ETFConstituentsUniverseSelectionModel("SPY"));
# Use daily data and select SPY ETF constituents as the trading universe. self.universe_settings.resolution = Resolution.DAILY self.add_universe_selection(ETFConstituentsUniverseSelectionModel("SPY"))
Leverage
The Leverage
leverage
setting is a float
decimal
that defines the maximum amount of leverage you can use for a single asset in a non-derivative universe. The default value is Security.NullLeverage
Security.NULL_LEVERAGE
(0). To change the leverage, in the Initialize method, adjust the algorithm's UniverseSettings
universe_settings
before you
create the Universe Selection model.
// Set unviverse leverage to 2x to increase potential returns from each asset in the non-derivative universe to increase potential returns. UniverseSettings.Leverage = 2.0m; // Select universe based on EMA cross signals to identify and trade assets with trending behaviors. AddUniverseSelection(new EmaCrossUniverseSelectionModel());
# Set unviverse leverage to 2x to increase potential returns from each asset in the non-derivative universe to increase potential returns. self.universe_settings.leverage = 2.0 # Select universe based on EMA cross signals to identify and trade assets with trending behaviors. self.add_universe_selection(EmaCrossUniverseSelectionModel())
Fill Forward
The FillForward
fill_forward
setting is a bool
that defines whether or not too fill forward data. The default value is true
True
. To disable fill forward in non-derivative universes, in the Initialize method, adjust the algorithm's UniverseSettings
universe_settings
before you
create the Universe Selection model.
// Disable fill forward to ensure each day's data is used exclusively, preventing previous day's data from influencing decisions and select options for SPY with a daily update interval to track specific option contracts. UniverseSettings.FillForward = false; AddUniverseSelection( new OptionUniverseSelectionModel( TimeSpan.FromDays(1), _ => new [] { QuantConnect.Symbol.Create("SPY", SecurityType.Option, Market.USA) } ) );
# Disable fill forward to ensure each day's data is used exclusively, preventing previous day's data from influencing decisions and select options for SPY with a daily update interval to track specific option contracts. from Selection.OptionUniverseSelectionModel import OptionUniverseSelectionModel self.universe_settings.fill_forward = False self.add_universe_selection( OptionUniverseSelectionModel( timedelta(1), lambda _: [Symbol.create("SPY", SecurityType.OPTION, Market.USA)] ) )
Extended Market Hours
The ExtendedMarketHours
extended_market_hours
setting is a bool
that defines the trading schedule. If it's true
True
, your algorithm receives price data for all trading hours. If it's false
False
, your algorithm receives price data only for regular trading hours. The default value is false
False
.
You only receive extended market hours data if you create the subscription with an intraday resolution. If you create the subscription with daily resolution, the daily bars only reflect the regular trading hours.
To view the trading schedule of an asset, open Asset Classes, click an asset class, then click .
To enable extended market hours, in the Initializeinitialize method, adjust the algorithm's UniverseSettings
before you create the Universe Selection model.
// Enable extended market hours for universe and manually select equity symbols for SPY, QQQ, and IWM to ensure trading during pre-market and after-hours sessions. UniverseSettings.ExtendedMarketHours = true; var tickers = new[] {"SPY", "QQQ", "IWM"}; var symbols = tickers.Select(ticker => QuantConnect.Symbol.Create(ticker, SecurityType.Equity, Market.USA)); AddUniverseSelection(new ManualUniverseSelectionModel(symbols));
# Enable extended market hours for universe and manually select equity symbols for SPY, QQQ, and IWM to ensure trading during pre-market and after-hours sessions. self.universe_settings.extended_market_hours = True tickers = ["SPY", "QQQ", "IWM"] symbols = [ Symbol.create(ticker, SecurityType.EQUITY, Market.USA) for ticker in tickers] self.add_universe_selection(ManualUniverseSelectionModel(symbols))
Minimum Time in Universe
The MinimumTimeInUniverse
minimum_time_in_universe
setting is a timedelta
TimeSpan
object that defines the minimum amount of time an asset must be in the universe before the universe can remove it. The default value is TimeSpan.FromDays(1)
timedelta(1)
. To change the minimum time, in the Initialize method, adjust the algorithm's UniverseSettings
universe_settings
before you
create the Universe Selection model.
// Keep each security in the universe for a minimum of 7 days. UniverseSettings.MinimumTimeInUniverse = TimeSpan.FromDays(7); AddUniverseSelection(new ETFConstituentsUniverseSelectionModel("QQQ"));
# Keep each security in the universe for a minimum of 7 days. self.universe_settings.minimum_time_in_universe = timedelta(7) self.add_universe_selection(ETFConstituentsUniverseSelectionModel("QQQ"))
Data Normalization Mode
The DataNormalizationMode
data_normalization_mode
setting is an enumeration that defines how historical data is adjusted. This setting is only applicable for US Equities and Futures.
In the case of US Equities, the data normalization mode affects how historical data is adjusted for corporate actions. To view all the available options, see Data Normalization. To change the data normalization mode, in the Initializeinitialize method, adjust the algorithm's UniverseSettings
universe_settings
before you create the Universe Selection model.
In the case of Futures, the data normalization mode affects how historical data of two contracts is stitched together to form the continuous contract. To view all the available options, see Data Normalization.
The default value is DataNormalizationMode.Adjusted
DataNormalizationMode.ADJUSTED
. To change the data normalization mode, in the Initialize method, adjust the algorithm's UniverseSettings
before you create the Universe Selection model.
// Set universe data normalization to use raw prices to reflect actual traded values without adjustments and manually select equities MSTR, MSFT, and IBM. UniverseSettings.DataNormalizationMode = DataNormalizationMode.Raw; var tickers = new[] {"MSTR", "MSFT", "IBM"}; var symbols = tickers.Select(ticker => QuantConnect.Symbol.Create(ticker, SecurityType.Equity, Market.USA)); AddUniverseSelection(new ManualUniverseSelectionModel(symbols));
# Set universe data normalization to use raw prices to reflect actual traded values without adjustments and manually select equities MSTR, MSFT, and IBM. self.universe_settings.data_normalization_mode = DataNormalizationMode.RAW tickers = ["MSTR", "MSFT", "IBM"] symbols = [ Symbol.create(ticker, SecurityType.EQUITY, Market.USA) for ticker in tickers] self.add_universe_selection(ManualUniverseSelectionModel(symbols))
Contract Depth Offset
The ContractDepthOffset
contract_depth_offset
setting is an int
that defines which contract to use for the continuous Futures contract. 0 is the front month contract, 1 is the following back month contract, and 3 is the second back month contract. The default value is 0. To change the contract depth offset, in the Initialize method,
adjust the algorithm's UniverseSettings
universe_settings
before you create the Universe Selection model.
// Select the following month contract dynamically to avoid low liquidity and high volatility, for S&P 500 E-mini futures with daily updates. UniverseSettings.ContractDepthOffset = 1; AddUniverseSelection( new FutureUniverseSelectionModel( TimeSpan.FromDays(1), _ => new List<Symbol> {{ QuantConnect.Symbol.Create(Futures.Indices.SP500EMini, SecurityType.Future, Market.CME) }} ) );
# Select the following month contract dynamically to avoid low liquidity and high volatility, for S&P 500 E-mini futures with daily updates. from Selection.FutureUniverseSelectionModel import FutureUniverseSelectionModel self.universe_settings.contract_depth_offset = 1 self.add_universe_selection( FutureUniverseSelectionModel( timedelta(1), lambda _: [Symbol.create(Futures.Indices.SP500E_MINI, SecurityType.FUTURE, Market.CME)] ) )
Asynchronous Selection
The Asynchronous
asynchronous
setting is a bool
that defines whether or not LEAN can run universe selection asynchronously, utilizing concurrent execution to increase the speed of your algorithm. The default value for this setting is false
False
. If you enable this setting, abide by the following rules:
- Don't make any history requests in your filter function. History requests can only provide data up to the algorithm time, but if your filter function runs asynchronously, the algorithm time may not be what you expect.
- Don't use the portfolio, security, or orders state. The
Portfolio
portfolio
,Securities
securities
, andTransactions
transactions
objects are also functions of the algorithm time. - If your filter function updates a class variable, don't update the class variable anywhere else in your algorithm.
To enable asynchronous universe selection, in the Initialize method, adjust the algorithm's UniverseSettings
universe_settings
before you
create the Universe Selection model.
// Run universe selection asynchronously to speed up your algorithm. UniverseSettings.Asynchronous = true; AddUniverseSelection(new EmaCrossUniverseSelectionModel());
# Run universe selection asynchronously to speed up your algorithm. self.universe_settings.asynchronous = True self.add_universe_selection(EmaCrossUniverseSelectionModel())
Schedule
The Schedule
setting defines the selection schedule of the universe.
Most universes run on a daily schedule.
To change the selection schedule, call the UniverseSettings.Schedule.On
universe_settings.schedule.on
method with an IDateRule
object before you create the Universe Selection model.
// Trigger selections at the begining of each month. UniverseSettings.Schedule.On(DateRules.MonthStart()); AddUniverseSelection(new ETFConstituentsUniverseSelectionModel("QQQ"));
# Trigger selections at the begining of each month. self.universe_settings.schedule.on(self.date_rules.month_start()) self.add_universe_selection(ETFConstituentsUniverseSelectionModel("QQQ"))
The following table describes the supported DateRules
:
Member | Description |
---|---|
self.date_rules.set_default_time_zone(time_zone: DateTimeZone)
DateRules.SetDefaultTimeZone(DateTimeZone timeZone); | Sets the time zone for the DateRules object used in all methods in this table. The default time zone is the algorithm time zone. |
self.date_rules.on(year: int, month: int, day: int)
DateRules.On(int year, int month, int day) | Trigger an event on a specific date. |
self.date_rules.every_day()
DateRules.EveryDay() | Trigger an event every day. |
self.date_rules.every_day(symbol: Symbol, extended_market_hours: bool = False)
DateRules.EveryDay(Symbol symbol, bool extendedMarketHours = false) | Trigger an event every day a specific symbol is trading. |
self.date_rules.every(days: List[DayOfWeek])
DateRules.Every(params DayOfWeek[] days) | Trigger an event on specific days throughout the week. To view the DayOfWeek enum members, see DayOfWeek Enum in the .NET documentation. |
self.date_rules.month_start(days_offset: int = 0)
DateRules.MonthStart(int daysOffset = 0) | Trigger an event on the first day of each month plus an offset. |
self.date_rules.month_start(symbol: Symbol, daysOffset: int = 0)
DateRules.MonthStart(Symbol symbol, int daysOffset = 0) | Trigger an event on the first tradable date of each month for a specific symbol plus an offset. |
self.date_rules.month_end(days_offset: int = 0)
DateRules.MonthEnd(int daysOffset = 0) | Trigger an event on the last day of each month minus an offset. |
self.date_rules.month_end(symbol: Symbol, daysOffset: int = 0)
DateRules.MonthEnd(Symbol symbol, int daysOffset = 0) | Trigger an event on the last tradable date of each month for a specific symbol minus an offset. |
self.date_rules.week_start(days_offset: int = 0)
DateRules.WeekStart(int daysOffset = 0) | Trigger an event on the first day of each week plus an offset. |
self.date_rules.week_start(symbol: Symbol, days_offset: int = 0)
DateRules.WeekStart(Symbol symbol, int daysOffset = 0) | Trigger an event on the first tradable date of each week for a specific symbol plus an offset. |
self.date_rules.week_end(days_offset: int = 0)
DateRules.WeekEnd(int daysOffset = 0) | Trigger an event on the last day of each week minus an offset. |
self.date_rules.week_end(symbol: Symbol, days_offset: int = 0)
DateRules.WeekEnd(Symbol symbol, int daysOffset = 0) | Trigger an event on the last tradable date of each week for a specific symbol minus an offset. |
self.date_rules.year_start(days_offset: int = 0)
DateRules.YearStart(int daysOffset = 0) | Trigger an event on the first day of each year plus an offset. |
self.date_rules.year_start(symbol: Symbol, days_offset: int = 0)
DateRules.YearStart(Symbol symbol, int daysOffset = 0) | Trigger an event on the first tradable date of each year for a specific symbol plus an offset. |
self.date_rules.year_end(days_offset: int = 0)
DateRules.YearEnd(int daysOffset = 0) | Trigger an event on the last day of each year minus an offset. |
self.date_rules.year_end(symbol: Symbol, days_offset: int = 0)
DateRules.YearEnd(Symbol symbol, int daysOffset = 0) | Trigger an event on the last tradable date of each year for a specific symbol minus an offset. |
self.date_rules.today DateRules.Today | Trigger an event once today. |
self.date_rules.tomorrow DateRules.Tomorrow | Trigger an event once tomorrow. |
To define custom date rules, create a FuncDateRule
object.
The FuncDateRule
constructor expects a name
argument of type string
str
and a getDatesFunction
get_dates_function
argument of type Func<DateTime, DateTime, IEnumerable<DateTime>>
Callable[[datetime, datetime], List[datetime]]
.
The getDatesFunction
get_dates_function
function receives the start and end dates of the algorithm and returns a list of dates for the date rule.
In live trading, the end date is 12/31/2025.
The following example demonstrates how to define a date rule that represents the 10th day of each month:
// Create a date rule that specifies the 10th day of each month. var dateRule = new FuncDateRule( name: "10th_day_of_the_month", getDatesFunction: (start, end) => Enumerable.Range(start.Year, end.Year - start.Year + 1) .SelectMany(year => Enumerable.Range(1, 12).Select(month => new DateTime(year, month, 10))) );
# Create a date rule that specifies the 10th day of each month. date_rule = FuncDateRule( name="10th_day_of_the_month", get_dates_function=lambda start, end: [ datetime(year, month, 10) for year in range(start.year, end.year) for month in range(1,12) ] )
In live trading, scheduled universes run at roughly 8 AM Eastern Time to ensure there is enough time for the data to process.
Configure Securities
Instead of configuring global universe settings, you can individually configure the settings of each security in the universe with a security initializer. Security initializers let you apply any security-level reality model or special data requests on a per-security basis. To set the security initializer, in the Initialize
initialize
method, call the SetSecurityInitializer
set_security_initializer
method and then define the security initializer.
// A custom security initializer can override default models such as // setting new fee and fill models for the security. SetSecurityInitializer(CustomSecurityInitializer); private void CustomSecurityInitializer(Security security) { security.SetFeeModel(new ConstantFeeModel(0, "USD")); }
# A custom security initializer can override default models such as # setting new fee and fill models for the security. self.set_security_initializer(self._custom_security_initializer) def _custom_security_initializer(self, security: Security) -> None: security.set_fee_model(ConstantFeeModel(0, "USD"))
For simple requests, you can use the functional implementation of the security initializer. This style lets you configure the security object with one line of code.
// Disable the trading fees for each security by passing a functional // implementation for the SetSecurityInitializer argument. SetSecurityInitializer(security => security.SetFeeModel(new ConstantFeeModel(0, "USD")));
# Disable the trading fees for each security by using lambda function # for the set_security_initializer argument. self.set_security_initializer(lambda security: security.set_fee_model(ConstantFeeModel(0, "USD")))
In some cases, you may want to trade a security in the same time loop that you create the security subscription. To avoid errors, use a security initializer to set the market price of each security to the last known price. The GetLastKnownPrices
get_last_known_prices
method seeds the security price by gathering the security data over the last 3 days. If there is no data during this period, the security price remains at 0.
// Gather the last 3 days of security prices by using GetLastKnowPrice as the seed in Initialize. var seeder = new FuncSecuritySeeder(GetLastKnownPrices); SetSecurityInitializer(security => seeder.SeedSecurity(security));
# Gather the last 3 days of security prices by using get_last_known_prices as the seed in initialize. seeder = FuncSecuritySeeder(self.get_last_known_prices) self.set_security_initializer(lambda security: seeder.seed_security(security))
If you call the SetSecurityInitializer
set_security_initializer
method, it overwrites the default security initializer. The default security initializer uses the security-level reality models of the brokerage model to set the following reality models of each security:
The default security initializer also sets the leverage of each security and intializes each security with a seeder function. To extend upon the default security initializer instead of overwriting it, create a custom BrokerageModelSecurityInitializer
.
public class BrokerageModelExampleAlgorithm : QCAlgorithm { public override void Initialize() { // In the Initialize method, set the security initializer to seed initial the prices and models of assets. SetSecurityInitializer(new MySecurityInitializer(BrokerageModel, new FuncSecuritySeeder(GetLastKnownPrices))); } } public class MySecurityInitializer : BrokerageModelSecurityInitializer { public MySecurityInitializer(IBrokerageModel brokerageModel, ISecuritySeeder securitySeeder) : base(brokerageModel, securitySeeder) {} public override void Initialize(Security security) { // First, call the superclass definition. // This method sets the reality models of each security using the default reality models of the brokerage model. base.Initialize(security); // Next, overwrite some of the reality models security.SetFeeModel(new ConstantFeeModel(0, "USD")); } }
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 some of the reality models security.set_fee_model(ConstantFeeModel(0, "USD"))
To set a seeder function without overwriting the reality models of the brokerage, use the standard BrokerageModelSecurityInitializer
.
var seeder = new FuncSecuritySeeder(GetLastKnownPrices); SetSecurityInitializer(new BrokerageModelSecurityInitializer(BrokerageModel, seeder));
seeder = FuncSecuritySeeder(self.get_last_known_prices) self.set_security_initializer(BrokerageModelSecurityInitializer(self.brokerage_model, seeder))