Implied Volatility Calibration via SVI

This project provides a robust pipeline for calibrating the implied volatility (IV) smile of Taiwan options and futures using the raw-SVI (Stochastic Volatility Inspired) model. The workflow includes data preprocessing, IV computation, SVI parameter calibration, and interactive visualization.

Project Structure

implied-volatility-calibration/
│
├── src/
│   └── iv_calibration/
│       ├── __init__.py
│       ├── config.py
│       ├── data_preprocessor.py
│       ├── metric_calculator.py
│       ├── svi_calibrator.py
│       └── visualization/
│           └── svi_plotter.py
│
├── scripts/
│   ├── run_data_preprocessor.py
│   ├── run_svi_calibrator.py
│   └── run_svi_plotter.py
│
├── data/
│   ├── raw/
│   │   ├── OptionsDaily_2023_07_21.csv
│   │   ├── Daily_2023_07_21.csv
│   │   └── MI_5MINS_INDEX.csv
│   ├── interim/
│   │   ├── option_resampled.parquet
│   │   └── futures_resampled.parquet
│   └── final/
│       └── vol_surface_svi.parquet
│
├── results/
│   ├── svi_iv_slider.html
│   └── svi_total_ivar_slider.html
│
├── tests/
│   ├── test_data_preprocessor.py
│   ├── test_svi_calibrator.py
│   └── test_svi_plotter.py
│
├── requirements.txt
├── .gitignore
└── README.md

Main Features

• Data Preprocessing: Cleans and resamples raw Taiwan option and futures data (TX, TXO).
• Implied Volatility Calculation: Computes Black-Scholes implied volatilities for options.
• SVI Calibration: Calibrates the volatility smile/surface using the raw-SVI model with volume-weighted objective.
• Interactive Visualization: Generates interactive HTML plots for IV and total implied variance surfaces.

How to Use

1. Install dependencies:

   • Python 3.8+
   • The following Python packages are required (see requirements.txt for details):
     • numpy >= 1.21.0
     • pandas >= 1.3.0
     • scipy >= 1.7.0
     • matplotlib >= 3.4.0
     • plotly >= 5.0.0

   Install all dependencies with:

   pip install -r requirements.txt

2. Prepare data:

   • Place your raw CSV files in data/raw/.
   • Example files:
     • OptionsDaily_2023_07_21.csv (option data)
     • Daily_2023_07_21.csv (futures data)
     • MI_5MINS_INDEX.csv (index data)

3. Run the pipeline:

   • Preprocess data:

     python scripts/run_data_preprocessor.py --input data/raw --output data/interim

   • Calibrate SVI parameters:

     python scripts/run_svi_calibrator.py --input data/interim/option_resampled.parquet --output data/final

   • Generate interactive plots:

     python scripts/run_svi_plotter.py --input data/final --output results

4. Import as a Python package:

   import pandas as pd
   from iv_calibration import (
       PATHS, compute_svi_params, plot_with_slider, build_svi_iv_curve
   )
   
   # Step 1: Load resampled option data
   option_resampled_df = pd.read_parquet(PATHS.option_resampled)
   
   # Step 2: Calibrate SVI parameters
   params_df = compute_svi_params(option_resampled_df)
   params_df.to_parquet(PATHS.vol_surface_svi)
   
   # Step 3: Plot IV surface
   plot_with_slider(
       option_resampled_df,
       params_df,
       build_svi_iv_curve,
       "iv",
       "Implied Volatility",
       PATHS.svi_iv_slider
   )

Directory Descriptions

• src/iv_calibration/: Core modules for data processing, IV calculation, SVI calibration, and visualization.
• scripts/: Command-line scripts for each pipeline step.
• data/raw/: Place raw data files here (ignored by git).
• data/interim/: Intermediate processed files (ignored by git).
• data/final/: Final calibrated SVI parameter files (ignored by git).
• results/: Output HTML plots (ignored by git).
• tests/: Test scripts for each module.

Configuration Parameters

The configuration for data paths and model settings is defined in src/iv_calibration/config.py.

PATHS

• raw: Path to the raw data directory (data/raw/).
• interim: Path to the directory for intermediate files (data/interim/).
• final: Path to the directory for final files (data/final/).
• results: Path to the results directory (results/).
• raw_option_data: Path to the main raw option CSV file.
• raw_futures_data: Path to the main raw futures CSV file.
• raw_twse_index_data: Path to the main raw index CSV file.
• option_resampled: Path to the resampled option parquet file.
• futures_resampled: Path to the resampled futures parquet file.
• vol_surface_svi: Path to the SVI parameter parquet file.
• svi_total_ivar_slider: Path to the total implied variance HTML plot.
• svi_iv_slider: Path to the IV HTML plot.

SETTINGS

• expiration_ts: Option expiration timestamp.
• annualization_factor: Annualization factor for time to expiry.
• carry_rate_default: Default carry rate.
• futures_code: Futures contract code.
• option_code: Option contract code.
• expiry: Expiry string.
• demo_resample_freq: Resample frequency for demo.
• metric_resample_freq: Resample frequency for metrics.
• open_time: Market open time.
• close_time: Market close time.
• sample_start_ts: Sample start timestamp.
• sample_end_ts: Sample end timestamp.

SVI_SETTINGS

• global_bounds: Parameter bounds for SVI calibration.
• default_init_params: Default initial parameters for SVI.
• call_lower_bound: Lower bound for call log-moneyness.
• put_upper_bound: Upper bound for put log-moneyness.
• call_volume_pct: Volume percentile threshold for calls.
• put_volume_pct: Volume percentile threshold for puts.

Testing

Test scripts are provided in the tests/ directory. Example:

python tests/test_data_preprocessor.py
python tests/test_svi_calibrator.py
python tests/test_svi_plotter.py