volatility-trading 0.3.0

Volatility trading research

Volatility Trading on Equity Options

This project develops and evaluates daily options-volatility strategies on index and single-stock underlyings. Research spans the full pipeline: data engineering and quality checks, implied-volatility surface modelling, volatility forecasting, and strategy backtesting. Backtests use realistic execution assumptions (bid/ask, slippage, commissions, position sizing, and risk limits) and are documented with reproducible notebooks and published reports.

Notebook reports (GitHub Pages): https://anthonymakarewicz.github.io/volatility-trading/

Quickstart

1. Clone the repository:

git clone https://github.com/anthonymakarewicz/volatility-trading.git
cd volatility_trading

2. Create a virtual environment (Python 3.12+):

python -m venv .venv
source .venv/bin/activate
pip install -U pip

3. Install dependencies:

Primary contributor setup (editable package + dev tooling):

pip install -e ".[dev]"

Secondary options:

• Runtime-only install (users running package code without dev tools):

pip install .

• Editable runtime-only install (local source edits, no dev tools):

pip install -e .

4. Set credentials (ORATS):

cp .env.example .env

Then set ORATS_API_KEY, ORATS_FTP_USER, and ORATS_FTP_PASS in .env.

ORATS ETL Pipeline (End-to-End)

Pipeline steps:

• API download
• API extract
• FTP download
• FTP extract
• Build options chain
• Build daily features
• QC options chain
• QC daily features

Use --dry-run to validate config, paths, and credentials before running writes/network.

orats-api-download --config config/orats/api_download.yml --dry-run

For the full command sequence, see Data pipeline.

Current Data Support Status

• Options ETL (options chain + daily features) is currently supported through the ORATS pipeline.
• External feed sync (fred-sync, yfinance-sync) currently covers rates/market time series, not a full generic options ETL path.
• The options backtesting runtime expects the current project options-chain schema (for example quotes/Greeks fields used by entry, sizing, and lifecycle).
• You can run backtests with non-ORATS data if it is pre-normalized to the expected schema.

Stability

• Current release line is 0.3.x (alpha / pre-1.0).
• Public APIs, data contracts, and configuration surfaces may evolve between minor versions.
• For reproducible research, pin exact package versions and review CHANGELOG.md before upgrading.
• Public vs internal boundaries are defined in API Scope.

Data Contract / Supported Inputs

Source	Input expected by backtester	Support status	Adapter path
ORATS ETL output	Canonical long-format options chain	First-class	CanonicalOptionsChainAdapter (or mode canonical)
OptionsDX ETL output	Cleaned long-format panel (reshape='long')	Supported	OptionsDxOptionsChainAdapter
Custom/vendor dataset	Long-format panel mapped to canonical fields	Supported with mapping	ColumnMapOptionsChainAdapter

Notes:

• Raw wide OptionsDX vendor format (c_* / p_*) is not accepted directly by the backtester.
• Contract details and adapter behavior: Options Data Adapters
• ORATS pipeline reference: Data Pipeline
• OptionsDX onboarding: OptionsDX Setup

Quick VRP Backtest Example

Assume you already prepared:

• options: long-format pandas options panel indexed by trade_date

1. Import strategy and backtesting types:

from volatility_trading.backtesting import (
    AccountConfig,
    BacktestRunConfig,
    BrokerConfig,
    ExecutionConfig,
    HedgeMarketData,
    MarginConfig,
    OptionsBacktestDataBundle,
    print_performance_report,
    to_daily_mtm,
)
from volatility_trading.backtesting.engine import Backtester
from volatility_trading.options import RegTMarginModel
from volatility_trading.signals import ShortOnlySignal
from volatility_trading.strategies import VRPHarvestingSpec, make_vrp_strategy

2. Build the backtest data bundle:

hedge_mid = options.groupby(level=0)["spot_price"].first().astype(float)
data = OptionsBacktestDataBundle(
    options=options,
    features=None,
    hedge_market=HedgeMarketData(mid=hedge_mid),
)

3. Define strategy spec and run configuration:

vrp_spec = VRPHarvestingSpec(
    signal=ShortOnlySignal(),
    rebalance_period=10,
    risk_budget_pct=0.03,
    margin_budget_pct=0.4,
)
strategy = make_vrp_strategy(vrp_spec)

cfg = BacktestRunConfig(
    account=AccountConfig(initial_capital=50_000),
    execution=ExecutionConfig(commission_per_leg=0.0),
    broker=BrokerConfig(
        margin=MarginConfig(model=RegTMarginModel(broad_index=False))
    ),
)

4. Run the backtest and compute daily MTM/performance metrics:

bt = Backtester(
    data=data,
    strategy=strategy,
    config=cfg,
)
trades, mtm = bt.run()
daily_mtm = to_daily_mtm(mtm, cfg.account.initial_capital)

metrics = print_performance_report(
    trades=trades,
    mtm_daily=daily_mtm,
    risk_free_rate=0.02,
)

For a full scriptable workflow (data loading + backtest run), see VRP end-to-end example. For focused hedging configuration examples (fixed band, WW band, cost baselines), see examples/README.md. For hedging model semantics and WW/fixed-band configuration details, see hedging.md. For option execution model behavior and option-cost attribution fields, see option_execution.md. For the research-style workflow and reporting exploration, see VRP notebook.

Advanced Option Execution Injection

Backtester intentionally keeps a stable high-level API and does not expose an option_execution_model argument.

If you want to override option execution behavior, inject the model at plan-build time:

from volatility_trading.backtesting.engine import run_backtest_execution_plan
from volatility_trading.backtesting.options_engine import (
    MidNoCostOptionExecutionModel,
    build_options_execution_plan,
)

plan = build_options_execution_plan(
    spec=strategy,
    data=data,
    config=cfg,
    capital=cfg.account.initial_capital,
    option_execution_model=MidNoCostOptionExecutionModel(),
)
trades, mtm = run_backtest_execution_plan(plan)

Tests

Run unit tests (default):

pytest -q

Run integration tests:

pytest -q -m integration

See Testing guide for layout and conventions.

Continuous Integration (CI)

GitHub Actions runs:

• Ruff lint + format checks
• Pyright type checks
• Unit tests by default
• Integration tests on PRs and pushes to main (and manual runs)

See CI workflow.

Developer Workflow

Common commands are available via Makefile:

make lint
make format
make check
make typecheck
make test
make test-unit
make test-integration
make package-check
make sync-nb
make sync-nb-all
make ci

For full setup and tooling details, see the Documentation index. Notebook HTML reports are built in GitHub Actions and published to GitHub Pages.

Docs

See Documentation index for the full docs map. Most-used pages:

• Development guide
• Testing guide
• Notebook catalog

Research Highlights

We publish research notebooks and strategy diagnostics as HTML reports on GitHub Pages.

• RV forecasting: HAR-RV-VIX reaches about 30% OOS R² vs a naive baseline.
• IV surface modelling: parametric vs non-parametric surface comparison workflows.
• Skew trading: delta-hedged RR strategy with realistic costs and risk controls.

Explore details here:

• Research results (detailed)
• Notebook catalog
• Published HTML reports