voly 0.0.129__py3-none-any.whl → 0.0.130__py3-none-any.whl

voly/client.py

@@ -368,3 +368,49 @@ class VolyClient:
             'x_surface': x_surface,
             'moments': moments
         }
+
+    @staticmethod
+    def get_garch_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',
+                             n_fits: int = 400,
+                             simulations: int = 5000,
+                             window_length: int = 365,
+                             variate_parameters: bool = True,
+                             bandwidth: float = 0.15) -> Dict[str, Any]:
+        """
+        Generate historical density using GARCH(1,1) model and Monte Carlo simulation.
+
+        This method implements the approach from SPD Trading, using:
+        1. GARCH(1,1) model fit with sliding windows
+        2. Monte Carlo simulation with innovation resampling
+        3. Kernel density estimation of terminal prices
+
+        Parameters:
+            model_results: DataFrame with model parameters and maturities
+            df_hist: DataFrame with historical price data
+            domain_params: Tuple of (min, max, num_points) for x-domain
+            return_domain: Domain for x-axis values ('log_moneyness', 'moneyness', 'returns', 'strikes')
+            n_fits: Number of sliding windows for GARCH parameter estimation
+            simulations: Number of Monte Carlo simulations
+            window_length: Length of each sliding window for GARCH estimation
+            variate_parameters: Whether to vary GARCH parameters between simulations
+            bandwidth: Bandwidth for KDE of final density
+
+        Returns:
+            Dictionary containing pdf_surface, cdf_surface, x_surface, and moments
+        """
+        logger.info("Calculating GARCH historical density surface")
+
+        return get_garch_hd_surface(
+            model_results=model_results,
+            df_hist=df_hist,
+            domain_params=domain_params,
+            return_domain=return_domain,
+            n_fits=n_fits,
+            simulations=simulations,
+            window_length=window_length,
+            variate_parameters=variate_parameters,
+            bandwidth=bandwidth
+        )

voly/core/hd.py

