optPricing 2.0.0__py3-none-any.whl

quantfin/data/historical_manager.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import yfinance as yf
+
+from quantfin.config import HISTORICAL_DIR
+
+
+def save_historical_returns(
+    tickers: list[str],
+    period: str = "10y",
+):
+    """
+    Fetches and saves historical log returns for a list of tickers.
+
+    This function iterates through a list of stock tickers, fetches historical
+    price data from yfinance for the specified period, calculates the daily
+    log returns, and saves them to a parquet file in the historical data directory.
+
+    Parameters
+    ----------
+    tickers : list[str]
+        A list of stock tickers to process, e.g., ['SPY', 'AAPL'].
+    period : str, optional
+        The time period for which to fetch data, e.g., "10y", "5y", "1mo".
+        Defaults to "10y".
+    """
+    print(f"--- Saving {period} Historical Returns ---")
+    for ticker in tickers:
+        try:
+            print(f"Fetching data for {ticker}...")
+            data = yf.Ticker(ticker).history(period=period)
+
+            if data.empty:
+                print(f"  -> No data found for {ticker}. Skipping.")
+                continue
+
+            log_returns = np.log(data["Close"] / data["Close"].shift(1)).dropna()
+            filename = HISTORICAL_DIR / f"{ticker}_{period}_returns.parquet"
+            log_returns.to_frame(name="log_return").to_parquet(filename)
+
+            print(f"  -> Saved to {filename}")
+
+        except Exception as e:
+            print(f"  -> FAILED to save data for {ticker}. Error: {e}")
+
+
+def load_historical_returns(
+    ticker: str,
+    period: str = "10y",
+) -> pd.Series:
+    """
+    Loads historical log returns, fetching and saving them if not found.
+
+    Checks for a pre-saved parquet file for the given ticker and period. If
+    the file does not exist, it calls `save_historical_returns` to download
+    and save it first.
+
+    Parameters
+    ----------
+    ticker : str
+        The stock ticker for which to load returns, e.g., 'SPY'.
+    period : str, optional
+        The time period for which to fetch data, e.g., "10y", "5y", "1mo".
+        Defaults to "10y".
+
+    Returns
+    -------
+    pd.Series
+        A pandas Series containing the historical log returns.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the data file cannot be found and also fails to be downloaded.
+    """
+    filename = HISTORICAL_DIR / f"{ticker}_{period}_returns.parquet"
+    if not filename.exists():
+        print(f"No historical data found for {ticker}. Fetching and saving now...")
+        save_historical_returns([ticker], period)
+
+    if not filename.exists():
+        raise FileNotFoundError(f"Could not find or save historical data for {ticker}.")
+
+    return pd.read_parquet(filename)["log_return"]

