get_started.Rmd

---
title: "Get Started"
author: "Dr. Markus Schimmer and EST Team"
date: "`r Sys.Date()`"
output:
  html_document:
    toc: true
    toc_float: true
    theme: readable
    highlight: tango
    css: kable.css
vignette: >
  %\VignetteIndexEntry{Get Started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r echo=FALSE}
knitr::opts_chunk$set(
  comment = "#>",
  collapse = TRUE,
  warning = FALSE,
  message = FALSE
)
```

# Motivation {#motivation}

The provided sample data and request files serve as an example to demonstrate the functionality of the EventStudyTools R-package.

These files contain data related to the addition of several well-known firms to the S&P 500 index during the late 1990s. Using this data, the R package helps you examine whether a company's stock value increases upon being added to the S&P 500 index. This research question has been previously addressed, such as in a 1997 study by Anthony W. Lynch and Richard R. Mendenhall, which found a positive effect of approximately 3.8% from the day after the announcement to the day before the effective date of the change.

With our R-package, you can conveniently explore this and similar research questions.

# Perform an Event Study from R {#perform-an-event-study-from-r}

## Authentication {#authentication}

For performing an Event Study with our API you need:

-   **API url** (defaults to `http://api.eventstudytools.com`)
-   **API key**

You get an API key from our website [EventStudyTools](https://www.eventstudytools.com/api-access). In the first step we need to authenticate to the web API. There are three ways to handle this two parameters:

```{r, eval=FALSE}
library(readr)
library(EventStudy)

apiUrl <- "http://api.eventstudytools.com"
apiKey <- "Please insert your key here"
```

**Option 1 and 2:** You can save API key and URL in the `options` object

```{r, eval=FALSE}
# The URL is already set by default
# options(EventStudy.URL = apiUrl)
options(EventStudy.KEY = apiKey)

# use EventStudy estAPIKey function
estAPIKey(apiKey)

# initialize object
estSetup <- EventStudyAPI$new()
```

**Option 2:** Set the API Key and URL directly during the `EventStudyAPI` `R6-class` initialization

```{r, eval=FALSE}
# Setup API Connection
estSetup <- EventStudyAPI$new(apiUrl)
estSetup$authentication(apiKey)
```

This API package is designed to conduct all analyses available on our website while allowing for the customization of all parameters. You can either set every parameter in R (details provided later) or perform a quick Event Study using default parameters, giving you flexibility and control over your analysis.

## Event Study Types {#event-study-types}

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 type 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:

```{r, eval=FALSE}
estType <- "arc"
```

## Data Files {#data-files}

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 it in a named vector:

```{r, eval=FALSE}
dataFiles <- c("request_file" = "01_RequestFile.csv", 
               "firm_data"    = "02_FirmData.csv", 
               "market_data"  = "03_MarketData.csv")
```

## Results {#results}

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

```{r, eval=FALSE}
resultPath <- "results"
```

**Attention**

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

## Performing the Event Study {#performing-the-event-study}

Finally, the Event Study is performed by:

```{r, eval=FALSE}
estResult <- estSetup$performDefaultEventStudy(estType    = estType,
                                               dataFiles  = dataFiles, 
                                               destDir    = resultPath)
```

It will write all result files into the result directory. Furthermore, results will be parsed into a R object.

# Data File Description {#data-file-description}

For performing an Event Study we need three files (file names can be chosen arbitrarily):

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 header, semi-colon separated and dates has to be in following format: 30.04.1997. In next section we will describe the file structure based on the S&P 500 example Event Study more detailed. You can always find more information on our website: [file-format instructions](https://www.eventstudytools.com/arc/instructions).

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

```{r, message=FALSE, warning=FALSE, results='hide'}
getSP500ExampleFiles()
```

We named the request and data files in following manner:

-   `01_RequestFile.csv`
-   `02_FirmData.csv`
-   `03_MarketData.csv`

## Event Definitions: `01_RequestFile.csv` {#event-definitions-01_requestfile.csv}

This CSV file contains the event definitions and consists of 9 columns. The order must follow the sequence below, as the columns are unnamed 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 smaller or equal zero (e.g. trading days before event).
-   **End Event Window** [Integer]: This integer value defines the end of the event window. This value must greater or equal zero (e.g. trading days after 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 example below, we have an event window of [-2, 2] (an event window of length 5), an estimation window of length 120, and the estimation window ending 11 days before the event.

```{r, message=FALSE}
df <- 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 be unique and numeric.

## Firm Data: `02_FirmData.csv` {#firm-data-02_firmdata.csv}

The stock data for each firm defined 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]: Closing price of volume of that day.

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

```{r, message=FALSE}
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))
```

## Firm Data: `03_MarketData.csv` {#firm-data-03_marketdata.csv}

This file is similary 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]: Closing price of volume of that day.

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

```{r, message=FALSE}
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 at <https://www.eventstudytools.com/arc/instructions>.

# More Vignettes {#more-vignettes}

1.  Event Study: Parameters: In this Vignette we show how you can set parameters and which parameters are allowed.
2.  Use case: Dieselgate.
3.  RStudio Addins: We wrote a RStudio addin for performing different types of Event Studies
    -   Abnormal Return Event Study
    -   Abnormal Volume Event Study
    -   Abnormal Volatility Event Study

# How to Cite {#how-to-cite}

Please cite our work in your [publication](https://www.eventstudytools.com/how-cite-eventstudytoolscom).