implemented IV plotting into API

Author: tyrneh

examples/appl_example.py

@@ -149,3 +149,28 @@
 # Select an arbitrary maturity
 # rebuilt_slice_df = surface_rebuild.slice(days_to_expiry=100).data
 # rebuilt_slice_df.head()
+
+# Test Plotting
+print("\nTesting Plotting...")
+try:
+    import matplotlib.pyplot as plt
+    
+    # 1. VolCurve Plot
+    # Pick the first available expiry
+    expiry_to_plot = appl_surface.expiries[0]
+    vol_curve = appl_surface.slice(expiry=expiry_to_plot)
+    fig_iv = vol_curve.plot(title=f"Fitted IV Smile ({expiry_to_plot.date()})")
+    # plt.show() # Uncomment to see plot
+    print("VolCurve.plot() successful")
+
+    # 2. Distribution Plot
+    dist = vol_curve.implied_distribution()
+    fig_pdf = dist.plot(kind="pdf", title="Implied PDF (100 days)")
+    # plt.show() # Uncomment to see plot
+    print("Distribution.plot() successful")
+    
+except ImportError:
+    print("Matplotlib not installed, skipping plotting tests")
+except Exception as e:
+    print(f"Plotting failed: {e}")
+    raise

oipd/interface/probability.py

@@ -135,6 +135,31 @@ def metadata(self) -> dict[str, Any] | None:
 
         return self._metadata
 
+    def plot(self, **kwargs) -> Any:
+        """Plot the risk-neutral probability distribution.
+
+        Args:
+            **kwargs: Arguments forwarded to ``oipd.presentation.plot_rnd.plot_rnd``.
+
+        Returns:
+            matplotlib.figure.Figure: The plot figure.
+        """
+        from oipd.presentation.plot_rnd import plot_rnd
+
+        underlying_price = self._resolved_market.underlying_price
+        valuation_date = self._resolved_market.valuation_date.strftime("%b %d, %Y")
+        expiry_date = self._resolved_market.expiry_date.strftime("%b %d, %Y")
+
+        return plot_rnd(
+            prices=self.prices,
+            pdf=self.pdf,
+            cdf=self.cdf,
+            current_price=underlying_price,
+            valuation_date=valuation_date,
+            expiry_date=expiry_date,
+            **kwargs,
+        )
+
 
 class DistributionSurface:
     """Multi-expiry risk-neutral distribution surface wrapper."""

oipd/interface/volatility.py

@@ -16,11 +16,13 @@
     VendorSnapshot,
     resolve_market,
 )
-from oipd.pipelines.vol_curve import fit_vol_curve_internal
+from oipd.pipelines.vol_curve import fit_vol_curve_internal, compute_fitted_smile
 from oipd.pipelines.distribution import derive_distribution_from_curve
 from oipd.pipelines.vol_surface import fit_surface
 from oipd.pipelines.vol_surface.models import FittedSurface
 
+from oipd.presentation.iv_plotting import plot_iv_smile, ReferenceAnnotation
+
 
 class VolCurve:
     """Single-expiry implied-volatility estimator with sklearn-style API.
@@ -155,6 +157,83 @@ def at_money_vol(self) -> float:
             raise ValueError("Call fit before accessing ATM volatility")
         return getattr(self._vol_curve, "at_money_vol", np.nan)
 
+    def iv_smile(
+        self,
+        domain: Optional[tuple[float, float]] = None,
+        points: int = 200,
+        include_observed: bool = True,
+    ) -> pd.DataFrame:
+        """Return the implied-volatility smile with fitted and market-observed values.
+
+        Args:
+            domain: Optional (min, max) strike range. If None, inferred from observed data.
+            points: Number of points in the grid.
+            include_observed: Whether to include market-observed IVs. If False, only
+                ``strike`` and ``fitted_iv`` columns are returned.
+
+        Returns:
+            DataFrame containing:
+            
+            - ``strike``: Strike levels.
+            - ``fitted_iv``: Fitted implied volatility from the calibrated model.
+            - ``market_iv``: *(if include_observed=True)* Mid-price implied volatility
+              computed by inverting the mid option price using the same pricing model
+              (Black-76 or Black-Scholes), risk-free rate, dividend assumptions, and
+              time-to-expiry as specified during ``.fit()``.
+            - ``market_bid_iv``: *(if include_observed=True)* Bid-price implied volatility
+              computed using the same methodology.
+            - ``market_ask_iv``: *(if include_observed=True)* Ask-price implied volatility
+              computed using the same methodology.
+            - ``market_last_iv``: *(if include_observed=True)* Last-price implied volatility
+              computed using the same methodology (only included if bid/ask are unavailable).
+
+        Note:
+            The market IVs are **not** raw quotes from exchanges—they are computed by
+            the library by solving the inverse problem: "What σ makes the model price
+            match the observed option price?" This ensures consistency with the fitted
+            curve, which uses the same pricing assumptions.
+        """
+        return compute_fitted_smile(
+            vol_curve=self,
+            metadata=self._metadata,
+            domain=domain,
+            points=points,
+            include_observed=include_observed,
+        )
+
+    def plot(self, **kwargs) -> Any:
+        """Plot the fitted implied volatility smile.
+        
+        Args:
+            **kwargs: Arguments forwarded to ``oipd.presentation.iv_plotting.plot_iv_smile``.
+        
+        Returns:
+            matplotlib.figure.Figure: The plot figure.
+        """        
+        smile_df = self.iv_smile()
+        
+        # Map our column names to what plot_iv_smile expects
+        plot_df = smile_df.rename(columns={
+            "market_bid_iv": "bid_iv",
+            "market_ask_iv": "ask_iv",
+            "market_last_iv": "last_iv"
+        })
+
+        # Extract reference price (forward) for log-moneyness plotting
+        reference = None
+        forward_price = self._metadata.get("forward_price")
+        if forward_price is not None:
+            reference = ReferenceAnnotation(
+                value=float(forward_price),
+                label=f"Forward: {float(forward_price):.2f}"
+            )
+        
+        # If no reference price is available, default to strike axis to avoid errors
+        if reference is None and "axis_mode" not in kwargs:
+            kwargs["axis_mode"] = "strike"
+
+        return plot_iv_smile(plot_df, reference=reference, **kwargs)
+
     @property
     def params(self) -> dict[str, Any]:
         """Return fitted parameter dictionary from the underlying curve.