quantfin/data/market_data_manager.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+
+import pandas as pd
+import yfinance as yf
+from polygon import RESTClient
+
+from quantfin.config import MARKET_SNAPSHOT_DIR, POLYGON_API_KEY, _config
+
+
+def _fetch_from_yfinance(ticker: str) -> pd.DataFrame | None:
+    """Fetches a live option chain using yfinance."""
+    print(f"Fetching live option chain for {ticker} from yfinance...")
+    try:
+        ticker_obj = yf.Ticker(ticker)
+        expirations = ticker_obj.options
+        if not expirations:
+            return None
+
+        all_options = []
+        for expiry in expirations:
+            opt = ticker_obj.option_chain(expiry)
+            if not opt.calls.empty:
+                opt.calls["optionType"] = "call"
+                opt.calls["expiry"] = pd.to_datetime(expiry)
+                all_options.append(opt.calls)
+            if not opt.puts.empty:
+                opt.puts["optionType"] = "put"
+                opt.puts["expiry"] = pd.to_datetime(expiry)
+                all_options.append(opt.puts)
+
+        if not all_options:
+            return None
+
+        chain_df = pd.concat(all_options, ignore_index=True)
+        today_date = datetime.combine(date.today(), datetime.min.time())
+        chain_df["maturity"] = (chain_df["expiry"] - today_date).dt.days / 365.25
+        chain_df["last_price"] = (chain_df["bid"] + chain_df["ask"]) / 2.0
+        chain_df["spot_price"] = ticker_obj.fast_info.get(
+            "last_price", ticker_obj.history("1d")["Close"].iloc[0]
+        )
+
+        chain_df.dropna(
+            subset=["last_price", "strike", "maturity", "impliedVolatility"],
+            inplace=True,
+        )
+        chain_df = chain_df[
+            (chain_df["last_price"] > 0.01) & (chain_df["maturity"] > 1 / 365.25)
+        ].copy()
+        return chain_df
+
+    except Exception as e:
+        print(f"  -> FAILED to fetch live yfinance data for {ticker}. Error: {e}")
+        return None
+
+
+def _fetch_from_polygon(ticker: str) -> pd.DataFrame | None:
+    """Fetches a live option chain using Polygon.io."""
+    print(f"Fetching live option chain for {ticker} from Polygon.io...")
+    if not POLYGON_API_KEY or "YOUR_KEY" in POLYGON_API_KEY:
+        print("Error: Polygon API key not set in config.yaml or environment variables.")
+        return None
+
+    client = RESTClient(POLYGON_API_KEY)
+    try:
+        # limited implementation for a free account
+        # gets the chain for the next expiration date.
+        expirations = list(
+            client.list_options_contracts(
+                underlying_ticker=ticker, expired=False, limit=1
+            )
+        )
+        if not expirations:
+            return None
+
+        expiry_date = expirations[0].expiration_date
+        contracts = list(
+            client.list_options_contracts(
+                underlying_ticker=ticker, expiration_date=expiry_date, limit=1000
+            )
+        )
+        if not contracts:
+            return None
+
+        # A single snapshot call
+        snapshot = client.get_options_chain(
+            underlying_ticker=ticker, expiration_date=expiry_date
+        )
+
+        data = []
+        for contract_details in snapshot.results:
+            greeks = contract_details.greeks
+            data.append(
+                {
+                    "ticker": contract_details.ticker,
+                    "underlying": ticker,
+                    "strike": contract_details.details.strike_price,
+                    "expiry": pd.to_datetime(contract_details.details.expiration_date),
+                    "optionType": "call"
+                    if contract_details.details.contract_type == "call"
+                    else "put",
+                    "spot_price": greeks.underlying_price,
+                    "last_price": contract_details.last_quote.bid,
+                    "impliedVolatility": greeks.implied_volatility,
+                    "volume": contract_details.day.volume,
+                    "open_interest": contract_details.open_interest,
+                }
+            )
+
+        df = pd.DataFrame(data)
+        df["maturity"] = (df["expiry"] - pd.Timestamp.now()).dt.days / 365.25
+        return df
+
+    except Exception as e:
+        print(f"An error occurred while fetching live Polygon data: {e}")
+        return None
+
+
+def get_live_option_chain(ticker: str) -> pd.DataFrame | None:
+    """
+    Fetches a live option chain from the configured data provider.
+
+    The data provider is determined by the `live_data_provider` key in the
+    `config.yaml` file. Supported providers are "yfinance" and "polygon".
+
+    Parameters
+    ----------
+    ticker : str
+        The stock ticker for which to fetch the option chain, e.g., 'SPY'.
+
+    Returns
+    -------
+    pd.DataFrame | None
+        A DataFrame containing the formatted option chain data, or None if
+        the fetch fails or no data is returned.
+    """
+    provider = _config.get("live_data_provider", "yfinance").lower()
+    if provider == "polygon":
+        return _fetch_from_polygon(ticker)
+
+    elif provider == "yfinance":
+        return _fetch_from_yfinance(ticker)
+
+    else:
+        print(
+            f"Warning: Unknown live_data_provider '{provider}'. Defaulting to yfinance."
+        )
+        return _fetch_from_yfinance(ticker)
+
+
+def save_market_snapshot(tickers: list[str]):
+    """
+    Saves a snapshot of the current market option chain for given tickers.
+
+    For each ticker, it fetches the live option chain using
+    `get_live_option_chain` and saves it to a parquet file named with the
+    ticker and the current date.
+
+    Parameters
+    ----------
+    tickers : list[str]
+        A list of stock tickers to process, e.g., ['SPY', 'AAPL'].
+    """
+    today_str = date.today().strftime("%Y-%m-%d")
+
+    print(f"--- Saving Market Data Snapshot for {today_str} ---")
+    for ticker in tickers:
+        chain_df = get_live_option_chain(ticker)
+
+        if chain_df is None or chain_df.empty:
+            print(f"  -> No valid option data found for {ticker}. Skipping.")
+            continue
+
+        filename = MARKET_SNAPSHOT_DIR / f"{ticker}_{today_str}.parquet"
+        chain_df.to_parquet(filename)
+        print(f"  -> Successfully saved {len(chain_df)} options to {filename}")
+
+
+def load_market_snapshot(ticker: str, snapshot_date: str) -> pd.DataFrame | None:
+    """
+    Loads a previously saved market data snapshot for a specific date.
+
+    Parameters
+    ----------
+    ticker : str
+        The stock ticker of the desired snapshot, e.g., 'SPY'.
+    snapshot_date : str
+        The date of the snapshot in 'YYYY-MM-DD' format.
+
+    Returns
+    -------
+    pd.DataFrame | None
+        A DataFrame containing the snapshot data, or None if the file
+        is not found.
+    """
+    filename = MARKET_SNAPSHOT_DIR / f"{ticker}_{snapshot_date}.parquet"
+    if not filename.exists():
+        print(f"Error: Snapshot file not found: {filename}")
+        return None
+
+    print(f"Loading data from {filename}...")
+    return pd.read_parquet(filename)
+
+
+def get_available_snapshot_dates(ticker: str) -> list[str]:
+    """
+    Lists all available snapshot dates for a given ticker.
+
+    Scans the market data directory for saved parquet files corresponding
+    to the ticker and extracts the date from the filenames.
+
+    Parameters
+    ----------
+    ticker : str
+        The stock ticker to search for, e.g., 'SPY'.
+
+    Returns
+    -------
+    list[str]
+        A sorted list of available dates in 'YYYY-MM-DD' format, from
+        most recent to oldest.
+    """
+    try:
+        files = [
+            f.name
+            for f in MARKET_SNAPSHOT_DIR.iterdir()
+            if f.name.startswith(f"{ticker}_") and f.name.endswith(".parquet")
+        ]
+        return sorted(
+            [f.replace(f"{ticker}_", "").replace(".parquet", "") for f in files],
+            reverse=True,
+        )
+
+    except FileNotFoundError:
+        return []

