voly 0.0.64__tar.gz → 0.0.66__tar.gz

{voly-0.0.64/src/voly.egg-info → voly-0.0.66}/PKG-INFO

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

{voly-0.0.64 → voly-0.0.66}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "voly"
-version = "0.0.64"
+version = "0.0.66"
 description = "Options & volatility research package"
 readme = "README.md"
 authors = [
@@ -60,7 +60,7 @@ line_length = 100
 multi_line_output = 3
 
 [tool.mypy]
-python_version = "0.0.64"
+python_version = "0.0.66"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true

{voly-0.0.64 → voly-0.0.66}/src/voly/core/charts.py

@@ -19,17 +19,38 @@ pio.renderers.default = "browser"
 
 
 @catch_exception
-def plot_volatility_smile(moneyness_array: np.ndarray,
+def plot_volatility_smile(x_domain: np.ndarray,
                           iv_array: np.ndarray,
                           option_chain: pd.DataFrame = None,
-                          maturity: Optional[str] = None) -> go.Figure:
-    """Plot volatility smile for a single expiry."""
+                          maturity: Optional[str] = None,
+                          domain_type: str = 'log_moneyness') -> go.Figure:
+    """
+    Plot volatility smile for a single expiry.
+
+    Parameters:
+    - x_domain: Array of x-axis values (log_moneyness, moneyness, strikes, delta)
+    - iv_array: Implied volatility values
+    - option_chain: Optional market data for comparison
+    - maturity: Maturity name for filtering market data
+    - domain_type: Type of x-domain ('log_moneyness', 'moneyness', 'strikes', 'delta')
+
+    Returns:
+    - Plotly figure
+    """
     fig = go.Figure()
 
+    # Map domain types to axis labels
+    domain_labels = {
+        'log_moneyness': 'Log Moneyness',
+        'moneyness': 'Moneyness (S/K)',
+        'strikes': 'Strike Price',
+        'delta': 'Call Delta'
+    }
+
     # Add model curve
     fig.add_trace(
         go.Scatter(
-            x=moneyness_array,
+            x=x_domain,
             y=iv_array * 100,  # Convert to percentage
             mode='lines',
             name='Model',
@@ -42,25 +63,39 @@ def plot_volatility_smile(moneyness_array: np.ndarray,
         maturity_data = option_chain[option_chain['maturity_name'] == maturity]
 
         if not maturity_data.empty:
-            # Add bid and ask IVs
-            for iv_type in ['bid_iv', 'ask_iv']:
-                if iv_type in maturity_data.columns:
-                    fig.add_trace(
-                        go.Scatter(
-                            x=maturity_data['log_moneyness'],
-                            y=maturity_data[iv_type] * 100,  # Convert to percentage
-                            mode='markers',
-                            name=iv_type.replace('_', ' ').upper(),
-                            marker=dict(size=8, symbol='circle', opacity=0.7)
+            # For market data, use log_moneyness by default as x-axis
+            market_x = maturity_data['log_moneyness']
+
+            # If domain is not log_moneyness, convert market data to match the domain
+            if domain_type == 'moneyness':
+                market_x = np.exp(market_x)
+            elif domain_type == 'strikes':
+                s = maturity_data['underlying_price'].iloc[0]
+                market_x = s / np.exp(market_x)
+            elif domain_type == 'delta':
+                # For delta, we'd need more complex conversion - only show model curve
+                pass
+
+            # Add bid and ask IVs if the domain type allows
+            if domain_type != 'delta':
+                for iv_type in ['bid_iv', 'ask_iv']:
+                    if iv_type in maturity_data.columns:
+                        fig.add_trace(
+                            go.Scatter(
+                                x=market_x,
+                                y=maturity_data[iv_type] * 100,  # Convert to percentage
+                                mode='markers',
+                                name=iv_type.replace('_', ' ').upper(),
+                                marker=dict(size=8, symbol='circle', opacity=0.7)
+                            )
                         )
-                    )
 
             dte_value = maturity_data['dtm'].iloc[0]
 
             # Update layout
             fig.update_layout(
                 title=f'Vol Smile for {maturity} (DTE: {dte_value:.1f})',
-                xaxis_title='Log Moneyness',
+                xaxis_title=domain_labels.get(domain_type, 'X Domain'),
                 yaxis_title='Implied Volatility (%)',
                 template='plotly_dark',
                 legend=dict(orientation='h', yanchor='bottom', y=1.02, xanchor='right', x=1)
@@ -70,16 +105,29 @@ def plot_volatility_smile(moneyness_array: np.ndarray,
 
 
 @catch_exception
-def plot_all_smiles(moneyness_array: np.ndarray,
+def plot_all_smiles(x_surface: Dict[str, np.ndarray],
                     iv_surface: Dict[str, np.ndarray],
-                    option_chain: Optional[pd.DataFrame] = None) -> List[go.Figure]:
-    """Plot volatility smiles for all expiries."""
+                    option_chain: Optional[pd.DataFrame] = None,
+                    domain_type: str = 'log_moneyness') -> List[go.Figure]:
+    """
+    Plot volatility smiles for all expiries.
+
+    Parameters:
+    - x_surface: Dictionary mapping maturity names to x-domain arrays
+    - iv_surface: Dictionary mapping maturity names to IV arrays
+    - option_chain: Optional market data for comparison
+    - domain_type: Type of x-domain ('log_moneyness', 'moneyness', 'strikes', 'delta')
+
+    Returns:
+    - List of Plotly figures
+    """
     return [
         plot_volatility_smile(
-            moneyness_array=moneyness_array,
+            x_domain=x_surface[maturity],
             iv_array=iv_surface[maturity],
             option_chain=option_chain,
-            maturity=maturity
+            maturity=maturity,
+            domain_type=domain_type
         )
         for maturity in iv_surface.keys()
     ]
@@ -87,7 +135,15 @@ def plot_all_smiles(moneyness_array: np.ndarray,
 
 @catch_exception
 def plot_parameters(fit_results: pd.DataFrame) -> go.Figure:
-    """Plot raw SVI parameters across different expiries."""
+    """
+    Plot raw SVI parameters across different expiries.
+
+    Parameters:
+    - fit_results: DataFrame from fit_model() with maturity names as index
+
+    Returns:
+    - Plotly figure
+    """
     # Select parameters to plot
     param_names = ['a', 'b', 'sigma', 'rho', 'm']
 
@@ -98,9 +154,12 @@ def plot_parameters(fit_results: pd.DataFrame) -> go.Figure:
                         for p in param_names] + ['']
     )
 
-    # Get maturity names and prepare tick labels
-    maturity_names = fit_results.columns
-    tick_labels = [f"{m} (DTE: {fit_results.loc['dtm', m]:.1f})" for m in maturity_names]
+    # Get maturity names from index
+    maturity_names = fit_results.index
+
+    # Create hover text with maturity info
+    tick_labels = [f"{m} (DTE: {fit_results.loc[m, 'dtm']:.1f}, YTE: {fit_results.loc[m, 'ytm']:.4f})"
+                   for m in maturity_names]
 
     # Plot each parameter
     for i, param in enumerate(param_names):
@@ -109,7 +168,7 @@ def plot_parameters(fit_results: pd.DataFrame) -> go.Figure:
         fig.add_trace(
             go.Scatter(
                 x=list(range(len(maturity_names))),
-                y=fit_results.loc[param],
+                y=fit_results[param],
                 mode='lines+markers',
                 name=param,
                 line=dict(width=2),
@@ -132,7 +191,7 @@ def plot_parameters(fit_results: pd.DataFrame) -> go.Figure:
     fig.update_layout(
         title='Raw SVI Parameters Across Expiries',
         template='plotly_dark',
-        showlegend=False,
+        showlegend=False
     )
 
     return fig
@@ -140,7 +199,15 @@ def plot_parameters(fit_results: pd.DataFrame) -> go.Figure:
 
 @catch_exception
 def plot_jw_parameters(fit_results: pd.DataFrame) -> go.Figure:
-    """Plot Jump-Wing parameters across different expiries."""
+    """
+    Plot Jump-Wing parameters across different expiries.
+
+    Parameters:
+    - fit_results: DataFrame from fit_model() with maturity names as index
+
+    Returns:
+    - Plotly figure
+    """
     # Select parameters to plot
     param_names = ['nu', 'psi', 'p', 'c', 'nu_tilde']
 
@@ -151,9 +218,12 @@ def plot_jw_parameters(fit_results: pd.DataFrame) -> go.Figure:
                         for p in param_names] + ['']
     )
 
-    # Get maturity names and prepare tick labels
-    maturity_names = fit_results.columns
-    tick_labels = [f"{m} (DTE: {fit_results.loc['dtm', m]:.1f})" for m in maturity_names]
+    # Get maturity names from index
+    maturity_names = fit_results.index
+
+    # Create hover text with maturity info
+    tick_labels = [f"{m} (DTE: {fit_results.loc[m, 'dtm']:.1f})"
+                   for m in maturity_names]
 
     # Plot each parameter
     for i, param in enumerate(param_names):
@@ -162,7 +232,7 @@ def plot_jw_parameters(fit_results: pd.DataFrame) -> go.Figure:
         fig.add_trace(
             go.Scatter(
                 x=list(range(len(maturity_names))),
-                y=fit_results.loc[param],
+                y=fit_results[param],
                 mode='lines+markers',
                 name=param,
                 line=dict(width=2, color='rgb(0, 180, 180)'),
@@ -185,15 +255,23 @@ def plot_jw_parameters(fit_results: pd.DataFrame) -> go.Figure:
     fig.update_layout(
         title='Jump-Wing Parameters Across Expiries',
         template='plotly_dark',
-        showlegend=False,
+        showlegend=False
     )
 
     return fig
 
 
 @catch_exception
-def plot_fit_performance(fit_performance: pd.DataFrame) -> go.Figure:
-    """Plot the fitting accuracy statistics."""
+def plot_fit_performance(fit_results: pd.DataFrame) -> go.Figure:
+    """
+    Plot the fitting accuracy statistics.
+
+    Parameters:
+    - fit_results: DataFrame from fit_model() with maturity names as index
+
+    Returns:
+    - Plotly figure
+    """
     # Define metrics to plot
     metrics = {
         'rmse': {'title': 'RMSE by Expiry', 'row': 1, 'col': 1, 'ylabel': 'RMSE (%)', 'scale': 100},
@@ -208,19 +286,19 @@ def plot_fit_performance(fit_performance: pd.DataFrame) -> go.Figure:
         subplot_titles=[metrics[m]['title'] for m in metrics]
     )
 
-    # Get maturity names and create x-axis indices
-    maturity_names = fit_performance.columns
+    # Get maturity names from index and create x-axis indices
+    maturity_names = fit_results.index
     x_indices = list(range(len(maturity_names)))
 
     # Create hover labels
-    hover_labels = [f"{m}" for m in maturity_names]
+    hover_labels = [f"{m} (DTE: {fit_results.loc[m, 'dtm']:.1f})" for m in maturity_names]
 
     # Plot each metric
     for metric, config in metrics.items():
         fig.add_trace(
             go.Scatter(
                 x=x_indices,
-                y=fit_performance.loc[metric] * config['scale'],
+                y=fit_results[metric] * config['scale'],
                 mode='lines+markers',
                 name=metric.upper(),
                 line=dict(width=2),
@@ -248,17 +326,37 @@ def plot_fit_performance(fit_performance: pd.DataFrame) -> go.Figure:
     fig.update_layout(
         title='Model Fitting Accuracy Statistics',
         template='plotly_dark',
-        showlegend=False,
+        showlegend=False
     )
 
     return fig
 
 
 @catch_exception
-def plot_3d_surface(moneyness_array: np.ndarray,
+def plot_3d_surface(x_surface: Dict[str, np.ndarray],
                     iv_surface: Dict[str, np.ndarray],
-                    fit_results: pd.DataFrame = None) -> go.Figure:
-    """Plot 3D implied volatility surface."""
+                    fit_results: pd.DataFrame = None,
+                    domain_type: str = 'log_moneyness') -> go.Figure:
+    """
+    Plot 3D implied volatility surface.
+
+    Parameters:
+    - x_surface: Dictionary mapping maturity names to x-domain arrays
+    - iv_surface: Dictionary mapping maturity names to IV arrays
+    - fit_results: Optional DataFrame with maturity information
+    - domain_type: Type of x-domain ('log_moneyness', 'moneyness', 'strikes', 'delta')
+
+    Returns:
+    - Plotly figure
+    """
+    # Map domain types to axis labels
+    domain_labels = {
+        'log_moneyness': 'Log Moneyness',
+        'moneyness': 'Moneyness (S/K)',
+        'strikes': 'Strike Price',
+        'delta': 'Delta'
+    }
+
     # Define custom colorscale
     custom_blue_scale = [[0, '#60AEFC'], [1, '#002040']]
 
@@ -268,39 +366,72 @@ def plot_3d_surface(moneyness_array: np.ndarray,
     # Get z-axis values (days to expiry)
     if fit_results is not None:
         # Use DTM values from fit_results
-        maturity_values = [fit_results.loc['dtm', name] for name in maturity_names]
+        maturity_values = [fit_results.loc[name, 'dtm'] for name in maturity_names]
     else:
         # Default to sequential values
         maturity_values = list(range(len(maturity_names)))
 
-    # Create 3D surface data
-    z_array = np.array([iv_surface[m] * 100 for m in maturity_names])  # Convert to percentage
-    X, Y = np.meshgrid(moneyness_array, maturity_values)
+    # Create a mesh grid for each maturity to handle different x domains
+    X = []
+    Y = []
+    Z = []
 
-    # Create figure
-    fig = go.Figure(data=[
-        go.Surface(
-            z=z_array,
-            x=X,
-            y=Y,
+    for i, m in enumerate(maturity_names):
+        x_values = x_surface[m]
+        z_values = iv_surface[m] * 100  # Convert to percentage
+        y_value = maturity_values[i]
+
+        # Add to point lists
+        for j in range(len(x_values)):
+            X.append(x_values[j])
+            Y.append(y_value)
+            Z.append(z_values[j])
+
+    # Create 3D scatter plot with lines connecting points within each maturity
+    fig = go.Figure()
+
+    # Add data as a 3D scatter plot
+    fig.add_trace(go.Scatter3d(
+        x=X, y=Y, z=Z,
+        mode='markers',
+        marker=dict(
+            size=3,
+            color=Z,
             colorscale=custom_blue_scale,
-            contours_z=dict(
-                show=True,
-                usecolormap=True,
-                highlightcolor="#0080FF",
-                project_z=True
-            )
-        )
-    ])
+            opacity=0.8
+        ),
+        hovertemplate="<b>%{y:.1f} days</b><br>X: %{x:.4f}<br>IV: %{z:.2f}%"
+    ))
+
+    # Add lines connecting points for each maturity
+    cumulative_index = 0
+    for i, m in enumerate(maturity_names):
+        points_count = len(x_surface[m])
+        indices = list(range(cumulative_index, cumulative_index + points_count))
+
+        if len(indices) > 1:
+            fig.add_trace(go.Scatter3d(
+                x=[X[j] for j in indices],
+                y=[Y[j] for j in indices],
+                z=[Z[j] for j in indices],
+                mode='lines',
+                line=dict(color='blue', width=3),
+                showlegend=False,
+                hoverinfo='none'
+            ))
+
+        cumulative_index += points_count
 
     # Update layout
     fig.update_layout(
         title='Implied Volatility 3D Surface',
         template='plotly_dark',
         scene=dict(
-            xaxis_title='Log Moneyness',
+            xaxis_title=domain_labels.get(domain_type, 'X Domain'),
             yaxis_title='Days to Expiry',
-            zaxis_title='Implied Volatility (%)'
+            zaxis_title='Implied Volatility (%)',
+            aspectmode='manual',
+            aspectratio=dict(x=1.5, y=1, z=1)
         ),
         margin=dict(l=65, r=50, b=65, t=90)
     )

{voly-0.0.64 → voly-0.0.66}/src/voly/core/fit.py

@@ -33,12 +33,18 @@ def calculate_residuals(params: List[float], ytm: float, option_chain: pd.DataFr
 def fit_model(option_chain: pd.DataFrame,
               model_name: str = 'svi',
               initial_params: Optional[List[float]] = None,
-              param_bounds: Optional[Tuple] = None) -> Tuple[pd.DataFrame, pd.DataFrame]:
+              param_bounds: Optional[Tuple] = None) -> pd.DataFrame:
     """
     Fit a volatility model to market data.
 
+    Parameters:
+    - option_chain: DataFrame with market data
+    - model_name: Type of model to fit (default: 'svi')
+    - initial_params: Optional initial parameters for optimization (default: model's defaults)
+    - param_bounds: Optional parameter bounds for optimization (default: model's defaults)
+
     Returns:
-    - Tuple of (fit_results_df, fit_performance_df)
+    - DataFrame with all fit results and performance metrics as columns, maturity_names as index
     """
     if model_name.lower() != 'svi':
         raise VolyError(f"Model type '{model_name}' is not supported. Currently only 'svi' is available.")
@@ -47,22 +53,22 @@ def fit_model(option_chain: pd.DataFrame,
     initial_params = initial_params or SVIModel.DEFAULT_INITIAL_PARAMS
     param_bounds = param_bounds or SVIModel.DEFAULT_PARAM_BOUNDS
 
-    # Define indices for result DataFrames
-    results_index = ['s', 'u', 'maturity_date', 'dtm', 'ytm',
-                     'a', 'b', 'sigma', 'rho', 'm',
-                     'nu', 'psi', 'p', 'c', 'nu_tilde',
-                     'oi', 'volume', 'r']
-
-    performance_index = ['fit_success', 'cost', 'optimality',
-                         'rmse', 'mae', 'r2', 'max_error', 'n_points']
+    # Define column names for the result DataFrame
+    result_columns = [
+        's', 'u', 'maturity_date', 'dtm', 'ytm',
+        'a', 'b', 'rho', 'm', 'sigma',
+        'nu', 'psi', 'p', 'c', 'nu_tilde',
+        'oi', 'volume', 'r',
+        'fit_success', 'cost', 'optimality',
+        'rmse', 'mae', 'r2', 'max_error', 'n_points'
+    ]
 
     # Get unique maturities and sort them
     unique_ytms = sorted(option_chain['ytm'].unique())
     maturity_names = [option_chain[option_chain['ytm'] == ytm]['maturity_name'].iloc[0] for ytm in unique_ytms]
 
-    # Create empty DataFrames
-    fit_results_df = pd.DataFrame(index=results_index, columns=maturity_names)
-    fit_performance_df = pd.DataFrame(index=performance_index, columns=maturity_names)
+    # Create empty DataFrame with maturity_names as index
+    results_df = pd.DataFrame(index=maturity_names, columns=result_columns)
 
     # ANSI color codes for terminal output
     GREEN, RED, RESET = '\033[32m', '\033[31m', '\033[0m'
@@ -108,42 +114,38 @@ def fit_model(option_chain: pd.DataFrame,
         # Aggregate open interest and volume
         oi = maturity_data['open_interest'].sum() if 'open_interest' in maturity_data.columns else 0
         volume = maturity_data['volume'].sum() if 'volume' in maturity_data.columns else 0
-        r = 0.0
+        r = maturity_data['interest_rate'].iloc[0] if 'interest_rate' in maturity_data.columns else 0
 
         # Calculate Jump-Wing parameters
         nu, psi, p, c, nu_tilde = SVIModel.raw_to_jw_params(a, b, sigma, rho, m, ytm)
 
-        # Store results
-        result_values = [s, u, maturity_data['maturity_date'].iloc[0], dtm, ytm,
-                         a, b, rho, m, sigma, nu, psi, p, c, nu_tilde, oi, volume, r]
-
-        for idx, val in zip(results_index, result_values):
-            fit_results_df.loc[idx, maturity_name] = val
-
-        # Store performance metrics
-        perf_values = [result.success, result.cost, result.optimality,
-                       rmse, mae, r2, max_error, len(maturity_data)]
-
-        for idx, val in zip(performance_index, perf_values):
-            fit_performance_df.loc[idx, maturity_name] = val
+        # Store all results in the DataFrame
+        results_df.loc[maturity_name] = [
+            s, u, maturity_data['maturity_date'].iloc[0], dtm, ytm,
+            a, b, rho, m, sigma,
+            nu, psi, p, c, nu_tilde,
+            oi, volume, r,
+            result.success, result.cost, result.optimality,
+            rmse, mae, r2, max_error, len(maturity_data)
+        ]
 
         # Log result
         status = f'{GREEN}SUCCESS{RESET}' if result.success else f'{RED}FAILED{RESET}'
         logger.info(f'Optimization for {maturity_name}: {status}')
         logger.info('-------------------------------------')
 
-    return fit_results_df, fit_performance_df
+    return results_df
 
 
 @catch_exception
 def get_iv_surface(fit_results: pd.DataFrame,
                    log_moneyness_params: Tuple[float, float, int] = (-1.5, 1.5, 1000),
-                   return_domain: str = 'log_moneyness') -> Tuple[Dict[str, np.ndarray], np.ndarray]:
+                   return_domain: str = 'log_moneyness') -> Tuple[Dict[str, np.ndarray], Dict[str, np.ndarray]]:
     """
     Generate implied volatility surface using optimized SVI parameters.
 
     Parameters:
-    - fit_results: DataFrame from fit_model()
+    - fit_results: DataFrame from fit_model() with maturity names as index
     - log_moneyness_params: Tuple of (min, max, num_points) for the moneyness grid
     - return_domain: Domain for x-axis values ('log_moneyness', 'moneyness', 'strikes', 'delta')
 
@@ -159,30 +161,32 @@ def get_iv_surface(fit_results: pd.DataFrame,
 
     iv_surface = {}
     x_surface = {}
-    for maturity in fit_results.columns:
+
+    # Process each maturity
+    for maturity in fit_results.index:
         # Calculate SVI total implied variance and convert to IV
         params = [
-            fit_results.loc['a', maturity],
-            fit_results.loc['b', maturity],
-            fit_results.loc['sigma', maturity],
-            fit_results.loc['rho', maturity],
-            fit_results.loc['m', maturity]
+            fit_results.loc[maturity, 'a'],
+            fit_results.loc[maturity, 'b'],
+            fit_results.loc[maturity, 'sigma'],
+            fit_results.loc[maturity, 'rho'],
+            fit_results.loc[maturity, 'm']
         ]
-        ytm = fit_results.loc['ytm', maturity]
+        ytm = fit_results.loc[maturity, 'ytm']
 
+        # Calculate implied volatility
         w_svi = np.array([SVIModel.svi(x, *params) for x in log_moneyness_array])
         iv_array = np.sqrt(w_svi / ytm)
         iv_surface[maturity] = iv_array
 
-        x_domain = get_x_domain(
+        # Calculate x domain for this maturity
+        x_surface[maturity] = get_x_domain(
             log_moneyness_params=log_moneyness_params,
             return_domain=return_domain,
-            s=fit_results.loc['s', maturity],
-            r=fit_results.loc['r', maturity],
+            s=fit_results.loc[maturity, 's'],
+            r=fit_results.loc[maturity, 'r'],
             iv_array=iv_array,
-            ytm=fit_results.loc['ytm', maturity]
+            ytm=ytm
         )
 
-        x_surface[maturity] = x_domain
-
     return iv_surface, x_surface

{voly-0.0.64 → voly-0.0.66}/src/voly/formulas.py

@@ -316,10 +316,8 @@ def get_x_domain(log_moneyness_params: Tuple[float, float, int] = (-1.5, 1.5, 10
         If required parameters are missing for the specified return_domain.
     """
 
-    # Extract log-moneyness parameters
+    # Extract log-moneyness parameters and generate array
     min_m, max_m, num_points = log_moneyness_params
-
-    # Generate the base log-moneyness array
     log_moneyness = np.linspace(min_m, max_m, num_points)
 
     # Handle different return domains

{voly-0.0.64 → voly-0.0.66/src/voly.egg-info}/PKG-INFO

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