quantflow 0.3.3__tar.gz → 0.4.1__tar.gz

{quantflow-0.3.3 → quantflow-0.4.1}/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2024 Quantmind
+Copyright (c) 2023-2025 Quantmind
 
 Redistribution and use in source and binary forms, with or without modification,
 are permitted provided that the following conditions are met:

{quantflow-0.3.3 → quantflow-0.4.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.3
 Name: quantflow
-Version: 0.3.3
+Version: 0.4.1
 Summary: quantitative analysis
 License: BSD-3-Clause
-Author: Luca
+Author: Luca Sbardella
 Author-email: luca@quantmind.com
-Requires-Python: >=3.11
+Requires-Python: >=3.11,<4.0
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -13,18 +13,18 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: cli
 Provides-Extra: data
-Requires-Dist: aio-fluid[http] (>=1.2.1,<2.0.0) ; extra == "data"
-Requires-Dist: asciichartpy (>=1.5.25,<2.0.0) ; extra == "cli"
-Requires-Dist: async-cache (>=1.1.1,<2.0.0) ; extra == "cli"
-Requires-Dist: ccy (>=1.7.1,<2.0.0)
-Requires-Dist: click (>=8.1.7,<9.0.0) ; extra == "cli"
-Requires-Dist: holidays (>=0.63,<0.64) ; extra == "cli"
-Requires-Dist: polars[pandas,pyarrow] (>=1.11.0,<2.0.0)
-Requires-Dist: prompt-toolkit (>=3.0.43,<4.0.0) ; extra == "cli"
-Requires-Dist: pydantic (>=2.0.2,<3.0.0)
-Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
-Requires-Dist: rich (>=13.9.4,<14.0.0) ; extra == "cli"
-Requires-Dist: scipy (>=1.14.1,<2.0.0)
+Requires-Dist: aio-fluid[http] (>=1.2.1) ; extra == "data"
+Requires-Dist: asciichartpy (>=1.5.25) ; extra == "cli"
+Requires-Dist: async-cache (>=1.1.1) ; extra == "cli"
+Requires-Dist: ccy (>=1.7.1)
+Requires-Dist: click (>=8.1.7) ; extra == "cli"
+Requires-Dist: holidays (>=0.63) ; extra == "cli"
+Requires-Dist: polars[pandas,pyarrow] (>=1.11.0)
+Requires-Dist: prompt-toolkit (>=3.0.43) ; extra == "cli"
+Requires-Dist: pydantic (>=2.0.2)
+Requires-Dist: python-dotenv (>=1.0.1)
+Requires-Dist: rich (>=13.9.4) ; extra == "cli"
+Requires-Dist: scipy (>=1.14.1)
 Project-URL: Documentation, https://quantmind.github.io/quantflow/
 Project-URL: Homepage, https://github.com/quantmind/quantflow
 Project-URL: Repository, https://github.com/quantmind/quantflow

{quantflow-0.3.3 → quantflow-0.4.1}/pyproject.toml

@@ -1,52 +1,48 @@
-[tool.poetry]
+[project]
 name = "quantflow"
-version = "0.3.3"
+version = "0.4.1"
 description = "quantitative analysis"
-authors = ["Luca <luca@quantmind.com>"]
+authors = [{ name = "Luca Sbardella", email = "luca@quantmind.com" }]
 license = "BSD-3-Clause"
 readme = "readme.md"
+requires-python = ">=3.11,<4.0"
+dependencies = [
+    "scipy>=1.14.1",
+    "pydantic>=2.0.2",
+    "ccy>=1.7.1",
+    "python-dotenv>=1.0.1",
+    "polars[pandas,pyarrow]>=1.11.0",
+]
 
-[tool.poetry.urls]
+[project.urls]
 Homepage = "https://github.com/quantmind/quantflow"
 Repository = "https://github.com/quantmind/quantflow"
 Documentation = "https://quantmind.github.io/quantflow/"
 
-[tool.poetry.dependencies]
-python = ">=3.11"
-scipy = "^1.14.1"
-pydantic = "^2.0.2"
-ccy = { version = "^1.7.1" }
-python-dotenv = "^1.0.1"
-polars = { version = "^1.11.0", extras = ["pandas", "pyarrow"] }
-asciichartpy = { version = "^1.5.25", optional = true }
-prompt-toolkit = { version = "^3.0.43", optional = true }
-aio-fluid = { version = "^1.2.1", extras = ["http"], optional = true }
-rich = { version = "^13.9.4", optional = true }
-click = { version = "^8.1.7", optional = true }
-holidays = { version = "^0.63", optional = true }
-async-cache = { version = "^1.1.1", optional = true }
+[project.optional-dependencies]
+data = ["aio-fluid[http]>=1.2.1"]
+cli = [
+    "asciichartpy>=1.5.25",
+    "async-cache>=1.1.1",
+    "prompt-toolkit>=3.0.43",
+    "rich>=13.9.4",
+    "click>=8.1.7",
+    "holidays>=0.63",
+]
+
+[project.scripts]
+qf = "quantflow.cli.script:main"
+
 
 [tool.poetry.group.dev.dependencies]
 black = "^25.1.0"
 pytest-cov = "^6.0.0"
 mypy = "^1.14.1"
 ghp-import = "^2.0.2"
-ruff = "^0.11.12"
-pytest-asyncio = "^0.26.0"
+ruff = "^0.12.2"
+pytest-asyncio = "^1.0.0"
 isort = "^6.0.1"
 
-
-[tool.poetry.extras]
-data = ["aio-fluid"]
-cli = [
-    "asciichartpy",
-    "async-cache",
-    "prompt-toolkit",
-    "rich",
-    "click",
-    "holidays",
-]
-
 [tool.poetry.group.book]
 optional = true
 
@@ -62,8 +58,6 @@ sphinx-autosummary-accessors = "^2023.4.0"
 sphinx-copybutton = "^0.5.2"
 autodocsumm = "^0.2.14"
 
-[tool.poetry.scripts]
-qf = "quantflow.cli.script:main"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

{quantflow-0.3.3 → quantflow-0.4.1}/quantflow/__init__.py

@@ -1,3 +1,3 @@
 """Quantitative analysis and pricing"""
 
-__version__ = "0.3.3"
+__version__ = "0.4.1"

{quantflow-0.3.3 → quantflow-0.4.1}/quantflow/data/deribit.py

@@ -9,8 +9,14 @@ from dateutil.parser import parse
 from fluid.utils.data import compact_dict
 from fluid.utils.http_client import AioHttpClient, HttpResponse, HttpResponseError
 
+from quantflow.options.inputs import OptionType
 from quantflow.options.surface import VolSecurityType, VolSurfaceLoader
-from quantflow.utils.numbers import round_to_step, to_decimal
+from quantflow.utils.numbers import (
+    Number,
+    round_to_step,
+    to_decimal,
+    to_decimal_or_none,
+)
 
 
 def parse_maturity(v: str) -> datetime:
@@ -80,9 +86,19 @@ class Deribit(AioHttpClient):
         kw.update(params=dict(currency=currency), callback=self.to_df)
         return await self.get_path("public/get_historical_volatility", **kw)
 
-    async def volatility_surface_loader(self, currency: str) -> VolSurfaceLoader:
+    async def volatility_surface_loader(
+        self,
+        currency: str,
+        *,
+        exclude_open_interest: Number | None = None,
+        exclude_volume: Number | None = None,
+    ) -> VolSurfaceLoader:
         """Create a :class:`.VolSurfaceLoader` for a given crypto-currency"""
-        loader = VolSurfaceLoader()
+        loader = VolSurfaceLoader(
+            asset=currency,
+            exclude_open_interest=to_decimal_or_none(exclude_open_interest),
+            exclude_volume=to_decimal_or_none(exclude_volume),
+        )
         futures = await self.get_book_summary_by_currency(
             currency=currency, kind=InstrumentKind.future
         )
@@ -92,9 +108,9 @@ class Deribit(AioHttpClient):
         instruments = await self.get_instruments(currency=currency)
         instrument_map = {i["instrument_name"]: i for i in instruments}
         min_tick_size = Decimal("inf")
-        for future in futures:
-            if (bid_ := future["bid_price"]) and (ask_ := future["ask_price"]):
-                name = future["instrument_name"]
+        for entry in futures:
+            if (bid_ := entry["bid_price"]) and (ask_ := entry["ask_price"]):
+                name = entry["instrument_name"]
                 meta = instrument_map[name]
                 tick_size = to_decimal(meta["tick_size"])
                 min_tick_size = min(min_tick_size, tick_size)
@@ -105,8 +121,8 @@ class Deribit(AioHttpClient):
                         VolSecurityType.spot,
                         bid=bid,
                         ask=ask,
-                        open_interest=int(future["open_interest"]),
-                        volume=int(future["volume_usd"]),
+                        open_interest=to_decimal(entry["open_interest"]),
+                        volume=to_decimal(entry["volume_usd"]),
                     )
                 else:
                     maturity = pd.to_datetime(
@@ -119,15 +135,15 @@ class Deribit(AioHttpClient):
                         maturity=maturity,
                         bid=bid,
                         ask=ask,
-                        open_interest=int(future["open_interest"]),
-                        volume=int(future["volume_usd"]),
+                        open_interest=to_decimal(entry["open_interest"]),
+                        volume=to_decimal(entry["volume_usd"]),
                     )
         loader.tick_size_forwards = min_tick_size
 
         min_tick_size = Decimal("inf")
