voly 0.0.1__py3-none-any.whl

voly/formulas.py

@@ -0,0 +1,243 @@
+"""
+Option pricing formulas and general calculations.
+"""
+
+import numpy as np
+from scipy.stats import norm
+from typing import Tuple, Dict, Union, List, Optional
+from voly.utils.logger import catch_exception
+from voly.models import SVIModel
+from math import exp
+
+
+def d1(s: float, k: float, r: float, vol: float, t: float) -> float:
+    if vol <= 0 or t <= 0:
+        return np.nan
+    return (np.log(s / k) + (r + vol * vol / 2) * t) / (vol * np.sqrt(t))
+
+
+def d2(s: float, k: float, r: float, vol: float, t: float) -> float:
+    if vol <= 0 or t <= 0:
+        return np.nan
+    return d1(s, k, r, vol, t) - vol * np.sqrt(t)
+
+
+@catch_exception
+def bs(s: float, k: float, r: float, vol: float, t: float, option_type: str = 'call') -> float:
+    if vol <= 0 or t <= 0:
+        # Intrinsic value at expiry
+        if option_type.lower() in ["call", "c"]:
+            return max(0, s - k)
+        else:
+            return max(0, k - s)
+
+    d1_val = d1(s, k, r, vol, t)
+    d2_val = d2(s, k, r, vol, t)
+
+    if option_type.lower() in ["call", "c"]:
+        return s * norm.cdf(d1_val) - k * np.exp(-r * t) * norm.cdf(d2_val)
+    else:  # put
+        return k * np.exp(-r * t) * norm.cdf(-d2_val) - s * norm.cdf(-d1_val)
+
+
+@catch_exception
+def delta(s: float, k: float, r: float, vol: float, t: float, option_type: str = 'call') -> float:
+    if vol <= 0 or t <= 0:
+        # At expiry, delta is either 0 or 1 for call, 0 or -1 for put
+        if option_type.lower() in ["call", "c"]:
+            return 1.0 if s > k else 0.0
+        else:
+            return -1.0 if s < k else 0.0
+
+    d1_val = d1(s, k, r, vol, t)
+
+    if option_type.lower() in ["call", "c"]:
+        return norm.cdf(d1_val)
+    else:  # put
+        return norm.cdf(d1_val) - 1.0
+
+
+@catch_exception
+def gamma(s: float, k: float, r: float, vol: float, t: float) -> float:
+    if vol <= 0 or t <= 0:
+        return 0.0
+
+    d1_val = d1(s, k, r, vol, t)
+    return norm.pdf(d1_val) / (s * vol * np.sqrt(t))
+
+
+@catch_exception
+def vega(s: float, k: float, r: float, vol: float, t: float) -> float:
+    if vol <= 0 or t <= 0:
+        return 0.0
+
+    d1_val = d1(s, k, r, vol, t)
+    return s * norm.pdf(d1_val) * np.sqrt(t) / 100  # Divided by 100 for 1% change
+
+
+@catch_exception
+def theta(s: float, k: float, r: float, vol: float, t: float, option_type: str = 'call') -> float:
+    if vol <= 0 or t <= 0:
+        return 0.0
+
+    d1_val = d1(s, k, r, vol, t)
+    d2_val = d2(s, k, r, vol, t)
+
+    # First part of theta (same for both call and put)
+    theta_part1 = -s * norm.pdf(d1_val) * vol / (2 * np.sqrt(t))
+
+    # Second part depends on option type
+    if option_type.lower() in ["call", "c"]:
+        theta_part2 = -r * k * np.exp(-r * t) * norm.cdf(d2_val)
+    else:  # put
+        theta_part2 = r * k * np.exp(-r * t) * norm.cdf(-d2_val)
+
+    # Return theta per day (t is in years)
+    return (theta_part1 + theta_part2) / 365.0
+
+
+@catch_exception
+def rho(s: float, k: float, r: float, vol: float, t: float, option_type: str = 'call') -> float:
+    if vol <= 0 or t <= 0:
+        return 0.0
+
+    d2_val = d2(s, k, r, vol, t)
+
+    if option_type.lower() in ["call", "c"]:
+        return k * t * np.exp(-r * t) * norm.cdf(d2_val) / 100
+    else:  # put
+        return -k * t * np.exp(-r * t) * norm.cdf(-d2_val) / 100
+
+
+@catch_exception
+def vanna(s: float, k: float, r: float, vol: float, t: float) -> float:
+    if vol <= 0 or t <= 0:
+        return 0.0
+
+    d1_val = d1(s, k, r, vol, t)
+    d2_val = d2(s, k, r, vol, t)
+
+    return -norm.pdf(d1_val) * d2_val / vol
+
+
+@catch_exception
+def volga(s: float, k: float, r: float, vol: float, t: float) -> float:
+    if vol <= 0 or t <= 0:
+        return 0.0
+
+    d1_val = d1(s, k, r, vol, t)
+    d2_val = d2(s, k, r, vol, t)
+
+    return s * norm.pdf(d1_val) * np.sqrt(t) * d1_val * d2_val / vol
+
+
+@catch_exception
+def charm(s: float, k: float, r: float, vol: float, t: float, option_type: str = 'call') -> float:
+    if vol <= 0 or t <= 0:
+        return 0.0
+
+    d1_val = d1(s, k, r, vol, t)
+    d2_val = d2(s, k, r, vol, t)
+
+    # First term is the same for calls and puts
+    term1 = -norm.pdf(d1_val) * d1_val / (2 * t)
+
+    # Second term depends on option type
+    if option_type.lower() in ["call", "c"]:
+        term2 = -r * np.exp(-r * t) * norm.cdf(d2_val)
+    else:  # put
+        term2 = r * np.exp(-r * t) * norm.cdf(-d2_val)
+
+    # Return charm per day (t is in years)
+    return (term1 + term2) / 365.0
+
+
+@catch_exception
+def greeks(s: float, k: float, r: float, vol: float, t: float,
+           option_type: str = 'call') -> Dict[str, float]:
+    return {
+        'price': bs(s, k, r, vol, t, option_type),
+        'delta': delta(s, k, r, vol, t, option_type),
+        'gamma': gamma(s, k, r, vol, t),
+        'vega': vega(s, k, r, vol, t),
+        'theta': theta(s, k, r, vol, t, option_type),
+        'rho': rho(s, k, r, vol, t, option_type),
+        'vanna': vanna(s, k, r, vol, t),
+        'volga': volga(s, k, r, vol, t),
+        'charm': charm(s, k, r, vol, t, option_type)
+    }
+
+
+@catch_exception
+def iv(option_price: float, s: float, k: float, r: float, t: float,
+       option_type: str = 'call', precision: float = 1e-8,
+       max_iterations: int = 100) -> float:
+    """
+    Calculate implied volatility using Newton-Raphson method.
+
+    Parameters:
+    - option_price: Market price of the option
+    - s: Underlying price
+    - k: Strike price
+    - r: Risk-free rate
+    - t: Time to expiry in years
+    - option_type: 'call' or 'put'
+    - precision: Desired precision
+    - max_iterations: Maximum number of iterations
+
+    Returns:
+    - Implied volatility
+    """
+    if t <= 0:
+        return np.nan
+
+    # Check if option price is within theoretical bounds
+    if option_type.lower() in ["call", "c"]:
+        intrinsic = max(0, s - k * np.exp(-r * t))
+        if option_price < intrinsic:
+            return np.nan  # Price below intrinsic value
+        if option_price >= s:
+            return np.inf  # Price exceeds underlying
+    else:  # put
+        intrinsic = max(0, k * np.exp(-r * t) - s)
+        if option_price < intrinsic:
+            return np.nan  # Price below intrinsic value
+        if option_price >= k:
+            return np.inf  # Price exceeds strike
+
+    # Initial guess - Manaster and Koehler (1982) method
+    vol = np.sqrt(2 * np.pi / t) * option_price / s
+
+    # Ensure initial guess is reasonable
+    vol = max(0.001, min(vol, 5.0))
+
+    for _ in range(max_iterations):
+        # Calculate option price and vega with current volatility
+        price = bs(s, k, r, vol, t, option_type)
+        v = vega(s, k, r, vol, t)
+
+        # Calculate price difference
+        price_diff = price - option_price
+
+        # Check if precision reached
+        if abs(price_diff) < precision:
+            return vol
+
+        # Avoid division by zero
+        if abs(v) < 1e-10:
+            # Change direction based on whether price is too high or too low
+            vol = vol * 1.5 if price_diff < 0 else vol * 0.5
+        else:
+            # Newton-Raphson update
+            vol = vol - price_diff / (v * 100)  # Vega is for 1% change
+
+        # Ensure volatility stays in reasonable bounds
+        vol = max(0.001, min(vol, 5.0))
+
+    # If we reach here, we didn't converge
+    return np.nan
+
+
+@catch_exception
+def rnd(log_moneyness: float, total_var: float) -> float:
+    return np.exp(-(log_moneyness ** 2) / (2 * total_var)) / (np.sqrt(2 * np.pi * total_var))

voly/models.py

@@ -0,0 +1,86 @@
+"""
+Volatility models for the Voly package.
+"""
+
+import numpy as np
+from typing import Tuple, Dict, List, Optional, Union
+
+# Configuration settings
+DEFAULT_MONEYNESS_RANGE = (-2, 2)
+DEFAULT_MONEYNESS_POINTS = 500
+MIN_DTE = 2.0  # Minimum days to expiry to include
+
+
+class SVIModel:
+    """
+    Stochastic Volatility Inspired (SVI) model.
+
+    This class provides methods for calculating implied volatility using the
+    SVI parameterization, as well as its derivatives and related functions.
+    """
+
+    # Default initial parameters and bounds
+    DEFAULT_INITIAL_PARAMS = [0.04, 0.1, 0.2, -0.5, 0.01]
+    DEFAULT_PARAM_BOUNDS = ([-np.inf, 0, 0, -1, -np.inf], [np.inf, np.inf, np.inf, 1, np.inf])
+
+    # Parameter names for reference
+    PARAM_NAMES = ['a', 'b', 'sigma', 'rho', 'm']
+    JW_PARAM_NAMES = ['nu', 'psi', 'p', 'c', 'nu_tilde']
+
+    # Parameter descriptions for documentation
+    PARAM_DESCRIPTIONS = {
+        'a': 'Base level of total implied variance',
+        'b': 'Volatility skewness/smile modulation (controls wing slopes)',
+        'sigma': 'Convexity control of the volatility smile (reduces ATM curvature)',
+        'rho': 'Skewness/slope of the volatility smile (-1 to 1, rotates smile)',
+        'm': 'Horizontal shift of the smile peak',
+        'nu': 'ATM variance (level of ATM volatility)',
+        'psi': 'ATM volatility skew (affects the gradient of the curve at ATM point)',
+        'p': 'Slope of put wing (left side of curve)',
+        'c': 'Slope of call wing (right side of curve)',
+        'nu_tilde': 'Minimum implied total variance',
+    }
+
+    @staticmethod
+    def svi(moneyness: float, a: float, b: float, sigma: float, rho: float, m: float) -> float:
+        return a + b * (rho * (moneyness - m) + np.sqrt((moneyness - m) ** 2 + sigma ** 2))
+
+    @staticmethod
+    def svi_d(moneyness: float, a: float, b: float, sigma: float, rho: float, m: float) -> float:
+        return b * (rho + ((moneyness - m) / np.sqrt((moneyness - m) ** 2 + sigma ** 2)))
+
+    @staticmethod
+    def svi_dd(moneyness: float, a: float, b: float, sigma: float, rho: float, m: float) -> float:
+        return b * sigma ** 2 / ((moneyness - m) ** 2 + sigma ** 2) ** 1.5
+
+    @staticmethod
+    def svi_min_strike(sigma: float, rho: float, m: float) -> float:
+        return m - ((sigma * rho) / np.sqrt(1 - rho ** 2))
+
+    @staticmethod
+    def raw_to_jw_params(a: float, b: float, sigma: float, rho: float, m: float, t: float) -> Tuple[float, float, float, float, float]:
+        nu = (a + b * ((-rho) * m + np.sqrt(m ** 2 + sigma ** 2))) / t
+        psi = (1 / np.sqrt(nu * t)) * (b / 2) * (rho - (m / np.sqrt(m ** 2 + sigma ** 2)))
+        p = (1 / np.sqrt(nu * t)) * b * (1 - rho)
+        c = (1 / np.sqrt(nu * t)) * b * (1 + rho)
+        nu_tilde = (1 / t) * (a + b * sigma * np.sqrt(1 - rho ** 2))
+        return nu, psi, p, c, nu_tilde
+
+    @staticmethod
+    def jw_to_raw_params(nu: float, phi: float, p: float, c: float, nu_tilde: float, t: float) -> Tuple[float, float, float, float, float]:
+        w = nu * t
+        b = (c + p) / 2
+        rho = (c - p) / (c + p)
+        beta = rho - ((2 * w * phi) / b)
+        alpha = np.sign(beta) * (np.sqrt((1 / (beta ** 2)) - 1))
+        m = (((nu ** 2) - (nu_tilde ** 2)) * t) / (
+                b * ((-rho) + (np.sign(alpha) * np.sqrt(1 + alpha ** 2)) - (alpha * np.sqrt(1 - rho ** 2))))
+        sigma = alpha * m
+        a = ((nu_tilde ** 2) * t) - (b * sigma * np.sqrt(1 - rho ** 2))
+        return a, b, sigma, rho, m
+
+
+# Models dictionary for easy access
+MODELS = {
+    'svi': SVIModel,
+}

voly/utils/__init__.py

@@ -0,0 +1,8 @@
+"""
+Utility functions for the Voly package.
+
+This module contains utility functions for logging, error handling,
+and other helper functions.
+"""
+
+from voly.utils.logger import logger, catch_exception

voly/utils/logger.py

@@ -0,0 +1,72 @@
+"""
+Logger module for the Voly package.
+
+This module provides a centralized logger configuration and
+a decorator for error catching.
+"""
+
+import os
+from datetime import datetime
+import sys
+from functools import wraps
+import asyncio
+from loguru import logger
+
+# Remove the default handler first
+logger.remove()
+
+# Handler for console output - less verbose output
+logger.add(
+    sys.stderr,
+    level="INFO",
+    backtrace=False,  # Don't show traceback
+    diagnose=False  # Don't show variables
+)
+
+
+def setup_file_logging(logs_dir="logs/"):
+    """
+    Set up file-based logging. This is optional and can be called
+    by the end user if they want file-based logging.
+
+    Parameters:
+    logs_dir (str): Directory to store log files
+    """
+    os.makedirs(logs_dir, exist_ok=True)
+    logger.add(
+        os.path.join(logs_dir, "voly_{time:YYYY-MM-DD}.log"),
+        level="INFO",
+        rotation="00:00",
+        retention="7 days",
+        backtrace=True,  # Keep full traceback in file
+        diagnose=True  # Keep variables in file
+    )
+    logger.info("File logging initialized")
+
+
+# Decorator for error catching (supports both sync and async functions)
+def catch_exception(func):
+    @wraps(func)
+    def sync_wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            logger.error(f"{func.__name__}: {str(e)}")
+            raise
+
+    @wraps(func)
+    async def async_wrapper(*args, **kwargs):
+        try:
+            return await func(*args, **kwargs)
+        except Exception as e:
+            logger.error(f"{func.__name__}: {str(e)}")
+            raise
+
+    if asyncio.iscoroutinefunction(func):
+        return async_wrapper
+    else:
+        return sync_wrapper
+
+
+# Initialize logger with basic info
+logger.info("Voly logger initialized")

voly-0.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 manudc22
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

voly-0.0.1.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.2
+Name: voly
+Version: 0.0.1
+Summary: Options & volatility research package
+Author-email: Manu de Cara <manu.de.cara@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: plotly>=5.3.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: websockets>=10.0
+Requires-Dist: requests>=2.26.0
+Requires-Dist: loguru>=0.5.3
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=22.1.0; extra == "dev"
+Requires-Dist: isort>=5.10.1; extra == "dev"
+Requires-Dist: mypy>=0.931; extra == "dev"
+Requires-Dist: flake8>=4.0.1; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: build>=0.8.0; extra == "dev"
+
+# Voly - Options & Volatility Research Package
+
+Voly is a Python package for options data analysis, volatility surface modeling, and risk-neutral density estimation. It provides a simple interface for handling common options research tasks, including data collection, model fitting, and visualization.
+
+## Features
+
+- **Data Collection**: Fetch options data from exchanges (currently supports Deribit)
+- **Volatility Surface Modeling**: Fit SVI (Stochastic Volatility Inspired) model to market data
+- **Risk-Neutral Density**: Calculate and analyze risk-neutral density distributions
+- **Surface Interpolation**: Interpolate volatility surfaces across different expiries
+- **Options Pricing & Greeks**: Calculate Black-Scholes prices and all major Greeks
+- **Visualizations**: Generate interactive plots using Plotly
+
+## Installation
+
+You can install Voly using pip:
+
+```bash
+pip install voly
+```
+
+## Quick Start
+
+```python
+import pandas as pd
+from voly import VolyClient
+
+# Initialize the client
+voly = VolyClient()
+
+# Fetch options data (or load your own data)
+option_chain = voly.get_option_chain(exchange='deribit', currency='BTC')
+
+# Fit an SVI model to the data with visualization
+fit_results = voly.fit_model(option_chain, plot=True)
+
+# Calculate risk-neutral density
+rnd_results = voly.rnd(fit_results, spot_price=option_chain['underlying_price'].iloc[0], plot=True)
+
+# Calculate probability of price above a target
+probability = voly.probability(rnd_results, target_price=32000, direction='above')
+print(f"Probability of price above 32000: {probability:.2%}")
+
+# Calculate option Greeks
+greeks = voly.greeks(s=30000, k=32000, r=0.05, vol=0.6, t=0.25, option_type='call')
+print(f"Option Greeks: {greeks}")
+```
+
+## Example: Visualizing the Volatility Surface
+
+```python
+import pandas as pd
+from voly import VolyClient
+
+# Initialize the client
+voly = VolyClient()
+
+# Load your own data or fetch from exchange
+# The DataFrame should have columns for:
+# - log_moneyness
+# - strike
+# - mark_iv (implied volatility)
+# - yte (years to expiry)
+# - dte (days to expiry)
+# - maturity_name (identifier for the expiry)
+data = pd.read_csv('your_options_data.csv')
+
+# Fit the SVI model
+fit_results = voly.fit_model(data, plot=True)
+
+# Display the 3D volatility surface
+surface_fig = fit_results['plots']['surface_3d']
+surface_fig.show()
+```
+
+## Documentation
+
+For full documentation, visit [https://docs.voly.io](https://docs.voly.io)
+
+## Development
+
+### Setting up the development environment
+
+```bash
+# Clone the repository
+git clone https://github.com/manudc22/voly.git
+cd voly
+
+# Install development dependencies & activate venv
+./env_setup.sh --all
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

voly-0.0.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+voly/__init__.py,sha256=8xyDk7rFCn_MOD5hxuv5cxxKZvBVRiSIM7TgaMPpwpw,211
+voly/client.py,sha256=BBoMURx5nlmwXpH__eQMjNEKy5WMQi3nJyUeVPStHVc,17589
+voly/exceptions.py,sha256=PBsbn1vNMvKcCJwwJ4lBO6glD85jo1h2qiEmD7ArAjs,92
+voly/formulas.py,sha256=aG_HSq_a4j7TcuKiINlHSpmNdmfZa_fzYbAk8EGt954,7427
+voly/models.py,sha256=YJ12aamLz_-aOni4Qm0_XV9u4bjKK3vfJz0J2gc1h0o,3565
+voly/core/__init__.py,sha256=GU6l7hpxJfitPx9jnmBtcb_QIeqOO8liZsSbLXXSbq8,384
+voly/core/charts.py,sha256=GF55IS-aZfcc_0yoSPRPIPBPcJhFD1El18wNCo_mI_A,29918
+voly/core/data.py,sha256=4nQuinjqG0vOY6peN2p00-1_MUck6zo7Hz0saikGneQ,11355
+voly/core/fit.py,sha256=oDNS0Rb7o1g8ioigQ-iqJLNLy45bzARcgETiP9jBi0E,11305
+voly/core/interpolate.py,sha256=fi_OQNdedDrdgawXCwhlO79HLGUvJ-nWjWxqFLd9ijU,8212
+voly/core/rnd.py,sha256=Qlk1Ylo0KEz-BQ6VaGZ-0qsgFyTjoMX1DqCoGXAS6kk,12163
+voly/utils/__init__.py,sha256=E05mWatyC-PDOsCxQV1p5Xi1IgpOomxrNURyCx_gB-w,200
+voly/utils/logger.py,sha256=mujudi610WveZoGJJzoBtGbraFNJUzwWFTza645j08U,1821
+voly-0.0.1.dist-info/LICENSE,sha256=wcHIVbE12jfcBOai_wqBKY6xvNQU5E909xL1zZNq_2Q,1065
+voly-0.0.1.dist-info/METADATA,sha256=4AkfO7MvVz_fB5GZV68zvk4hv1ETQd0Z16IB0ZQhi-A,4136
+voly-0.0.1.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
+voly-0.0.1.dist-info/top_level.txt,sha256=ZfLw2sSxF-LrKAkgGjOmeTcw6_gD-30zvtdEY5W4B7c,5
+voly-0.0.1.dist-info/RECORD,,

voly-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (76.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

voly-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+voly