---
title: "Introduction to estudy2"
author: "Iegor Rudnytskyi"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to estudy2}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

The `estduy2` package is an implementation of an event study methodology. The event study is a statistical toolbox that allows examining the impact of certain events on the stock valuation of companies. The idea of the event study is to compare the market valuation of companies during an event-free period (called the estimation period) and a period when an event happened (the event period).

In order to complete a full event study one has to:

* Select companies of interest

* Select dates of the event and the estimation periods

* Obtain prices of companies' stocks

* Compute rates of return

* Fit a market model to the data

* Test the expected returns against observed returns of companies

The `estudy2` package provides a set of functions to cover these steps. Functions' names are self-explanatory and functions should be called consecutively in the following order:

* `get_prices_from_tickers` returns daily prices for given tickers 

* `get_rates_from_prices` computes rates of returns from prices

* `apply_market_model` fits a market model to rates of returns data

* `parametric_tests` and `nonparametric_tests` performs parametric and nonparametric tests, respectively

The package is designed to work with one of the data types, namely `zoo`, `list`, or `data.frame` depending on user preference.

The purpose of this vignette is to provide a brief introduction of how to use this package. The illustrative example is the analysis of the impact of 9/11 terrorist attacks on World Trading Center on eight European insurance companies.

## Obtaining prices of companies' stocks

We select eight European insurance companies, tickers of which are listed in the code snippet below. The starting and ending date are set to `"2000-01-01"` and `"2002-01-01"`, respectively, in order to include both the estimation and the event periods. Then, prices of securities should be downloaded. The function `get_prices_from_tickers` downloads prices for companies' tickers between `start` and `end` date. Under the hood, this function is a wrapper around `get.hist.quote` from `tseries`. The function can return either Open or Close quote (`quote` argument). Also one has to choose the returning class among `"list"`, `"zoo"`, and `"data.frame"`. Further in the vignette we use `zoo` objects. We download historical prices of companies with:

```{r, message=FALSE, warning=FALSE}
library(estudy2)
tickers <- c("ALV.DE", "CS.PA", "G.MI", "HNR1.HA", "HSX.L", "MUV2.DE", "RSA.L",
             "TOP.CO")
prices <- get_prices_from_tickers(tickers, 
                                  start = as.Date("2000-01-01"),
                                  end = as.Date("2002-01-01"),
                                  quote = "Close",
                                  retclass = "zoo")
```

For using a single-index market model we also need to download prices of an index (proxy):

```{r, message=FALSE, warning=FALSE}
prices_indx <- get_prices_from_tickers("^N100",
                                       start = as.Date("2000-01-01"),
                                       end = as.Date("2002-01-01"),
                                       quote = "Close",
                                       retclass = "zoo")
```

## Computing rates of returns from prices
Now we need to compute rates of returns form companies' prices. For this purpose the function `get_rates_from_prices` is used, which is an S3 generic function dispatched on `prices` argument allowing for `list`, `zoo`, and `data.frame` (the same classes which `get_prices_from_tickers` returns). The function computes rates of returns of given prices using either continuous or discrete compounding depending on `compounding` argument value. Furthermore, setting `multi_day` to `TRUE` allows for rates of returns between non-consecutive days (for instance, Friday - Monday rate of return). We calculate rates of returns of companies and the index by:

```{r}
rates <- get_rates_from_prices(prices,
                               quote = "Close",
                               multi_day = TRUE,
                               compounding = "continuous")

rates_indx <- get_rates_from_prices(prices_indx, 
                                    quote = "Close",
                                    multi_day = TRUE,
                                    compounding = "continuous")
```

## Applying a market model

To calculate expected rates of returns during the event period we need to train a market model based on date from the estimation period. `apply_market_model` goes over each company (column) in `rates` and calibrates a chosen model. The function returns a list of S3 `returns` class objects, which can be passed to `parametric_tests` and `nonparametric_tests`. For our case we use the single-index market model:

```{r}
securities_returns <- apply_market_model(
    rates = rates,
    regressor = rates_indx,
    same_regressor_for_all = TRUE,
    market_model = "sim",
    estimation_method = "ols",
    estimation_start = as.Date("2001-03-26"),
    estimation_end = as.Date("2001-09-10")
)
```

## Tests

The event study utilizes both parametric and nonparametric tests. Parametric tests are Brown and Warner (1980), Brown and Warner (1985), t-test, Patell (1976), Boehmer (1991), and Lamb (1995) tests. To avoid calling all these tests separately, one can call `parametric_tests` with `all = TRUE`. The same applies to nonparametric tests, i.e. simple binomial sign, binomial sign, Corrado (1992), rank, modified rank, and Wilcoxon signed rank tests can be called all at once by specifying `all = TRUE` in `nonparametric_tests`. These tests are also available separately. Both functions return data frames with statistics and significance for each date in the event period. See `?parametric_tests` and `?nonparametric_tests` for references and more details.

```{r}
parametric_tests(list_of_returns = securities_returns,
                 event_start = as.Date("2001-09-11"),
                 event_end = as.Date("2001-09-28"))

nonparametric_tests(list_of_returns = securities_returns,
                    event_start = as.Date("2001-09-11"),
                    event_end = as.Date("2001-09-28"))

```

## Using `magrittr`

One can notice that the result of the previous function is passed to the next function. In order to avoid naming all the intermediate objects or using a function composition, it possible to utilize a power of the pipe operator from `magrittr`. The above code can be rewritten with: 

```{r, message=FALSE, warning=FALSE}
library(magrittr)

rates_indx <- get_prices_from_tickers("^N100",
                                      start = as.Date("2000-01-01"),
                                      end = as.Date("2002-01-01"),
                                      quote = "Close",
                                      retclass = "zoo") %>%
    get_rates_from_prices(quote = "Close",
                          multi_day = TRUE,
                          compounding = "continuous")

tickers <- c("ALV.DE", "CS.PA", "G.MI", "HNR1.HA", "HSX.L", "MUV2.DE", "RSA.L",
             "TOP.CO")
nine_eleven_param <- get_prices_from_tickers(tickers,
                                             start = as.Date("2000-01-01"),
                                             end = as.Date("2002-01-01"),
                                             quote = "Close",
                                             retclass = "zoo") %>%
    get_rates_from_prices(quote = "Close",
                          multi_day = TRUE,
                          compounding = "continuous") %>%
    apply_market_model(regressor = rates_indx,
                       same_regressor_for_all = TRUE,
                       market_model = "sim",
                       estimation_method = "ols",
                       estimation_start = as.Date("2001-03-26"),
                       estimation_end = as.Date("2001-09-10")) %>%
    parametric_tests(event_start = as.Date("2001-09-11"),
                     event_end = as.Date("2001-09-28"))
```
