---
title: "documentation"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{documentation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup}
library(eventstudyr)
```

## Event Studies

Linear panel models, and the event-study plots that often accompany them, are popular tools for learning about policy effects. 
 
## eventstudyr

`eventstudyr` facilitates estimating linear panel event-study models and constructing event-study plots following the suggestions in [Freyaldenhoven _et al._ (2021)](https://www.nber.org/system/files/working_papers/w29170/w29170.pdf). In particular, it provides functionality for:

* depicting cumulative estimated effects of a policy relative to a user-controlled normalized period
* adding confidence intervals and sup-t confidence bands
* testing for the presence of "pre-trends" and stable dynamics post-event
* plotting the least "wiggly" confound consistent with the estimates
 
## Data

We will use the `example_data` dataset to demonstrate the basic functionality of `eventstudyr`. These sample data are from the [replication archive](https://data.nber.org/data-appendix/w29170/) for Freyaldenhoven et al. (2021). The documentation can be accessed using `?example_data`.
 
```{r Data preview}

dim(example_data)
head(example_data)
```


## EventStudy()

`EventStudy()` estimates the regression model from Equation (2) in Freyaldenhoven et al. (2021) and returns a list object that stores the estimation results (as an lm() object) as well as the arguments given in the function call. It accepts variables specifying the outcome, policy, ID and time variables. One must also specify the number of periods in the past before which the past values of the policy are not supposed to affect the value of the outcome and the number of periods in the future after which the future values of the policy are not supposed to affect the value of the outcome today. The function optionally accepts variables specifying the controls, the time window, whether fixed effects should be included, and the period to be used for normalization.

Here is an example using the sample data:

```{r Basic Eventstudy Example - Show Code, eval = FALSE}
results <- EventStudy(estimator = "OLS",
                      data = example_data,
                      outcomevar = "y_jump_m",
                      policyvar = "z",
                      idvar = "id",
                      timevar = "t",
                      post = 3,
                      pre = 0)
```
```{r Basic Eventstudy Example - Run Code, echo = FALSE}
results <- EventStudy(estimator = "OLS",
                      data = example_data,
                      outcomevar = "y_jump_m",
                      policyvar = "z",
                      idvar = "id",
                      timevar = "t",
                      post = 3,
                      pre = 0)
```
```{r Basic Eventstudy Example - Show Results 1, echo=TRUE, eval=TRUE}
summary(results$output)
```
<details>
  <summary>Click for `results$arguments`</summary>
  ```{r}
  ## Estimator
  results$arguments$estimator
  
  ## Data
  results$arguments$data[1:5,]
  
  ## Variables
  results$arguments$outcomevar
  results$arguments$outcomevar
  results$arguments$policyvar
  results$arguments$idvar
  results$arguments$timevar
  results$arguments$controls
  
  ## Proxies
  results$arguments$proxy
  results$arguments$proxyIV
  
  ## Fixed effects
  results$arguments$FE
  results$arguments$TFE
  
  ## Periods
  results$arguments$post
  results$arguments$overidpost
  results$arguments$pre
  results$arguments$overidpre
  
  ## Normalization
  results$arguments$normalize
  results$arguments$normalization_column
  
  ## Cluster
  results$arguments$cluster
  
  ## Eventstudy coefficients
  results$arguments$eventstudy_coefficients
  ```
</details>

## EventStudyPlot()
`EventStudyPlot()` prepares an event-study plot based on the suggestions in Freyaldenhoven et al. (2021).

This function is designed to use the output of the `EventStudy()` and returns a ggplot object. Here is an example of using the function with some default settings:

```{r EventStudyPlot example 1, fig.dim = c(7, 5)}
eventstudy_estimates_ols <- EventStudy(estimator = "OLS",
                                       data = example_data,
                                       outcomevar = "y_jump_m",
                                       policyvar = "z",
                                       idvar = "id",
                                       timevar = "t",
                                       post = 3,
                                       pre = 0)
 
EventStudyPlot(estimates = eventstudy_estimates_ols,
               xtitle = "Event time",
               ytitle = "Coefficient")
```

## References

Freyaldenhoven, S., Hansen, C., Pérez, J.P. and Shapiro, J.M., 2021. Visualization, identification, and estimation in the linear panel event-study design (No. w29170). National Bureau of Economic Research.