derivatives

Python library for equity derivatives pricing and risk analytics: GARCH volatility estimation, Black–Scholes pricing, Greeks, and implied-volatility surface construction. Part of the QFIN workspace alongside fixed-income, equity, and risk.

Roadmap

Capabilities (target)

Install

python3 -m pip install -e .

Optional extras:

python3 -m pip install -e '.[data]'      # datasets[data], requests, pandas, python-dotenv
python3 -m pip install -e '.[models]'    # arch (GARCH)
python3 -m pip install -e '.[viz]'       # plotly, dash, matplotlib, …
python3 -m pip install -e '.[tableau]'   # pyarrow, pantab
python3 -m pip install -e '.[dev]'       # pytest, ruff, build
python3 -m pip install -e '.[dev,data,models,viz,tableau]'

Quickstart

Runnable end-to-end script (from repo root, with .env set):

conda activate fixed_income   # or your env with derivatives installed
cd derivatives
python3 -m pip install -e '.[data,models,viz,tableau]'

python3 scripts/quickstart.py                    # full pipeline (~12 API calls)
python3 scripts/quickstart.py --skip-options     # stock + treasury only (~2 calls)
python3 scripts/quickstart.py --serve            # + Dash risk monitor

from datetime import date
from derivatives.data import (
    CachedDataSource,
    MassiveStockHistorySource,
    MassiveTreasuryYieldsSource,
    load_project_dotenv,
)

load_project_dotenv()
stock = CachedDataSource(MassiveStockHistorySource("SPY")).fetch(as_of=date.today())
treasury = CachedDataSource(MassiveTreasuryYieldsSource()).fetch(as_of=date.today())
print(stock.spot(), treasury.latest_point().yield_10_year)

Price a chain with GARCH + Black–Scholes:

from derivatives import price_option_chain
from derivatives.data import MassiveOptionChainSource

chain = MassiveOptionChainSource("SPY", max_contracts=20).fetch(as_of=date.today())
result = price_option_chain(chain, stock, treasury)
print(result.garch_sigma, len(result.surface.points))

Ingest to Parquet:

python3 scripts/ingest_market_data.py --as-of 2026-06-06 --underlying SPY --skip-options

Dash risk monitor

from derivatives.dashboards import create_risk_monitor_app

app = create_risk_monitor_app(result, chain, stock)
app.run(debug=True)

Tableau export

from derivatives.dashboards import export_tableau_bundle

export_tableau_bundle(result, chain, stock)
# → data/processed/{as_of}/tableau/*.hyper and *.csv

Project layout

derivatives/
├── derivatives/          # Python package
│   ├── data/             # DataSource adapters, cache, types
│   ├── models/           # GARCH, Black–Scholes, IV surface
│   ├── charts/           # Plotly figures
│   └── dashboards/       # Dash apps + Tableau exports
├── data/
│   ├── raw/              # Manual CSV fallbacks (gitignored)
│   └── processed/        # Parquet snapshots (gitignored)
├── scripts/              # ingest_market_data.py, build scripts
├── tests/
├── docs/
└── examples/             # Jupyter notebooks (Phase IV)

Development

bash scripts/build_test.sh

Data access details: docs/data_access.md.