Universe Selection

Scheduled Universes

Introduction

A Scheduled Universe Selection model selects assets at fixed, regular intervals. In live trading, you can use this type of model to fetch tickers from Dropbox or to perform periodic historical analysis and select some assets.

Scheduled Universe Selection

The ScheduledUniverseSelectionModel selects assets on the schedule you provide. To use this model, provide a DateRule, TimeRule, and a selector function. The DateRule and TimeRule define the selection schedule. The selector function receives a datetimeDateTime object and returns a list of Symbol objects. The Symbol objects you return from the selector function are the constituents of the universe.

// Enable asynchronous universe selection to speed up your algorithm.
UniverseSettings.Asynchronous = true;
// Add a universe that selects assets at the beginning of each month.
AddUniverseSelection(
    new ScheduledUniverseSelectionModel(
        DateRules.MonthStart(), 
        TimeRules.Midnight, 
        // Select SPY for October. Otherwise, select QQQ.
        dt => new List<Symbol> { 
            QuantConnect.Symbol.Create(dt.Month == 10 ? "SPY" : "QQQ", SecurityType.Equity, Market.USA) 
        }
    )
);
# Enable asynchronous universe selection to speed up your algorithm.
self.universe_settings.asynchronous = True
# Add a universe that selects assets at the beginning of each month.
self.add_universe_selection(
    ScheduledUniverseSelectionModel(
        self.date_rules.month_start(), 
        self.time_rules.midnight, 
        # Select SPY for October. Otherwise, select QQQ.
        lambda dt: [Symbol.create("SPY" if dt.month == 10 else "QQQ", SecurityType.EQUITY, Market.USA)]
    )
)

The following table describes the arguments the model accepts:

ArgumentData TypeDescriptionDefault Value
dateRuledate_ruleIDateRuleDate rule defines what days the universe selection function will be invoked
timeRuletime_ruleITimeRuleTime rule defines what times on each day selected by date rule the universe selection function will be invoked
selectorFunc<DateTime, IEnumerable<Symbol>>Callable[[datetime], List[Symbol]]Selector function accepting the date time firing time and returning the universe selected symbols
settingsUniverseSettingsThe universe settings. If you don't provide an argument, the model uses the algorithm.UniverseSettingsalgorithm.universe_settings by default.Nonenull

The model assumes the timeRuletime_rule argument is in Coordinated Universal Time (UTC). To use a different timezone, pass a timeZone argument of type DateTimeZone before the dateRuledate_rule argument.

To return the current universe constituents from the selector function, return Universe.UnchangedUNCHANGED.

// Add a universe that selects assets on Monday, Tuesday, and Thursday at 00:00, 06:00, 12:00, and 18:00 UTC.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.Every(DayOfWeek.Monday, DayOfWeek.Tuesday, DayOfWeek.Thursday),
    TimeRules.Every(TimeSpan.FromHours(6)),
    SelectSymbols
));

// Define the selection function.
private IEnumerable<Symbol> SelectSymbols(DateTime dateTime)
{
    var tickers = new[] {"SPY", "AAPL", "IBM"};
    return tickers.Select(ticker =>
        QuantConnect.Symbol.Create(ticker, SecurityType.Equity, Market.USA));
}
# Add a universe that selects assets on Monday, Tuesday, and Thursday at 00:00, 06:00, 12:00, and 18:00 UTC.
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.every(DayOfWeek.MONDAY, DayOfWeek.TUESDAY, DayOfWeek.THURSDAY),
    self.time_rules.every(timedelta(hours = 6)),
    self.select_symbols # selection function in algorithm.
))

# Define the selection function.
def select_symbols(self, date_time: datetime) -> List[Symbol]:
    tickers = ['SPY', 'AAPL', 'IBM']
    return [Symbol.create(ticker, SecurityType.EQUITY, Market.USA)
        for ticker in tickers]

To view the implementation of this model, see the LEAN GitHub repository.

Date Rules

The following table describes the supported DateRules:

MemberDescription
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.todayDateRules.TodayTrigger an event once today.
self.date_rules.tomorrowDateRules.TomorrowTrigger an event once tomorrow.