quantfin/models/__init__.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+__doc__ = """
+The `models` package contains all financial models for option pricing.
+
+It provides the abstract `BaseModel` and a suite of concrete implementations,
+from the standard Black-Scholes-Merton to advanced stochastic volatility
+and jump-diffusion models.
+"""
+
+from .base import CF, BaseModel, ParamValidator, PDECoeffs
+from .bates import BatesModel
+from .blacks_approx import BlacksApproxModel
+from .bsm import BSMModel
+from .cev import CEVModel
+from .cgmy import CGMYModel
+from .cir import CIRModel
+from .dupire_local import DupireLocalVolModel
+from .heston import HestonModel
+from .hyperbolic import HyperbolicModel
+from .kou import KouModel
+from .merton_jump import MertonJumpModel
+from .nig import NIGModel
+from .perpetual_put import PerpetualPutModel
+from .sabr import SABRModel
+from .sabr_jump import SABRJumpModel
+from .vasicek import VasicekModel
+from .vg import VarianceGammaModel
+
+__all__ = [
+    # Base Components
+    "BaseModel",
+    "CF",
+    "PDECoeffs",
+    "ParamValidator",
+    # Concrete Models
+    "BatesModel",
+    "BlacksApproxModel",
+    "BSMModel",
+    "CEVModel",
+    "CGMYModel",
+    "CIRModel",
+    "DupireLocalVolModel",
+    "HestonModel",
+    "HyperbolicModel",
+    "KouModel",
+    "MertonJumpModel",
+    "NIGModel",
+    "PerpetualPutModel",
+    "SABRJumpModel",
+    "SABRModel",
+    "VarianceGammaModel",
+    "VasicekModel",
+]

quantfin/models/base/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+__doc__ = """
+This module provides the foundational abstract classes and utilities for all
+financial models in the library, including the abstract `BaseModel` and
+parameter validation tools.
+"""
+from .base_model import CF, BaseModel, PDECoeffs
+from .validators import ParamValidator
+
+__all__ = [
+    "BaseModel",
+    "CF",
+    "PDECoeffs",
+    "ParamValidator",
+]

