voly 0.0.1__py3-none-any.whl

voly/core/data.py

@@ -0,0 +1,312 @@
+"""
+Data fetching and processing module for the Voly package.
+
+This module handles fetching options data from exchanges and processing 
+it into a standardized format for further analysis.
+"""
+
+import os
+import asyncio
+import websockets
+import json
+import pandas as pd
+import requests
+import time
+import datetime
+import re
+import numpy as np
+from typing import List, Dict, Any, Optional, Union
+from voly.utils.logger import logger, catch_exception
+from voly.exceptions import DataError, ExchangeError, ConnectionError
+
+
+async def subscribe_channels(ws, channels):
+    """Helper function to subscribe to a list of channels"""
+    await ws.send(json.dumps({
+        "jsonrpc": "2.0",
+        "method": "public/subscribe",
+        "id": 42,
+        "params": {"channels": channels}
+    }))
+    await ws.recv()  # Skip confirmation
+
+
+async def unsubscribe_channels(ws, channels):
+    """Helper function to unsubscribe from a list of channels"""
+    await ws.send(json.dumps({
+        "jsonrpc": "2.0",
+        "method": "public/unsubscribe",
+        "id": 43,
+        "params": {"channels": channels}
+    }))
+    await ws.recv()  # Skip confirmation
+
+
+@catch_exception
+async def process_batch(ws, batch: List[str], batch_num: int, total_batches: int) -> List[Dict[str, Any]]:
+    """Process a batch of instruments and return their data"""
+    batch_start = time.time()
+
+    # Create channel subscriptions
+    ticker_channels = [f"ticker.{instr}.100ms" for instr in batch]
+    book_channels = [f"book.{instr}.100ms" for instr in batch]
+    channels = ticker_channels + book_channels
+
+    # Subscribe to channels
+    await subscribe_channels(ws, channels)
+
+    # Process batch responses
+    data_count = 0
+    needed_responses = len(batch) * 2  # Ticker and book for each instrument
+    instrument_data = {}
+
+    while data_count < needed_responses:
+        try:
+            response = await ws.recv()
+            data = json.loads(response)
+
+            if 'params' in data and 'data' in data['params'] and 'channel' in data['params']:
+                channel = data['params']['channel']
+                parts = channel.split('.')
+
+                if len(parts) >= 2:
+                    channel_type = parts[0]  # 'ticker' or 'book'
+                    instr_name = parts[1]
+
+                    if instr_name in batch:
+                        if instr_name not in instrument_data:
+                            instrument_data[instr_name] = {}
+
+                        if channel_type not in instrument_data[instr_name]:
+                            instrument_data[instr_name][channel_type] = data['params']['data']
+                            data_count += 1
+
+        except Exception as e:
+            logger.error(f"Error in batch {batch_num}: {e}")
+            break
+
+    # Unsubscribe from channels
+    await unsubscribe_channels(ws, channels)
+
+    # Process data for this batch
+    batch_results = []
+    for instr_name, channels_data in instrument_data.items():
+        row = {"instrument_name": instr_name}
+
+        # Merge ticker data
+        if 'ticker' in channels_data:
+            ticker = channels_data['ticker']
+            # Add basic fields
+            for k, v in ticker.items():
+                if k not in ['stats', 'greeks']:
+                    row[k] = v
+
+            # Flatten stats and greeks
+            for nested_key in ['stats', 'greeks']:
+                if nested_key in ticker and isinstance(ticker[nested_key], dict):
+                    for k, v in ticker[nested_key].items():
+                        row[k] = v
+
+        # Merge book data
+        if 'book' in channels_data:
+            book = channels_data['book']
+            # Add book fields that don't conflict with ticker
+            for k, v in book.items():
+                if k not in row and k not in ['bids', 'asks']:
+                    row[k] = v
+
+            # Store raw bids and asks
+            if 'bids' in book:
+                row['bids'] = book['bids']
+            if 'asks' in book:
+                row['asks'] = book['asks']
+
+        batch_results.append(row)
+
+    batch_time = time.time() - batch_start
+    logger.info(
+        f"Batch {batch_num}/{total_batches} completed in {batch_time:.2f}s - {len(batch_results)} instruments processed")
+
+    return batch_results
+
+
+@catch_exception
+async def get_deribit_data(currency: str = "BTC") -> pd.DataFrame:
+    """
+    Get options data with ticker and order book information from Deribit.
+
+    Parameters:
+    currency (str): Currency to fetch options for (default: "BTC")
+
+    Returns:
+    pandas.DataFrame: DataFrame with ticker and book data
+    """
+    total_start = time.time()
+
+    # Get active options instruments
+    logger.info(f"Fetching {currency} options...")
+    try:
+        response = requests.get(
+            "https://www.deribit.com/api/v2/public/get_instruments",
+            params={"currency": currency, "kind": "option", "expired": "false"}
+        )
+        response.raise_for_status()  # Raise exception for non-200 status codes
+    except requests.RequestException as e:
+        raise ConnectionError(f"Failed to connect to Deribit API: {str(e)}")
+
+    try:
+        instruments = [i['instrument_name'] for i in response.json()['result']]
+    except (KeyError, json.JSONDecodeError) as e:
+        raise DataError(f"Failed to parse Deribit API response: {str(e)}")
+
+    total_instruments = len(instruments)
+    logger.info(f"Found {total_instruments} active {currency} options")
+
+    # Calculate batches
+    total_batches = (total_instruments + 100 - 1) // 100
+
+    # Collect data
+    all_data = []
+
+    try:
+        async with websockets.connect('wss://www.deribit.com/ws/api/v2') as ws:
+            for i in range(0, total_instruments, 100):
+                batch_num = i // 100 + 1
+                batch = instruments[i:i + 100]
+
+                batch_results = await process_batch(ws, batch, batch_num, total_batches)
+                all_data.extend(batch_results)
+    except (websockets.exceptions.WebSocketException, ConnectionError) as e:
+        raise ConnectionError(f"WebSocket connection error: {str(e)}")
+
+    total_time = time.time() - total_start
+    logger.info(f"Total processing time: {total_time:.2f}s - {len(all_data)} instruments processed")
+
+    if not all_data:
+        raise DataError("No data collected from Deribit")
+
+    return pd.DataFrame(all_data)
+
+
+@catch_exception
+def process_option_chain(df: pd.DataFrame, currency: str, min_dte: float = 2.0) -> pd.DataFrame:
+    """
+    Process raw option chain data into a standardized format.
+
+    Parameters:
+    df (pd.DataFrame): Raw option chain data
+    currency (str): Currency code (e.g., 'BTC', 'ETH')
+    min_dte (float): Minimum days to expiry to include
+
+    Returns:
+    pd.DataFrame: Processed option chain data
+    """
+    logger.info(f"Processing option chain data for {currency}...")
+
+    # Extract instrument details
+    # Format is typically BTC-DDMMMYY-STRIKE-C/P or ETH-DDMMMYY-STRIKE-C/P
+    def extract_details(instrument_name):
+        pattern = f"{currency}-([\\d]{{1,2}})([A-Z]{{3}})(\\d{{2}})-([\\d]+)-([CP])"
+        match = re.match(pattern, instrument_name)
+        if match:
+            day = int(match.group(1))
+            month_str = match.group(2)
+            year = 2000 + int(match.group(3))
+            strike = float(match.group(4))
+            option_type = match.group(5)
+
+            month_dict = {'JAN': 1, 'FEB': 2, 'MAR': 3, 'APR': 4, 'MAY': 5, 'JUN': 6,
+                          'JUL': 7, 'AUG': 8, 'SEP': 9, 'OCT': 10, 'NOV': 11, 'DEC': 12}
+            month = month_dict.get(month_str)
+
+            maturity_name = f"{day}{month_str}{str(year)[-2:]}"
+
+            return {'day': day, 'month': month, 'year': year,
+                    'strike': strike, 'option_type': option_type,
+                    'maturity_name': maturity_name}
+        return None
+
+    # Apply extraction to create new columns
+    logger.info(f"Extracting option details from instrument names...")
+    df['details'] = df['instrument_name'].apply(lambda x: extract_details(x))
+    df['strike'] = df['details'].apply(lambda x: x['strike'] if x else None)
+    df['option_type'] = df['details'].apply(lambda x: x['option_type'] if x else None)
+    df['maturity_name'] = df['details'].apply(lambda x: x['maturity_name'] if x else None)
+
+    # Create expiry date at 8:00 AM UTC
+    df['expiry_date'] = df['details'].apply(
+        lambda x: datetime.datetime(x['year'], x['month'], x['day'], 8, 0, 0) if x else None
+    )
+
+    # Get reference time from timestamp
+    reference_time = datetime.datetime.fromtimestamp(df['timestamp'].iloc[0] / 1000)
+    logger.info(f"Reference time: {reference_time}")
+
+    # Calculate days to expiry (DTE)
+    df['dte'] = (df['expiry_date'] - reference_time).dt.total_seconds() / (24 * 60 * 60)
+
+    # Calculate time to expiry in years
+    df['yte'] = df['dte'] / 365.25
+
+    # Calculate implied volatility (convert from percentage)
+    df['mark_iv'] = df['mark_iv'] / 100
+    df['bid_iv'] = df['bid_iv'].replace({0: np.nan}) / 100
+    df['ask_iv'] = df['ask_iv'].replace({0: np.nan}) / 100
+
+    # Calculate log-moneyness
+    df['log_moneyness'] = np.log(df['underlying_price'] / df['strike'])
+
+    # Remove rows with missing implied volatility
+    original_rows = len(df)
+    df = df.dropna(subset=['mark_iv', 'log_moneyness', 'yte'])
+    logger.info(f"Removed {original_rows - len(df)} rows with missing data")
+
+    # Filter options with DTE > min_dte
+    if min_dte > 0:
+        original_count = len(df)
+        df = df[df['dte'] > min_dte]
+        logger.info(f"Filtered out {original_count - len(df)} options with DTE < {min_dte}")
+
+    # Group by time to expiry and ensure we have enough data points for each expiry
+    expiry_counts = df.groupby('yte').size()
+    valid_expiries = expiry_counts[expiry_counts >= 5].index
+    df = df[df['yte'].isin(valid_expiries)]
+    logger.info(f"Filtered to {len(df)} options with at least 5 strikes per expiry")
+
+    # Report on the maturities we're working with
+    maturities = df.groupby(['maturity_name', 'yte']).size().reset_index()
+    for _, row in maturities.iterrows():
+        logger.info(f"Maturity: {row['maturity_name']}, YTE: {row['yte']:.4f}, Strikes: {row[0]}")
+
+    return df
+
+
+@catch_exception
+async def fetch_option_chain(exchange: str = 'deribit',
+                             currency: str = 'BTC',
+                             depth: bool = False) -> pd.DataFrame:
+    """
+    Fetch option chain data from the specified exchange.
+
+    Parameters:
+    exchange (str): Exchange to fetch data from (currently only 'deribit' is supported)
+    currency (str): Currency to fetch options for (e.g., 'BTC', 'ETH')
+    depth (bool): Whether to include full order book depth. Else, just top of book.
+
+    Returns:
+    pd.DataFrame: Processed option chain data
+    """
+    if exchange.lower() != 'deribit':
+        raise ExchangeError(f"Exchange '{exchange}' is not supported. Currently only 'deribit' is available.")
+
+    # Get raw data
+    raw_data = await get_deribit_data(currency=currency)
+
+    # Process data
+    processed_data = process_option_chain(raw_data, currency)
+
+    # Remove order book depth if not needed
+    if not depth and 'bids' in processed_data.columns and 'asks' in processed_data.columns:
+        processed_data = processed_data.drop(columns=['bids', 'asks'])
+
+    return processed_data