-        for option in options:
-            if (bid_ := option["bid_price"]) and (ask_ := option["ask_price"]):
-                name = option["instrument_name"]
+        for entry in options:
+            if (bid_ := entry["bid_price"]) and (ask_ := entry["ask_price"]):
+                name = entry["instrument_name"]
                 meta = instrument_map[name]
                 tick_size = to_decimal(meta["tick_size"])
                 min_tick_size = min(min_tick_size, tick_size)
@@ -139,9 +155,15 @@ class Deribit(AioHttpClient):
                         unit="ms",
                         utc=True,
                     ).to_pydatetime(),
-                    call=meta["option_type"] == "call",
+                    option_type=(
+                        OptionType.call
+                        if meta["option_type"] == "call"
+                        else OptionType.put
+                    ),
                     bid=round_to_step(bid_, tick_size),
                     ask=round_to_step(ask_, tick_size),
+                    open_interest=to_decimal(entry["open_interest"]),
+                    volume=to_decimal(entry["volume_usd"]),
                 )
         loader.tick_size_options = min_tick_size
         return loader

{quantflow-0.3.3 → quantflow-0.4.1}/quantflow/data/fmp.py

@@ -74,7 +74,7 @@ class FMP(AioHttpClient):
         if not to_date:
             to_date = date.today() + timedelta(days=7)
         params = {"from": isoformat(from_date), "to": isoformat(to_date)}