@@ -205,3 +205,350 @@ def get_hd_surface(model_results: pd.DataFrame,
     moments = pd.DataFrame(all_moments).T
 
     return pdf_surface, cdf_surface, x_surface, moments
+
+
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+from typing import Dict, List, Tuple, Optional, Union, Any
+from voly.utils.logger import logger, catch_exception
+from voly.exceptions import VolyError
+
+
+class GARCHModel:
+    """
+    GARCH(1,1) model for volatility modeling and simulation.
+
+    Fits a GARCH(1,1) model to historical returns and simulates future paths
+    for historical density estimation.
+    """
+
+    def __init__(self,
+                 data: np.ndarray,
+                 data_name: str,
+                 n_fits: int = 400,
+                 window_length: int = 365,
+                 z_h: float = 0.1):
+        """
+        Initialize the GARCH model.
+
+        Args:
+            data: Array of log returns
+            data_name: Identifier for the dataset
+            n_fits: Number of sliding windows to use for parameter estimation
+            window_length: Length of each sliding window
+            z_h: Bandwidth factor for kernel density estimation of innovations
+        """
+        self.data = data
+        self.data_name = data_name
+        self.n_fits = n_fits
+        self.window_length = window_length
+        self.z_h = z_h
+
+        # Parameters to be created during fitting and simulation
+        self.parameters = None
+        self.e_process = None
+        self.z_process = None
+        self.sigma2_process = None
+        self.z_dens = None
+        self.simulated_log_returns = None
+        self.simulated_tau_mu = None
+
+    def fit(self):
+        """
+        Fit GARCH(1,1) model to historical data using sliding windows.
+
+        For each window, estimates parameters (ω, α, β) and extracts innovations.
+        """
+        from arch import arch_model
+
+        if len(self.data) < self.window_length + self.n_fits:
+            raise VolyError(
+                f"Not enough data points. Need at least {self.window_length + self.n_fits}, got {len(self.data)}")
+
+        start = self.window_length + self.n_fits
+        end = self.n_fits
+
+        parameters = np.zeros((self.n_fits, 4))
+        z_process = []
+        e_process = []
+        sigma2_process = []
+
+        logger.info(f"Fitting GARCH model with {self.n_fits} windows...")
+
+        for i in range(self.n_fits):
+            window = self.data[end - i - 1:start - i - 1]
+            data = window - np.mean(window)
+
+            model = arch_model(data, vol='GARCH', p=1, q=1)
+            GARCH_fit = model.fit(disp='off')
+
+            mu, omega, alpha, beta = [
+                GARCH_fit.params["mu"],
+                GARCH_fit.params["omega"],
+                GARCH_fit.params["alpha[1]"],
+                GARCH_fit.params["beta[1]"],
+            ]
+            parameters[i, :] = [mu, omega, alpha, beta]
+
+            if i == 0:
+                sigma2_tm1 = omega / (1 - alpha - beta)
+            else:
+                sigma2_tm1 = sigma2_process[-1]
+
+            e_t = data.tolist()[-1]  # last observed log-return
+            e_tm1 = data.tolist()[-2]  # previous observed log-return
+            sigma2_t = omega + alpha * e_tm1 ** 2 + beta * sigma2_tm1
+            z_t = e_t / np.sqrt(sigma2_t)
+
+            e_process.append(e_t)
+            z_process.append(z_t)
+            sigma2_process.append(sigma2_t)
+
+        self.parameters = parameters
+        self.e_process = e_process
+        self.z_process = z_process
+        self.sigma2_process = sigma2_process
+
+        # Kernel density estimation for innovations
+        z_dens_x = np.linspace(min(self.z_process), max(self.z_process), 500)
+        h_dyn = self.z_h * (np.max(z_process) - np.min(z_process))
+
+        # Use scipy's gaussian_kde for innovation distribution
+        kde = stats.gaussian_kde(np.array(z_process), bw_method=h_dyn)
+        z_dens_y = kde(z_dens_x)
+
+        self.z_dens = {"x": z_dens_x, "y": z_dens_y}
+
+        logger.info("GARCH model fitting complete")
+
+    def _GARCH_simulate(self, pars, horizon):
+        """
+        Simulate a single GARCH path to specified horizon.
+
+        Args:
+            pars: Tuple of (mu, omega, alpha, beta)
+            horizon: Number of steps to simulate
+
+        Returns:
+            Tuple of (sigma2_process, e_process) of simulated values
+        """
+        mu, omega, alpha, beta = pars
+        burnin = horizon * 2
+        sigma2 = [omega / (1 - alpha - beta)]
+        e = [self.data.tolist()[-1] - mu]  # last observed log-return mean adjusted
+
+        # Convert density to probability weights
+        weights = self.z_dens["y"] / np.sum(self.z_dens["y"])
+
+        for _ in range(horizon + burnin):
+            sigma2_tp1 = omega + alpha * e[-1] ** 2 + beta * sigma2[-1]
+            # Sample from the estimated innovation distribution
+            z_tp1 = np.random.choice(self.z_dens["x"], 1, p=weights)[0]
+            e_tp1 = z_tp1 * np.sqrt(sigma2_tp1)
+            sigma2.append(sigma2_tp1)
+            e.append(e_tp1)
+
+        return sigma2[-horizon:], e[-horizon:]
+
+    def _variate_pars(self, pars, bounds):
+        """
+        Add variation to GARCH parameters for simulation uncertainty.
+
+        Args:
+            pars: Array of mean parameters [mu, omega, alpha, beta]
+            bounds: Standard deviation bounds for parameters
+
+        Returns:
+            Array of slightly varied parameters
+        """
+        new_pars = []
+        for i, (par, bound) in enumerate(zip(pars, bounds)):
+            var = bound ** 2 / self.n_fits
+            new_par = np.random.normal(par, var, 1)[0]
+            if (new_par <= 0) and (i >= 1):
+                new_par = 0.01
+            new_pars.append(new_par)
+        return new_pars
+
+    def simulate_paths(self, horizon, simulations=5000, variate_parameters=True):
+        """
+        Simulate multiple GARCH paths using Monte Carlo.
+
+        Args:
+            horizon: Number of steps to simulate (days)
+            simulations: Number of Monte Carlo simulations
+            variate_parameters: Whether to add variation to GARCH parameters
+
+        Returns:
+            Tuple of (simulated_log_returns, simulated_tau_mu)
+        """
+        if self.parameters is None:
+            self.fit()
+
+        pars = np.mean(self.parameters, axis=0).tolist()  # [mu, omega, alpha, beta]
+        bounds = np.std(self.parameters, axis=0).tolist()
+
+        logger.info(f"Simulating {simulations} GARCH paths for {horizon} steps...")
+        logger.info(f"GARCH parameters: mu={pars[0]:.6f}, omega={pars[1]:.6f}, alpha={pars[2]:.6f}, beta={pars[3]:.6f}")
+
+        np.random.seed(42)  # For reproducibility
+
+        new_pars = pars.copy()  # start with unchanged parameters
+        simulated_log_returns = np.zeros(simulations)
+        simulated_tau_mu = np.zeros(simulations)
+
+        for i in range(simulations):
+            if ((i + 1) % (simulations // 10) == 0):
+                logger.info(f"Simulation progress: {i + 1}/{simulations}")
+
+            if ((i + 1) % (simulations // 20) == 0) and variate_parameters:
+                new_pars = self._variate_pars(pars, bounds)
+
+            sigma2, e = self._GARCH_simulate(new_pars, horizon)
+            simulated_log_returns[i] = np.sum(e)  # Sum log returns over horizon
+            simulated_tau_mu[i] = horizon * pars[0]  # Total drift
+
+        self.simulated_log_returns = simulated_log_returns
+        self.simulated_tau_mu = simulated_tau_mu
+
+        return simulated_log_returns, simulated_tau_mu
+
+
+@catch_exception
+def get_garch_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',
+                         n_fits: int = 400,
+                         simulations: int = 5000,
+                         window_length: int = 365,
+                         variate_parameters: bool = True,
+                         bandwidth: float = 0.15) -> Dict[str, Any]:
+    """
+    Generate historical density surface using GARCH(1,1) model and Monte Carlo simulation.
+
+    Parameters:
+        model_results: DataFrame with model parameters and maturities
+        df_hist: DataFrame with historical price data (must have 'close' column)
+        domain_params: Tuple of (min, max, num_points) for x-domain
+        return_domain: Domain for x-axis values ('log_moneyness', 'moneyness', 'returns', 'strikes')
+        n_fits: Number of sliding windows for GARCH parameter estimation
+        simulations: Number of Monte Carlo simulations
+        window_length: Length of each sliding window for GARCH estimation
+        variate_parameters: Whether to vary GARCH parameters between simulations
+        bandwidth: Bandwidth for kernel density estimation of final density
+
+    Returns:
+        Dictionary containing pdf_surface, cdf_surface, x_surface, and moments
+    """
+    # Check if required columns are present
+    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}")
+
+    # Calculate log returns from price history
+    log_returns = np.log(df_hist['close'] / df_hist['close'].shift(1)) * 100
+    log_returns = log_returns.dropna().values
+
+    pdf_surface = {}
+    cdf_surface = {}
+    x_surface = {}
+    all_moments = {}
+
+    # Process each maturity
+    for i in model_results.index:
+        # Get parameters for this maturity
+        s = model_results.loc[i, 's']  # Current spot price
+        r = model_results.loc[i, 'r']  # Risk-free rate
+        t = model_results.loc[i, 't']  # Time to maturity in years
+
+        tau_day = int(t * 365.25)  # Convert years to days
+
+        logger.info(f"Processing GARCH HD for maturity {i} (t={t:.4f} years, {tau_day} days)")
+
+        # Initialize GARCH model
+        garch_model = GARCHModel(
+            data=log_returns,
+            data_name=str(i),
+            n_fits=min(n_fits, len(log_returns) // 3),  # Ensure we have enough data
+            window_length=min(window_length, len(log_returns) // 3),
+            z_h=0.1
+        )
+
+        # Simulate paths
+        simulated_log_returns, simulated_tau_mu = garch_model.simulate_paths(
+            horizon=tau_day,
+            simulations=simulations,
+            variate_parameters=variate_parameters
+        )
+
+        # Convert to terminal prices
+        simulated_prices = s * np.exp(simulated_log_returns / 100 + simulated_tau_mu / 100)
+
+        # Convert to moneyness domain
+        simulated_moneyness = s / simulated_prices
+
+        # Get x domain grid based on requested return_domain
+        LM = np.linspace(domain_params[0], domain_params[1], domain_params[2])
+        M = np.exp(LM)  # Moneyness
+        R = M - 1  # Returns
+        K = s / M  # Strike prices
+
+        # Perform kernel density estimation in moneyness domain
+        kde = stats.gaussian_kde(simulated_moneyness, bw_method=bandwidth)
+        pdf_m = kde(M)
+
+        # Ensure density integrates to 1
+        dx = LM[1] - LM[0]
+        total_area = np.sum(pdf_m * dx)
+        pdf_m = pdf_m / total_area
+
+        # Transform to other domains as needed
+        pdf_lm = pdf_m * M  # Transform to log-moneyness domain
+        pdf_k = pdf_lm / K  # Transform to strike domain
+        pdf_r = pdf_lm / (1 + R)  # Transform to returns domain
+
+        # Calculate CDF
+        cdf = np.cumsum(pdf_lm) * dx
+        cdf = np.minimum(cdf / cdf[-1], 1.0)  # Normalize and cap at 1.0
+
+        # Select appropriate domain for return
+        if return_domain == 'log_moneyness':
+            x = LM
+            pdf = pdf_lm
+            moments = get_all_moments(x, pdf)
+        elif return_domain == 'moneyness':
+            x = M
+            pdf = pdf_m
+            moments = get_all_moments(x, pdf)
+        elif return_domain == 'returns':
+            x = R
+            pdf = pdf_r
+            moments = get_all_moments(x, pdf)
+        elif return_domain == 'strikes':
+            x = K
+            pdf = pdf_k
+            moments = get_all_moments(x, pdf)
+        else:
+            raise VolyError(f"Unsupported return_domain: {return_domain}")
+
+        # Store results
+        pdf_surface[i] = pdf
+        cdf_surface[i] = cdf
+        x_surface[i] = x
+        all_moments[i] = moments
+
+    # Create DataFrame with moments
+    moments = pd.DataFrame(all_moments).T
+
+    logger.info("GARCH historical density calculation complete")
+
+    return {
+        'pdf_surface': pdf_surface,
+        'cdf_surface': cdf_surface,
+        'x_surface': x_surface,
+        'moments': moments
+    }

{voly-0.0.129.dist-info → voly-0.0.130.dist-info}/METADATA

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

{voly-0.0.129.dist-info → voly-0.0.130.dist-info}/RECORD

@@ -1,5 +1,5 @@
 voly/__init__.py,sha256=8xyDk7rFCn_MOD5hxuv5cxxKZvBVRiSIM7TgaMPpwpw,211
-voly/client.py,sha256=CJjQzes3K6ZdzPV1JFBoXQ35_EDz05MyP26YQKJe9dc,13402
+voly/client.py,sha256=yjElxRwONsyjhYaoKQ6dpqlVJ4vppXlshE0r171ng6I,15575
 voly/exceptions.py,sha256=PBsbn1vNMvKcCJwwJ4lBO6glD85jo1h2qiEmD7ArAjs,92
 voly/formulas.py,sha256=G_soRiPwQlHy6milOAj6TdmBWr-fNZpMvm0joXAMZ90,10767
 voly/models.py,sha256=o-pHujGfr5Gn8ItckMzLI4Q8yaX9FQaV8UjCxv2zgTY,3364
@@ -7,13 +7,13 @@ 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=spxNmqw_L3xym-CcPQ_GJEpIFibsuP9bPGLZj0YhDtw,7423
+voly/core/hd.py,sha256=EgecHfptfOR39DlKQMJDxiDwJIvGIMTNPZxhnS7OayI,19957
 voly/core/interpolate.py,sha256=JkK172-FXyhesW3hY4pEeuJWG3Bugq7QZXbeKoRpLuo,5305
 voly/core/rnd.py,sha256=0VE77lxesx_BPAO46QwKpcauZNaHnPTiDhmRbSURn3c,10022
 voly/utils/__init__.py,sha256=E05mWatyC-PDOsCxQV1p5Xi1IgpOomxrNURyCx_gB-w,200
 voly/utils/logger.py,sha256=4-_2bVJmq17Q0d7Rd2mPg1AeR8gxv6EPvcmBDMFWcSM,1744
-voly-0.0.129.dist-info/licenses/LICENSE,sha256=wcHIVbE12jfcBOai_wqBKY6xvNQU5E909xL1zZNq_2Q,1065
-voly-0.0.129.dist-info/METADATA,sha256=Rz2f3yO-_gVqp17STAGQtZYHTOio5Gcwda-qd3njTgE,4115
-voly-0.0.129.dist-info/WHEEL,sha256=DK49LOLCYiurdXXOXwGJm6U4DkHkg4lcxjhqwRa0CP4,91
-voly-0.0.129.dist-info/top_level.txt,sha256=ZfLw2sSxF-LrKAkgGjOmeTcw6_gD-30zvtdEY5W4B7c,5
-voly-0.0.129.dist-info/RECORD,,
+voly-0.0.130.dist-info/licenses/LICENSE,sha256=wcHIVbE12jfcBOai_wqBKY6xvNQU5E909xL1zZNq_2Q,1065
+voly-0.0.130.dist-info/METADATA,sha256=d7uTEFck6kosnM29aDW0jyg8g8CgPNo9PD_a7yZABVw,4115
+voly-0.0.130.dist-info/WHEEL,sha256=DK49LOLCYiurdXXOXwGJm6U4DkHkg4lcxjhqwRa0CP4,91
+voly-0.0.130.dist-info/top_level.txt,sha256=ZfLw2sSxF-LrKAkgGjOmeTcw6_gD-30zvtdEY5W4B7c,5
+voly-0.0.130.dist-info/RECORD,,