Universe Selection

We have identified several types of universes that cover most people's requirements and built helper classes to make their implementation easier. The following table describes the types of pre-built Universe Selection models:

To add a Universe Selection model, in the Initialize method, call the AddUniverseSelection method.

var symbols = new [] {QuantConnect.Symbol.Create("SPY", SecurityType.Equity, Market.USA)};
AddUniverseSelection(new ManualUniverseSelectionModel(symbols));

symbols = [Symbol.Create("SPY", SecurityType.Equity, Market.USA)]
self.AddUniverseSelection(ManualUniverseSelectionModel(symbols))

To view all the pre-built Universe Selection models, see Types of Universe Selection.

You can add multiple Universe Selection models to a single algorithm.

AddUniverseSelection(new EmaCrossUniverseSelectionModel());
AddUniverseSelection(new FineFundamentalUniverseSelectionModel(SelectCoarse, SelectFine));

self.AddUniverseSelection(EmaCrossUniverseSelectionModel())
self.AddUniverseSelection(FineFundamentalUniverseSelectionModel(self.SelectCoarse, self.SelectFine))

If you add multiple Universe Selection models, the algorithm subscribes to the constituents of all the models.

Universe Selection models should extend the UniverseSelectionModel class. Extensions of the UniverseSelectionModel class must implement the CreateUniverses method, which receives an algorithm object and returns an array of Universe objects.

public class MyUniverseSelectionModel : UniverseSelectionModel
{
    // Creates the universes for this algorithm
    public override IEnumerable<Universe> CreateUniverses(QCAlgorithm algorithm)
    {
        return new List<Universe>();
    }

    // Gets the next time the framework should invoke the `CreateUniverses` method to refresh the set of universes.
    public override DateTime GetNextRefreshTimeUtc()
    {
        return DateTime.MaxValue;
    }
}

class MyUniverseSelectionModel(UniverseSelectionModel):

    # Creates the universes for this algorithm
    def CreateUniverses(self, algorithm: QCAlgorithm) -> List[Universe]:
        universes = []
        return universes
    
    # Gets the next time the framework should invoke the `CreateUniverses` method to refresh the set of universes.
    def GetNextRefreshTimeUtc(self):
        return datetime.max

The algorithm argument that the methods receive is an instance of the base QCAlgorithm class, not your subclass of it.

Generally, you should be able to extend one of the pre-built Universe Selection types. If you need to do something that doesn't fit into the pre-built types, let us know and we'll create a new foundational type of Universe Selection model.

When the Universe Selection model adjusts the universe constituents, we notify your algorithm through the OnSecuritiesChanged event handler on your other framework components. The method receives QCAlgorithm and SecurityChanges objects. The QCAlgorithm object is an instance of the base QCAlgorithm class, not a reference to your algorithm object. To access the added securities, check the changes.AddedSecurities property. To access the removed securities, check the changes.RemovedSecurities property.

public override void OnSecuritiesChanged(QCAlgorithm algorithm, SecurityChanges changes)
{
    foreach (var security in changes.AddedSecurities)
    {
        Log($"Added {security.Symbol}");
    }

    foreach (var security in changes.RemovedSecurities)
    {
        Log($"Removed {security.Symbol}");
    }
}

def OnSecuritiesChanged(self, algorithm: QCAlgorithm, changes: SecurityChanges) -> None:
    for security in changes.AddedSecurities:
        self.Log(f"Added {security.Symbol}")

    for security in changes.RemovedSecurities:
        self.Log(f"Removed {security.Symbol}")

In live trading, the securities in your brokerage account are added to your user-defined universe. If your Universe Selection model doesn't select these securities, they are not removed from your user-defined universe. When you liquidate the positions, you can remove them from the user-defined universe. If you call the RemoveSecurity method, it automatically liquidates the position.

To see the securities in your user-defined universe that were loaded from your brokerage account, check your algorithm's ActiveSecurities in the OnWarmupFinished event handler.