oipd/pipelines/vol_curve/__init__.py

@@ -1,5 +1,8 @@
 """Volatility curve fitting pipeline."""
 
-from oipd.pipelines.vol_curve.vol_curve_pipeline import fit_vol_curve_internal
+from oipd.pipelines.vol_curve.vol_curve_pipeline import (
+    fit_vol_curve_internal,
+    compute_fitted_smile,
+)
 
-__all__ = ["fit_vol_curve_internal"]
+__all__ = ["fit_vol_curve_internal", "compute_fitted_smile"]

oipd/pipelines/vol_curve/vol_curve_pipeline.py

@@ -87,3 +87,83 @@ def fit_vol_curve_internal(
     }
 
     return vol_curve, metadata
+
+
+def compute_fitted_smile(
+    vol_curve: Any,
+    metadata: Dict[str, Any],
+    domain: Optional[Tuple[float, float]] = None,
+    points: int = 200,
+    include_observed: bool = True,
+) -> pd.DataFrame:
+    """
+    Generate a DataFrame representing the fitted smile and observed data.
+
+    Args:
+        vol_curve: The callable volatility curve.
+        metadata: Metadata dictionary containing observed IVs.
+        domain: Optional (min, max) strike range.
+        points: Number of points in the grid.
+        include_observed: Whether to include market observed IVs (mid, bid, ask).
+
+    Returns:
+        DataFrame with columns: strike, fitted_iv, [market_iv, market_bid_iv, ...]
+    """
+    observed_iv = metadata.get("observed_iv")
+
+    # Determine grid
+    if domain is None:
+        if observed_iv is None or observed_iv.empty:
+            raise ValueError(
+                "No observed data found to infer grid domain. "
+                "Please provide an explicit `domain=(min, max)` argument."
+            )
+        else:
+            min_strike = observed_iv["strike"].min()
+            max_strike = observed_iv["strike"].max()
+            if np.isclose(min_strike, max_strike):
+                strike_grid = np.array([min_strike])
+            else:
+                # Add 20% padding
+                padding = 0.2 * (max_strike - min_strike)
+                strike_grid = np.linspace(
+                    max(0.01, min_strike - padding),
+                    max_strike + padding,
+                    points,
+                )
+    else:
+        strike_grid = np.linspace(domain[0], domain[1], points)
+
+    # Evaluate curve
+    fitted_values = vol_curve(strike_grid)
+
+    smile_df = pd.DataFrame(
+        {
+            "strike": strike_grid,
+            "fitted_iv": fitted_values,
+        }
+    )
+
+    if not include_observed:
+        return smile_df
+
+    # Merge observed data if available
+    if observed_iv is not None and not observed_iv.empty:
+        # Mid IV
+        mid_subset = observed_iv[["strike", "iv"]].rename(columns={"iv": "market_iv"})
+        smile_df = pd.merge(smile_df, mid_subset, on="strike", how="left")
+
+    # Bid/Ask/Last IVs from metadata
+    for key, col_name in [
+        ("observed_iv_bid", "market_bid_iv"),
+        ("observed_iv_ask", "market_ask_iv"),
+        ("observed_iv_last", "market_last_iv"),
+    ]:
+        obs_df = metadata.get(key)
+        if isinstance(obs_df, pd.DataFrame) and not obs_df.empty:
+            subset = obs_df[["strike", "iv"]].rename(columns={"iv": col_name})
+            # Ensure strike is float for merging
+            subset["strike"] = subset["strike"].astype(float)
+            smile_df = pd.merge(smile_df, subset, on="strike", how="left")
+
+    return smile_df