# documentation

    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). 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 for Freyaldenhoven et al. (2021). The documentation can be accessed using `?example_data`.

    dim(example_data)
    #> [1] 2000   12

    head(example_data)
    #> # A tibble: 6 × 12
    #>      id eventtime     t     z y_base eta_m y_jump_m y_smooth_m x_jump_m eta_r
    #>   <dbl>     <dbl> <dbl> <dbl>  <dbl> <dbl>    <dbl>      <dbl>    <dbl> <dbl>
    #> 1     1        32     1     0 -0.609 0.180     41.6       41.6   0.684      1
    #> 2     1        32     2     0 -0.870 0.180     41.3       41.3   0.0167     1
    #> 3     1        32     3     0 -0.906 0.180     41.3       41.3   0.153      1
    #> 4     1        32     4     0  0.148 0.180     42.3       42.3  -0.930      1
    #> 5     1        32     5     0  0.579 0.180     42.8       42.8  -0.316      1
    #> 6     1        32     6     0 -0.340 0.180     41.8       41.8   1.69       1
    #> # ℹ 2 more variables: y_r <dbl>, x_r <dbl>

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

    results <- EventStudy(estimator = "OLS",
                          data = example_data,
                          outcomevar = "y_jump_m",
                          policyvar = "z",
                          idvar = "id",
                          timevar = "t",
                          post = 3, pre = 0,
                          kernel = "fixest")

    #> NOTE: 350 observations removed because of NA values (RHS: 350).

    summary(results$output)
    #> OLS estimation, Dep. Var.: y_jump_m
    #> Observations: 1,650
    #> Fixed-effects: id: 50,  t: 33
    #> Standard-errors: Clustered (id)
    #>            Estimate Std. Error  t value   Pr(>|t|)
    #> z_lead3    0.239047   0.143291 1.668259 1.0164e-01
    #> z_fd_lead3 0.175241   0.161829 1.082876 2.8416e-01
    #> z_fd_lead2 0.123848   0.174806 0.708486 4.8200e-01
    #> z_fd       0.830860   0.133247 6.235477 1.0137e-07 ***
    #> z_fd_lag1  0.855168   0.176619 4.841873 1.3276e-05 ***
    #> z_fd_lag2  0.632607   0.153833 4.112303 1.4907e-04 ***
    #> z_fd_lag3  0.246352   0.182958 1.346493 1.8434e-01
    #> z_lag4     0.142752   0.126989 1.124128 2.6644e-01
    #> ---
    #> Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
    #> RMSE: 0.694438     Adj. R2: 0.055505
    #>                  Within R2: 0.053267

Click for `results$arguments`

      ## Estimator
      results$arguments$estimator
      #> [1] "OLS"

      ## Data
      results$arguments$data[1:5,]
      #>       id eventtime     t     z     y_base eta_m y_jump_m y_smooth_m    x_jump_m
      #>    <num>     <num> <num> <num>      <num> <num>    <num>      <num>       <num>
      #> 1:     1        32     1     0 -0.6087238  0.18 41.57128   41.57128  0.68367314
      #> 2:     1        32     2     0 -0.8699341  0.18 41.31007   41.31007  0.01667022
      #> 3:     1        32     3     0 -0.9059790  0.18 41.27402   41.27402  0.15259252
      #> 4:     1        32     4     0  0.1482184  0.18 42.32822   42.32822 -0.93015540
      #> 5:     1        32     5     0  0.5785761  0.18 42.75858   42.75858 -0.31635490
      #>    eta_r      y_r       x_r  z_fd z_fd_lag1 z_fd_lag2 z_fd_lag3 z_fd_lead3
      #>    <num>    <num>     <num> <num>     <num>     <num>     <num>      <num>
      #> 1:     1 1.891276 0.5520976    NA        NA        NA        NA          0
      #> 2:     1 1.630066 2.3021448     0        NA        NA        NA          0
      #> 3:     1 1.594021 1.0289093     0         0        NA        NA          0
      #> 4:     1 2.648218 0.2615794     0         0         0        NA          0
      #> 5:     1 3.078576 1.2146608     0         0         0         0          0
      #>    z_fd_lead2 z_fd_lead1 z_lag4 z_lead3
      #>         <num>      <num>  <num>   <num>
      #> 1:          0          0     NA       1
      #> 2:          0          0     NA       1
      #> 3:          0          0     NA       1
      #> 4:          0          0     NA       1
      #> 5:          0          0      0       1

      ## Variables
      results$arguments$outcomevar
      #> [1] "y_jump_m"

      results$arguments$outcomevar
      #> [1] "y_jump_m"

      results$arguments$policyvar
      #> [1] "z"

      results$arguments$idvar
      #> [1] "id"

      results$arguments$timevar
      #> [1] "t"

      results$arguments$controls
      #> NULL

      ## Proxies
      results$arguments$proxy
      #> NULL

      results$arguments$proxyIV
      #> NULL

      ## Fixed effects
      results$arguments$FE
      #> [1] TRUE

      results$arguments$TFE
      #> [1] TRUE

      ## Periods
      results$arguments$post
      #> [1] 3

      results$arguments$overidpost
      #> [1] 1

      results$arguments$pre
      #> [1] 0

      results$arguments$overidpre
      #> [1] 3

      ## Normalization
      results$arguments$normalize
      #> [1] -1

      results$arguments$normalization_column
      #> [1] "z_fd_lead1"

      ## Cluster
      results$arguments$cluster
      #> [1] TRUE

      ## Eventstudy coefficients
      results$arguments$eventstudy_coefficients
      #> [1] "z_lead3"    "z_fd_lead3" "z_fd_lead2" "z_fd"       "z_fd_lag1"
      #> [6] "z_fd_lag2"  "z_fd_lag3"  "z_lag4"

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

    eventstudy_estimates_ols <- EventStudy(estimator = "OLS",
                                           data = example_data,
                                           outcomevar = "y_jump_m",
                                           policyvar = "z",
                                           idvar = "id",
                                           timevar = "t",
                                           post = 3, pre = 0,
                                           kernel = "fixest")
    #> NOTE: 350 observations removed because of NA values (RHS: 350).

    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.