QuantConnect
US Equity Security Master
Introduction
The US Equity Security Master dataset by QuantConnect tracks US Equity corporate actions, including splits, dividends, delistings, mergers, and ticker changes through history. The data covers approximately 27,500 US Equities, starts in January 1998, and is delivered on a daily update frequency. You can easily download and install the dataset with the LEAN CLI so it's ready to use by LEAN. LEAN automatically handles all corporate actions and passes them into your algorithm as events.
This is not the underlying Equity data (US Equities dataset), which you need to purchase separately with a license from AlgoSeek. This security master dataset is required to purchase the US Equities or US Equities Options datasets.
For more information about the US Equity Security Master dataset, including CLI commands and pricing, see the dataset listing.
About the Provider
QuantConnect was founded in 2012 to serve quants everywhere with the best possible algorithmic trading technology. Seeking to disrupt a notoriously closed-source industry, QuantConnect takes a radically open-source approach to algorithmic trading. Through the QuantConnect web platform, more than 50,000 quants are served every month.
Data Summary
Data is delivered as a daily updated zip archive of map and factor files. The data is designed to be used in the LEAN Engine and cannot be consumed another way. The following table shows the dataset properties:
| Property | Value |
|---|---|
| Start Date | January 1998 |
| Data Points | Splits, Dividends, Mergers, IPO, & Delistings |
| Asset Coverage | 27,500 US Equities |
| Resolution | Daily |
| Timezone | New York |
This is not the underlying Equity data (US Equities dataset), which you need to purchase separately with a license from AlgoSeek. This security master dataset is required to purchase the US Equities or US Equities Options datasets.
Getting Started
You don't need any special code to utilize the US Equity Security Master. It automatically loads when you request US Equities data.
Accessing Splits
To get the current split data, index the Splitssplits property of the current Slice with the Equity Symbol. Slice objects deliver unique events to your algorithm as they happen, but the Slice may not contain data for your security at every time step. To avoid issues, check if the Slice contains the data you want before you index it.
def on_data(self, slice: Slice) -> None:
# Check if any splits for the symbol
if slice.splits.contains_key(self._symbol):
# If so, get the mapped split object
split = slice.splits[self._symbol]
split_type = {0: "Warning", 1: "SplitOccurred"}.get(split.type)
self.log(f"Split: {split.symbol}\t{split.split_factor}\t{split.reference_price}\t{split_type}") public override void OnData(Slice slice)
{
// Check if any splits for the symbol
if (slice.Splits.ContainsKey(_symbol))
{
// If so, get the mapped split object
var split = slice.Splits[_symbol];
Log($"Split: {split.Symbol}\t{split.SplitFactor}\t{split.ReferencePrice}\t{split.Type}");
}
}
For more information about accessing splits, see Splits.
Accessing Dividends
To get the current dividend data, index the Dividendsdividends property of the current Slice with the Equity Symbol. Slice objects deliver unique events to your algorithm as they happen, but the Slice may not contain data for your security at every time step. To avoid issues, check if the Slice contains the data you want before you index it.
def on_data(self, slice: Slice) -> None:
# Check if any dividend for the symbol
if slice.dividends.contains_key(self._symbol):
# If so, get the mapped dividend object
dividend = slice.dividends[self._symbol]
self.log(f'Dividend: {dividend.symbol}\t{dividend.distribution}\t{dividend.reference_price}') public override void OnData(Slice slice)
{
// Check if any dividend for the symbol
if (slice.Dividends.ContainsKey(_symbol))
{
// If so, get the mapped dividend object
var dividend = slice.Dividends[_symbol];
Log($"Dividend: {dividend.Symbol}\t{dividend.Distribution}\t{dividend.ReferencePrice}");
}
}
For more information about accessing dividends, see Dividends.
Accessing Delistings
To get the current Delistings data, index the Delistingsdelistings property of the current Slice with the Equity Symbol. Slice objects deliver unique events to your algorithm as they happen, but the Slice may not contain data for your security at every time step. To avoid issues, check if the Slice contains the data you want before you index it.
def on_data(self, slice: Slice) -> None:
# Check if any delisting for the symbol
if slice.delistings.contains_key(self._symbol):
# If so, get the mapped delisting object
delisting = slice.delistings[self._symbol]
delisting_type = {0: "Warning", 1: "Delisted"}.get(delisting.type)
self.log(f'Delistings: {delisting_type}') public override void OnData(Slice slice)
{
// Check if any delisting for the symbol
if (slice.Delistings.ContainsKey(_symbol))
{
// If so, get the mapped delisting object
var delisting = slice.Delistings[_symbol];
Log($"Delistings: {delisting.Type}");
}
}
For more information about accessing delistings, see Delistings.
Accessing Symbol Change Events
To get the current Symbol change events, index the SymbolChangedEventssymbol_changed_events property of the current Slice with the Equity Symbol. Slice objects deliver unique events to your algorithm as they happen, but the Slice may not contain data for your security at every time step. To avoid issues, check if the Slice contains the data you want before you index it.
def on_data(self, slice: Slice) -> None:
# Check if any symbol change event for the symbol
if slice.symbol_changed_events.contains_key(self._symbol):
# If so, get the mapped SymbolChangeEvent object
symbol_changed_event = slice.symbol_changed_events[self._symbol]
self.log(f"Symbol changed: {symbol_changed_event.old_symbol} -> {symbol_changed_event.new_symbol}")
public override void OnData(Slice slice){
// Check if any symbol change event for the symbol
if (slice.SymbolChangedEvents.ContainsKey(_symbol))
{
// If so, get the mapped SymbolChangeEvent object
var symbolChangedEvent = slice.SymbolChangedEvents[_symbol];
Log($"Symbol changed: {symbolChangedEvent.OldSymbol} -> {symbolChangedEvent.NewSymbol}");
}
}
For more information about accessing Symbol change events, see Symbol Changes.
Historical Data
To get historical US Equity Security Master data, call the Historyhistory method with the data type and the Equity Symbol. If there is no data in the period you request, the history result is empty.
# Splits split_history_df = self.history(Split, self._symbol, timedelta(5*365)) split_history = self.history[Split](self._symbol, timedelta(5*365)) # Dividends dividend_history_df = self.history(Dividend, self._symbol, timedelta(5*365)) dividend_history = self.history[Dividend](self._symbol, timedelta(5*365)) # Symbol Changes symbol_change_history_df = self.history(SymbolChangedEvent, self._symbol, timedelta(5*365)) symbol_change_history = self.history[SymbolChangedEvent](self._symbol, timedelta(5*365)) # Delistings delisting_history_df = self.history(Delisting, self._symbol, timedelta(5*365)) delisting_history = self.history[Delisting](self._symbol, timedelta(5*365))
// Splits var splitHistory = History<Split>(_symbol, TimeSpan.FromDays(5*365)); // Dividends var dividendHistory = History<Dividend>(_symbol, TimeSpan.FromDays(5*365)); // Symbol Changes var symbolChangeHistory = History<SymbolChangedEvent>(_symbol, TimeSpan.FromDays(5*365)); // Delistings var delistingHistory = History<Delisting>(_symbol, TimeSpan.FromDays(5*365));
For more information about historical data, see History Requests.
Supported Assets
To view the supported assets in the US Equity Security Master dataset, see the Data Explorer. This dataset doesn't include Over-the-Counter (OTC) stocks.
Example Applications
The US Security Master enables you to accurately design strategies harnessing any core corporate actions. Examples include the following strategies:
- Post-dividend announcement trading strategies.
- Trading on new Equities by monitoring for IPOs.
- Harnessing split announcements for reverse-split announcement momentum.
Classic Algorithm Example
The following example algorithm logs the Split, Dividend, Delisting, and SymbolChangedEvent objects of Apple:
from AlgorithmImports import *
class USEquitySecurityMasterAlgorithm (QCAlgorithm):
def initialize(self):
self.set_start_date(2024, 9, 1)
self.set_end_date(2024, 12, 31)
self.set_cash(1000000)
self.equity = self.add_equity("AAPL", Resolution.DAILY).symbol
def on_data(self, slice: Slice) -> None:
# Accessing Data - Splits
split = slice.splits.get(self.equity)
if split:
self.debug(f"{self.time} >> SPLIT >> {split.symbol} - {split.split_factor} - {self.portfolio.cash} - {self.portfolio[self.equity].price}")
# Accessing Data - Dividends
dividend = slice.dividends.get(self.equity)
if dividend:
self.debug(f"{self.time} >> DIVIDEND >> {dividend.symbol} - {dividend.distribution} - {self.portfolio.cash} - {self.portfolio[self.equity].price}")
# Accessing Data - Delisting
delisting = slice.delistings.get(self.equity)
if delisting:
delistingType = {0: "Warning", 1: "Delisted"}.get(delisting.type)
self.debug(f"{self.time} >> DELISTING >> {delisting.symbol} - {delistingType}")
# Accessing Data - Symbol Changed Event
symbolChangedEvent = slice.symbol_changed_events.get(self.equity)
if symbolChangedEvent:
self.debug(f"{self.time} >> SYMBOL CHANGED >> {symbolChangedEvent.old_symbol} -> {symbolChangedEvent.new_symbol}")
public class USEquitySecurityMasterAlgorithm : QCAlgorithm
{
private Symbol _equity;
public override void Initialize()
{
SetStartDate(2024, 9, 1);
SetEndDate(2024, 12, 31);
SetCash(1000000);
_equity = AddEquity("AAPL", Resolution.Daily).Symbol;
}
public override void OnData(Slice slice)
{
// Accessing Data - Splits
if (slice.Splits.ContainsKey(_equity))
{
var split = slice.Splits[_equity];
Debug($"Split: {split.Symbol}\t{split.SplitFactor}\t{split.ReferencePrice}\t{split.Type}");
}
// Accessing Data - Dividends
if (slice.Dividends.ContainsKey(_equity))
{
var dividend = slice.Dividends[_equity];
Log($"Dividend: {dividend.Symbol}\t{dividend.Distribution}\t{dividend.ReferencePrice}");
}
// Accessing Data - Delisting
if (slice.Delistings.ContainsKey(_equity))
{
var delisting = slice.Delistings[_equity];
Log($"Delistings: {delisting.Type}");
}
// Accessing Data - Symbol Changed Event
if (slice.SymbolChangedEvents.ContainsKey(_equity))
{
var symbolChangedEvent = slice.SymbolChangedEvents[_equity];
Log($"Symbol changed: {symbolChangedEvent.OldSymbol} -> {symbolChangedEvent.NewSymbol}");
}
}
}Framework Algorithm Example
The following algorithm demonstrates the payments for cash dividends in backtesting. When the data normalization mode is Raw, your portfolio receives cash dividends.
from AlgorithmImports import *
class PaymentAlgorithm(QCAlgorithm):
def initialize(self) -> None:
self.set_start_date(2024, 9, 1)
self.set_end_date(2024, 12, 31)
# this will use the Tradier Brokerage open order split behavior
# forward split will modify open order to maintain order value
# reverse split open orders will be canceled
self.set_brokerage_model(BrokerageName.TRADIER_BROKERAGE)
self.universe_settings.resolution = Resolution.DAILY
self.universe_settings.data_normalization_mode = DataNormalizationMode.RAW
# MSFT: Splits and Dividends
# GOOG: Symbol Changed Event
# AAA.1: Delisting
self.set_universe_selection(ManualUniverseSelectionModel(
Symbol.create("MSFT", SecurityType.EQUITY, Market.USA)))
self.set_alpha(PaymentAlphaModel())
self.set_portfolio_construction(EqualWeightingPortfolioConstructionModel())
self.set_execution(BracketExecutionModel())
class PaymentAlphaModel(AlphaModel):
symbol = Symbol.EMPTY
def update(self, algorithm: QCAlgorithm, slice: Slice) -> List[Insight]:
# Accessing Data - Splits
split = slice.splits.get(self.symbol)
if split:
algorithm.debug(f"{algorithm.time} >> SPLIT >> {split.symbol} - {split.split_factor} - {algorithm.portfolio.cash} - {algorithm.portfolio[self.symbol].price}")
# Accessing Data - Dividends
dividend = slice.dividends.get(self.symbol)
if dividend:
algorithm.debug(f"{algorithm.time} >> DIVIDEND >> {dividend.symbol} - {dividend.distribution} - {algorithm.portfolio.cash} - {algorithm.portfolio[self.symbol].price}")
# Accessing Data - Delistings
delisting = slice.delistings.get(self.symbol)
if delisting:
delistingType = {0: "Warning", 1: "Delisted"}.get(delisting.type)
algorithm.debug(f"{algorithm.time} >> DELISTING >> {delisting.symbol} - {delistingType}")
# Accessing Data - Symbol Changed Events
symbolChangedEvent = slice.symbol_changed_events.get(self.symbol)
if symbolChangedEvent:
algorithm.debug(f"{algorithm.time} >> SYMBOL CHANGED >> {symbolChangedEvent.old_symbol} -> {symbolChangedEvent.new_symbol}")
bar = slice.bars.get(self.symbol)
return [Insight.price(self.symbol, timedelta(1), InsightDirection.UP)] if bar else []
def on_securities_changed(self, algorithm: QCAlgorithm, changes: SecurityChanges) -> None:
self.symbol = list(changes.added_securities)[0].symbol
class BracketExecutionModel(ExecutionModel):
def __init__(self) -> None:
'''Initializes a new instance of the ImmediateExecutionModel class'''
self.targets_collection = PortfolioTargetCollection()
def execute(self, algorithm: QCAlgorithm, targets: List[PortfolioTarget]) -> None:
# for performance we check count value, OrderByMarginImpact and ClearFulfilled are expensive to call
self.targets_collection.add_range(targets)
if self.targets_collection.count > 0:
for target in self.targets_collection.order_by_margin_impact(algorithm):
# calculate remaining quantity to be ordered
quantity = OrderSizing.get_unordered_quantity(algorithm, target)
if quantity != 0 and algorithm.transactions.orders_count == 0:
bar = algorithm.securities[target.symbol].get_last_data()
algorithm.market_order(target.symbol, quantity)
# place some orders that won't fill, when the split comes in they'll get modified to reflect the split
algorithm.stop_market_order(target.symbol, -quantity, bar.low/2)
algorithm.limit_order(target.symbol, -quantity, bar.high*2)
self.targets_collection.clear_fulfilled(algorithm)
public class PaymentsAlgorithm : QCAlgorithm
{
public override void Initialize()
{
SetStartDate(2024, 9, 1);
SetEndDate(2024, 12, 31);
// this will use the Tradier Brokerage open order split behavior
// forward split will modify open order to maintain order value
// reverse split open orders will be canceled
SetBrokerageModel(BrokerageName.TradierBrokerage);
UniverseSettings.Resolution = Resolution.Daily;
UniverseSettings.DataNormalizationMode = DataNormalizationMode.Raw;
// MSFT: Splits and Dividends
// GOOG: Symbol Changed Event
// AAA.1: Delisting
SetUniverseSelection(new ManualUniverseSelectionModel(
QuantConnect.Symbol.Create("MSFT", SecurityType.Equity, Market.USA)));
SetAlpha(new PaymentAlphaModel());
SetPortfolioConstruction(new EqualWeightingPortfolioConstructionModel());
SetExecution(new BracketExecutionModel());
}
}
public class PaymentAlphaModel : AlphaModel
{
private Symbol _symbol = Symbol.Empty;
public override IEnumerable<Insight> Update(QCAlgorithm algorithm, Slice slice)
{
// Accessing Data - Splits
if (slice.Splits.ContainsKey(_symbol))
{
var split = slice.Splits[_symbol];
algorithm.Debug($"{split.Time.ToIso8601Invariant()} >> SPLIT >> {split.Symbol} - " +
$"{split.SplitFactor.ToStringInvariant()} - " +
$"{algorithm.Portfolio.Cash.ToStringInvariant()} - " +
$"{algorithm.Portfolio[_symbol].Quantity.ToStringInvariant()}");
}
// Accessing Data - Dividends
if (slice.Dividends.ContainsKey(_symbol))
{
var dividend = slice.Dividends[_symbol];
algorithm.Debug($"{dividend.Time.ToStringInvariant("o")} >> DIVIDEND >> {dividend.Symbol} - " +
$"{dividend.Distribution.ToStringInvariant("C")} - {algorithm.Portfolio.Cash} - " +
$"{algorithm.Portfolio[_symbol].Price.ToStringInvariant("C")}");
}
// Accessing Data - Delisting
if (slice.Delistings.ContainsKey(_symbol))
{
var delisting = slice.Delistings[_symbol];
algorithm.Debug($"{delisting.Time.ToStringInvariant("o")} >> DELISTING >> {delisting.Type}");
}
// Accessing Data - Symbol Changed Event
if (slice.SymbolChangedEvents.ContainsKey(_symbol))
{
var symbolChangedEvent = slice.SymbolChangedEvents[_symbol];
algorithm.Debug($"{symbolChangedEvent.Time.ToStringInvariant("o")} >> Symbol Changed Event >> " +
$"{symbolChangedEvent.OldSymbol} -> {symbolChangedEvent.OldSymbol}");
}
return slice.Bars.ContainsKey(_symbol)
? new [] { Insight.Price(_symbol, TimeSpan.FromDays(1), InsightDirection.Up) }
: Enumerable.Empty<Insight>();
}
public override void OnSecuritiesChanged(QCAlgorithm algorithm, SecurityChanges changes)
{
_symbol = changes.AddedSecurities.First().Symbol;
}
}
public class BracketExecutionModel : ExecutionModel
{
private readonly PortfolioTargetCollection _targetsCollection = new PortfolioTargetCollection();
public override void Execute(QCAlgorithm algorithm, IPortfolioTarget[] targets)
{
_targetsCollection.AddRange(targets);
// for performance we check count value, OrderByMarginImpact and ClearFulfilled are expensive to call
if (_targetsCollection.Count > 0)
{
foreach (var target in _targetsCollection.OrderByMarginImpact(algorithm))
{
// calculate remaining quantity to be ordered
var quantity = OrderSizing.GetUnorderedQuantity(algorithm, target);
if (quantity != 0 && algorithm.Transactions.OrdersCount == 0)
{
var bar = algorithm.Securities[target.Symbol].GetLastData() as TradeBar;
algorithm.MarketOrder(target.Symbol, quantity);
// place some orders that won't fill, when the split comes in they'll get modified to reflect the split
algorithm.StopMarketOrder(target.Symbol, -quantity, bar.Low/2);
algorithm.LimitOrder(target.Symbol, -quantity, bar.High*2);
}
}
_targetsCollection.ClearFulfilled(algorithm);
}
}
}Data Point Attributes
The US Equity Security Master dataset provides Split, Dividend, Delisting, and SymbolChangedEvent objects.
Split Attributes
When a split or merger occurs, we pass the previous Symbol data into your algorithm. Split objects have the following attributes:
Dividend Attributes
Dividend events are triggered on the payment date. Dividend objects have the following attributes:
Delisting Attributes
When a security is delisted, we notify your algorithm. Delisting objects have the following attributes:
SymbolChangedEvent Attributes
When a security changes their ticker, we notify your algorithm. SymbolChangedEvent objects have the following attributes: