voly 0.0.156__py3-none-any.whl → 0.0.157__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/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
+    # Get scaled returns
+    scaled_returns, dte_returns = calculate_historical_returns(df_hist, n_periods)
 
-    # 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)
+    # 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,149 @@ 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
+
+    logger.info(f"Estimated degrees of freedom for t-distribution: {df:.2f}")
+
+    # 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 +335,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 +359,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 +400,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 +422,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 +436,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-0.0.156.dist-info → voly-0.0.157.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voly
-Version: 0.0.156
+Version: 0.0.157
 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.157.dist-info}/RECORD

@@ -1,5 +1,5 @@
 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/models.py,sha256=o-pHujGfr5Gn8ItckMzLI4Q8yaX9FQaV8UjCxv2zgTY,3364
@@ -7,14 +7,14 @@ 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/fit.py,sha256=Tb9eeG7e_2dQTcqt6aqEwFrZdy6jR9rSNqe6tzOdVhQ,9245
-voly/core/hd.py,sha256=gQgph4JFv6xbgm82uUf_ek7JTBMkN09CdQilpJ_lPbM,8919
+voly/core/hd.py,sha256=kAQO2ft6vmobW60mokhoZbzVElYC_wy1OeBXhmeCtAg,14850
 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.157.dist-info/licenses/LICENSE,sha256=wcHIVbE12jfcBOai_wqBKY6xvNQU5E909xL1zZNq_2Q,1065
+voly-0.0.157.dist-info/METADATA,sha256=5RTJLbGrsh2EQQ4jTBqIGoYF6UDI4_4UnRHsSEDSMM8,4115
+voly-0.0.157.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+voly-0.0.157.dist-info/top_level.txt,sha256=ZfLw2sSxF-LrKAkgGjOmeTcw6_gD-30zvtdEY5W4B7c,5
+voly-0.0.157.dist-info/RECORD,,