How-To Example: S&P 500 Reconstitution Events

For performing an Event Study with our API you need:

• API url (defaults to http://api.eventstudytools.com)
• API key (get your API key here)

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

apiUrl <- "http://api.eventstudytools.com"
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)
estSetup$authentication(apiKey)

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

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.

library(readr)
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)

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.

library(readr)
df <- readr::read_delim("02_FirmData.csv", col_names = F, delim = ";")
names(df) <- c("Firm ID", "Date", "Closing Price")
knitr::kable(head(df))

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.

library(readr)
df <- readr::read_delim("03_MarketData.csv", col_names = F, delim = ";")
names(df) <- c("Market ID", "Date", "Closing Price")
knitr::kable(head(df))

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.