That one question — implied vs realized volatility — is what VolScope is built around. Type any ticker and its hero chart answers it at a glance, wrapped in the context a vol desk reads: IV rank, a volatility cone, a time-travelling term structure, 25Δ skew, and a plain-English verdict — all from VolScope's own Black-Scholes solver (never Yahoo's IV). The volatility screen you'd otherwise rent from Bloomberg, self-hosted in a browser tab.
This is what VolScope is. Everything else exists to add context to it.
vol % AAPL · IMPLIED vs REALIZED
▲
│ ╭──╮ ← IV 30d (what options cost)
│ ╭─────╯ ╰────╮ ╭────
│ ─────╯ · · · · · ╰──────╯· · ← HV 20d (what the stock did)
│ ░░░░░░ ▒▒▒▒▒▒▒▒ ░░░░░ ▓▓▓ ← background shaded by vol regime
└────────────────────────────────► time ◆ = earnings
IV above HV → options RICH · IV below HV → options CHEAP
When the implied-vol line (what options are charging) sits above realized vol (what the stock has actually moved), the market is paying up for movement — options are rich. When it dips below, they're cheap. The background is shaded by volatility regime, earnings dates are flagged, and a one-line verdict sits above it. It is the first, largest chart on the Scope page — front and centre, because it is the product.
A retail options trader's single hardest question — is this option cheap or expensive right now? — normally takes a Bloomberg terminal or a pile of spreadsheets. VolScope answers it in one glance, for any ticker, on your own machine. What makes it strong:
- 🧮 Its own math, not Yahoo's. Every implied vol is recomputed from the bid/ask mid with VolScope's Black-Scholes-Merton Newton-Raphson solver — never Yahoo's opaque, rate-limited IV column. Historical vol is Yang-Zhang (drift-independent, gap-aware). The numbers are yours and they are honest.
- 📊 The views a vol desk actually reads. IV rank & percentile (with a spike-contamination guard), a volatility cone across horizons, a term structure that time-travels (−7d/−30d ghost curves show shift vs twist vs flatten), 25Δ skew with its own percentile rank, regime-shaded IV history, and expected-move cards — IV-implied vs HV-implied.
- 🗣️ It speaks plain English. A one-line verdict sits above the fold on every ticker: "AAPL IV is in the 12th percentile — historically cheap; earnings in 9 days." No jargon decoding required.
- ⚡ Fast and self-hosted. Embedded DuckDB + Streamlit, sub-second navigation after the first load. No account, no subscription, no data leaving your machine.
- 🔬 Rigorous by construction. Put-call parity holds to 1e-6, every estimator is property-tested, and analytics never crash the UI — bad input returns nothing, not an exception.
macOS / Linux, Python 3.11+. Three lines — the last one does everything:
git clone https://github.com/SchoenTom/volscope.git && cd volscope
python3 -m venv .venv && source .venv/bin/activate
make quickstartmake quickstart is self-contained: it installs every dependency,
creates a read-only .env (API keys are optional), seeds a 2-ticker
starter universe (SPY + QQQ, or your existing watchlist), and opens the
app at http://localhost:8501. Grow the universe from the sidebar's
add-ticker form or Watchlist → 📥 Import (paste a TradingView export).
Bigger initial seeds:
| Target | Tickers | Time |
|---|---|---|
make quickstart (default) |
SPY + QQQ, or your watchlist | ~2 min |
make quickstart-bot |
~75 | ~4 min |
make seed-broad |
~280 | ~10 min |
make quickstart-full |
~842 | ~30-45 min |
Daily afterwards: make start (refresh today's data + launch) or just
make run (launch on existing data).
RESEARCH
- Discover — universe-wide opportunity ranker: which names have the cheapest / richest IV right now, plus today's biggest movers and crowded extremes.
- Scope — the hero single-ticker view: a one-line plain-English verdict, IV vs HV, full term structure (with −7d/−30d ghost curves), a volatility cone, 25Δ skew, 52-week IV range, and regime-shaded history.
- Heatmap — sector × IV-percentile treemap of the whole universe.
- Earnings Hub — weekly grid of implied moves, crowdedness, and IV-crush calibration around earnings.
- Vol Insights — skew-adjusted expected move, front/back IV decomposition, OI heatmap with max-pain.
- Scanner — filter the universe by IV rank / percentile / spread.
- Alerts — watchlist-scoped or universe-wide threshold trips (anomaly, flow, regime, earnings).
MANAGE
- Watchlist — TradingView-style groupings, live spot + 1-day %Δ, per-list alarm configuration.
- Command — a market-overview dashboard plus a manual trade journal ("was vol cheap when I entered?").
- Options Lab — BSM-priced payoff + Greeks surfaces, scenario matrix, time decay, probability cone, IV-slider driven.
yfinance / FRED ──► daily scrape ──► DuckDB ──► analytics ──► Streamlit UI
(prices, chains, (own BSM IV (embedded, (BSM, Yang-Zhang, (10 focused
risk-free rate) per strike) local) cones, regime) research views)
A single daily scrape recomputes IV from option-chain mids with VolScope's own solver and writes a tidy snapshot to an embedded DuckDB. Every page reads from that DB and the shared analytics layer — one BSM solver, one HV estimator, one source of truth, all running locally.
VolScope's analytics rest on published, citable methods — and ship with golden-master tests that pin them to the textbook values:
- Hull (2018), Options, Futures, and Other Derivatives — Black-Scholes worked examples (validation goldens).
- Yang & Zhang (2000) — drift-independent historical-vol estimator.
- Bali et al. (2008) — volatility-risk-premium magnitudes.
- tastytrade Market Measures — IV-rank / percentile decision thresholds.
PRs welcome — Conventional Commits, pre-commit hooks, tests green
(make pre-merge-check). See CONTRIBUTING.md.
MIT — see LICENSE. VolScope is research / educational software:
it computes and visualises volatility and is not investment advice.