voly 0.0.155__py3-none-any.whl → 0.0.157__py3-none-any.whl

voly/client.py

@@ -306,7 +306,8 @@ 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') -> Dict[str, Any]:
+                        method: str = 'rookley',
+                        centered: bool = False) -> Dict[str, Any]:
         """
         Generate risk-neutral density surface from volatility surface parameters.
 
@@ -315,6 +316,7 @@ class VolyClient:
         - 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')
+        - centered: Whether to center distributions at their modes (peaks)
 
         Returns:
         - Dictionary with pdf_surface, cdf_surface, x_surface, and moments
@@ -325,7 +327,8 @@ class VolyClient:
             model_results=model_results,
             domain_params=domain_params,
             return_domain=return_domain,
-            method=method
+            method=method,
+            centered=centered
         )
 
     # -------------------------------------------------------------------------
@@ -349,7 +352,6 @@ class VolyClient:
         Returns:
         - Historical price data with OHLCV columns and datetime index
         """
-
         return get_historical_data(
             currency=currency,
             lookback_days=lookback_days,
@@ -361,24 +363,30 @@ class VolyClient:
     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]:
+                       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
+            return_domain=return_domain,
+            method=method,
+            centered=centered
         )

voly/core/hd.py

@@ -9,10 +9,17 @@ 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
-from voly.utils.density import prepare_domains, normalize_density, transform_to_domains, select_domain_results
+from voly.utils.density import (
+    prepare_domains,
+    normalize_density,
+    transform_to_domains,
+    select_domain_results,
+    center_distributions
+)
 
 
 @catch_exception
@@ -83,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,
@@ -114,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)
@@ -145,13 +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') -> Dict[str, Any]:
+                   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:
     -----------
@@ -163,6 +335,10 @@ 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)
 
     Returns:
     --------
@@ -183,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))
@@ -208,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,
@@ -230,16 +422,21 @@ 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:
+        pdf_surface, cdf_surface = center_distributions(pdf_surface, cdf_surface, x_surface)
+        logger.info("Distributions have been centered at their modes")
 
     # 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/core/rnd.py

@@ -11,7 +11,13 @@ from voly.exceptions import VolyError
 from voly.models import SVIModel
 from voly.formulas import bs, d1, d2
 from scipy import stats
-from voly.utils.density import prepare_domains, normalize_density, transform_to_domains, select_domain_results
+from voly.utils.density import (
+    prepare_domains,
+    normalize_density,
+    transform_to_domains,
+    select_domain_results,
+    center_distributions
+)
 
 
 @catch_exception
@@ -299,7 +305,8 @@ def get_all_moments(x, pdf, model_params=None):
 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') -> Dict[str, Any]:
