parameters.Rmd

---
title: "Event Study: Parameters"
author: "EST Team"
date: "`r Sys.Date()`"
output:
  html_document:
    toc: true
    toc_float: true
    theme: readable
    highlight: tango
    css: kable.css
vignette: >
  %\VignetteEncoding{UTF-8}
  %\VignetteIndexEntry{Event Study: Parameters}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  markdown: 
    wrap: 72
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

# Motivation {#motivation}

You can manually adjust all parameters in your R environment. Save this
object and use it in all your Event Studies. This vignette gives you an
overview on how to set the correct parameters in R.

# Options {#options}

You are able to set some general options in the R option object. This
enables you to setup your API credentials for all R sessions.

-   *EventStudy.URL*: The API url (default: see bottom)
-   *EventStudy.KEY*: The API key (default: NULL)
-   *EventStudy.verbose*: Verbose level (range: 1 - 3, default: 3)
-   *EventStudy.tryAttempts*: Attempts to retry http request (default:
    3)  

The options can be changed by the `options` function in R, e.g.

```{r, eval=FALSE}
options(EventStudy.URL = "http://api.eventstudytools.com")
```

The options can be retained by the

```{r, eval=FALSE}
getOption("EventStudy.tryAttempts")
```

# Performing an Event Study (ARC, AVC, or AVyC) {#performing-an-event-study-arc-avc-or-avyc}

After you have set your parameters, you can easily perform your Event
Study:

```{r, eval=FALSE}
apiUrl <- "http://api.eventstudytools.com"
apiKey <- "Please insert your key here"

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

# Perform Event Study
estResults <- estSetup$performEventStudy(estParams     = volatilityEstParams, 
                                         dataFiles     = c("request_file" = "01_RequestFile.csv",
                                                           "firm_data"    = "02_FirmData.csv",
                                                           "market_data"  = "03_MarketData.csv"),
                                         downloadFiles = T, # download result files
                                         checkFiles    = T) # check input files                     
```

When you set your url or api key via `EventStudy.URL` and
`EventStudy.KEY`, then just leave the arguments to `EventStudyAPI$new()`
and `$authentication()` empty. A default key and url can be
set by:

```{r, eval=FALSE}
options(EventStudy.KEY = apiKey)
```

# General Event Study Parameters {#general-event-study-parameters}

There are several parameters applicable to all types of Event Studies,
including Return, Volatility, and Volume Event Studies. Each Event Study
type requires initializing its own R6 object before performing the
analysis:

-   `ARCApplicationInput`: Return Event Study
-   `AVCApplicationInput`: Volume Event Study
-   `AVyCApplicationInput`: Volatility Event Study

For the remainder of this section, we will focus on a Return Event Study
object. However, the parameters discussed in this section can also be
applied to the other two objects.

```{r, eval=FALSE}
returnEstParams <- ARCApplicationInput$new()
```

## Return File Type {#return-file-type}

The return type defines the type of the result file. Possible options
are

-   **csv** (*default*): comma-separated file with `;` as delimiter,
-   **xls**: Excel 2007,
-   **xlsx**: Excel 2010 and newer, or
-   **ods**: OpenOffice Spreadsheet.

The R API just works with CSV files.

**Usage:**

```{r, eval=FALSE}
returnEstParams$setResultFileType("xlsx")
```

## Return Type {#return-type}

-   **log** (*default*): Return calculation by using log
-   **simple**: Simple return calculation

**Usage:**

```{r, eval=FALSE}
returnEstParams$setReturnType("simple")
```

## Adjustment of Non-trading Days {#adjustment-of-non-trading-days}

-   **earlier**: Select the previous trading day (Choose an earlier date
    if the event day falls on a non-trading day, such as a weekend).
-   **later** (default): Retain non-trading days (Preserve announcement
    dates even if they occur on non-trading days, such as weekends).
-   **keep**: Retain non-trading days (Preserve announcement dates even
    if they occur on non-trading days, such as weekends).
-   **skip**: Omit specific observations (Exclude observations with
    event dates that fall on non-trading days, such as weekends).

**Usage:**

```{r, eval=FALSE}
returnEstParams$setNonTradingDays("earlier")
```

