---
title: "Getting Started with rdstagger"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with rdstagger}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

`rdstagger` implements a unified framework that combines three identification
strategies simultaneously:

1. **Regression Discontinuity (RD)** — treatment assignment by running variable cutoff
2. **Staggered DiD** — heterogeneous treatment adoption timing across cohorts
3. **Network Interference** — spillover effects through a known network

This vignette walks through a complete analysis using simulated data.

## Installation

```{r eval = FALSE}
# CRAN
install.packages("rdstagger")

# GitHub (development)
remotes::install_github("causalfragility-lab/rdstagger")
```

## Step 1: Simulate Data

```{r}
library(rdstagger)

set.seed(42)
sim <- sim_rdstagger(
  n               = 400,
  nperiods        = 8,
  n_cohorts       = 3,
  cutoff          = 0,
  bw              = 1,
  network_density = 0.08,
  true_direct     = 0.30,
  true_spill      = 0.10,
  outcome_type    = "continuous"
)

head(sim$data)
sim$true_params
```

The data contains:

- `id` — unit identifier
- `period` — calendar time
- `y` — outcome
- `x` — running variable (treatment assigned when `x < 0`)
- `g` — cohort (first treated period; `Inf` = never treated)
- `treated` — treatment indicator
- `neighbor_treated` — whether any network neighbor is treated
- `spillover_share` — share of neighbors treated

## Step 2: Estimate ATT(g,t)

```{r}
res <- rdstagger_attgt(
  data    = sim$data,
  yname   = "y",
  xname   = "x",
  cutoff  = 0,
  gname   = "g",
  tname   = "period",
  idname  = "id",
  network = sim$network,
  bw      = 1.5,
  boot    = FALSE        # set TRUE for inference
)

print(res)
```

## Step 3: Pre-Treatment Falsification Test

```{r}
pt <- rdstagger_pretest(res, method = "both")
print(pt)
```

A p-value above 0.05 in the joint test indicates no evidence of
pre-treatment trends — a necessary condition for the parallel trends
assumption within the bandwidth.

## Step 4: Aggregate into Event Study

```{r}
agg <- rdstagger_agg(res, type = "dynamic")
print(agg)
plot(agg)
```

The event study plot shows ATT estimates relative to treatment adoption.
Pre-treatment estimates (event time < 0) should be close to zero.

## Step 5: Cohort-Level Aggregation

```{r}
agg_group <- rdstagger_agg(res, type = "group")
print(agg_group)
```

## Step 6: Spillover Estimates

Spillover estimates are stored in `res$spillgt`:

```{r}
if (!is.null(res$spillgt)) {
  head(res$spillgt)
}
```

## Bandwidth Selection

Optimal bandwidth can be selected automatically:

```{r eval = FALSE}
bw_sel <- rdstagger_bw(
  data   = sim$data,
  yname  = "y",
  xname  = "x",
  cutoff = 0,
  gname  = "g",
  tname  = "period"
)
bw_sel$bw_common
```

## References

Callaway, B., & Sant'Anna, P. H. C. (2021). Difference-in-differences
with multiple time periods. *Journal of Econometrics*, 225(2), 200–230.

Calonico, S., Cattaneo, M. D., & Titiunik, R. (2014). Robust nonparametric
confidence intervals for regression-discontinuity designs.
*Econometrica*, 82(6), 2295–2326.

Manski, C. F. (2013). Identification of treatment response with social
interactions. *The Econometrics Journal*, 16(1), S1–S23.