-        return await self.get_path("stock_dividend_calendar", params=params, **kw)
+        return await self.get_path("dividends-calendar", params=params, **kw)
 
     # Executives
 

quantflow-0.4.1/quantflow/options/inputs.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import enum
+from datetime import datetime
+from decimal import Decimal
+from typing import TypeVar
+
+from pydantic import BaseModel
+
+from quantflow.utils.numbers import ZERO
+
+P = TypeVar("P")
+
+
+class Side(enum.StrEnum):
+    """Side of the market"""
+
+    bid = enum.auto()
+    ask = enum.auto()
+
+
+class OptionType(enum.StrEnum):
+    """Type of option"""
+
+    call = enum.auto()
+    put = enum.auto()
+
+    def is_call(self) -> bool:
+        return self is OptionType.call
+
+    def is_put(self) -> bool:
+        return self is OptionType.put
+
+
+class VolSecurityType(enum.StrEnum):
+    """Type of security for the volatility surface"""
+
+    spot = enum.auto()
+    forward = enum.auto()
+    option = enum.auto()
+
+    def vol_surface_type(self) -> VolSecurityType:
+        return self
+
+
+class VolSurfaceInput(BaseModel):
+    bid: Decimal
+    ask: Decimal
+    open_interest: Decimal = ZERO
+    volume: Decimal = ZERO
+
+
+class SpotInput(VolSurfaceInput):
+    security_type: VolSecurityType = VolSecurityType.spot
+
+
+class ForwardInput(VolSurfaceInput):
+    maturity: datetime
+    security_type: VolSecurityType = VolSecurityType.forward
+
+
+class OptionInput(VolSurfaceInput):
+    strike: Decimal
+    maturity: datetime
+    option_type: OptionType
+    security_type: VolSecurityType = VolSecurityType.option
+
+
+class VolSurfaceInputs(BaseModel):
+    asset: str
+    ref_date: datetime
+    inputs: list[ForwardInput | SpotInput | OptionInput]