voly/core/fit.py

@@ -0,0 +1,331 @@
+"""
+Model fitting and calibration module for the Voly package.
+
+This module handles fitting volatility models to market data and
+calculating fitting statistics.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import List, Tuple, Dict, Optional, Union, Any
+from scipy.optimize import least_squares
+from sklearn.metrics import mean_squared_error, mean_absolute_error, r2_score
+from voly.utils.logger import logger, catch_exception
+from voly.exceptions import ModelError, ValidationError
+from voly.models import SVIModel
+
+
+@catch_exception
+def calculate_residuals(params: List[float],
+                        time_to_expiry: float,
+                        market_data: pd.DataFrame,
+                        model: Any = SVIModel) -> np.ndarray:
+    """
+    Calculate the residuals between market and model implied volatilities.
+
+    Parameters:
+    - params: Model parameters (e.g., SVI parameters [a, b, sigma, rho, m])
+    - time_to_expiry: The time to expiry in years
+    - market_data: DataFrame with market data
+    - model: Model class to use (default: SVIModel)
+
+    Returns:
+    - Array of residuals
+    """
+    # Filter market data for the specific time to expiry
+    specific_expiry_data = market_data[market_data['yte'] == time_to_expiry]
+
+    # Calculate the total implied variance using the model for filtered data
+    w_model = np.array([model.svi(x, *params) for x in specific_expiry_data['log_moneyness']])
+
+    # Extract the actual market implied volatilities
+    iv_actual = specific_expiry_data['mark_iv'].values
+
+    # Calculate residuals between market implied volatilities and model predictions
+    residuals = iv_actual - np.sqrt(w_model / time_to_expiry)
+
+    return residuals
+
+
+@catch_exception
+def optimize_svi_parameters(market_data: pd.DataFrame,
+                            initial_params: Optional[List[float]] = None,
+                            param_bounds: Optional[Tuple] = None) -> Dict[str, Dict[str, Any]]:
+    """
+    Optimize SVI parameters for all unique expiries in the market data.
+
+    Parameters:
+    - market_data: DataFrame with market data
+    - initial_params: Initial guess for SVI parameters (default: from SVIModel)
+    - param_bounds: Bounds for parameters (default: from SVIModel)
+
+    Returns:
+    - Dictionary of optimization results by maturity name
+    """
+    results = {}
+    unique_expiries = sorted(market_data['yte'].unique())
+
+    # Use defaults if not provided
+    if initial_params is None:
+        initial_params = SVIModel.DEFAULT_INITIAL_PARAMS
+
+    if param_bounds is None:
+        param_bounds = SVIModel.DEFAULT_PARAM_BOUNDS
+
+    for t_dte in unique_expiries:
+        # Get maturity name for reporting
+        expiry_data = market_data[market_data['yte'] == t_dte]
+        maturity_name = expiry_data['maturity_name'].iloc[0]
+        dte_value = expiry_data['dte'].iloc[0]
+
+        logger.info(f"Optimizing for {maturity_name} (DTE: {dte_value:.1f}, YTE: {t_dte:.4f})...")
+
+        # Optimize SVI parameters
+        try:
+            result = least_squares(
+                calculate_residuals,
+                initial_params,
+                args=(t_dte, market_data, SVIModel),
+                bounds=param_bounds,
+                max_nfev=1000
+            )
+        except Exception as e:
+            raise ModelError(f"Optimization failed for {maturity_name}: {str(e)}")
+
+        # Store results with maturity name as key
+        results[maturity_name] = {
+            'params': result.x,
+            'success': result.success,
+            'cost': result.cost,
+            'optimality': result.optimality,
+            'message': result.message,
+            'yte': t_dte,
+            'dte': dte_value
+        }
+
+        if result.success:
+            logger.info(f'Optimization for {maturity_name} (DTE: {dte_value:.1f}): SUCCESS')
+        else:
+            logger.warning(f'Optimization for {maturity_name} (DTE: {dte_value:.1f}): FAILED')
+
+        logger.info('------------------------------------------')
+
+    return results
+
+
+@catch_exception
+def create_parameters_matrix(optimization_results: Dict[str, Dict[str, Any]]) -> Tuple[pd.DataFrame, pd.DataFrame]:
+    """
+    Create matrices of optimized parameters for each expiry.
+    Uses maturity names as column names.
+
+    Parameters:
+    - optimization_results: Dictionary of optimization results by maturity name
+
+    Returns:
+    - Tuple of DataFrames with optimized parameters:
+      1. Raw SVI parameters (a, b, sigma, rho, m)
+      2. Jump-Wing parameters (nu, psi, p, c, nu_tilde)
+    """
+    # Get maturity names in order by DTE
+    maturity_names = sorted(optimization_results.keys(),
+                            key=lambda x: optimization_results[x]['dte'])
+
+    # Create DataFrame for raw parameters with maturity names as columns
+    raw_param_matrix = pd.DataFrame(
+        columns=maturity_names,
+        index=SVIModel.PARAM_NAMES
+    )
+
+    # Create DataFrame for JW parameters
+    jw_param_matrix = pd.DataFrame(
+        columns=maturity_names,
+        index=SVIModel.JW_PARAM_NAMES
+    )
+
+    # Store YTE and DTE values for reference
+    yte_values = {}
+    dte_values = {}
+
+    # Fill the matrices with optimized parameters
+    for maturity_name in maturity_names:
+        result = optimization_results[maturity_name]
+
+        # Extract raw SVI parameters
+        a, b, sigma, rho, m = result['params']
+        raw_param_matrix[maturity_name] = [a, b, sigma, rho, m]
+
+        # Get time to expiry
+        yte = result['yte']
+        yte_values[maturity_name] = yte
+        dte_values[maturity_name] = result['dte']
+
+        # Calculate JW parameters
+        nu, psi, p, c, nu_tilde = SVIModel.svi_jw_params(a, b, sigma, rho, m, yte)
+        jw_param_matrix[maturity_name] = [nu, psi, p, c, nu_tilde]
+
+    # Store YTE and DTE as attributes in all DataFrames for reference
+    attrs = {
+        'yte_values': yte_values,
+        'dte_values': dte_values
+    }
+
+    raw_param_matrix.attrs.update(attrs)
+    jw_param_matrix.attrs.update(attrs)
+
+    return raw_param_matrix, jw_param_matrix
+
+
+@catch_exception
+def generate_implied_volatility_surface(
+        param_matrix: pd.DataFrame,
+        moneyness_range: Tuple[float, float] = (-2, 2),
+        num_points: int = 500
+) -> Tuple[np.ndarray, Dict[float, np.ndarray]]:
+    """
+    Generate implied volatility surface using optimized SVI parameters.
+
+    Parameters:
+    - param_matrix: Matrix of optimized SVI parameters with maturity names as columns
+    - moneyness_range: (min, max) range for moneyness grid
+    - num_points: Number of points for moneyness grid
+
+    Returns:
+    - Moneyness grid and implied volatility surface
+    """
+    # Generate moneyness grid
+    min_m, max_m = moneyness_range
+    moneyness_values = np.linspace(min_m, max_m, num=num_points)
+    implied_volatility_surface = {}
+
+    # Get YTE values from the parameter matrix attributes
+    yte_values = param_matrix.attrs['yte_values']
+
+    # Generate implied volatility for each expiry
+    for maturity_name, yte in yte_values.items():
+        svi_params = param_matrix[maturity_name].values
+        w_svi = [SVIModel.svi(x, *svi_params) for x in moneyness_values]
+        implied_volatility_surface[yte] = np.sqrt(np.array(w_svi) / yte)
+
+    return moneyness_values, implied_volatility_surface
+
+
+@catch_exception
+def calculate_fit_statistics(market_data: pd.DataFrame, param_matrix: pd.DataFrame) -> pd.DataFrame:
+    """
+    Calculate fitting accuracy statistics for each expiry.
+
+    Parameters:
+    - market_data: DataFrame with market data
+    - param_matrix: Matrix of optimized SVI parameters with maturity names as columns
+
+    Returns:
+    - DataFrame with fitting statistics
+    """
+    # Get YTE values from the parameter matrix attributes
+    yte_values = param_matrix.attrs['yte_values']
+    dte_values = param_matrix.attrs['dte_values']
+
+    # Initialize lists for statistics
+    maturity_name_list = []
+    dte_list = []
+    yte_list = []
+    rmse_list = []
+    mae_list = []
+    r2_list = []
+    max_error_list = []
+    num_points_list = []
+
+    # Calculate statistics for each expiry
+    for maturity_name, yte in yte_values.items():
+        # Filter market data for the specific expiry
+        expiry_data = market_data[market_data['yte'] == yte]
+        dte_value = dte_values[maturity_name]
+
+        # Calculate SVI model predictions
+        svi_params = param_matrix[maturity_name].values
+        w_svi = np.array([SVIModel.svi(x, *svi_params) for x in expiry_data['log_moneyness']])
+        iv_model = np.sqrt(w_svi / yte)
+
+        # Get actual market implied volatilities
+        iv_market = expiry_data['mark_iv'].values
+
+        # Calculate statistics
+        rmse = np.sqrt(mean_squared_error(iv_market, iv_model))
+        mae = mean_absolute_error(iv_market, iv_model)
+        r2 = r2_score(iv_market, iv_model)
+        max_error = np.max(np.abs(iv_market - iv_model))
+        num_points = len(expiry_data)
+
+        # Append to lists
+        maturity_name_list.append(maturity_name)
+        dte_list.append(dte_value)
+        yte_list.append(yte)
+        rmse_list.append(rmse)
+        mae_list.append(mae)
+        r2_list.append(r2)
+        max_error_list.append(max_error)
+        num_points_list.append(num_points)
+
+    # Create DataFrame with statistics
+    stats_df = pd.DataFrame({
+        'Maturity': maturity_name_list,
+        'DTE': dte_list,
+        'YTE': yte_list,
+        'RMSE': rmse_list,
+        'MAE': mae_list,
+        'R²': r2_list,
+        'Max Error': max_error_list,
+        'Number of Points': num_points_list
+    })
+
+    return stats_df
+
+
+@catch_exception
+def fit_model(market_data: pd.DataFrame,
+              model_name: str = 'svi',
+              moneyness_range: Tuple[float, float] = (-2, 2),
+              num_points: int = 500) -> Dict[str, Any]:
+    """
+    Fit a volatility model to market data.
+
+    Parameters:
+    - market_data: DataFrame with market data
+    - model_name: Type of model to fit (default: 'svi')
+    - moneyness_range: (min, max) range for moneyness grid
+    - num_points: Number of points for moneyness grid
+
+    Returns:
+    - Dictionary with fitting results
+    """
+    if model_name.lower() != 'svi':
+        raise ValidationError(f"Model type '{model_name}' is not supported. Currently only 'svi' is available.")
+
+    # Step 1: Optimize model parameters
+    optimization_results = optimize_svi_parameters(market_data)
+
+    # Step 2: Create parameter matrices
+    raw_param_matrix, jw_param_matrix = create_parameters_matrix(optimization_results)
+
+    # Step 3: Generate implied volatility surface
+    moneyness_grid, iv_surface = generate_implied_volatility_surface(
+        raw_param_matrix, moneyness_range, num_points
+    )
+
+    # Step 4: Calculate fitting statistics
+    stats_df = calculate_fit_statistics(market_data, raw_param_matrix)
+
+    # Step 5: Get unique expiries in sorted order (in years)
+    unique_expiries_years = np.array(sorted(market_data['yte'].unique()))
+
+    # Return all results in a dictionary
+    return {
+        'optimization_results': optimization_results,
+        'raw_param_matrix': raw_param_matrix,
+        'jw_param_matrix': jw_param_matrix,
+        'moneyness_grid': moneyness_grid,
+        'iv_surface': iv_surface,
+        'stats_df': stats_df,
+        'unique_expiries': unique_expiries_years,
+    }