+                    method: str = 'rookley',
+                    centered: bool = False) -> Dict[str, Any]:
     """
     Generate risk-neutral density surface from volatility surface parameters.
 
@@ -313,6 +320,8 @@ def get_rnd_surface(model_results: pd.DataFrame,
         Domain for results ('log_moneyness', 'moneyness', 'returns', 'strikes')
     method : str
         Method for RND estimation ('rookley' or 'breeden')
+    centered : bool
+        Whether to center distributions at their modes (peaks)
 
     Returns:
     --------
@@ -379,6 +388,11 @@ def get_rnd_surface(model_results: pd.DataFrame,
     if not pdf_surface:
         raise VolyError("No valid densities could be calculated. Check your input data.")
 
+    # Center distributions if requested
+    if centered:
+        pdf_surface, cdf_surface = center_distributions(pdf_surface, cdf_surface, x_surface)
+        logger.info("Distributions have been centered at their modes")
+
     # Create DataFrame with moments
     moments = pd.DataFrame(all_moments).T
 

voly/utils/density.py

@@ -7,7 +7,7 @@ densities across different domains, used by both RND and HD calculations.
 
 import numpy as np
 from typing import Dict, Tuple, List, Any
-from scipy import stats
+from scipy import stats, interpolate
 from voly.utils.logger import catch_exception
 from voly.formulas import d1, d2
 
@@ -153,3 +153,52 @@ def select_domain_results(pdfs: Dict[str, np.ndarray],
     cdf = pdfs['cdf']
 
     return pdf, cdf, x
+
+
+@catch_exception
+def center_distributions(pdf_surface: Dict[str, np.ndarray],
+                         cdf_surface: Dict[str, np.ndarray],
+                         x_surface: Dict[str, np.ndarray]) -> Tuple[Dict[str, np.ndarray], Dict[str, np.ndarray]]:
+    """
+    Center distributions so their peaks (modes) are at x=0 while maintaining the same domain.
+
+    This function shifts each distribution so that its mode (peak) is at x=0,
+    without changing the domain range. It uses interpolation to recalculate
+    the PDF and CDF values on the original domain.
+
+    Parameters:
+    -----------
+    pdf_surface : Dict[str, np.ndarray]
+        Dictionary of PDFs by maturity
+    cdf_surface : Dict[str, np.ndarray]
+        Dictionary of CDFs by maturity
+    x_surface : Dict[str, np.ndarray]
+        Dictionary of x-domains by maturity
+
+    Returns:
+    --------
+    Tuple[Dict[str, np.ndarray], Dict[str, np.ndarray]]
+        (centered_pdf_surface, centered_cdf_surface)
+    """
+    centered_pdf_surface = {}
+    centered_cdf_surface = {}
+
+    for maturity in pdf_surface.keys():
+        pdf = pdf_surface[maturity]
+        cdf = cdf_surface[maturity]
+        x = x_surface[maturity]
+
+        # Find the mode (peak) of the distribution
+        mode_idx = np.argmax(pdf)
+        mode = x[mode_idx]
+
+        # Create interpolation functions for the original distributions
+        f_pdf = interpolate.interp1d(x, pdf, bounds_error=False, fill_value=0)
+        f_cdf = interpolate.interp1d(x, cdf, bounds_error=False, fill_value=0)
+
+        # Evaluate the centered distributions on the original domain
+        # g(x) = f(x + mode) shifts the distribution so that the peak is at x=0
+        centered_pdf_surface[maturity] = f_pdf(x + mode)
+        centered_cdf_surface[maturity] = f_cdf(x + mode)
+
+    return centered_pdf_surface, centered_cdf_surface

{voly-0.0.155.dist-info → voly-0.0.157.dist-info}/METADATA

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

{voly-0.0.155.dist-info → voly-0.0.157.dist-info}/RECORD

@@ -1,5 +1,5 @@
 voly/__init__.py,sha256=8xyDk7rFCn_MOD5hxuv5cxxKZvBVRiSIM7TgaMPpwpw,211
-voly/client.py,sha256=csTdngnF2uvRfBLGTPXSUKSgJbbK-VGmToqu4Sldftc,14271
+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=_JLdeNlnwZPafs4oRO_ydGrG6aqgcZKo_HQ503Ifo0s,8525
+voly/core/hd.py,sha256=kAQO2ft6vmobW60mokhoZbzVElYC_wy1OeBXhmeCtAg,14850
 voly/core/interpolate.py,sha256=JkK172-FXyhesW3hY4pEeuJWG3Bugq7QZXbeKoRpLuo,5305
-voly/core/rnd.py,sha256=3rhIA2rN2jcw2JvXDFsZgA62RZVgepshNculwo2X9zc,12912
+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=fUJf1AsbyqwxBlhAP53RvcI4KxVEmRRtXXW1WSMFTFE,4017
+voly/utils/density.py,sha256=q0fX4im9TGwMCZ32Hzdv8CNh56KnJo8bmG5w0gVWZH8,5879
 voly/utils/logger.py,sha256=4-_2bVJmq17Q0d7Rd2mPg1AeR8gxv6EPvcmBDMFWcSM,1744
-voly-0.0.155.dist-info/licenses/LICENSE,sha256=wcHIVbE12jfcBOai_wqBKY6xvNQU5E909xL1zZNq_2Q,1065
-voly-0.0.155.dist-info/METADATA,sha256=bXTB5FkOkzjIQ-70pWR_ccn5HuFtQIbd87tqsP47QsU,4115
-voly-0.0.155.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-voly-0.0.155.dist-info/top_level.txt,sha256=ZfLw2sSxF-LrKAkgGjOmeTcw6_gD-30zvtdEY5W4B7c,5
-voly-0.0.155.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,,