/event-study-cars

name: event-study-cars
description: >-
  Complete methodology for computing publication-quality cumulative abnormal returns with
  proper event-study test statistics, matching the robustness of Kaspereit's eventstudy2 for
  Stata. Covers dateline construction, event-date mapping, estimation and event windows,
  thin-trading adjustment, OLS with Theil prediction error correction, abnormal return
  computation, CAR/CAAR/AAR accumulation, boundary contamination guards, and common tests such
  as Patell, BMP, Kolari-Pynnonen, generalized sign, Wilcoxon, and GRANK-T. Use when the user
  mentions abnormal returns, event windows, market-model regressions, CARs, CAAR, AAR,
  eventstudy2, thin trading, trade-to-trade returns, or event-study test statistics.

Event Study: Cumulative Abnormal Returns (CARs)

A complete methodology reference for computing publication-quality CARs with robust test statistics, matching the rigor of Kaspereit's eventstudy2 (v3.2b) for Stata. This skill is **generic** — applicable to any market, asset class, or event type.

Use the shipped engine first (do not rewrite it)

`scripts/eventstudy.py` is a complete, runnable Python replication of eventstudy2, validated against the Stata package to floating-point precision (AR ~1e-8, CAR ~6e-8, CAAR and the implemented test statistics ~1e-7) on a generic CRSP sample across all four models (FM, COMEAN, MA, RAW). It is generic — all column names, the model, windows, thin-trading, and log handling are CLI flags. When a user wants CARs computed, **run this engine**; do not author a new pipeline.

python scripts/eventstudy.py --selftest          # synthetic self-check, no inputs
python scripts/eventstudy.py \
    --returns returns.csv --market market.csv --events events.csv \
    --id-col permno --ret-col ret --event-date-col event_date --mkt-col vwretd \
    --model FM --car-windows "-1,1;-5,5;-10,10" \
    --eswlb -250 --eswub -30 --evwlb -10 --evwub 10 --out-dir out/

Inputs are CSV/Parquet: returns (`id, date, ret`), market/factors (`date, mkt[, factors]`), events (`id, event_date`). Outputs: `ar_panel.csv`, `car_panel.csv`, `test_statistics.csv`. Requires numpy/pandas/scipy. Run `--help` for all flags (`--factor-cols smb,hml`, `--model MA`, `--no-thin-trading`, ...). The sections below document the methodology the engine implements; read them to audit, extend, or port it.

Methodology Overview: The 8-Step Pipeline

Step 1: Build Trading Calendar (Dateline)

Construct a master list of valid trading dates from the security returns file.

1. Collect all unique dates on which at least one security has a non-missing return (or, if using a factor model, dates where market/factor returns exist). 2. Count the number of securities with valid returns on each date. 3. Optionally drop weekends (`delweekend`). 4. Apply `dateline_threshold`: drop dates where the count of return observations falls below `threshold × mean(daily_count)`. A threshold of 0.2 works well for international samples with heterogeneous holidays. 5. The resulting date vector is the **dateline** — all downstream windows are defined in dateline time (relative trading days), not calendar time.

Step 2: Map Event Dates to Nearest Valid Trading Day

For each event: 1. Find the nearest dateline date **on or after** the event date. 2. If the shift exceeds `max_shift` calendar days (default: 3), **exclude** the event entirely — do not silently map it to a distant trading day. 3. Events with missing dates, or dates outside the dateline range, are also excluded and logged with the reason.

Step 3: Construct Estimation and Event Windows

For each firm-event pair, define windows in **relative trading time** (offsets from the event day on the dateline):

• **Estimation window**: `[esw_lb, esw_ub]` — default `[-250, -30]`.
• **Event window**: `[evw_lb, evw_ub]` — determined by the widest CAR window

requested.

• Enforce a **gap** between the estimation and event windows to prevent event

contamination of the benchmark model.

**Exclusion checks** (per firm-event):

• Insufficient estimation-window observations (fewer than `min_esw_obs`,

default 120).

• Insufficient event-window observations.
• **IPO/delisting guard**: if the stock's first observed return date falls

after `evw_lb` or last observed return date falls before `evw_ub`, exclude the firm-event. These are survivorship-biased observations.

Step 4: Apply Thin-Trading Adjustment

For markets with non-trivially thin trading (most markets outside US mega-caps), apply the Maynes-Rumsey (1993) trade-to-trade transformation **by default**.

> Read `references/thin_trading.md` for the complete transformation, including > the `cum_periods` construction, the regression specification with `nocons`, > and the boundary contamination guard.

**Summary**: Non-trading days accumulate into the next trading day's return. All variables (returns, factors, intercept) are divided by `sqrt(cum_periods)`. OLS is run with `nocons` because the intercept regressor `1/sqrt(d)` replaces the standard constant. This is a GLS correction for the heteroscedasticity introduced by multi-period returns.

Step 5: Run OLS and Compute STDF

For each firm-event pair, estimate the benchmark model over the estimation window and compute the **standard deviation of forecast** (STDF) for every observation (estimation + event window).

> Read `references/estimation_models.md` for model specifications (RAW, > COMEAN, MA, FM, BHAR).

**STDF** (Theil 1971 prediction error correction):

For each observation t, the forecast standard deviation is:

STDF_it = sigma_hat_i * sqrt(1 + x'_t (X'X)^{-1} x_t)

where `x_t` is the regressor vector at time t, `X` is the estimation-window design matrix, and `sigma_hat_i = sqrt(SSR / (T_i - 2 - df))` is the OLS residual standard deviation. `df` is the number of additional factors beyond the market (0 for market model, 2 for FF3, etc.).

The STDF accounts for bot