To define custom date rules, create a FuncDateRule object. The FuncDateRule constructor expects a name argument of type stringstr and a getDatesFunctionget_dates_function argument of type Func<DateTime, DateTime, IEnumerable<DateTime>>Callable[[datetime, datetime], List[datetime]]. The getDatesFunctionget_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)
    ]
) 

Time Rules

The following table describes the supported TimeRules:

MemberDescription
self.time_rules.set_default_time_zone(time_zone: DateTimeZone) TimeRules.SetDefaultTimeZone(DateTimeZone timeZone)Sets the time zone for the TimeRules object used in all methods in this table, except when a different time zone is given. The default time zone is the algorithm time zone.
self.time_rules.before_market_open(symbol: Symbol, minutes_before_open: float = 0, extended_market_open: bool = False) TimeRules.BeforeMarketOpen(Symbol symbol, double minutesBeforeOpen = 0, bool extendedMarketOpen = false)Trigger an event a few minutes before market open for a specific symbol (default is 0). This rule doesn't work for Crypto securities or custom data.
self.time_rules.after_market_open(symbol: Symbol, minutes_after_open: float = 0, extended_market_open: bool = False) TimeRules.AfterMarketOpen(Symbol symbol, double minutesAfterOpen = 0, bool extendedMarketOpen = false)Trigger an event a few minutes after market open for a specific symbol (default is 0). This rule doesn't work for Crypto securities or custom data.
self.time_rules.before_market_close(symbol: Symbol, minutes_before_close: float = 0, extended_market_open: bool = False) TimeRules.BeforeMarketClose(Symbol symbol, double minutesBeforeClose = 0, bool extendedMarketOpen = false)Trigger an event a few minutes before market close for a specific symbol (default is 0). This rule doesn't work for Crypto securities or custom data.
self.time_rules.after_market_close(symbol: Symbol, minutes_after_close: float = 0, extended_market_open: bool = False) TimeRules.AfterMarketClose(Symbol symbol, double minutesAfterClose = 0, bool extendedMarketOpen = false)Trigger an event a few minutes after market close for a specific symbol (default is 0). This rule doesn't work for Crypto securities or custom data.
self.time_rules.every(interval: timedelta) TimeRules.Every(TimeSpan interval)Trigger an event every period interval starting at midnight.
self.time_rules.nowTimeRules.NowTrigger an event at the current time of day.
self.time_rules.midnightTimeRules.MidnightTrigger an event at midnight.
self.time_rules.noonTimeRules.NoonTrigger an event at noon.
self.time_rules.at(hour: int, minute: int, second: int = 0) TimeRules.At(int hour, int minute, int second = 0)Trigger an event at a specific time of day (e.g. 13:10).
self.time_rules.at(hour: int, minute: int, second: int, time_zone: DateTimeZone) TimeRules.At(int hour, int minute, int second, DateTimeZone timeZone)Trigger an event at a specific time of day in the given time zone (e.g. 13:10 UTC).

To define custom time rules, create a FuncTimeRule object. The FuncTimeRule constructor expects a name argument of type stringstr and a createUtcEventTimesFunctioncreate_utc_event_times_function argument of type Func<IEnumerable<DateTime>, IEnumerable<DateTime>>Callable[[List[datetime]], List[datetime]]. The function receives the list of dates from the date rule and then returns a list of DateTimedatetime that define the time rule.

var timeRule = new FuncTimeRule(
    name: "CustomTimeRule",
    createUtcEventTimesFunction: dates => dates.Select(d => d.AddHours(10)));
time_rule = FuncTimeRule(
    name="CustomTimeRule", 
    create_utc_event_times_function=lambda dates: [d + timedelta(hours=10) for d in dates]
)

Examples

// Select the universe on a specific date at a specific time.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.On(2013, 10, 7),
    TimeRules.At(13, 0),
    SelectSymbols));

// Select the universe 10 minutes after SPY starts trading each day.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.EveryDay("SPY"),
    TimeRules.AfterMarketOpen("SPY", 10),
    SelectSymbols));

// Select the universe 10 minutes before SPY stops trading each day.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.EveryDay("SPY"),
    TimeRules.BeforeMarketClose("SPY", 10),
    SelectSymbols));

