# ExxonMobil event-study replication kit

Self-contained reproduction of the ExxonMobil announcement-day analysis on
the SMU CGI Reincorporation Tracker. Designed so an independent reviewer
with **only daily closing prices** and **five to ten minutes** in Python, R,
or Stata can verify the published numbers from first principles.

**No WRDS subscription, no CRSP access, no proprietary data needed.**
Everything required is in this folder.

---

## What you can do with this kit

Three users, three workflows. Pick the one that fits.

### Academic / journal reviewer

> *I want to verify the methodology survives peer review.*

Run the **Stata** version — it includes the full battery: five
specifications, Patell-z, Corrado rank test, TOST equivalence at +/- 2 pp,
and the placebo permutation distribution. Cross-check the output against
`expected_results.json`; flag any specification that exceeds the tolerance
bands documented below. If everything passes, the methodology has cleared
an independent reproducibility check at the level top-three finance journals
expect.

### Practitioner (corporate counsel, GC, institutional investor)

> *I want to know whether the headline number is robust enough to act on.*

Open `day0_car_table.csv` — it has the five specifications and their day-0
abnormal returns in one compact table. Run **Python** if you want to
confirm on your own machine; it takes five minutes and produces
`output.json`. The headline is the oil-augmented day-0 AR of -2.19% with
Patell p = 0.0488 (significant at 5%). Three of the four other
specifications fail to reject the null. Read the methodology in section 3
below for what this means in practice.

### Educated layman (journalist, board member, policy staff)

> *I just want to understand what's being claimed and how confident the
> analysis is.*

Open the firm page at
https://reincorporation-tracker.netlify.app/firms/XOM and click any
specification row in the announcement-window table. The modal that pops up
has both a plain-English explanation (with analogies) and the underlying
formula. The key claim: when you account for ExxonMobil's normal co-movement
with oil prices, its stock fell more on announcement day than the energy
sector did overall — a roughly 2 percentage-point gap that is statistically
distinguishable from random noise at the 5% level. The other specifications,
which don't account for oil, are inconclusive.

---

## What's in the box

| File | Format | Size | What it is |
|---|---|---|---|
| `daily_closes.csv` | CSV | ~400 KB | Daily closing prices for XOM + 21 energy peers + SPY + BNO from June 2023 through April 2026 (713 trading days). The only raw input. |
| `day0_car_table.csv` | CSV | <1 KB | Compact five-row summary: one row per specification, columns for Day-0 AR, p-value, R-squared. |
| `full_results.json` | JSON | ~2 KB | Complete machine-readable output — every estimate, p-value, donor weight, robustness diagnostic. |
| `expected_results.json` | JSON | ~2 KB | The published v1.4 numbers, frozen. Diff your replication against this. |
| `replicate_xom.py` | Python | ~11 KB | Python replication. pandas + numpy + scipy. ~200 lines. |
| `replicate_xom.R` | R | ~7 KB | R port using quadprog for the synthetic-control simplex problem. |
| `event_study_replication.do` | Stata | ~17 KB | Stata replication — most comprehensive. Includes TOST and placebo permutation. |
| `requirements.txt` | text | small | Pinned Python dependencies. |
| `README.md` | Markdown | ~6 KB | This file. |

---

## Quick start

### Python (5 minutes)

```bash
pip install -r requirements.txt
python replicate_xom.py
# compare your output against the reference
diff <(python -m json.tool output.json) <(python -m json.tool expected_results.json)
```

### R (5 minutes)

```r
install.packages(c("readr", "dplyr", "jsonlite", "lubridate", "quadprog"))
Rscript replicate_xom.R
# compare output_R.json against expected_results.json
```

### Stata (10 minutes)

```stata
ssc install synth
ssc install mat2txt
ssc install estout

do event_study_replication.do
```

The Stata version produces `event_study_replication.log` with every
estimate, the placebo permutation distribution, and the TOST equivalence
result. It is the most thorough of the three.

---

## Tolerance rules

A replication is **PASS** if every quantity falls within these bands of the
reference output. Anything outside is a **finding** worth reporting.

| Statistic | Tolerance | Why |
|---|---|---|
| Point estimates (CARs, BHARs, day-0 ARs) | +/- 0.5 percentage points | Reflects rounding + estimator sensitivity to numerical optimizer choice |
| P-values | +/- 0.05 | Reflects bootstrap-iteration noise and permutation seed |
| R-squared values | +/- 0.01 | Reflects floating-point precision |
| Synthetic-control donor weights | +/- 0.05 (5 pp) | SLSQP / quadprog may converge to slightly different local optima on the simplex |

If your value exceeds the band, that is a real finding. Document the
specification, your replicated value, the published value, your environment
(Pyth