---
title: "Introduction to fixes"
author: "Yosuke Abe"
date: "`r Sys.setlocale('LC_TIME', 'C'); format(Sys.Date(), '%B %d, %Y')`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to fixes}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE,
  message = FALSE,
  fig.width = 7,
  fig.height = 5,
  dpi = 150
)

# Load the development version of the package
library(fixes)
library(dplyr)
library(ggplot2)
```

## Introduction

The **fixes** package provides an easy-to-use toolkit for creating, estimating, and visualizing event study models using fixed effects regression. With **fixes**, you can automatically generate lead and lag dummy variables, flexibly estimate fixed effects event study regressions, and visualize the results with `ggplot2` using a single pipeline.

This vignette introduces the core functions of the package through simple examples, including recent updates such as multiple confidence interval support and improved plotting options.

## Installation

Install the released version from CRAN:

```r
install.packages("fixes")
```

Or with **pak** (recommended for fast install):

```r
pak::pak("fixes")
```

To install the latest development version from GitHub:

```r
pak::pak("yo5uke/fixes")
```

or

```r
devtools::install_github("yo5uke/fixes")
```

## Minimal Example

Below is a basic example using the built-in `fixest::base_did` dataset, running an event study, and visualizing the results.

```{r minimal-example}
# Load example data
df <- fixest::base_did

# Run the event study (supports multiple confidence levels)
event_study <- run_es(
  data       = df,
  outcome    = y,
  treatment  = treat,
  time       = period,
  timing     = 5,  # Treatment occurs at period 5
  fe         = ~ id + period,
  cluster    = ~ id,
  baseline   = -1,
  interval   = 1,
  lead_range = 3,
  lag_range  = 3,
  conf.level = c(0.90, 0.95, 0.99)  # Multiple CIs supported!
)

# View results
head(event_study)
```

## Visualizing Event Study Results

The **fixes** package provides `plot_es()` for flexible visualization. You can easily switch between ribbon-style or error bar CIs, select the displayed CI level, and customize appearance.

```{r plot-basic}
# Basic plot (default: ribbon, 95% CI)
plot_es(event_study)
```

```{r plot-errorbar}
# Plot with error bars and 99% CI
plot_es(event_study, type = "errorbar", ci_level = 0.99)
```

```{r plot-custom}
# Customize further with ggplot2
plot_es(event_study, type = "errorbar", ci_level = 0.9, theme_style = "classic") +
  scale_x_continuous(breaks = seq(-3, 3, by = 1)) +
  ggtitle("Event Study with 90% CI and Classic Theme")
```

## Staggered Treatment with `sunab`

For staggered adoption designs where treatment timing varies across units, you can use `method = "sunab"` to implement the Sun & Abraham (2021) estimator, which is robust to heterogeneous treatment effects.

```{r sunab-example}
# Example with fixest::base_stagg data
df_stagg <- fixest::base_stagg

event_study_sunab <- run_es(
  data       = df_stagg,
  outcome    = y,
  treatment  = treated,
  time       = year,
  timing     = year_treated,
  fe         = ~ id + year,
  staggered  = TRUE,
  method     = "sunab",  # Use Sun & Abraham decomposition
  lead_range = 3,
  lag_range  = 3,
  cluster    = ~ id
)

head(event_study_sunab)
```

```{r plot-sunab}
# Visualize sunab results
plot_es(event_study_sunab) +
  ggtitle("Staggered Adoption Event Study (Sun & Abraham 2021)")
```

**New in v0.7.1:** The `baseline` parameter now applies to both `classic` and `sunab` methods, and the baseline period is included in results with zero estimates for consistent visualization.

## Package Highlights

- **`run_es()`**:
    - Fast, one-step event study for panel data.
    - Automatic creation of lead/lag dummies relative to treatment.
    - Supports both classic and staggered timing, covariates, clustering, weights, and flexible baseline normalization.
    - Choice of estimation methods: `classic` (factor expansion) or `sunab` (Sun & Abraham 2021 for staggered designs).
    - Multiple confidence interval levels supported (e.g., 90%, 95%, 99%).
    - Handles irregular time panels via `time_transform`.
    - Results are filtered to specified `lead_range` and `lag_range` (v0.7.1+).

- **`plot_es()`**:
    - Intuitive event study plot with ribbon or errorbar CI display.
    - CI level and visual style are fully customizable.
    - ggplot2-based for further modification.

- **`plot_es_interactive()`** (v0.7.0+):
    - Interactive plotly-based visualizations with hover tooltips.
    - Displays point estimates, confidence intervals, standard errors, and p-values on hover.

## Conclusion

The **fixes** package streamlines event study estimation and visualization for panel data researchers. With a minimal API, multiple CI support, and robust visualization, it accelerates the workflow for dynamic treatment effect analysis.

For further details and full argument documentation, see:

```r
?run_es
?plot_es
```

Happy analyzing!🥂