# Abnormal Return Event Study {#abnormal-return-event-study}

For performing Return Event Studies you need to initialize an
`ARCApplicationInput` R6 object.

```{r, eval=FALSE}
returnEstParams <- ARCApplicationInput$new()
```

## Benchmark Models {#benchmark-models}

A comparison of our models can be found on our website.

-   **mm** (default): *Market Model*\
    The Market Model is a statistical method used to estimate the
    relationship between a stock's returns and overall market returns,
    often represented by a market index, through a linear regression
    model.
-   **mm-sw**: *Scholes/Williams Model*\
    The Scholes/Williams Model is a modified version of the Market Model
    that adjusts for potential biases in beta estimation caused by
    non-synchronous trading or infrequent trading of stocks by
    incorporating both leading and lagging market returns.
-   **cpmam**: *Comparison Period Mean Adjusted*\
    Comparison Period Mean Adjusted is a method used in event studies to
    calculate abnormal returns by adjusting each stock's return during
    the event window using the average return of the stock during a
    specified comparison period.
-   **ff3fm**: *Fama-French 3 Factor Model*\
    The Fama-French 3 Factor Model is an asset pricing model that
    expands upon the Capital Asset Pricing Model (CAPM) by incorporating
    two additional factors, size (market capitalization) and value
    (book-to-market ratio), to better explain stock returns and
    portfolio performance.
-   **ffm4fm**: *Fama-French-Momentum 4 Factor Model*\
    The Fama-French-Momentum 4 Factor Model is an extension of the
    Fama-French 3 Factor Model that adds a momentum factor, capturing
    the tendency of stocks with high past returns to continue
    outperforming, thus providing a more comprehensive framework for
    explaining stock returns and portfolio performance.
-   **garch**: `GARCH (1, 1)` *Model*\
    The `GARCH (1, 1)` Model, or Generalized Autoregressive Conditional
    Heteroskedasticity model, is a time-series forecasting model that
    accounts for volatility clustering by estimating the variance of a
    financial variable based on its own past values and past errors,
    thereby improving the accuracy of forecasts in financial markets.
-   **egarch**: `EGARCH (1, 1)` *Model*\
    The `EGARCH (1, 1)` Model, or Exponential Generalized Autoregressive
    Conditional Heteroskedasticity model, is an extension of the GARCH
    model that accounts for both positive and negative shocks to
    volatility by using a natural logarithm transformation, allowing for
    better modeling of asymmetric volatility effects in financial
    markets.

**Usage:**

```{r, eval=FALSE}
returnEstParams$setBenchmarkModel("mm-sw")
```

## Test Statistics {#test-statistics}

