CRATES
Crypto & Cross‑Asset Event Study Toolkit — Cross‑Asset Event Study Analysis Repository
Install / Use
/learn @DocAMYMEI/CRATESREADME
CRATES — Crypto & Cross‑Asset Event Study Toolkit — Cross‑Asset Event Study Analysis Repository
CRATES is an end‑to‑end, research‑grade event‑study laboratory for cross‑asset markets. It couples Cumulative Abnormal Return (CAR) pipelines with batched Regression Discontinuity (RD) analysis and ships a full notebook gallery for high‑impact visual communication.
Designed for analysts who want journal‑quality statistics without sacrificing engineering rigour.
🎞️ Quick Preview
Open the sample/ folder to instantly see what CRATES produces — PNG heatmaps, interactive HTML dashboards, and nicely‑formatted XLSX reports.
✨ Key Features
- Full Stack – From raw OHLCV to Excel workbooks, high‑res figures, and interactive dashboards.
- Multi‑asset – Crypto, equities, indices and commodities handled identically.
- Modular – Nine CAR visual modules (V1‑9) plus three advanced (VA1‑3); separate RD tracks for price and volume.
- Reproducible – Version‑pinned environment, deterministic outputs, 100% tested core maths.
- Transparent – Every cell is annotated; parameters surfaced via YAML for easy what‑if runs.
🗂️ Repository Layout
crates/
├── benchmark/ # fixed benchmarks: Gold.csv, Nasdaq100.csv, SPY.csv
├── crypto_data/ # swappable crypto assets (same column schema)
├── events/ # event calendars: training_set.csv, test_set.csv
├── outcome/ # autogenerated CSV/XLSX/HTML (git‑ignored)
├── sample/ # PNG snapshots of analysis outputs
├── CAR_main.ipynb
├── CAR_V1-2_High-Level Impact & Screening.ipynb
├── CAR_V3-4_Distribution & Risk Analysis.ipynb
├── CAR_V5-7_Temporal Dynamics Analysis.ipynb
├── CAR_V8-9_Model Robustness & Diagnostics.ipynb
├── CAR_VA1-3_Advanced Techniques & Presentation Methods.ipynb
├── RDD_Price.ipynb
├── RDD_Price to excel.ipynb
├── RDD_Vol..ipynb
├── RDD_Vol. to excel.ipynb
├── requirements.txt
├── LICENSE # CC BY‑NC‑SA 4.0
└── README.md # you are here
📊 Visual Gallery
<!-- Category 1 ------------------------------------------------------------ -->Category 1 · High-Level Impact & Screening
Goal: Provide a birds-eye view of which assets and event groups matter most.
<div align="center"> <img src="sample/sampleV1%EF%BC%9AEvent%20Impact%20Overview%20for%20All%20Windows.png" alt="Event Impact Overview" width="720"/> <br/> <img src="sample/sampleV2.1%EF%BC%9ASignificance%20Heatmaps%20for%20All%20Windows.png" alt="Heat-map (-1,+1)" width="320"/> <img src="sample/sampleV2.2%EF%BC%9ASignificance%20Heatmaps%20for%20All%20Windows.png" alt="Heat-map (-5,+5)" width="320"/> <img src="sample/sampleV2.3%EF%BC%9ASignificance%20Heatmaps%20for%20All%20Windows.png" alt="Heat-map (-10,+10)" width="320"/> </div><!-- Category 2 ------------------------------------------------------------ -->
Category 2 · Distribution & Risk Analysis
Goal: Understand full CAR distribution and risk asymmetry.
<div align="center"> <img src="sample/sampleV3%EF%BC%9ACAR%20Distribution%20across%20All%20Windows.png" alt="CAR Distribution" width="720"/> <br/> <img src="sample/sampleV4%EF%BC%9ACumulative%20Distribution%20Function%20%28CDF%29%20Plot.png" alt="CAR CDF" width="450"/> </div><!-- Category 3 ------------------------------------------------------------ -->
Category 3 · Temporal Dynamics Analysis
Goal: Show how impact evolves over time and which days drive final CAR.
<div align="center"> <img src="sample/sampleV5%EF%BC%9AMean%20CAR%20Timeliness%20Analysis%20%28Point%20Plot%29.png" alt="Timeliness Analysis" width="720"/> <br/> <img src="sample/sampleV7%EF%BC%9ADaily%20Cumulative%20Abnormal%20Return%20%28CAR%29%20Trend.png" alt="Daily CAR Trend" width="350"/> <img src="sample/sampleV8%EF%BC%9ACAR%20Contribution%20Waterfall%20Chart.png" alt="CAR Waterfall" width="350"/> </div><!-- Category 4 ------------------------------------------------------------ -->
Category 4 · Model Robustness & Diagnostics
Goal: Verify findings across factor models and check model fit.
<div align="center"> <img src="sample/sampleV6%EF%BC%9AModel%20Robustness%20Check%20%28Grouped%20Bar%20Chart%29.png" alt="Model Robustness" width="350"/> <img src="sample/sampleV9%EF%BC%9AModel%20Fit%20Diagnostic%20%28Scatter%20Plot%29.png" alt="Model Fit Diagnostic" width="350"/> </div><!-- Category 5 ------------------------------------------------------------ -->
Category 5 · Advanced Techniques & Presentation
Goal: High-density layouts and statistical annotation for pro reports.
<div align="center"> <img src="sample/sampleVA1%EF%BC%9AAdvanced%20Facet%20Grid.png" alt="Facet Grid" width="720"/> <br/> <img src="sample/sampleVA2%EF%BC%9ASignificance%20Annotation%20on%20a%20Bar%20Chart%20%28Corrected%29.png" alt="Annotated Bar" width="450"/> </div>All figures are produced automatically by CRATES notebooks (V1 – V9, VA1 – VA2).
📦 Data Folders Explained
| Folder | Initial State | Purpose | Notes |
| -------------- | -------------- | --------------------------------------------------------------------- | -------------------------------------- |
| benchmark/ | (empty) | Place benchmark assets such as Gold.csv, Nasdaq100.csv, SPY.csv | Must follow Bench CSV Format below |
| crypto_data/ | (empty) | Drop crypto (or equity) CSVs e.g. Bitcoin.csv, BNB.csv | Same 7‑column schema |
| events/ | (empty) | Store training_set.csv & test_set.csv event calendars | Two‑line multi‑column layout |
| outcome/ | Auto‑generated | Runtime artefacts: CAR tables, RD Excel, Plotly HTML | .gitignored |
| sample/ | Pre‑populated | PNG, HTML, XLSX that illustrate expected outputs | For instant visual reference |
Bench / Crypto CSV Format
Date,Price,Open,High,Low,Vol.,Change %
06/18/2025,3,411.00,3,405.20,3,418.90,3,389.05,85.86K,0.16%
06/17/2025,3,405.62,3,404.20,3,422.70,3,384.40,4.16K,-0.34%
Why do the numbers contain commas? The comma is a thousands separator widely used in financial terminals. When loading with pandas, use
pd.read_csv(path, thousands=',')to ensure values are parsed as numerics rather than strings. The same option applies to both benchmark and crypto files. csv Date,Price,Open,High,Low,Vol.,Change % 06/18/2025,3,411.00,3,405.20,3,418.90,3,389.05,85.86K,0.16% 06/17/2025,3,405.62,3,404.20,3,422.70,3,384.40,4.16K,-0.34%
#### Events CSV Format
```csv
internal_good,internal_neutral,internal_bad,external_good,external_neutral,external_bad
22/1/2021,18/4/2020,9/2/2021,3/11/2022,15/8/2022,9/2/2020
,1/7/2025,,,,7/12/2023
,,,,,26/6/2025
All dates are interpreted as DD/MM/YYYY; leave blank cells for non‑applicable categories.
--- | --- | --- | --- |
| benchmark/ | Fixed | Gold.csv, Nasdaq100.csv, SPY.csv | Do not replace — referenced in notebooks & tests |
| crypto_data/ | Flexible | Bitcoin.csv, BNB.csv, Dogecoin.csv, Ethereum.csv | May swap with any asset that follows the same column schema (see below) |
| events/ | Editable | training_set.csv, test_set.csv | Update event dates here; notebooks read directly |
| outcome/ | Auto | Runtime artefacts: CAR tables, RD Excel, Plotly HTML | Path is .gitignored by default |
| sample/ | Reference | PNG figures illustrating expected outputs | Safe to prune if repo size matters |
🛠️ Core Dependencies
All required packages are declared in requirements.txt (auto‑generated via pip‑compile). Key libraries:
| Category | Package(s) | Notes |
| -------------------------------------- | ----------------------------------------- | ----------------------------------------- |
| Data processing & scientific computing | pandas, numpy, scipy, statsmodels | Event‑study math + regressions |
| Visualisation | matplotlib, seaborn, plotly | Static + interactive charts |
| Specialised charts | waterfallcharts | Waterfall diagnostics (V8‑9) |
| Excel export | XlsxWriter | High‑fidelity XLSX tables with formatting |
| Notebook environment | jupyterlab | Recommended IDE (≥ 4.0) |
You can inspect or modify version pins directly in requirements.txt.
🚀 Quick Start
# clone + env
git clone https://github.com/DocAMYMEI/crates.git
cd crates && python -m venv .venv && source .venv/bin/activate
# install deps
pip install -r requirements.txt
# run master notebook
jupyter lab CAR_main.ipynb
Data required. The notebooks assume you have already placed properly‑formatted CSVs into benchmark/ and crypto_data/, and populated events/ with the event calendars.
We do not ship data nor auto‑fetch from public APIs. Obtain prices from your licensed market data terminal (e.g. Bloomberg, Wind, Refinitiv) and ensure the schema matches the examples below before running any analysis.
bash
🧪 Methodology Snapshot
1. Cumulative Abnormal Return (CAR)
Three models: Market, Market‑Adjusted, Historical Average.
Estimation window default [-200, -2] trading days; event windows configurable (e.g. (-1,+1), (-5,+5), (-10,+10)).
2. Regression Discontinuity (RD)
Kernel‑weighted local linear regression (Imbens‑Kalyanaram
