Volatility Surface (V1)

Minimal instructions to fetch option data, compute implied vols, and plot smiles + a 3D IV surface.

---

Code structure

scripts/
  fetch_raw.py        # download raw calls/puts + spot + tenors
  clean_processed.py  # filters, compute T/F/k → clean.csv
  compute_iv.py       # OTM-only price + IV inversion → iv.csv
  plot_v1.py          # per-expiry smiles + 3D IV surface
src/
  config.py           # load_config() from config.yaml
  dataio.py           # yfinance helpers, expiry→T
  clean.py            # clean_to_processed()
  bs.py               # Black–Scholes price + vega
  iv.py               # implied_vol() hybrid solver
  plotting.py         # plot_smiles(), plot_iv_surface()

---

Setup & run

cd ~/.../vol-surface-localvol
source .venv/bin/activate   # ensure env is active

# 1) fetch raw option chains + spot
python -m scripts.fetch_raw

# 2) clean/enrich to clean.csv
python -m scripts.clean_processed

# 3) compute implied vols to iv.csv
python -m scripts.compute_iv

# 4) plot smiles + IV surface
python -m scripts.plot_v1

Outputs:

• data/raw/<ASOF>/ — raw CSVs (calls_*.csv, puts_*.csv), tenors.csv, spot.txt
• data/processed/<ASOF>/clean.csv — filtered quotes with T/F/k
• data/processed/<ASOF>/iv.csv — one OTM-normalized call per strike with iv
• docs/figures/ — smile_<EXPIRY_YYYYMMDD>.png, iv_surface_<ASOF_YYYYMMDD>.png

---

What it does

1. Fetch raw calls/puts for several expiries (Yahoo Finance).
2. Clean quotes and compute time-to-maturity T, forward F = S·e^{(r−q)T}, and log‑moneyness k = ln(K/F).
3. Build OTM-only call prices (use call for k≥0, put→call via parity for k<0) and invert IV with Black–Scholes.
4. Plot per‑expiry smiles (iv vs k) and a 3D IV surface over (k, T).

---

Figures (example)

Your file names will match today’s date/expiries. Replace the example paths below with the ones in docs/figures/ if needed.

Per‑expiry smile (example):

3D IV surface (example):

---