voly 0.0.1__py3-none-any.whl

voly/core/interpolate.py

@@ -0,0 +1,221 @@
+"""
+Surface interpolation module for the Voly package.
+
+This module handles interpolation of implied volatility surfaces
+across both moneyness and time dimensions.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import List, Tuple, Dict, Optional, Union, Any
+from scipy.interpolate import interp1d, pchip_interpolate
+from voly.utils.logger import logger, catch_exception
+from voly.exceptions import InterpolationError
+from voly.models import SVIModel
+
+
+@catch_exception
+def interpolate_surface_time(
+        moneyness_grid: np.ndarray,
+        expiries: np.ndarray,
+        surface_values: np.ndarray,
+        target_expiries: np.ndarray,
+        method: str = 'cubic'
+) -> np.ndarray:
+    """
+    Interpolate the surface across the time dimension.
+
+    Parameters:
+    - moneyness_grid: Array of log-moneyness values
+    - expiries: Array of expiry times (in years)
+    - surface_values: 2D array of values to interpolate (rows=expiries, cols=moneyness)
+    - target_expiries: Array of target expiry times to interpolate to
+    - method: Interpolation method ('linear', 'cubic', 'pchip', etc.)
+
+    Returns:
+    - 2D array of interpolated values (rows=target_expiries, cols=moneyness)
+    """
+    if len(expiries) < 2:
+        raise InterpolationError("At least two expiries are required for time interpolation")
+
+    # Initialize the output array
+    interpolated_surface = np.zeros((len(target_expiries), len(moneyness_grid)))
+
+    # For each moneyness point, interpolate across time
+    for i in range(len(moneyness_grid)):
+        if method == 'pchip':
+            # Use PCHIP (Piecewise Cubic Hermite Interpolating Polynomial)
+            interpolated_values = pchip_interpolate(expiries, surface_values[:, i], target_expiries)
+        else:
+            # Use regular interpolation (linear, cubic, etc.)
+            interp_func = interp1d(expiries, surface_values[:, i], kind=method, bounds_error=False,
+                                   fill_value='extrapolate')
+            interpolated_values = interp_func(target_expiries)
+
+        interpolated_surface[:, i] = interpolated_values
+
+    return interpolated_surface
+
+
+@catch_exception
+def create_target_expiries(
+        min_dte: float,
+        max_dte: float,
+        num_points: int = 10,
+        specific_days: Optional[List[int]] = None
+) -> np.ndarray:
+    """
+    Create a grid of target expiry days for interpolation.
+
+    Parameters:
+    - min_dte: Minimum days to expiry
+    - max_dte: Maximum days to expiry
+    - num_points: Number of points for regular grid
+    - specific_days: Optional list of specific days to include (e.g., [7, 30, 90, 180])
+
+    Returns:
+    - Array of target expiry times in years
+    """
+    # Create regular grid in days
+    if specific_days is not None:
+        # Filter specific days to be within range
+        days = np.array([d for d in specific_days if min_dte <= d <= max_dte])
+        if len(days) == 0:
+            logger.warning("No specific days within range, using regular grid")
+            days = np.linspace(min_dte, max_dte, num_points)
+    else:
+        # Use regular grid
+        days = np.linspace(min_dte, max_dte, num_points)
+
+    # Convert to years
+    years = days / 365.25
+
+    return years
+
+
+@catch_exception
+def interpolate_svi_parameters(
+        raw_param_matrix: pd.DataFrame,
+        target_expiries_years: np.ndarray,
+        method: str = 'cubic'
+) -> pd.DataFrame:
+    """
+    Interpolate SVI parameters across time.
+
+    Parameters:
+    - raw_param_matrix: Matrix of SVI parameters with maturity names as columns
+    - target_expiries_years: Array of target expiry times (in years)
+    - method: Interpolation method ('linear', 'cubic', 'pchip', etc.)
+
+    Returns:
+    - Matrix of interpolated SVI parameters
+    """
+    # Get expiry times in years from the parameter matrix
+    yte_values = raw_param_matrix.attrs['yte_values']
+    dte_values = raw_param_matrix.attrs['dte_values']
+
+    # Sort maturity names by DTE
+    maturity_names = sorted(yte_values.keys(), key=lambda x: dte_values[x])
+
+    # Extract expiry times in order
+    expiry_years = np.array([yte_values[m] for m in maturity_names])
+
+    # Check if we have enough points for interpolation
+    if len(expiry_years) < 2:
+        raise InterpolationError("At least two expiries are required for interpolation")
+
+    # Create new parameter matrix for interpolated values
+    interp_param_matrix = pd.DataFrame(
+        columns=[f"t{i:.2f}" for i in target_expiries_years],
+        index=SVIModel.PARAM_NAMES
+    )
+
+    # For each SVI parameter, interpolate across time
+    for param in SVIModel.PARAM_NAMES:
+        param_values = np.array([raw_param_matrix.loc[param, m] for m in maturity_names])
+
+        if method == 'pchip':
+            interpolated_values = pchip_interpolate(expiry_years, param_values, target_expiries_years)
+        else:
+            interp_func = interp1d(expiry_years, param_values, kind=method, bounds_error=False,
+                                   fill_value='extrapolate')
+            interpolated_values = interp_func(target_expiries_years)
+
+        # Store interpolated values
+        for i, t in enumerate(target_expiries_years):
+            interp_param_matrix.loc[param, f"t{t:.2f}"] = interpolated_values[i]
+
+    # Create matching DTE values for convenience
+    interp_dte_values = target_expiries_years * 365.25
+
+    # Store YTE and DTE as attributes in the DataFrame for reference
+    interp_param_matrix.attrs['yte_values'] = {f"t{t:.2f}": t for t in target_expiries_years}
+    interp_param_matrix.attrs['dte_values'] = {f"t{t:.2f}": t * 365.25 for t in target_expiries_years}
+
+    return interp_param_matrix
+
+
+@catch_exception
+def interpolate_model(
+        fit_results: Dict[str, Any],
+        specific_days: Optional[List[int]] = None,
+        num_points: int = 10,
+        method: str = 'cubic'
+) -> Dict[str, Any]:
+    """
+    Interpolate a fitted model to specific days to expiry.
+
+    Parameters:
+    - fit_results: Dictionary with fitting results from fit_model()
+    - specific_days: Optional list of specific days to include (e.g., [7, 30, 90, 180])
+    - num_points: Number of points for regular grid if specific_days is None
+    - method: Interpolation method ('linear', 'cubic', 'pchip', etc.)
+
+    Returns:
+    - Dictionary with interpolation results
+    """
+    # Extract required data from fit results
+    raw_param_matrix = fit_results['raw_param_matrix']
+    moneyness_grid = fit_results['moneyness_grid']
+
+    # Get min and max DTE from the original data
+    dte_values = list(raw_param_matrix.attrs['dte_values'].values())
+    min_dte = min(dte_values)
+    max_dte = max(dte_values)
+
+    # Create target expiry grid
+    target_expiries_years = create_target_expiries(min_dte, max_dte, num_points, specific_days)
+
+    # Interpolate SVI parameters
+    interp_param_matrix = interpolate_svi_parameters(raw_param_matrix, target_expiries_years, method)
+
+    # Generate implied volatility surface from interpolated parameters
+    iv_surface = {}
+    for maturity_name, yte in interp_param_matrix.attrs['yte_values'].items():
+        svi_params = interp_param_matrix[maturity_name].values
+        w_svi = [SVIModel.svi(x, *svi_params) for x in moneyness_grid]
+        iv_surface[yte] = np.sqrt(np.array(w_svi) / yte)
+
+    # Convert to Jump-Wing parameters for the interpolated maturities
+    jw_param_matrix = pd.DataFrame(
+        columns=interp_param_matrix.columns,
+        index=SVIModel.JW_PARAM_NAMES
+    )
+
+    for maturity_name, yte in interp_param_matrix.attrs['yte_values'].items():
+        a, b, sigma, rho, m = interp_param_matrix[maturity_name].values
+        nu, psi, p, c, nu_tilde = SVIModel.svi_jw_params(a, b, sigma, rho, m, yte)
+        jw_param_matrix[maturity_name] = [nu, psi, p, c, nu_tilde]
+
+    # Copy attributes from param matrix
+    jw_param_matrix.attrs = interp_param_matrix.attrs.copy()
+
+    return {
+        'moneyness_grid': moneyness_grid,
+        'target_expiries_years': target_expiries_years,
+        'target_expiries_days': target_expiries_years * 365.25,
+        'interp_param_matrix': interp_param_matrix,
+        'interp_jw_param_matrix': jw_param_matrix,
+        'iv_surface': iv_surface,
+        'method': method
+    }

voly/core/rnd.py

@@ -0,0 +1,389 @@
+"""
+This module handles calculating risk-neutral densities from
+fitted volatility models and converting to probability functions.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Dict, List, Tuple, Optional, Union, Any
+from voly.utils.logger import logger, catch_exception
+from voly.exceptions import RNDError
+from voly.models import SVIModel
+from voly.formulas import rnd_base
+
+
+@catch_exception
+def calculate_risk_neutral_density(
+        log_moneyness: np.ndarray,
+        params: List[float],
+        model: Any = SVIModel
+) -> np.ndarray:
+    """
+    Calculate the risk-neutral density (RND) from model parameters.
+
+    Parameters:
+    - log_moneyness: Array of log-moneyness values
+    - params: Model parameters (e.g., SVI parameters [a, b, sigma, rho, m])
+    - model: Model class to use (default: SVIModel)
+
+    Returns:
+    - Array of RND values corresponding to each log-moneyness value
+    """
+    # Adjust parameter order to match function signatures
+    a, b, sigma, rho, m = params
+
+    # Calculate total variance
+    total_var = np.array([model.svi(x, a, b, sigma, rho, m) for x in log_moneyness])
+
+    # Calculate risk-neutral density using the base RND function
+    rnd_values = np.array([rnd_base(x, var) for x, var in zip(log_moneyness, total_var)])
+
+    return rnd_values
+
+
+@catch_exception
+def calculate_rnd_for_all_expiries(
+        moneyness_grid: np.ndarray,
+        param_matrix: pd.DataFrame,
+        model: Any = SVIModel
+) -> Dict[str, np.ndarray]:
+    """
+    Calculate RND for all expiries in the parameter matrix.
+
+    Parameters:
+    - moneyness_grid: Grid of log-moneyness values
+    - param_matrix: Matrix containing model parameters for each expiry
+    - model: Model class to use (default: SVIModel)
+
+    Returns:
+    - Dictionary mapping maturity names to RND arrays
+    """
+    rnd_surface = {}
+
+    # Get YTE values from the parameter matrix attributes
+    yte_values = param_matrix.attrs['yte_values']
+
+    # Calculate RND for each expiry
+    for maturity_name, yte in yte_values.items():
+        params = param_matrix[maturity_name].values
+
+        # Calculate RND
+        rnd_values = calculate_risk_neutral_density(
+            moneyness_grid,
+            params,
+            yte,
+            model=model
+        )
+
+        rnd_surface[maturity_name] = rnd_values
+
+    return rnd_surface
+
+
+@catch_exception
+def calculate_probability_thresholds(
+        moneyness_grid: np.ndarray,
+        rnd_values: np.ndarray,
+        thresholds=None
+) -> Dict[str, float]:
+    """
+    Calculate probabilities at specific log-moneyness thresholds.
+
+    Parameters:
+    - moneyness_grid: Grid of log-moneyness values
+    - rnd_values: Risk-neutral density values
+    - thresholds: Log-moneyness thresholds to calculate probabilities for
+
+    Returns:
+    - Dictionary mapping thresholds to their probabilities
+    """
+    # Calculate step size for integration
+    if thresholds is None:
+        thresholds = [-2.0, -1.5, -1.0, -0.5, 0.0, 0.5, 1.0, 1.5, 2.0]
+
+    dx = moneyness_grid[1] - moneyness_grid[0]
+
+    # Normalize the RND for proper probability
+    total_density = np.sum(rnd_values) * dx
+    normalized_rnd = rnd_values / total_density if total_density > 0 else rnd_values
+
+    # Calculate cumulative distribution function (CDF)
+    cdf = np.cumsum(normalized_rnd) * dx
+
+    # Initialize probability results dictionary
+    result = {}
+
+    # Calculate probabilities for each threshold
+    for threshold in thresholds:
+        # Find the nearest index
+        idx = np.abs(moneyness_grid - threshold).argmin()
+
+        # Get exact threshold value (may be slightly different from requested)
+        actual_threshold = moneyness_grid[idx]
+
+        # Calculate probability P(X ≤ threshold)
+        if idx < len(cdf):
+            prob = cdf[idx]
+        else:
+            prob = 1.0
+
+        # Calculate probability of exceeding positive thresholds
+        # and probability of going below negative thresholds
+        if threshold >= 0:
+            # P(X > threshold) = 1 - P(X ≤ threshold)
+            result[f"p_above_{threshold}"] = 1.0 - prob
+        else:
+            # P(X < threshold) = P(X ≤ threshold)
+            result[f"p_below_{threshold}"] = prob
+
+    return result
+
+
+@catch_exception
+def calculate_moments(
+        moneyness_grid: np.ndarray,
+        rnd_values: np.ndarray) -> Dict[str, float]:
+    """
+    Calculate statistical moments (mean, variance, skewness, kurtosis) of the RND.
+
+    Parameters:
+    - moneyness_grid: Grid of log-moneyness values
+    - rnd_values: Array of RND values
+
+    Returns:
+    - Dictionary with statistical moments
+    """
+    # Calculate total probability (for normalization)
+    dx = moneyness_grid[1] - moneyness_grid[0]
+    total_prob = np.sum(rnd_values) * dx
+
+    # Normalize the RND if needed
+    normalized_rnd = rnd_values / total_prob if total_prob > 0 else rnd_values
+
+    # Calculate moments in percentage terms
+    # First, convert log-moneyness to percentage returns
+    returns_pct = (np.exp(moneyness_grid) - 1) * 100  # Convert to percentage returns
+
+    # Calculate mean (expected return in %)
+    mean_pct = np.sum(returns_pct * normalized_rnd) * dx
+
+    # Calculate variance (in % squared)
+    centered_returns = returns_pct - mean_pct
+    variance_pct = np.sum(centered_returns ** 2 * normalized_rnd) * dx
+    std_dev_pct = np.sqrt(variance_pct)
+
+    # Skewness and kurtosis are unitless
+    skewness = np.sum(centered_returns ** 3 * normalized_rnd) * dx / (std_dev_pct ** 3) if std_dev_pct > 0 else 0
+    kurtosis = np.sum(centered_returns ** 4 * normalized_rnd) * dx / (variance_pct ** 2) if variance_pct > 0 else 0
+
+    return {
+        "mean_pct": mean_pct,  # Mean return in percentage
+        "variance_pct": variance_pct,  # Variance in percentage squared
+        "std_dev_pct": std_dev_pct,  # Standard deviation in percentage
+        "skewness": skewness,  # Unitless
+        "kurtosis": kurtosis,  # Unitless
+        "excess_kurtosis": kurtosis - 3  # Unitless
+    }
+
+
+@catch_exception
+def analyze_rnd_statistics(
+        moneyness_grid: np.ndarray,
+        rnd_surface: Dict[str, np.ndarray],
+        param_matrix: pd.DataFrame) -> pd.DataFrame:
+    """
+    Analyze RND statistics for all expiries.
+
+    Parameters:
+    - moneyness_grid: Grid of log-moneyness values
+    - rnd_surface: Dictionary mapping maturity names to RND arrays
+    - param_matrix: Matrix containing model parameters
+
+    Returns:
+    - DataFrame with RND statistics for each expiry
+    """
+    # Get maturity information
+    dte_values = param_matrix.attrs['dte_values']
+    yte_values = param_matrix.attrs['yte_values']
+
+    # Initialize data dictionary
+    data = {
+        "maturity_name": [],
+        "dte": [],
+        "yte": [],
+        "mean_pct": [],
+        "std_dev_pct": [],
+        "skewness": [],
+        "excess_kurtosis": []
+    }
+
+    # Calculate moments for each expiry
+    for maturity_name, rnd in rnd_surface.items():
+        moments = calculate_moments(moneyness_grid, rnd)
+
+        data["maturity_name"].append(maturity_name)
+        data["dte"].append(dte_values[maturity_name])
+        data["yte"].append(yte_values[maturity_name])
+        data["mean_pct"].append(moments["mean_pct"])
+        data["std_dev_pct"].append(moments["std_dev_pct"])
+        data["skewness"].append(moments["skewness"])
+        data["excess_kurtosis"].append(moments["excess_kurtosis"])
+
+    # Create DataFrame and sort by DTE
+    stats_df = pd.DataFrame(data)
+    stats_df = stats_df.sort_values(by="dte")
+
+    return stats_df
+
+
+@catch_exception
+def calculate_pdf(
+        moneyness_grid: np.ndarray,
+        rnd_values: np.ndarray,
+        spot_price: float = 1.0
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Calculate probability density function (PDF) from RND values.
+
+    Parameters:
+    - moneyness_grid: Grid of log-moneyness values
+    - rnd_values: Array of RND values
+    - spot_price: Spot price of the underlying
+
+    Returns:
+    - Tuple of (prices, pdf_values) for plotting
+    """
+    # Calculate step size for normalization
+    dx = moneyness_grid[1] - moneyness_grid[0]
+
+    # Normalize the RND
+    total_density = np.sum(rnd_values) * dx
+    pdf_values = rnd_values / total_density if total_density > 0 else rnd_values
+
+    # Convert log-moneyness to actual prices
+    prices = spot_price * np.exp(moneyness_grid)
+
+    return prices, pdf_values
+
+
+@catch_exception
+def calculate_cdf(
+        moneyness_grid: np.ndarray,
+        rnd_values: np.ndarray,
+        spot_price: float = 1.0
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Calculate cumulative distribution function (CDF) from RND values.
+
+    Parameters:
+    - moneyness_grid: Grid of log-moneyness values
+    - rnd_values: Array of RND values
+    - spot_price: Spot price of the underlying
+
+    Returns:
+    - Tuple of (prices, cdf_values) for plotting
+    """
+    # Calculate step size for normalization
+    dx = moneyness_grid[1] - moneyness_grid[0]
+
+    # Normalize the RND
+    total_density = np.sum(rnd_values) * dx
+    normalized_rnd = rnd_values / total_density if total_density > 0 else rnd_values
+
+    # Calculate CDF
+    cdf_values = np.cumsum(normalized_rnd) * dx
+
+    # Convert log-moneyness to actual prices
+    prices = spot_price * np.exp(moneyness_grid)
+
+    return prices, cdf_values
+
+
+@catch_exception
+def calculate_strike_probability(
+        target_price: float,
+        moneyness_grid: np.ndarray,
+        rnd_values: np.ndarray,
+        spot_price: float,
+        direction: str = 'above'
+) -> float:
+    """
+    Calculate probability of price being above or below a target price.
+
+    Parameters:
+    - target_price: Target price level
+    - moneyness_grid: Grid of log-moneyness values
+    - rnd_values: Array of RND values
+    - spot_price: Current spot price
+    - direction: 'above' or 'below'
+
+    Returns:
+    - Probability (0 to 1)
+    """
+    # Convert target price to log-moneyness
+    target_moneyness = np.log(target_price / spot_price)
+
+    # Calculate CDF
+    _, cdf_values = calculate_cdf(moneyness_grid, rnd_values, spot_price)
+
+    # Find the nearest index to target moneyness
+    target_idx = np.abs(moneyness_grid - target_moneyness).argmin()
+
+    # Get probability
+    if target_idx < len(cdf_values):
+        cdf_at_target = cdf_values[target_idx]
+    else:
+        cdf_at_target = 1.0
+
+    # Return probability based on direction
+    if direction.lower() == 'above':
+        return 1.0 - cdf_at_target
+    else:  # below
+        return cdf_at_target
+
+
+@catch_exception
+def calculate_rnd(
+        fit_results: Dict[str, Any],
+        maturity: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Calculate risk-neutral density from fit results.
+
+    Parameters:
+    - fit_results: Dictionary with fitting results from fit_model()
+    - maturity: Optional maturity name to calculate RND for a specific expiry
+
+    Returns:
+    - Dictionary with RND results
+    """
+    # Extract required data from fit results
+    raw_param_matrix = fit_results['raw_param_matrix']
+    moneyness_grid = fit_results['moneyness_grid']
+
+    # Calculate RND for all expiries or just the specified one
+    if maturity is not None:
+        # Validate maturity
+        if maturity not in raw_param_matrix.columns:
+            raise RNDError(f"Maturity '{maturity}' not found in fit results")
+
+        # Just calculate for the specified maturity
+        yte = raw_param_matrix.attrs['yte_values'][maturity]
+        params = raw_param_matrix[maturity].values
+        rnd_values = calculate_risk_neutral_density(moneyness_grid, params, yte)
+        rnd_surface = {maturity: rnd_values}
+    else:
+        # Calculate for all maturities
+        rnd_surface = calculate_rnd_for_all_expiries(moneyness_grid, raw_param_matrix)
+
+    # Calculate statistics
+    rnd_statistics = analyze_rnd_statistics(moneyness_grid, rnd_surface, raw_param_matrix)
+
+    # Calculate probabilities
+    rnd_probabilities = analyze_rnd_probabilities(moneyness_grid, rnd_surface, raw_param_matrix)
+
+    return {
+        'moneyness_grid': moneyness_grid,
+        'rnd_surface': rnd_surface,
+        'rnd_statistics': rnd_statistics,
+        'rnd_probabilities': rnd_probabilities
+    }

voly/exceptions.py

@@ -0,0 +1,3 @@
+class VolyError(Exception):
+    """Base exception for all Voly-specific errors."""
+    pass