How-To Example: S&P 500 Reconstitution Events

Please use the sample provided on the web user interface of the abnormal return calculator. The files hold data about the addition of several well-known firms to the S&P 500 index in the late 1990s. With this data, we will investigate the typical stock responses to reconstitution events of the S&P 500. This is a common research question and has been addressed, among others, by Anthony W. Lynch and Richard R. Mendenha in a 1997 study: They found a positive effect of about 3.8% over the period starting the day after the announcement of an addition and ending the day before the effective date of the change (see: Mergers & Acquisitions).

You can use our R-package to easily investigate such and similar questions.

Installing the R-Package

# you need to install devtools first

Authentication with API Key

For performing an Event Study with our API you need:

In the first step, you need to authenticate to the web API. There are two ways to handle these two parameters:

apiUrl <- ""
apiKey <- "Please insert your key here"

Option 1: You can save the API key and url in the options object

options(apiServerUrl = apiUrl)
options(eventStudyKey = apiKey)

# initialize object
estSetup <- EventStudyAPI$new()

Option 2: Alternatively, you can set them directly during the EventStudyAPI R6-class initialization

# Setup API Connection
estSetup <- EventStudyAPI$new(apiUrl)

This API package is designed to perform all analyses we provide on our website. Furthermore, all parameters can be set. You can set every parameter in R (we will provide more details later) or you can perform a fast Event Study with default parameters.

Parameter choices and default values, incl. type of event study

Our API offers different types of Event Studies:

  • Return Event Study: arc
  • Trading Volume Event Study: avc
  • Abnormal Volatility Event Study: avyc

Default parameters for all types of above Event Studies are:

  • Benchmark model: Market Model for arc and avc and GARCH(1, 1) Model for avyc
  • Statistics: All available test statistics are calculated
  • Result file type: csv
  • Return type calculation: log
  • Handling non-trading days: later

The type of Event Study can be set by parameter:

estType <- "arc"

Default data file names and how to change them

By default, all data files must be named as follows. Furthermore, they have to be in the current directory:

  • 01_RequestFile.csv
  • 02_firmData.csv
  • 03_MarketData.csv

You are also able to set custom file names and paths by defining them in a named vector:

dataFiles <- c("request_file" = "01_RequestFile.csv", 
               "firm_data"    = "02_firmData.csv", 
               "market_data"  = "03_MarketData.csv")

Default folder for result storage and how to change it

All results will be written by default in the directory ./results. You can easily change this path by setting it as a parameter:

resultPath <- "results"

Attention: If the resultPath do not exist, the R package will create this directory.


Starting the Event Study

Finally, the Event Study is performed by:

estResult <- estSetup$performDefaultEventStudy(estType   = estType,
                                               dataFiles = dataFiles, 
                                               destDir   = resultPath)

The package will write all result files into the result directory. Furthermore, results will be parsed into an R object.


Data File Requirements

For performing an Event Study, you need to provide three files:

  1. A request file where the structure of the Event Study is defined
  2. A firm data file containing the stock data for each firm defined in the request file
  3. A market data file containing the reference market data (multiple reference markets per study are possible)

All files must be saved without a header, semi-colon separated and dates have to be in the following format: 30.04.1997. In the next section, we will describe the file structure based on the S&P 500 example Event Study in more detail. You find further information about data file requirements on the instruction page of the server-side research app.

We added the S&P 500 example Event Study to this package. The three necessary files can be easily generated by the following command:


We named the request and data files in the following manner:

  • 01_RequestFile.csv
  • 02_FirmData.csv
  • 03_MarketData.csv

In your analysis, you can name them as you want.

01_RequestFile.csv: Specification of events

This CSV file contains the event definitions. It contains 9 columns. The order must be in the following way, as the columns are not named in the CSV.

  • Event ID [Integer]: A unique event identifier.
  • Firm ID [String]: The firm name or stock ID. This ID must match the ID in the firm data.
  • Market ID [String]: The reference market ID. This ID must match the ID in the market data.
  • Event Date [30.04.1997]: Date of the event.
  • Grouping Variable [String]: This column is used to group events. Most test statistics are based on looking at groups.
  • Start Event Window [Integer]: This integer value defines the start of the event window. This value must be smaller or equal to zero (e.g. trading days before the event).
  • End Event Window [Integer]: This integer value defines the end of the event window. This value must be greater or equal to zero (e.g. trading days after the event).
  • End of Estimation Window [Integer]: This negative value defines the end of the estimation window (counted from event day).
  • Estimation Window Length [Integer]: Length of the estimation window.

In the following example, we have an event window of [-2, 2] (an event window of length 5), an estimation window of length 120, and the estimation window ends 11 days before the event.

df <- readr::read_delim("01_RequestFile.csv", col_names = F, delim = ";")
names(df) <- c("Event ID", "Firm ID", "Market ID", "Event Date", "Grouping Variable", "Start Event Window", "End Event Window", "End of Estimation Window", "Estimation Window Length")
knitr::kable(head(df), pad=0)
Event ID Firm ID Market ID Event Date Grouping Variable Start Event Window End Event Window End of Estimation Window Estimation Window Length
75510 Adobe Systems SP500 30.04.1997 Addition -2 2 -11 120
64390 Progressive SP500 25.07.1997 Addition -2 2 -11 120
23473 Cincinnati SP500 16.12.1997 Addition -2 2 -11 120
70500 Coca-Cola Enterprises SP500 01.10.1998 Addition -2 2 -11 120
70519 Travelers Group SP500 01.10.1998 Addition -2 2 -11 120
76149 Safeway SP500 05.11.1998 Addition -2 2 -11 120

Attention: The first column (Event IDs) must hold unique numeric values.


02_FirmData.csv: Stock market closing data of the studied firms

This file holds the stock data for the firms listed in the request file. It contains 3 columns.

  • Firm ID [String]: The firm or stock ID. This ID must match the ID in the Firm ID in the request file.
  • Date [30.04.1997]: Date of the closing price.
  • Closing Price [Double]: The closing price or the volume of that day.

The following table shows the first 20 entries of our example firm data.

df <- readr::read_delim("02_FirmData.csv", col_names = F, delim = ";")
names(df) <- c("Firm ID", "Date", "Closing Price")
Firm ID Date Closing Price
Cincinnati 01.10.1996 58.000
Cincinnati 02.10.1996 57.000
Cincinnati 03.10.1996 56.750
Cincinnati 04.10.1996 57.500
Cincinnati 07.10.1996 57.625
Cincinnati 08.10.1996 57.750

03_MarketData.csv: Stock market closing data of the reference indices

This file is similarly structured as 02_FirmData.csv:

  • Market ID [String]: The market ID or stock ID. This ID must match the ID in the Market ID in the request file.
  • Date [30.04.1997]: Date of the closing price.
  • Closing Price [Double]: The closing price or the volume of that day.

The following table shows the first 20 entries of our example firm data.

df <- readr::read_delim("03_MarketData.csv", col_names = F, delim = ";")
names(df) <- c("Market ID", "Date", "Closing Price")
Market ID Date Closing Price
SP500 30.09.1996 100.0000
SP500 01.10.1996 100.2575
SP500 02.10.1996 100.9747
SP500 03.10.1996 100.7958
SP500 04.10.1996 102.0587
SP500 07.10.1996 102.3380

You are also able to apply a Fama-French 3-Factor Model or a Fama-French Momentum-4-Factor Model. This will change the necessary data you need for performing an Event Study (e.g. by adding Fama-French Factors). You find more information on our instruction page.