quantfin/models/base/base_model.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+
+__doc__ = """
+Defines the abstract base class for all option pricing models.
+"""
+
+CF = Callable[[np.ndarray], np.ndarray]
+PDECoeffs = Callable[[np.ndarray, float], tuple[np.ndarray, np.ndarray, np.ndarray]]
+
+
+class BaseModel(ABC):
+    """
+    Abstract base class for all financial pricing models.
+
+    This class defines a common interface for all models, including parameter
+    validation, metadata flags for supported features (e.g., characteristic
+    function, SDE), and methods for creating modified model instances.
+
+    Attributes
+    ----------
+    name : str
+        A string identifier for the model (e.g., "Black-Scholes-Merton").
+    params : dict[str, float]
+        A dictionary holding the model's parameters.
+    supports_cf : bool
+        Flag indicating if the model implements a characteristic function.
+    supports_sde : bool
+        Flag indicating if the model implements an SDE simulation path.
+    supports_pde : bool
+        Flag indicating if the model provides PDE coefficients.
+    has_closed_form : bool
+        Flag indicating if a closed-form solution is available.
+    has_variance_process : bool
+        Flag for stochastic volatility models (e.g., Heston, SABR).
+    is_pure_levy : bool
+        Flag for pure Levy models where the terminal value can be sampled directly.
+    has_jumps : bool
+        Flag for models that include a jump component.
+    """
+
+    name: str = "BaseModel"
+    params: dict[str, float]
+    supports_cf: bool = False
+    supports_sde: bool = False
+    supports_pde: bool = False
+    has_closed_form: bool = False
+    has_variance_process: bool = False
+    is_pure_levy: bool = False
+    has_jumps: bool = False
+
+    # TODO: Rename cf_kwargs to something more specific like `pricing_args`
+    # as it's used by more than just the characteristic function.
+    cf_kwargs: tuple[str, ...] = ()
+
+    __slots__ = ("params",)
+
+    def __init__(self, params: dict[str, float]) -> None:
+        """
+        Initializes the model and validates its parameters.
+
+        Parameters
+        ----------
+        params : dict[str, float]
+            A dictionary of parameter names to values for the model.
+        """
+        self.params = params
+        self._validate_params()
+
+    @abstractmethod
+    def _validate_params(self) -> None:
+        """
+        Abstract method for subclasses to validate their specific parameters.
+
+        This method should be implemented by all concrete model classes to ensure
+        that the provided `self.params` dictionary contains all required keys
+        and that their values are valid.
+        """
+        raise NotImplementedError
+
+    def cf(self, **kwargs: Any) -> CF:
+        """
+        Return the characteristic function of the log-price process.
+
+        Raises
+        ------
+        NotImplementedError
+            If the model does not support a characteristic function.
+        """
+        if not self.supports_cf:
+            raise NotImplementedError(
+                f"{self.name} does not support characteristic functions."
+            )
+        return self._cf_impl(**kwargs)
+
+    @abstractmethod
+    def _cf_impl(self, **kwargs: Any) -> CF:
+        """Internal implementation of the characteristic function."""
+        ...
+
+    def get_sde_sampler(self, **kwargs: Any) -> Callable:
+        """
+        Return a function that can be used to sample paths from the model's SDE.
+
+        Raises
+        ------
+        NotImplementedError
+            If the model does not support SDE sampling.
+        """
+        if not self.supports_sde:
+            raise NotImplementedError(f"{self.name} does not support SDE sampling.")
+        return self._sde_impl(**kwargs)
+
+    @abstractmethod
+    def _sde_impl(self, **kwargs: Any) -> Callable:
+        """Internal implementation for returning an SDE sampler."""
+        ...
+
+    def get_pde_coeffs(self, **kwargs: Any) -> PDECoeffs:
+        """
+        Return the coefficients for the pricing PDE.
+
+        Raises
+        ------
+        NotImplementedError
+            If the model does not support PDE solving.
+        """
+        if not self.supports_pde:
+            raise NotImplementedError(f"{self.name} does not support PDE solving.")
+        return self._pde_impl(**kwargs)
+
+    @abstractmethod
+    def _pde_impl(self, **kwargs: Any) -> PDECoeffs:
+        """Internal implementation for returning PDE coefficients."""
+        ...
+
+    def price_closed_form(self, *args, **kwargs) -> float:
+        """
+        Compute the option price using a closed-form solution, if available.
+
+        Raises
+        ------
+        NotImplementedError
+            If the model does not have a closed-form solution.
+        """
+        if not self.has_closed_form:
+            raise NotImplementedError(
+                f"{self.name} does not have a closed-form solution."
+            )
+        return self._closed_form_impl(*args, **kwargs)
+
+    @abstractmethod
+    def _closed_form_impl(self, *args, **kwargs) -> float:
+        """Internal implementation of the closed-form pricing formula."""
+        ...
+
+    def with_params(self, **updated_params: float) -> BaseModel:
+        """
+        Create a new model instance with updated parameters.
+
+        This is useful for calibration and sensitivity analysis.
+
+        Parameters
+        ----------
+        **updated_params : float
+            Keyword arguments for the parameters to update.
+
+        Returns
+        -------
+        BaseModel
+            A new instance of the model with the updated parameters.
+        """
+        new_params = {**self.params, **updated_params}
+        return self.__class__(params=new_params)
+
+    def __repr__(self) -> str:
+        """Provide a formal string representation of the model."""
+        param_str = ", ".join(f"{k}={v:.4f}" for k, v in self.params.items())
+        return f"{self.__class__.__name__}({param_str})"
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Check for equality based on class type and parameters.
+        """
+        if not isinstance(other, self.__class__):
+            return NotImplemented
+        return self.params == other.params
+
+    def __hash__(self) -> int:
+        """
+        Provide a hash for the model, making it usable in sets and dict keys.
+        """
+        return hash((self.__class__, tuple(sorted(self.params.items()))))

quantfin/models/base/validators.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+__doc__ = """
+Provides a utility class for validating parameters passed to financial models.
+"""
+
+
+class ParamValidator:
+    """
+    A utility class containing static methods for model parameter validation.
+
+    This class is not meant to be instantiated. It serves as a namespace
+    for common validation logic used by `BaseModel` subclasses.
+    """
+
+    @staticmethod
+    def require(params: dict[str, float], required: list[str], *, model: str) -> None:
+        """
+        Check for the presence of required parameters.
+
+        Parameters
+        ----------
+        params : dict[str, float]
+            The dictionary of parameters to validate.
+        required : list[str]
+            A list of parameter names that must be present in `params`.
+        model : str
+            The name of the model performing the validation, for error messages.
+
+        Raises
+        ------
+        ValueError
+            If any of the required parameters are missing.
+        """
+        missing = [k for k in required if k not in params]
+        if missing:
+            raise ValueError(
+                f"{model}: missing required parameters: {', '.join(missing)}"
+            )
+
+    @staticmethod
+    def positive(params: dict[str, float], keys: list[str], *, model: str) -> None:
+        """
+        Check if specified parameters are strictly positive.
+
+        Parameters
+        ----------
+        params : dict[str, float]
+            The dictionary of parameters to validate.
+        keys : list[str]
+            A list of parameter names that must be positive.
+        model : str
+            The name of the model performing the validation, for error messages.
+
+        Raises
+        ------
+        ValueError
+            If any of the specified parameters are not strictly positive.
+        """
+        nonpos = [k for k in keys if params.get(k, 0.0) <= 0.0]
+        if nonpos:
+            raise ValueError(
+                f"{model}: parameters must be positive: {', '.join(nonpos)}"
+            )
+
+    @staticmethod
+    def bounded(
+        params: dict[str, float], key: str, low: float, high: float, *, model: str
+    ) -> None:
+        """
+        Check if a parameter is within a specified inclusive range.
+
+        Parameters
+        ----------
+        params : dict[str, float]
+            The dictionary of parameters to validate.
+        key : str
+            The name of the parameter to check.
+        low : float
+            The lower bound of the valid range.
+        high : float
+            The upper bound of the valid range.
+        model : str
+            The name of the model performing the validation, for error messages.
+
+        Raises
+        ------
+        ValueError
+            If the parameter is outside the [low, high] range.
+        """
+        val = params.get(key)
+        if val is None or not (low <= val <= high):
+            raise ValueError(
+                f"{model}: parameter '{key}' must be in [{low}, {high}], got {val}"
+            )