// Select the universe on Monday and Friday at noon.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.Every(DayOfWeek.Monday, DayOfWeek.Friday),
    TimeRules.At(12, 0),
    SelectSymbols));

// Select the universe now.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.Today,
    TimeRules.Now,
    SelectSymbols));

// Select the universe tomorrow at midnight.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.Tomorrow,
    TimeRules.Midnight,
    SelectSymbols));

// Select the universe today at noon.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.Today,
    TimeRules.Noon,
    SelectSymbols));

// Select the universe every 10 minutes on everyday.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.EveryDay(), 
    TimeRules.Every(TimeSpan.FromMinutes(10)),
    SelectSymbols));
            
// Select the universe at the market open on the first day of the month the SPY starts trading.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.MonthStart("SPY"),
    TimeRules.AfterMarketOpen("SPY"),
    SelectSymbols));

// Select the universe at the market close on the last day of the month the SPY trades.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.MonthEnd("SPY"),
    TimeRules.BeforeMarketClose("SPY"),
    SelectSymbols));

// Select the universe 5 minutes after SPY starts trading each week.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.WeekStart("SPY"),
    TimeRules.AfterMarketOpen("SPY", 5),
    SelectSymbols));

// Select the universe 5 minutes before the SPY stops trading each week.
AddUniverseSelection(new ScheduledUniverseSelectionModel(
    DateRules.WeekEnd("SPY"),
    TimeRules.BeforeMarketClose("SPY", 5),
    SelectSymbols));


// Define a selection function that returns Symbol objects.
private IEnumerable<Symbol> SelectSymbols(DateTime dateTime)
{
    var tickers = new[] {"SPY", "AAPL", "IBM"};
    return tickers.Select(ticker =>
        QuantConnect.Symbol.Create(ticker, SecurityType.Equity, Market.USA));
}      
# Select the universe on a specific date at a specific time.
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.on(2013, 10, 7), 
    self.time_rules.at(13, 0),
    self.select_symbols))
    
# Select the universe 10 minutes after SPY starts trading each day.
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.every_day("SPY"), 
    self.time_rules.after_market_open("SPY", 10),
    self.select_symbols))

# Select the universe 10 minutes before SPY stops trading each day.
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.every_day("SPY"),
    self.time_rules.before_market_close("SPY", 10),
    self.select_symbols))

# Select the universe on Monday and Friday at noon.
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.every(DayOfWeek.MONDAY, DayOfWeek.FRIDAY),
    self.time_rules.at(12, 0),
    self.select_symbols))

# Select the universe now
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.today,
    self.time_rules.now,
    self.select_symbols))

# Select the universe tomorrow at midnight.
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.tomorrow,
    self.time_rules.midnight,
    self.select_symbols))
    
# Select the universe today at noon.
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.today,
    self.time_rules.noon,
    self.select_symbols))

# Select the universe every 10 minutes on everyday.
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.every_day(), 
    self.time_rules.every(timedelta(minutes=10)),
    self.select_symbols))

# Select the universe at the market open on the first day of the month the SPY starts trading.
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.month_start("SPY"),
    self.time_rules.after_market_open("SPY"),
    self.select_symbols))

# Select the universe at the market close on the last day of the month the SPY trades.
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.month_end("SPY"),
    self.time_rules.before_market_close("SPY"),
    self.select_symbols))

# Select the universe 5 minutes after SPY starts trading each week.
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.week_start("SPY"),
    self.time_rules.after_market_open("SPY", 5),
    self.select_symbols))

# Select the universe 5 minutes before the SPY stops trading each week.
self.add_universe_selection(ScheduledUniverseSelectionModel(
    self.date_rules.week_end("SPY"),
    self.time_rules.before_market_close("SPY", 5),
    self.select_symbols))


# Define a selection function that returns Symbol objects.
def select_symbols(self, date_time: datetime) -> List[Symbol]:
    tickers = ['SPY', 'AAPL', 'IBM']
    return [Symbol.create(ticker, SecurityType.EQUITY, Market.USA)
        for ticker in tickers]

You can also see our Videos. You can also get in touch with us via Discord.

Did you find this page helpful?

Contribute to the documentation: