voly 0.0.152__tar.gz → 0.0.154__tar.gz

{voly-0.0.152/src/voly.egg-info → voly-0.0.154}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voly
-Version: 0.0.152
+Version: 0.0.154
 Summary: Options & volatility research package
 Author-email: Manu de Cara <manu.de.cara@gmail.com>
 License: MIT

{voly-0.0.152 → voly-0.0.154}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "voly"
-version = "0.0.152"
+version = "0.0.154"
 description = "Options & volatility research package"
 readme = "README.md"
 authors = [
@@ -60,7 +60,7 @@ line_length = 100
 multi_line_output = 3
 
 [tool.mypy]
-python_version = "0.0.152"
+python_version = "0.0.154"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true

{voly-0.0.152 → voly-0.0.154}/src/voly/client.py

@@ -23,8 +23,7 @@ from voly.core.rnd import get_rnd_surface
 from voly.core.hd import get_historical_data, get_hd_surface
 from voly.core.interpolate import interpolate_model
 from voly.core.charts import (
-    plot_all_smiles, plot_raw_parameters, plot_jw_parameters, plot_fit_performance, plot_3d_surface,
-    plot_fit_performance
+    plot_all_smiles, plot_raw_parameters, plot_jw_parameters, plot_fit_performance, plot_3d_surface
 )
 
 
@@ -37,10 +36,14 @@ class VolyClient:
         - enable_file_logging: Whether to enable file-based logging
         - logs_dir: Directory for log files if file logging is enabled
         """
+
+        from importlib.metadata import version
+        voly_version = version("voly")
+
         if enable_file_logging:
             setup_file_logging(logs_dir)
 
-        logger.info("VolyClient initialized")
+        logger.info(f"VolyClient (v{voly_version}) initialized")
         self._loop = None  # For async operations
 
     def _get_event_loop(self):
@@ -156,10 +159,6 @@ class VolyClient:
            option_type: str = 'call') -> float:
         return iv(option_price, s, K, r, t, option_type)
 
-    @staticmethod
-    def pdf_to_calls(pdf_K: np.ndarray, s: float, K: np.ndarray, r: float, t: float):
-        return pdf_to_calls(pdf_K, s, K, r, t)
-
     # -------------------------------------------------------------------------
     # Model Fitting
     # -------------------------------------------------------------------------
@@ -307,8 +306,19 @@ class VolyClient:
     def get_rnd_surface(model_results: pd.DataFrame,
                         domain_params: Tuple[float, float, int] = (-1.5, 1.5, 1000),
                         return_domain: str = 'log_moneyness',
-                        method: str = 'rookley') -> Tuple[Dict[str, np.ndarray], Dict[str, np.ndarray], Dict[str, np.ndarray], pd.DataFrame]:
+                        method: str = 'rookley') -> Dict[str, Any]:
+        """
+        Generate risk-neutral density surface from volatility surface parameters.
+
+        Parameters:
+        - model_results: DataFrame from fit_model() or interpolate_model()
+        - domain_params: Tuple of (min_log_moneyness, max_log_moneyness, num_points)
+        - return_domain: Domain for results ('log_moneyness', 'moneyness', 'returns', 'strikes')
+        - method: Method for RND estimation ('rookley' or 'breeden')
 
+        Returns:
+        - Dictionary with pdf_surface, cdf_surface, x_surface, and moments
+        """
         logger.info("Calculating RND surface")
 
         return get_rnd_surface(
@@ -326,41 +336,50 @@ class VolyClient:
     def get_historical_data(currency: str = 'BTC',
                             lookback_days: str = '90d',
                             granularity: str = '15m',
-                            exchange_name: str = 'binance'):
+                            exchange_name: str = 'binance') -> pd.DataFrame:
+        """
+        Fetch historical OHLCV data for a cryptocurrency.
 
-        # Generate the surface
-        df_hist = get_historical_data(
+        Parameters:
+        - currency: The cryptocurrency to fetch data for (e.g., 'BTC', 'ETH')
+        - lookback_days: The lookback period in days, formatted as '90d', '30d', etc.
+        - granularity: The time interval for data points (e.g., '15m', '1h', '1d')
+        - exchange_name: The exchange to fetch data from (default: 'binance')
+
+        Returns:
+        - Historical price data with OHLCV columns and datetime index
+        """
+        logger.info(f"Fetching historical {currency} data from {exchange_name}...")
+
+        return get_historical_data(
             currency=currency,
             lookback_days=lookback_days,
             granularity=granularity,
             exchange_name=exchange_name
         )
 
-        return df_hist
-
     @staticmethod
     def get_hd_surface(model_results: pd.DataFrame,
                        df_hist: pd.DataFrame,
                        domain_params: Tuple[float, float, int] = (-1.5, 1.5, 1000),
-                       return_domain: str = 'log_moneyness',
-                       method: str = 'garch',
-                       distribution: str = 'normal',
-                       window_length: str = '30d',
-                       n_fits: int = 400,
-                       simulations: int = 5000,
-                       bandwidth: str = 'silverman') -> Dict[str, Any]:
+                       return_domain: str = 'log_moneyness') -> Dict[str, Any]:
+        """
+        Generate historical density surface using normal distributions.
 
-        logger.info(f"Calculating historical density surface using {method} method")
+        Parameters:
+        - model_results: DataFrame with model parameters and maturities
+        - df_hist: DataFrame with historical price data
+        - domain_params: Tuple of (min_log_moneyness, max_log_moneyness, num_points)
+        - return_domain: Domain for results ('log_moneyness', 'moneyness', 'returns', 'strikes')
+
+        Returns:
+        - Dictionary with pdf_surface, cdf_surface, x_surface, and moments
+        """
+        logger.info("Calculating HD surface")
 
         return get_hd_surface(
             model_results=model_results,
             df_hist=df_hist,
             domain_params=domain_params,
-            return_domain=return_domain,
-            method=method,
-            distribution=distribution,
-            window_length=window_length,
-            n_fits=n_fits,
-            simulations=simulations,
-            bandwidth=bandwidth
+            return_domain=return_domain
         )

voly-0.0.154/src/voly/core/hd.py

@@ -0,0 +1,249 @@
+"""
+This module handles calculating historical densities from time series of prices
+and converting them to probability distributions.
+"""
+
+import ccxt
+import numpy as np
+import pandas as pd
+import datetime as dt
+from typing import Dict, Tuple, Any, Optional, List
+from scipy import stats
+from voly.utils.logger import logger, catch_exception
+from voly.exceptions import VolyError
+from voly.core.rnd import get_all_moments
+from voly.utils.density import prepare_domains, normalize_density, transform_to_domains, select_domain_results
+
+
+@catch_exception
+def get_historical_data(currency: str,
+                        lookback_days: str,
+                        granularity: str,
+                        exchange_name: str) -> pd.DataFrame:
+    """
+    Fetch historical OHLCV data for a cryptocurrency.
+
+    Parameters:
+    -----------
+    currency : str
+        The cryptocurrency to fetch data for (e.g., 'BTC', 'ETH')
+    lookback_days : str
+        The lookback period in days, formatted as '90d', '30d', etc.
+    granularity : str
+        The time interval for data points (e.g., '15m', '1h', '1d')
+    exchange_name : str
+        The exchange to fetch data from (default: 'binance')
+
+    Returns:
+    --------
+    pd.DataFrame
+        Historical price data with OHLCV columns and datetime index
+    """
+    # Validate inputs
+    if not lookback_days.endswith('d'):
+        raise VolyError("lookback_days should be in format '90d', '30d', etc.")
+
+    try:
+        # Get the exchange class from ccxt
+        exchange_class = getattr(ccxt, exchange_name.lower())
+        exchange = exchange_class({'enableRateLimit': True})
+    except (AttributeError, TypeError):
+        raise VolyError(f"Exchange '{exchange_name}' not found in ccxt. Please check the exchange name.")
+
+    # Form the trading pair symbol
+    symbol = f"{currency}/USDT"
+
+    # Convert lookback_days to timestamp
+    days_ago = int(lookback_days[:-1])
+    date_start = (dt.datetime.now() - dt.timedelta(days=days_ago)).strftime('%Y-%m-%d %H:%M:%S')
+    from_ts = exchange.parse8601(date_start)
+
+    ohlcv_list = []
+    ohlcv = exchange.fetch_ohlcv(symbol, granularity, since=from_ts, limit=1000)
+    ohlcv_list.append(ohlcv)
+
+    while True:
+        from_ts = ohlcv[-1][0]
+        new_ohlcv = exchange.fetch_ohlcv(symbol, granularity, since=from_ts, limit=1000)
+        if len(new_ohlcv) <= 1:  # No new data or just one overlapping candle
+            break
+        ohlcv.extend(new_ohlcv[1:])  # Skip the first one to avoid duplicates
+        if len(new_ohlcv) != 1000:
+            break
+
+    # Convert to DataFrame
+    df_hist = pd.DataFrame(ohlcv, columns=['date', 'open', 'high', 'low', 'close', 'volume'])
+    df_hist['date'] = pd.to_datetime(df_hist['date'], unit='ms')
+    df_hist.set_index('date', inplace=True)
+    df_hist = df_hist.sort_index(ascending=True)
+    df_hist = df_hist[~df_hist.index.duplicated(keep='last')].sort_index()
+
+    logger.info(f"Data fetched successfully: {len(df_hist)} rows from {df_hist.index[0]} to {df_hist.index[-1]}")
+
+    return df_hist
+
+
+@catch_exception
+def calculate_normal_hd(df_hist: pd.DataFrame,
+                        t: float,
+                        r: float,
+                        n_periods: int,
+                        domains: Dict[str, np.ndarray]) -> Dict[str, np.ndarray]:
+    """
+    Calculate historical density using a normal distribution based on historical returns.
+
+    Parameters:
+    -----------
+    df_hist : pd.DataFrame
+        Historical price data
+    t : float
+        Time to maturity in years
+    r : float
+        Risk-free rate
+    n_periods : int
+        Number of periods to scale returns
+    domains : Dict[str, np.ndarray]
+        Domain arrays
+
+    Returns:
+    --------
+    Dict[str, np.ndarray]
+        Dictionary of PDFs in different domains
+    """
+    # Extract log-moneyness domain
+    LM = domains['log_moneyness']
+    dx = domains['dx']
+
+    # Calculate log returns
+    returns = np.log(df_hist['close'] / df_hist['close'].shift(1)).dropna().values
+
+    # Filter historical data based on n_periods
+    if len(returns) < n_periods:
+        logger.warning(f"Not enough historical data, using all {len(returns)} points available")
+        dte_returns = returns
+    else:
+        dte_returns = returns[-n_periods:]
+
+    # Calculate scaled parameters for normal distribution
+    mu_scaled = np.mean(dte_returns) * np.sqrt(n_periods)
+    sigma_scaled = np.std(dte_returns) * np.sqrt(n_periods)
+
+    # Apply Girsanov adjustment to shift to risk-neutral measure
+    expected_risk_neutral_mean = (r - 0.5 * sigma_scaled ** 2) * np.sqrt(t)
+    adjustment = mu_scaled - expected_risk_neutral_mean
+    mu_rn = mu_scaled - adjustment
+
+    # Calculate PDF using normal distribution in log-moneyness domain
+    pdf_lm = stats.norm.pdf(LM, loc=mu_rn, scale=sigma_scaled)
+
+    # Normalize the PDF
+    pdf_lm = normalize_density(pdf_lm, dx)
+
+    # Transform to other domains
+    pdfs = transform_to_domains(pdf_lm, domains)
+
+    return pdfs
+
+
+@catch_exception
+def get_hd_surface(model_results: pd.DataFrame,
+                   df_hist: pd.DataFrame,
+                   domain_params: Tuple[float, float, int] = (-1.5, 1.5, 1000),
+                   return_domain: str = 'log_moneyness') -> Dict[str, Any]:
+    """
+    Generate historical density surface using normal distributions.
+
+    Parameters:
+    -----------
+    model_results : pd.DataFrame
+        DataFrame with model parameters and maturities
+    df_hist : pd.DataFrame
+        DataFrame with historical price data
+    domain_params : Tuple[float, float, int]
+        (min_log_moneyness, max_log_moneyness, num_points)
+    return_domain : str
+        Domain for results ('log_moneyness', 'moneyness', 'returns', 'strikes')
+
+    Returns:
+    --------
+    Dict[str, Any]
+        Dictionary with pdf_surface, cdf_surface, x_surface, and moments
+    """
+    # Validate inputs
+    required_columns = ['s', 't', 'r']
+    missing_columns = [col for col in required_columns if col not in model_results.columns]
+    if missing_columns:
+        raise VolyError(f"Required columns missing in model_results: {missing_columns}")
+
+    if len(df_hist) < 2:
+        raise VolyError("Not enough data points in df_hist")
+
+    # Validate return domain
+    valid_domains = ['log_moneyness', 'moneyness', 'returns', 'strikes']
+    if return_domain not in valid_domains:
+        raise VolyError(f"Invalid return_domain: {return_domain}. Must be one of {valid_domains}")
+
+    # Determine granularity from data (minutes between data points)
+    time_diff = (df_hist.index[1] - df_hist.index[0]).total_seconds() / 60
+    minutes_per_period = max(1, int(time_diff))
+
+    # Initialize result containers
+    pdf_surface = {}
+    cdf_surface = {}
+    x_surface = {}
+    all_moments = {}
+
+    # Process each maturity
+    for i in model_results.index:
+        try:
+            # Get parameters for this maturity
+            s = model_results.loc[i, 's']  # Spot price
+            t = model_results.loc[i, 't']  # Time to maturity in years
+            r = model_results.loc[i, 'r']  # Risk-free rate
+
+            # Calculate relevant periods for this maturity
+            dte = t * 365.25  # Days to expiry
+            n_periods = max(1, int(dte * 24 * 60 / minutes_per_period))
+
+            # Prepare domains
+            domains = prepare_domains(domain_params, s)
+
+            # Calculate density
+            pdfs = calculate_normal_hd(
+                df_hist=df_hist,
+                t=t,
+                r=r,
+                n_periods=n_periods,
+                domains=domains
+            )
+
+            # Select results for the requested domain
+            pdf, cdf, x = select_domain_results(pdfs, domains, return_domain)
+
+            # Calculate moments
+            moments = get_all_moments(x, pdf)
+
+            # Store results
+            pdf_surface[i] = pdf
+            cdf_surface[i] = cdf
+            x_surface[i] = x
+            all_moments[i] = moments
+
+        except Exception as e:
+            logger.warning(f"Failed to calculate HD for maturity {i}: {str(e)}")
+
+    # Check if we have any valid results
+    if not pdf_surface:
+        raise VolyError("No valid densities could be calculated. Check your input data.")
+
+    # Create DataFrame with moments
+    moments = pd.DataFrame(all_moments).T
+
+    logger.info("Historical density calculation complete using normal distribution")
+
+    return {
+        'pdf_surface': pdf_surface,
+        'cdf_surface': cdf_surface,
+        'x_surface': x_surface,
+        'moments': moments
+    }

{voly-0.0.152 → voly-0.0.154}/src/voly/core/rnd.py

@@ -9,154 +9,9 @@ from typing import Dict, List, Tuple, Optional, Union, Any, Callable
 from voly.utils.logger import logger, catch_exception
 from voly.exceptions import VolyError
 from voly.models import SVIModel
-from voly.formulas import bs, d1, d2, get_domain
+from voly.formulas import bs, d1, d2
 from scipy import stats
-
-
-@catch_exception
-def _prepare_domains(domain_params, s, r, o, t):
-    """
-    Calculate domain arrays for different representations (log_moneyness, moneyness, etc.).
-
-    Parameters:
-    -----------
-    domain_params : tuple
-        (min_log_moneyness, max_log_moneyness, num_points)
-    s : float
-        Spot price
-    r : float
-        Risk-free rate
-    o : ndarray
-        Implied volatility array
-    t : float
-        Time to expiry in years
-
-    Returns:
-    --------
-    dict
-        Dictionary containing arrays for different domains
-    """
-    domains = {}
-    domains['log_moneyness'] = get_domain(domain_params, s, r, o, t, 'log_moneyness')
-    domains['moneyness'] = get_domain(domain_params, s, r, o, t, 'moneyness')
-    domains['returns'] = get_domain(domain_params, s, r, o, t, 'returns')
-    domains['strikes'] = get_domain(domain_params, s, r, o, t, 'strikes')
-    domains['delta'] = get_domain(domain_params, s, r, o, t, 'delta')
-
-    # Precompute differentials for integration
-    domains['dx'] = domains['log_moneyness'][1] - domains['log_moneyness'][0]
-
-    return domains
-
-
-@catch_exception
-def _normalize_density(pdf_values, dx):
-    """
-    Normalize a probability density function to integrate to 1.
-
-    Parameters:
-    -----------
-    pdf_values : ndarray
-        Array of PDF values
-    dx : float
-        Grid spacing
-
-    Returns:
-    --------
-    ndarray
-        Normalized PDF values
-    """
-    total_area = np.sum(pdf_values * dx)
-    if total_area <= 0:
-        logger.warning("PDF area is negative or zero, using absolute values")
-        total_area = np.sum(np.abs(pdf_values) * dx)
-
-    return pdf_values / total_area
-
-
-@catch_exception
-def _transform_to_domains(rnd_k, domains):
-    """
-    Transform density from strike domain to other domains.
-
-    Parameters:
-    -----------
-    rnd_k : ndarray
-        PDF in strike domain
-    domains : dict
-        Domain arrays
-
-    Returns:
-    --------
-    dict
-        Dictionary of PDFs in different domains
-    """
-    LM = domains['log_moneyness']
-    M = domains['moneyness']
-    K = domains['strikes']
-    R = domains['returns']
-    dx = domains['dx']
-
-    # Calculate PDF in different domains
-    rnd_lm = rnd_k * K  # Convert to log-moneyness domain
-    pdf_lm = _normalize_density(rnd_lm, dx)
-
-    # Transform to other domains
-    pdf_k = pdf_lm / K
-    pdf_m = pdf_k * domains['strikes'][0]  # s = K[0] * M[0]
-    pdf_r = pdf_lm / (1 + R)
-
-    # For delta domain, need special handling due to non-monotonicity
-    pdf_d1 = stats.norm.pdf(d1(domains['strikes'][0], K, 0, domains['delta'][0], 1, option_type='call'))
-    dd_dK = pdf_d1 / (domains['delta'][0] * np.sqrt(1) * K)
-    pdf_d = pdf_k / dd_dK
-
-    # Calculate CDF
-    cdf = np.cumsum(pdf_lm * dx)
-    cdf = np.minimum(cdf / cdf[-1], 1.0)  # Ensure max value is 1
-
-    return {
-        'log_moneyness': pdf_lm,
-        'moneyness': pdf_m,
-        'returns': pdf_r,
-        'strikes': pdf_k,
-        'delta': pdf_d,
-        'cdf': cdf
-    }
-
-
-@catch_exception
-def _select_domain_results(pdfs, domains, return_domain):
-    """
-    Select results for the requested domain.
-
-    Parameters:
-    -----------
-    pdfs : dict
-        PDFs in different domains
-    domains : dict
-        Domain arrays
-    return_domain : str
-        Requested domain
-
-    Returns:
-    --------
-    tuple
-        (pdf, cdf, x, moments)
-    """
-    if return_domain == 'delta':
-        # Special handling for delta domain due to potential non-monotonicity
-        D = domains['delta']
-        pdf_d = pdfs['delta']
-        sort_idx = np.argsort(D)
-        x = D[sort_idx]
-        pdf = pdf_d[sort_idx]
-    else:
-        x = domains[return_domain]
-        pdf = pdfs[return_domain]
-
-    moments = get_all_moments(x, pdf)
-    return pdf, pdfs['cdf'], x, moments
+from voly.utils.density import prepare_domains, normalize_density, transform_to_domains, select_domain_results
 
 
 @catch_exception
@@ -177,7 +32,7 @@ def breeden(domain_params, s, r, o, t, return_domain):
     t : float
         Time to expiry in years
     return_domain : str
-        Domain for results ('log_moneyness', 'moneyness', 'returns', 'strikes', 'delta')
+        Domain for results ('log_moneyness', 'moneyness', 'returns', 'strikes')
 
     Returns:
     --------
@@ -185,8 +40,9 @@ def breeden(domain_params, s, r, o, t, return_domain):
         (pdf, cdf, x, moments)
     """
     # Prepare domain arrays
-    domains = _prepare_domains(domain_params, s, r, o, t)
+    domains = prepare_domains(domain_params, s)
     K = domains['strikes']
+    dx = domains['dx']
 
     # Calculate option prices and derivatives
     c = bs(s, K, r, o, t, option_type='call')
@@ -196,11 +52,21 @@ def breeden(domain_params, s, r, o, t, return_domain):
     # Calculate RND in strike domain and apply discount factor
     rnd_k = np.maximum(np.exp(r * t) * c2, 0)
 
+    # Transform to log-moneyness domain first
+    LM = domains['log_moneyness']
+    rnd_lm = rnd_k * K  # Convert to log-moneyness domain
+    pdf_lm = normalize_density(rnd_lm, dx)
+
     # Transform to other domains
-    pdfs = _transform_to_domains(rnd_k, domains)
+    pdfs = transform_to_domains(pdf_lm, domains)
 
     # Return results for requested domain
-    return _select_domain_results(pdfs, domains, return_domain)
+    pdf, cdf, x = select_domain_results(pdfs, domains, return_domain)
+
+    # Calculate moments
+    moments = get_all_moments(x, pdf)
+
+    return pdf, cdf, x, moments
 
 
 @catch_exception
@@ -221,7 +87,7 @@ def rookley(domain_params, s, r, o, t, return_domain):
     t : float
         Time to expiry in years
     return_domain : str
-        Domain for results ('log_moneyness', 'moneyness', 'returns', 'strikes', 'delta')
+        Domain for results ('log_moneyness', 'moneyness', 'returns', 'strikes')
 
     Returns:
     --------
@@ -229,9 +95,10 @@ def rookley(domain_params, s, r, o, t, return_domain):
         (pdf, cdf, x, moments)
     """
     # Prepare domain arrays
-    domains = _prepare_domains(domain_params, s, r, o, t)
+    domains = prepare_domains(domain_params, s)
     M = domains['moneyness']
     K = domains['strikes']
+    dx = domains['dx']
 
     # Calculate volatility derivatives with respect to moneyness
     o1 = np.gradient(o, M)
@@ -287,11 +154,21 @@ def rookley(domain_params, s, r, o, t, return_domain):
     # Calculate RND in strike domain and apply discount factor
     rnd_k = np.maximum(ert * s * dd_c_K, 0)
 
+    # Transform to log-moneyness domain first
+    LM = domains['log_moneyness']
+    rnd_lm = rnd_k * K  # Convert to log-moneyness domain
+    pdf_lm = normalize_density(rnd_lm, dx)
+
     # Transform to other domains
-    pdfs = _transform_to_domains(rnd_k, domains)
+    pdfs = transform_to_domains(pdf_lm, domains)
 
     # Return results for requested domain
-    return _select_domain_results(pdfs, domains, return_domain)
+    pdf, cdf, x = select_domain_results(pdfs, domains, return_domain)
+
+    # Calculate moments
+    moments = get_all_moments(x, pdf)
+
+    return pdf, cdf, x, moments
 
 
 @catch_exception
@@ -433,7 +310,7 @@ def get_rnd_surface(model_results: pd.DataFrame,
     domain_params : tuple
         (min_log_moneyness, max_log_moneyness, num_points)
     return_domain : str
-        Domain for results ('log_moneyness', 'moneyness', 'returns', 'strikes', 'delta')
+        Domain for results ('log_moneyness', 'moneyness', 'returns', 'strikes')
     method : str
         Method for RND estimation ('rookley' or 'breeden')
 
@@ -453,7 +330,7 @@ def get_rnd_surface(model_results: pd.DataFrame,
         raise VolyError(f"Invalid method: {method}. Must be 'rookley' or 'breeden'")
 
     # Validate return_domain
-    valid_domains = ['log_moneyness', 'moneyness', 'returns', 'strikes', 'delta']
+    valid_domains = ['log_moneyness', 'moneyness', 'returns', 'strikes']
     if return_domain not in valid_domains:
         raise VolyError(f"Invalid return_domain: {return_domain}. Must be one of {valid_domains}")