{quantflow-0.3.3 → quantflow-0.4.1}/quantflow/options/surface.py

@@ -10,17 +10,19 @@ from typing import Any, Generic, Iterator, NamedTuple, Protocol, Self, TypeVar
 import numpy as np
 import pandas as pd
 from ccy.core.daycounter import ActAct, DayCounter
+from pydantic import BaseModel
 
 from quantflow.utils import plot
 from quantflow.utils.dates import utcnow
 from quantflow.utils.interest_rates import rate_from_spot_and_forward
-from quantflow.utils.numbers import Number, sigfig, to_decimal
+from quantflow.utils.numbers import ZERO, Number, sigfig, to_decimal
 
 from .bs import black_price, implied_black_volatility
 from .inputs import (
     ForwardInput,
     OptionInput,
-    OptionSidesInput,
+    OptionType,
+    Side,
     SpotInput,
     VolSecurityType,
     VolSurfaceInput,
@@ -28,7 +30,6 @@ from .inputs import (
 )
 
 INITIAL_VOL = 0.5
-ZERO = Decimal("0")
 default_day_counter = ActAct()
 
 
@@ -70,44 +71,59 @@ class Price(Generic[S]):
 
 @dataclass
 class SpotPrice(Price[S]):
-    open_interest: int = 0
-    volume: int = 0
+    open_interest: Decimal = ZERO
+    volume: Decimal = ZERO
 
     def inputs(self) -> SpotInput:
-        return SpotInput(bid=self.bid, ask=self.ask)
+        return SpotInput(
+            bid=self.bid,
+            ask=self.ask,
+            open_interest=self.open_interest,
+            volume=self.volume,
+        )
 
 
 @dataclass
 class FwdPrice(Price[S]):
     maturity: datetime
-    open_interest: int = 0
-    volume: int = 0
+    open_interest: Decimal = ZERO
+    volume: Decimal = ZERO
 
     def inputs(self) -> ForwardInput:
         return ForwardInput(
             bid=self.bid,
             ask=self.ask,
             maturity=self.maturity,
+            open_interest=self.open_interest,
+            volume=self.volume,
         )
 
 
-@dataclass
-class OptionPrice:
-    price: Decimal
-    """Price of the option divided by the forward price"""
+class OptionMetadata(BaseModel):
     strike: Decimal
     """Strike price"""
-    call: bool
-    """True if call, False if put"""
+    option_type: OptionType
+    """Type of the option"""
     maturity: datetime
     """Maturity date"""
     forward: Decimal = ZERO
     """Forward price of the underlying"""
-    implied_vol: float = 0
-    """Implied Black volatility"""
     ttm: float = 0
     """Time to maturity in years"""
-    side: str = "bid"
+    open_interest: Decimal = ZERO
+    """Open interest of the option"""
+    volume: Decimal = ZERO
+    """Volume of the option in USD"""
+
+
+class OptionPrice(BaseModel):
+    price: Decimal
+    """Price of the option divided by the forward price"""
+    meta: OptionMetadata
+    """Metadata of the option price"""
+    implied_vol: float = 0
+    """Implied Black volatility"""
+    side: Side = Side.bid
     """Side of the market"""
     converged: bool = True
     """Flag indicating if implied vol calculation converged"""
@@ -123,7 +139,9 @@ class OptionPrice:
         ref_date: datetime | None = None,
         maturity: datetime | None = None,
         day_counter: DayCounter | None = None,
-        call: bool = True,
+        option_type: OptionType = OptionType.call,
+        open_interest: Number = ZERO,
+        volume: Number = ZERO,
     ) -> OptionPrice:
         """Create an option price
 
@@ -134,14 +152,46 @@ class OptionPrice:
         day_counter = day_counter or default_day_counter
         return cls(
             price=to_decimal(price),
-            strike=to_decimal(strike),
-            forward=to_decimal(forward or strike),
             implied_vol=implied_vol,
-            call=call,
-            maturity=maturity,
-            ttm=day_counter.dcf(ref_date, maturity),
+            meta=OptionMetadata(
+                strike=to_decimal(strike),
+                forward=to_decimal(forward or strike),
+                option_type=option_type,
+                maturity=maturity,
+                ttm=day_counter.dcf(ref_date, maturity),
+                open_interest=to_decimal(open_interest),
+                volume=to_decimal(volume),
+            ),
         )
 
+    @property
+    def strike(self) -> Decimal:
+        return self.meta.strike
+
+    @property
+    def forward(self) -> Decimal:
+        return self.meta.forward
+
+    @property
+    def maturity(self) -> datetime:
+        return self.meta.maturity
+
+    @property
+    def ttm(self) -> float:
+        return self.meta.ttm
+
+    @property
+    def option_type(self) -> OptionType:
+        return self.meta.option_type
+
+    @property
+    def open_interest(self) -> Decimal:
+        return self.meta.open_interest
+
+    @property
+    def volume(self) -> Decimal:
+        return self.meta.volume
+
     @property
     def moneyness(self) -> float:
         return float(np.log(float(self.strike / self.forward)))
@@ -156,7 +206,7 @@ class OptionPrice:
 
     @property
     def price_intrinsic(self) -> Decimal:
-        if self.call:
+        if self.option_type.is_call():
             return max(self.forward - self.strike, ZERO) / self.forward
         else:
             return max(self.strike - self.forward, ZERO) / self.forward
@@ -171,7 +221,7 @@ class OptionPrice:
 
         use put-call parity to calculate the call price if a put
         """
