voly 0.0.156__py3-none-any.whl → 0.0.158__py3-none-any.whl

voly/client.py

@@ -364,26 +364,29 @@ class VolyClient:
                        df_hist: pd.DataFrame,
                        domain_params: Tuple[float, float, int] = (-1.5, 1.5, 1000),
                        return_domain: str = 'log_moneyness',
+                       method: str = 'normal',
                        centered: bool = False) -> Dict[str, Any]:
         """
-        Generate historical density surface using normal distributions.
+        Generate historical density surface using various distribution methods.
 
         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')
+        - method: Method for density estimation ('normal', 'student_t', 'kde')
         - centered: Whether to center distributions at their modes (peaks)
 
         Returns:
         - Dictionary with pdf_surface, cdf_surface, x_surface, and moments
         """
-        logger.info("Calculating HD surface")
+        logger.info(f"Calculating HD surface using {method} method")
 
         return get_hd_surface(
             model_results=model_results,
             df_hist=df_hist,
             domain_params=domain_params,
             return_domain=return_domain,
+            method=method,
             centered=centered
         )

voly/core/data.py

@@ -232,6 +232,109 @@ def process_option_chain(df: pd.DataFrame, currency: str) -> pd.DataFrame:
     return df
 
 
+@catch_exception
+def process_order_book_depth(option_chain, max_depth=5):
+    """
+    Process the order book depth data to enhance option pricing and weighting.
+
+    Args:
+        option_chain: DataFrame containing option data with 'bids' and 'asks' columns
+        max_depth: Maximum number of levels to consider from the order book
+
+    Returns:
+        Enhanced option_chain with additional columns for depth analysis
+    """
+    # Create new columns for depth analysis
+    option_chain['vwap_bid'] = float('nan')
+    option_chain['vwap_ask'] = float('nan')
+    option_chain['vwap_mid'] = float('nan')
+    option_chain['depth_bid_qty'] = float('nan')
+    option_chain['depth_ask_qty'] = float('nan')
+    option_chain['vwap_bid_iv'] = float('nan')
+    option_chain['vwap_ask_iv'] = float('nan')
+    option_chain['vwap_mid_iv'] = float('nan')
+    option_chain['depth_liquidity'] = float('nan')
+
+    for idx, row in option_chain.iterrows():
+        s = row['underlying_price']
+        k = row['strikes']
+        t = row['t']
+        r = row['interest_rate'] if 'interest_rate' in row else 0.0
+        option_type = 'C' if row['option_type'] == 'call' else 'P'
+
+        # Process bid side
+        if 'bids' in row and isinstance(row['bids'], list) and len(row['bids']) > 0:
+            # Clean up the bid data
+            clean_bids = []
+            for bid in row['bids'][:max_depth]:  # Limit to max_depth levels
+                if len(bid) >= 3:
+                    # Extract price and quantity, removing 'new' if present
+                    price = float(bid[1]) if bid[0] == 'new' else float(bid[0])
+                    qty = float(bid[2]) if bid[0] == 'new' else float(bid[1])
+                    clean_bids.append((price, qty))
+
+            if clean_bids:
+                # Calculate volume-weighted average price
+                total_qty = sum(qty for _, qty in clean_bids)
+                vwap_bid = sum(price * qty for price, qty in clean_bids) / total_qty if total_qty > 0 else float('nan')
+
+                # Calculate IV for VWAP
+                try:
+                    vwap_bid_iv = voly.iv(vwap_bid * s, s, k, r, t, option_type)
+                except:
+                    vwap_bid_iv = float('nan')
+
+                option_chain.at[idx, 'vwap_bid'] = vwap_bid
+                option_chain.at[idx, 'depth_bid_qty'] = total_qty
+                option_chain.at[idx, 'vwap_bid_iv'] = vwap_bid_iv
+
+        # Process ask side
+        if 'asks' in row and isinstance(row['asks'], list) and len(row['asks']) > 0:
+            # Clean up the ask data
+            clean_asks = []
+            for ask in row['asks'][:max_depth]:  # Limit to max_depth levels
+                if len(ask) >= 3:
+                    # Extract price and quantity, removing 'new' if present
+                    price = float(ask[1]) if ask[0] == 'new' else float(ask[0])
+                    qty = float(ask[2]) if ask[0] == 'new' else float(ask[1])
+                    clean_asks.append((price, qty))
+
+            if clean_asks:
+                # Calculate volume-weighted average price
+                total_qty = sum(qty for _, qty in clean_asks)
+                vwap_ask = sum(price * qty for price, qty in clean_asks) / total_qty if total_qty > 0 else float('nan')
+
+                # Calculate IV for VWAP
+                try:
+                    vwap_ask_iv = voly.iv(vwap_ask * s, s, k, r, t, option_type)
+                except:
+                    vwap_ask_iv = float('nan')
+
+                option_chain.at[idx, 'vwap_ask'] = vwap_ask
+                option_chain.at[idx, 'depth_ask_qty'] = total_qty
+                option_chain.at[idx, 'vwap_ask_iv'] = vwap_ask_iv
+
+        # Calculate mid VWAP if both bid and ask are available
+        if not np.isnan(option_chain.at[idx, 'vwap_bid']) and not np.isnan(option_chain.at[idx, 'vwap_ask']):
+            vwap_mid = (option_chain.at[idx, 'vwap_bid'] + option_chain.at[idx, 'vwap_ask']) / 2
+
+            # Calculate IV for mid VWAP
+            try:
+                vwap_mid_iv = voly.iv(vwap_mid * s, s, k, r, t, option_type)
+            except:
+                vwap_mid_iv = float('nan')
+
+            option_chain.at[idx, 'vwap_mid'] = vwap_mid
+            option_chain.at[idx, 'vwap_mid_iv'] = vwap_mid_iv
+
+        # Calculate depth liquidity (sum of bid and ask quantities)
+        bid_qty = option_chain.at[idx, 'depth_bid_qty'] if not np.isnan(option_chain.at[idx, 'depth_bid_qty']) else 0
+        ask_qty = option_chain.at[idx, 'depth_ask_qty'] if not np.isnan(option_chain.at[idx, 'depth_ask_qty']) else 0
+        option_chain.at[idx, 'depth_liquidity'] = bid_qty + ask_qty
+
+    return option_chain
+
+
 @catch_exception
 async def fetch_option_chain(exchange: str = 'deribit',
                              currency: str = 'BTC',

voly/core/hd.py

@@ -9,6 +9,7 @@ import pandas as pd
 import datetime as dt
 from typing import Dict, Tuple, Any, Optional, List
 from scipy import stats
+from scipy.stats import t as student_t
 from voly.utils.logger import logger, catch_exception
 from voly.exceptions import VolyError
 from voly.core.rnd import get_all_moments
@@ -89,6 +90,42 @@ def get_historical_data(currency: str,
     return df_hist
 
 
+@catch_exception
+def calculate_historical_returns(df_hist: pd.DataFrame, n_periods: int) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Calculate historical returns and scale them appropriately.
+
+    Parameters:
+    -----------
+    df_hist : pd.DataFrame
+        Historical price data
+    n_periods : int
+        Number of periods to scale returns
+
+    Returns:
+    --------
+    Tuple[np.ndarray, np.ndarray]
+        (scaled_returns, raw_returns) tuple
+    """
+    # Calculate log returns
+    raw_returns = np.log(df_hist['close'] / df_hist['close'].shift(1)).dropna().values
+
+    # Filter historical data based on n_periods
+    if len(raw_returns) < n_periods:
+        logger.warning(f"Not enough historical data, using all {len(raw_returns)} points available")
+        dte_returns = raw_returns
+    else:
+        dte_returns = raw_returns[-n_periods:]
+
+    # Calculate scaling factor
+    scaling_factor = np.sqrt(n_periods)
+
+    # Scale returns for the maturity
+    scaled_returns = dte_returns * scaling_factor
+
+    return scaled_returns, dte_returns
+
+
 @catch_exception
 def calculate_normal_hd(df_hist: pd.DataFrame,
                         t: float,
@@ -120,19 +157,12 @@ def calculate_normal_hd(df_hist: pd.DataFrame,
     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:]
+    # Get scaled returns
+    scaled_returns, dte_returns = calculate_historical_returns(df_hist, 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)
+    # Calculate parameters for normal distribution
+    mu_scaled = np.mean(scaled_returns)
+    sigma_scaled = np.std(scaled_returns)
 
     # Apply Girsanov adjustment to shift to risk-neutral measure
     expected_risk_neutral_mean = (r - 0.5 * sigma_scaled ** 2) * np.sqrt(t)
@@ -151,14 +181,147 @@ def calculate_normal_hd(df_hist: pd.DataFrame,
     return pdfs
 
 
+@catch_exception
+def calculate_student_t_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 Student's t-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']
+
+    # Get scaled returns
+    scaled_returns, dte_returns = calculate_historical_returns(df_hist, n_periods)
+
+    # Calculate parameters for t-distribution
+    mu_scaled = np.mean(scaled_returns)
+    sigma_scaled = np.std(scaled_returns)
+
+    # Estimate excess kurtosis and calculate degrees of freedom
+    kurtosis = stats.kurtosis(dte_returns, fisher=True)
+
+    # Convert kurtosis to degrees of freedom (df)
+    # For t-distribution: kurtosis = 6/(df-4) for df > 4
+    # Solve for df: df = 6/kurtosis + 4
+    if kurtosis > 0:
+        df = min(max(6 / kurtosis + 4, 3), 30)  # Bound between 3 and 30
+    else:
+        df = 5  # Default value if kurtosis calculation fails
+
+    # 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
+
+    # Scale parameter for t-distribution
+    # In scipy's t-distribution, the scale parameter is different from normal std
+    # For t-distribution: variance = (df/(df-2)) * scale^2
+    # So: scale = sqrt(variance * (df-2)/df)
+    scale = sigma_scaled * np.sqrt((df - 2) / df) if df > 2 else sigma_scaled
+
+    # Calculate PDF using t-distribution in log-moneyness domain
+    pdf_lm = student_t.pdf(LM, df=df, loc=mu_rn, scale=scale)
+
+    # 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 calculate_kde_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 Kernel Density Estimation (KDE) 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']
+
+    # Get scaled returns
+    scaled_returns, dte_returns = calculate_historical_returns(df_hist, n_periods)
+
+    # Calculate parameters (for Girsanov adjustment)
+    mu_scaled = np.mean(scaled_returns)
+    sigma_scaled = np.std(scaled_returns)
+
+    # 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
+
+    # Shift the returns to be risk-neutral
+    rn_returns = scaled_returns - adjustment + expected_risk_neutral_mean
+
+    # Fit KDE model using scipy's gaussian_kde with Scott's rule for bandwidth
+    kde = stats.gaussian_kde(rn_returns, bw_method='scott')
+
+    # Evaluate KDE at points in log-moneyness domain
+    pdf_lm = kde(LM)
+
+    # 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',
+                   method: str = 'normal',
                    centered: bool = False) -> Dict[str, Any]:
     """
-    Generate historical density surface using normal distributions.
+    Generate historical density surface using various distribution methods.
 
     Parameters:
     -----------
@@ -170,6 +333,8 @@ def get_hd_surface(model_results: pd.DataFrame,
         (min_log_moneyness, max_log_moneyness, num_points)
     return_domain : str
         Domain for results ('log_moneyness', 'moneyness', 'returns', 'strikes')
+    method : str
+        Method for estimating density ('normal', 'student_t', 'kde')
     centered : bool
         Whether to center distributions at their modes (peaks)
 
@@ -192,6 +357,22 @@ def get_hd_surface(model_results: pd.DataFrame,
     if return_domain not in valid_domains:
         raise VolyError(f"Invalid return_domain: {return_domain}. Must be one of {valid_domains}")
 
+    # Validate method
+    valid_methods = ['normal', 'student_t', 'kde']
+    if method not in valid_methods:
+        raise VolyError(f"Invalid method: {method}. Must be one of {valid_methods}")
+
+    # Select calculation function based on method
+    if method == 'student_t':
+        calculate_hd = calculate_student_t_hd
+        logger.info("Using Student's t-distribution for historical density")
+    elif method == 'kde':
+        calculate_hd = calculate_kde_hd
+        logger.info("Using Kernel Density Estimation (KDE) for historical density")
+    else:  # default to normal
+        calculate_hd = calculate_normal_hd
+        logger.info("Using normal distribution for historical density")
+
     # 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))
@@ -217,8 +398,8 @@ def get_hd_surface(model_results: pd.DataFrame,
             # Prepare domains
             domains = prepare_domains(domain_params, s)
 
-            # Calculate density
-            pdfs = calculate_normal_hd(
+            # Calculate density using the selected method
+            pdfs = calculate_hd(
                 df_hist=df_hist,
                 t=t,
                 r=r,
@@ -239,11 +420,11 @@ def get_hd_surface(model_results: pd.DataFrame,
             all_moments[i] = moments
 
         except Exception as e:
-            logger.warning(f"Failed to calculate HD for maturity {i}: {str(e)}")
+            logger.warning(f"Failed to calculate HD for maturity {i} using {method} method: {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.")
+        raise VolyError(f"No valid densities could be calculated using {method} method. Check your input data.")
 
     # Center distributions if requested
     if centered:
@@ -253,7 +434,7 @@ def get_hd_surface(model_results: pd.DataFrame,
     # Create DataFrame with moments
     moments = pd.DataFrame(all_moments).T
 
-    logger.info("Historical density calculation complete using normal distribution")
+    logger.info(f"Historical density calculation complete using {method} distribution")
 
     return {
         'pdf_surface': pdf_surface,

voly/formulas.py

@@ -251,7 +251,6 @@ def iv(option_price: float, s: float, K: float, r: float, t: float,
         K=K,
         t=t,
         r=r,
-        q=0.0,  # Assume zero dividend yield
         flag=flag
     )
     return iv_value

{voly-0.0.156.dist-info → voly-0.0.158.dist-info}/METADATA

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

{voly-0.0.156.dist-info → voly-0.0.158.dist-info}/RECORD

@@ -1,20 +1,20 @@
 voly/__init__.py,sha256=8xyDk7rFCn_MOD5hxuv5cxxKZvBVRiSIM7TgaMPpwpw,211
-voly/client.py,sha256=ZhHpGSTDsU62FA18EUlkXeWZOul4QSR2hV2P_eyVMwM,14577
+voly/client.py,sha256=-yE1_cBvjkK-BO_kKCYtn4WPbNOhAzT0hsfykU5LvQQ,14761
 voly/exceptions.py,sha256=PBsbn1vNMvKcCJwwJ4lBO6glD85jo1h2qiEmD7ArAjs,92
-voly/formulas.py,sha256=G_soRiPwQlHy6milOAj6TdmBWr-fNZpMvm0joXAMZ90,10767
+voly/formulas.py,sha256=oXttz6cnn1a_WXBVIl4n38XdGUsd4ZSM4Dg6hM1tUG8,10722
 voly/models.py,sha256=o-pHujGfr5Gn8ItckMzLI4Q8yaX9FQaV8UjCxv2zgTY,3364
 voly/core/__init__.py,sha256=bu6fS2I1Pj9fPPnl-zY3L7NqrZSY5Zy6NY2uMUvdhKs,183
 voly/core/charts.py,sha256=E21OZB5lTY4YL2flgaFJ6s5g3_ExtAQT2zryZZxLPyM,12735
-voly/core/data.py,sha256=pDeuYhP0GX4RbtlqByvsE3rfHcIkix0BU5MLW8sKIeI,8935
+voly/core/data.py,sha256=_iXiZ7N08J9V3EUG538QPX3lW_Yo8mEsk4VH9E9GtwQ,13581
 voly/core/fit.py,sha256=Tb9eeG7e_2dQTcqt6aqEwFrZdy6jR9rSNqe6tzOdVhQ,9245
-voly/core/hd.py,sha256=gQgph4JFv6xbgm82uUf_ek7JTBMkN09CdQilpJ_lPbM,8919
+voly/core/hd.py,sha256=UFAyLncNUHivpPAcko6IK1bC55mudVtdlRFfXp63HXE,14771
 voly/core/interpolate.py,sha256=JkK172-FXyhesW3hY4pEeuJWG3Bugq7QZXbeKoRpLuo,5305
 voly/core/rnd.py,sha256=GoC3m1Q46Wnk5tV_mstr-3_aktHeue6BBLh4DQTciW0,13307
 voly/utils/__init__.py,sha256=E05mWatyC-PDOsCxQV1p5Xi1IgpOomxrNURyCx_gB-w,200
 voly/utils/density.py,sha256=q0fX4im9TGwMCZ32Hzdv8CNh56KnJo8bmG5w0gVWZH8,5879
 voly/utils/logger.py,sha256=4-_2bVJmq17Q0d7Rd2mPg1AeR8gxv6EPvcmBDMFWcSM,1744
-voly-0.0.156.dist-info/licenses/LICENSE,sha256=wcHIVbE12jfcBOai_wqBKY6xvNQU5E909xL1zZNq_2Q,1065
-voly-0.0.156.dist-info/METADATA,sha256=B6HFS29vi8kBKECuW0KrUgUYAWkw522hD3Bfs55CN1A,4115
-voly-0.0.156.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-voly-0.0.156.dist-info/top_level.txt,sha256=ZfLw2sSxF-LrKAkgGjOmeTcw6_gD-30zvtdEY5W4B7c,5
-voly-0.0.156.dist-info/RECORD,,
+voly-0.0.158.dist-info/licenses/LICENSE,sha256=wcHIVbE12jfcBOai_wqBKY6xvNQU5E909xL1zZNq_2Q,1065
+voly-0.0.158.dist-info/METADATA,sha256=GkUeHlcZ1_2FLecO_vu1FX5_aGC5HqzTwwLQ1BnK_Cc,4115
+voly-0.0.158.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+voly-0.0.158.dist-info/top_level.txt,sha256=ZfLw2sSxF-LrKAkgGjOmeTcw6_gD-30zvtdEY5W4B7c,5
+voly-0.0.158.dist-info/RECORD,,