Per default all test statistics are activated. A detailed description
can be found on our
[website](https://www.eventstudytools.com/significance-tests).

*Parametric Test Statistics:*

-   t-Test:
    -   art
    -   cart
    -   abhart
-   Cross-Sectional Test (CSect T):
    -   aart
    -   caart
    -   abhart
-   Time-Series Standard Deviation or Crude Dependence Test (CDA T):
    -   aarcdat
    -   caarcdat
-   Patell or Standardized Residual Test (Patell Z):
    -   aarptlz
    -   caarptlz
-   Kolari and Pynnönen adjusted Patell or Standardized Residual Test
    (Adjusted Patell Z):
    -   aaraptlz
    -   caaraptlz
-   Standardized Cross-Sectional or BMP Test (StdCSect Z):
    -   aarbmpz
    -   caarbmpz
-   Kolari and Pynnönen Adjusted Standardized Cross-Sectional or BMP
    Test (Adjusted StdCSect Z)
    -   aarabmpz
    -   caarabmpz
-   Skewness Corrected Test (Skewness Corrected T):
    -   aarskewadjt
    -   caarskewadjt
    -   abharskewadjt
-   Jackknife Test (Abbr.: Jackknife T)
    -   aarjackknivet
    -   caarjackknivet

**Non-Parametric Test Statistics:**

-   Corrado Rank Test (Rank Z):
    -   aarrankz
    -   caarrankz
-   Generalized Rank T Test (Generalized Rank T):
    -   aargrankt
    -   caargrankt
-   Generalized Rank Z Test (Generalized Rank Z):
    -   aargrankz
    -   caargrankz
-   Cowan Generalized Sign Test (Generalized Sign Z)
    -   aargsignz
    -   caargsignz

**Usage:**

```{r, eval=FALSE}
returnEstParams$setTestStatistics(c("aarptlz", "aarrankz"))
```

# Abnormal Volume Event Study {#abnormal-volume-event-study}

For performing Return Event Studies you need to initialize an
`AVCApplicationInput` R6 object.

```{r, eval=FALSE}
volumeEstParams <- AVCApplicationInput$new()
```

## Benchmark Models {#benchmark-models-1}

-   **mm** (default): Market Model
-   **mm-sw**: Scholes/Williams Model
-   **cpmam**: Comparison Period Mean Adjusted
-   **ff3fm**: Fama-French 3 Factor Model
-   **ffm4fm**: Fama-French-Momentum 4 Factor Model

**Usage:**

```{r, eval=FALSE}
volumeEstParams$setBenchmarkModel("mm-sw")
```

## Test Statistics {#test-statistics-1}

Per default all test statistics are activated. A detailed description
can be found on our
[website](https://www.eventstudytools.com/significance-tests).

*Parametric Test Statistics:*

-   t-Test:
    -   art
    -   cart
    -   abhart
-   Cross-Sectional Test (CSect T):
    -   aart
    -   caart
    -   abhart
-   Time-Series Standard Deviation or Crude Dependence Test (CDA T):
    -   aarcdat
    -   caarcdat
-   Patell or Standardized Residual Test (Patell Z):
    -   aarptlz
    -   caarptlz
-   Kolari and Pynnönen adjusted Patell or Standardized Residual Test
    (Adjusted Patell Z):
    -   aaraptlz
    -   caaraptlz
-   Standardized Cross-Sectional or BMP Test (StdCSect Z):
    -   aarbmpz
    -   caarbmpz
-   Kolari and Pynnönen Adjusted Standardized Cross-Sectional or BMP
    Test (Adjusted StdCSect Z)
    -   aarabmpz
    -   caarabmpz
-   Skewness Corrected Test (Skewness Corrected T):
    -   aarskewadjt
    -   caarskewadjt
    -   abharskewadjt
-   Jackknife Test (Abbr.: Jackknife T)
    -   aarjackknivet
    -   caarjackknivet

**Non-Parametric Test Statistics:**

-   Corrado Rank Test (Rank Z):
    -   aarrankz
    -   caarrankz
-   Generalized Rank T Test (Generalized Rank T):
    -   aargrankt
    -   caargrankt
-   Generalized Rank Z Test (Generalized Rank Z):
    -   aargrankz
    -   caargrankz
-   Cowan Generalized Sign Test (Generalized Sign Z)
    -   aargsignz
    -   caargsignz

**Usage:**

```{r, eval=FALSE}
volumeEstParams$setTestStatistics(c("aarptlz", "aarrankz"))
```

# Abnormal Volatility Event Study {#abnormal-volatility-event-study}

For performing Return Event Studies you need to initialize an
`AVyCApplicationInput` R6 object.

```{r, eval=FALSE}
volatilityEstParams <- AVyCApplicationInput$new()
```

## Benchmark Models {#benchmark-models-2}

-   **garch** (default): Garch(1, 1) Model

## Test Statistics {#test-statistics-2}

Per default all test statistics are activated. A detailed description
can be found on our
[website](https://www.eventstudytools.com/other-event-study-types).

**Volatility Test Statistics:**

-   Cross-Sectional Test for Abnormal Volatility
    -   aarcsvyt
-   Corrected Cross-Sectional Test for Abnormal Volatility
    -   aarcscvyt
-   AAR Volatility Ratio-Test
    -   aarlambdaz

**Abnormal Return Test Statistics:**

-   Cross-Sectional Test for Abnormal Return
    -   aarcsart
-   Cross-Sectional-Corrected Test for Abnormal Return
    -   aarcscart

**Usage:**

```{r, eval=FALSE}
volatilityEstParams$setTestStatistics(c("aarptlz", "aarrankz"))
```

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

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