-        if self.call:
+        if self.option_type.is_call():
             return self.price
         else:
             return self.price + 1 - self.strike / self.forward
@@ -182,15 +232,11 @@ class OptionPrice:
 
         use put-call parity to calculate the put price if a call
         """
-        if self.call:
+        if self.option_type.is_call():
             return self.price - 1 + self.strike / self.forward
         else:
             return self.price
 
-    @property
-    def option_type(self) -> str:
-        return "call" if self.call else "put"
-
     def can_price(self, converged: bool, select: OptionSelection) -> bool:
         if self.price_time > ZERO and not np.isnan(self.implied_vol):
             if not self.converged and converged is True:
@@ -200,14 +246,6 @@ class OptionPrice:
             return True
         return False
 
-    def inputs(self) -> OptionInput:
-        return OptionInput(
-            strike=self.strike,
-            price=self.price,
-            maturity=self.maturity,
-            call=self.call,
-        )
-
     def calculate_price(self) -> OptionPrice:
         self.price = Decimal(
             sigfig(
@@ -215,7 +253,7 @@ class OptionPrice:
                     np.asarray(self.moneyness),
                     self.implied_vol,
                     self.ttm,
-                    1 if self.call else -1,
+                    1 if self.option_type.is_call() else -1,
                 ).sum(),
                 8,
             )
@@ -233,8 +271,10 @@ class OptionPrice:
             price=float(self.price),
             price_bp=float(self.price_bp),
             forward_price=float(self.forward_price),
-            type=self.option_type,
-            side=self.side,
+            type=str(self.option_type),
+            side=str(self.side),
+            open_interest=float(self.open_interest),
+            volume=float(self.volume),
         )
 
 
@@ -250,10 +290,9 @@ class OptionArrays(NamedTuple):
 @dataclass
 class OptionPrices(Generic[S]):
     security: S
+    meta: OptionMetadata
     bid: OptionPrice
     ask: OptionPrice
-    open_interest: int = 0
-    volume: int = 0
 
     def prices(
         self,
@@ -264,18 +303,32 @@ class OptionPrices(Generic[S]):
         initial_vol: float = INITIAL_VOL,
         converged: bool = True,
     ) -> Iterator[OptionPrice]:
+        """Iterator over bid/ask option prices
+
+        :param forward: Forward price of the underlying asset
+        :param ttm: Time to maturity in years
+        :param select: the :class:`.OptionSelection` method
+        :param initial_vol: Initial volatility for the root finding algorithm
+        """
+        self.meta.forward = forward
+        self.meta.ttm = ttm
         for o in (self.bid, self.ask):
-            o.forward = forward
-            o.ttm = ttm
+            o.meta.forward = forward
+            o.meta.ttm = ttm
             if not o.implied_vol:
                 o.implied_vol = initial_vol
             if o.can_price(converged, select):
                 yield o
 
-    def inputs(self) -> OptionSidesInput:
-        return OptionSidesInput(
-            bid=self.bid.inputs(),
-            ask=self.ask.inputs(),
+    def inputs(self) -> OptionInput:
+        return OptionInput(
+            bid=self.bid.price,
+            ask=self.ask.price,
+            open_interest=self.meta.open_interest,
+            volume=self.meta.volume,
+            strike=self.meta.strike,
+            maturity=self.meta.maturity,
+            option_type=self.meta.option_type,
         )
 
 
@@ -402,6 +455,8 @@ class VolSurface(Generic[S]):
 
     ref_date: datetime
     """Reference date for the volatility surface"""
+    asset: str
+    """Name of the underlying asset"""
     spot: SpotPrice[S]
     """Spot price of the underlying asset"""
     maturities: tuple[VolCrossSection[S], ...]
@@ -421,7 +476,9 @@ class VolSurface(Generic[S]):
 
     def inputs(self) -> VolSurfaceInputs:
         return VolSurfaceInputs(
-            ref_date=self.ref_date, inputs=list(s.inputs() for s in self.securities())
+            asset=self.asset,
+            ref_date=self.ref_date,
+            inputs=list(s.inputs() for s in self.securities()),
         )
 
     def term_structure(self, frequency: float = 0) -> pd.DataFrame:
@@ -442,7 +499,12 @@ class VolSurface(Generic[S]):
         initial_vol: float = INITIAL_VOL,
         converged: bool = True,
     ) -> Iterator[OptionPrice]:
-        "Iterator over selected option prices in the surface"
+        """Iterator over selected option prices in the surface
+
+        :param select: the :class:`.OptionSelection` method
+        :param index: Index of the cross section to use, if None use all
+        :param initial_vol: Initial volatility for the root finding algorithm
+        """
         if index is not None:
             yield from self.maturities[index].option_prices(
                 self.ref_date,
@@ -543,7 +605,12 @@ class VolSurface(Generic[S]):
         initial_vol: float = INITIAL_VOL,
         converged: bool = True,
     ) -> OptionArrays:
-        """Organize option prices in a numpy arrays for black volatility calculation"""
+        """Organize option prices in a numpy arrays for black volatility calculation
+
+        :param select: the :class:`.OptionSelection` method
+        :param index: Index of the cross section to use, if None use all
+        :param initial_vol: Initial volatility for the root finding algorithm
+        """
         options = list(
             self.option_prices(
                 select=select,
@@ -562,7 +629,7 @@ class VolSurface(Generic[S]):
             price.append(float(option.price))
             ttm.append(float(option.ttm))
             vol.append(float(option.implied_vol))
-            call_put.append(1 if option.call else -1)
+            call_put.append(1 if option.option_type.is_call() else -1)
         return OptionArrays(
             options=options,
             moneyness=np.array(moneyness),
@@ -616,35 +683,29 @@ class VolCrossSectionLoader(Generic[S]):
     def add_option(
         self,
         strike: Decimal,
-        call: bool,
+        option_type: OptionType,
         security: S,
         bid: Decimal = ZERO,
         ask: Decimal = ZERO,
-        open_interest: int = 0,
-        volume: int = 0,
+        open_interest: Decimal = ZERO,
+        volume: Decimal = ZERO,
     ) -> None:
         if strike not in self.strikes:
             self.strikes[strike] = Strike(strike=strike)
-        option = OptionPrices(
-            security,
-            bid=OptionPrice(
-                price=bid,
-                strike=strike,
-                call=call,
-                maturity=self.maturity,
-                side="bid",
-            ),
-            ask=OptionPrice(
-                price=ask,
-                strike=strike,
-                call=call,
-                maturity=self.maturity,
-                side="ask",
-            ),
+        meta = OptionMetadata(
+            strike=strike,
+            option_type=option_type,
+            maturity=self.maturity,
             open_interest=open_interest,
             volume=volume,
         )
-        if call:
+        option = OptionPrices(
+            security=security,
+            meta=meta,
+            bid=OptionPrice(price=bid, meta=meta, side=Side.bid),
+            ask=OptionPrice(price=ask, meta=meta, side=Side.ask),
+        )
+        if option_type.is_call():
             self.strikes[strike].call = option
         else:
             self.strikes[strike].put = option
@@ -674,6 +735,8 @@ class VolCrossSectionLoader(Generic[S]):
 class GenericVolSurfaceLoader(Generic[S]):
     """Helper class to build a volatility surface from a list of securities"""
 
+    asset: str = ""
+    """Name of the underlying asset"""
     spot: SpotPrice[S] | None = None
     """Spot price of the underlying asset"""
     maturities: dict[datetime, VolCrossSectionLoader[S]] = field(default_factory=dict)
@@ -684,6 +747,10 @@ class GenericVolSurfaceLoader(Generic[S]):
     """Tick size for rounding forward and spot prices - optional"""
     tick_size_options: Decimal | None = None
     """Tick size for rounding option prices - optional"""
+    exclude_open_interest: Decimal | None = None
+    """Exclude options with open interest at or below this value"""
+    exclude_volume: Decimal | None = None
+    """Exclude options with volume at or below this value"""
 
     def get_or_create_maturity(self, maturity: datetime) -> VolCrossSectionLoader[S]:
         if maturity not in self.maturities:
@@ -698,8 +765,8 @@ class GenericVolSurfaceLoader(Generic[S]):
         security: S,
         bid: Decimal = ZERO,
         ask: Decimal = ZERO,
-        open_interest: int = 0,
-        volume: int = 0,
+        open_interest: Decimal = ZERO,
+        volume: Decimal = ZERO,
     ) -> None:
         """Add a spot to the volatility surface loader"""
         if security.vol_surface_type() != VolSecurityType.spot:
@@ -718,8 +785,8 @@ class GenericVolSurfaceLoader(Generic[S]):
         maturity: datetime,
         bid: Decimal = ZERO,
         ask: Decimal = ZERO,
-        open_interest: int = 0,
-        volume: int = 0,
+        open_interest: Decimal = ZERO,
+        volume: Decimal = ZERO,
     ) -> None:
         """Add a forward to the volatility surface loader"""
         if security.vol_surface_type() != VolSecurityType.forward:
@@ -738,19 +805,26 @@ class GenericVolSurfaceLoader(Generic[S]):
         security: S,
         strike: Decimal,
         maturity: datetime,
-        call: bool,
+        option_type: OptionType,
         bid: Decimal = ZERO,
         ask: Decimal = ZERO,
-        open_interest: int = 0,
-        volume: int = 0,
+        open_interest: Decimal = ZERO,
+        volume: Decimal = ZERO,
     ) -> None:
         """Add an option to the volatility surface loader"""
         if security.vol_surface_type() != VolSecurityType.option:
             raise ValueError("Security is not an option")
+        if self.exclude_volume is not None and volume <= self.exclude_volume:
+            return
+        if (
+            self.exclude_open_interest is not None
+            and open_interest <= self.exclude_open_interest
+        ):
+            return
         self.get_or_create_maturity(maturity=maturity).add_option(
-            strike,
-            call,
-            security,
+            strike=strike,
+            option_type=option_type,
+            security=security,
             bid=bid,
             ask=ask,
             open_interest=open_interest,
@@ -766,6 +840,7 @@ class GenericVolSurfaceLoader(Generic[S]):
             if section := self.maturities[maturity].cross_section():
                 maturities.append(section)
         return VolSurface(
+            asset=self.asset,
             ref_date=ref_date or utcnow(),
             spot=self.spot,
             maturities=tuple(maturities),
@@ -776,29 +851,41 @@ class GenericVolSurfaceLoader(Generic[S]):
 
 
 class VolSurfaceLoader(GenericVolSurfaceLoader[VolSecurityType]):
-    def add(self, input: VolSurfaceInput[Any]) -> None:
+    """A volatility surface loader"""
+
+    def add(self, input: VolSurfaceInput) -> None:
         """Add a volatility security input to the loader
 
         :params input: The input data for the security,
             it can be spot, forward or option
         """
         if isinstance(input, SpotInput):
-            self.add_spot(VolSecurityType.spot, bid=input.bid, ask=input.ask)
+            self.add_spot(
+                VolSecurityType.spot,
+                bid=input.bid,
+                ask=input.ask,
+                open_interest=input.open_interest,
+                volume=input.volume,
+            )
         elif isinstance(input, ForwardInput):
             self.add_forward(
                 VolSecurityType.forward,
                 maturity=input.maturity,
                 bid=input.bid,
                 ask=input.ask,
+                open_interest=input.open_interest,
+                volume=input.volume,
             )
-        elif isinstance(input, OptionSidesInput):
+        elif isinstance(input, OptionInput):
             self.add_option(
                 VolSecurityType.option,
-                strike=assert_same(input.bid.strike, input.ask.strike),
-                call=assert_same(input.bid.call, input.ask.call),
-                maturity=assert_same(input.bid.maturity, input.ask.maturity),
-                bid=input.bid.price,
-                ask=input.ask.price,
+                strike=input.strike,
+                option_type=input.option_type,
+                maturity=input.maturity,
+                bid=input.bid,
+                ask=input.ask,
+                open_interest=input.open_interest,
+                volume=input.volume,
             )
         else:
             raise ValueError(f"Unknown input type {type(input)}")

{quantflow-0.3.3 → quantflow-0.4.1}/quantflow/utils/numbers.py

@@ -18,6 +18,11 @@ def to_decimal(value: Number) -> Decimal:
     return Decimal(str(value)) if not isinstance(value, Decimal) else value
 
 
+def to_decimal_or_none(value: Number | None) -> Decimal | None:
+    """Convert a value to Decimal, or return None if the value is None."""
+    return to_decimal(value) if value is not None else None
+
+
 def sigfig(value: Number, sig: int = 5) -> str:
     """round a number to the given significant digit"""
     return f"%.{sig}g" % to_decimal(value)

{quantflow-0.3.3 → quantflow-0.4.1}/quantflow/utils/plot.py

@@ -40,7 +40,7 @@ def plot_marginal_pdf(
     label: str = "characteristic PDF",
     log_y: bool = False,
     fig: Any | None = None,
-    **kwargs: Any
+    **kwargs: Any,
 ) -> Any:
     """Plot the marginal pdf on an input support"""
     check_plotly()
@@ -104,7 +104,7 @@ def plot_vol_surface(
     color_series: str = "side",
     fig: Any | None = None,
     fig_params: dict | None = None,
-    **kwargs: Any
+    **kwargs: Any,
 ) -> Any:
     check_plotly()
     # Define a color map for the categorical values
@@ -144,7 +144,7 @@ def plot_vol_surface_3d(
     *,
     marker_size: int = 10,
     series: str = "implied_vol",
-    **kwargs: Any
+    **kwargs: Any,
 ) -> Any:
     check_plotly()
     return px.scatter_3d(df, x="moneyness_ttm", y="ttm", z=series, color="side")
@@ -158,7 +158,7 @@ def plot_vol_cross(
     marker_size: int = 10,
     fig: Any | None = None,
     name: str = "model",
-    **kwargs: Any
+    **kwargs: Any,
 ) -> Any:
     check_plotly()
     fig = fig or go.Figure()
@@ -188,7 +188,7 @@ def plot3d(
     z: FloatArray,
     contours: Any | None,
     colorscale: str = "viridis",
-    **kwargs: Any
+    **kwargs: Any,
 ) -> Any:
     check_plotly()
     fig = go.Figure(

quantflow-0.3.3/quantflow/options/inputs.py

@@ -1,51 +0,0 @@
-from __future__ import annotations
-
-import enum
-from datetime import datetime
-from decimal import Decimal
-from typing import Generic, TypeVar
-
-from pydantic import BaseModel
-
-P = TypeVar("P")
-
-
-class VolSecurityType(enum.StrEnum):
-    """Type of security for the volatility surface"""
-
-    spot = enum.auto()
-    forward = enum.auto()
-    option = enum.auto()
-
-    def vol_surface_type(self) -> VolSecurityType:
-        return self
-
-
-class VolSurfaceInput(BaseModel, Generic[P]):
-    bid: P
-    ask: P
-
-
-class OptionInput(BaseModel):
-    price: Decimal
-    strike: Decimal
-    maturity: datetime
-    call: bool
-
-
-class SpotInput(VolSurfaceInput[Decimal]):
-    security_type: VolSecurityType = VolSecurityType.spot
-
-
-class ForwardInput(VolSurfaceInput[Decimal]):
-    maturity: datetime
-    security_type: VolSecurityType = VolSecurityType.forward
-
-
-class OptionSidesInput(VolSurfaceInput[OptionInput]):
-    security_type: VolSecurityType = VolSecurityType.option
-
-
-class VolSurfaceInputs(BaseModel):
-    ref_date: datetime
-    inputs: list[ForwardInput | SpotInput | OptionSidesInput]