quantflow 0.3.0__tar.gz → 0.3.2__tar.gz

{quantflow-0.3.0 → quantflow-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: quantflow
-Version: 0.3.0
+Version: 0.3.2
 Summary: quantitative analysis
 License: BSD-3-Clause
 Author: Luca
@@ -15,8 +15,10 @@ 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: ccy (==1.6.0)
+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)
@@ -38,7 +40,7 @@ Description-Content-Type: text/markdown
 
 Quantitative analysis and pricing tools.
 
-Documentation is available as [quantflow jupyter book](https://quantmind.github.io/quantflow/).
+Documentation is available as [quantflow jupyter book](https://quantflow.quantmind.com).
 
 ## Installation
 
@@ -51,10 +53,13 @@ pip install quantflow
 
 ## Modules
 
-* [quantflow.cli](https://github.com/quantmind/quantflow/tree/main/quantflow/cli) aommand line client (requires `quantflow[cli,data]`)
+* [quantflow.cli](https://github.com/quantmind/quantflow/tree/main/quantflow/cli) command line client (requires `quantflow[cli,data]`)
 * [quantflow.data](https://github.com/quantmind/quantflow/tree/main/quantflow/data) data APIs (requires `quantflow[data]`)
 * [quantflow.options](https://github.com/quantmind/quantflow/tree/main/quantflow/options) option pricing and calibration
 * [quantflow.sp](https://github.com/quantmind/quantflow/tree/main/quantflow/sp) stochastic process primitives
+* [quantflow.ta](https://github.com/quantmind/quantflow/tree/main/quantflow/ta) timeseries analysis tools
+* [quantflow.utils](https://github.com/quantmind/quantflow/tree/main/quantflow/utils) utilities and helpers
+
 
 
 ## Command line tools

{quantflow-0.3.0 → quantflow-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "quantflow"
-version = "0.3.0"
+version = "0.3.2"
 description = "quantitative analysis"
 authors = ["Luca <luca@quantmind.com>"]
 license = "BSD-3-Clause"
@@ -15,7 +15,7 @@ Documentation = "https://quantmind.github.io/quantflow/"
 python = ">=3.11"
 scipy = "^1.14.1"
 pydantic = "^2.0.2"
-ccy = {version="1.6.0"}
+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 }
@@ -23,32 +23,44 @@ 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}
 
 [tool.poetry.group.dev.dependencies]
-black = "^24.1.1"
+black = "^25.1.0"
 pytest-cov = "^6.0.0"
-mypy = "^1.13.0"
+mypy = "^1.14.1"
 ghp-import = "^2.0.2"
-ruff = "^0.8.1"
-pytest-asyncio = "^0.25.0"
-isort = "^5.13.2"
+ruff = "^0.11.2"
+pytest-asyncio = "^0.26.0"
+isort = "^6.0.1"
 
 
 [tool.poetry.extras]
 data = ["aio-fluid"]
-cli = ["asciichartpy", "prompt-toolkit", "rich", "click"]
+cli = [
+    "asciichartpy",
+    "async-cache",
+    "prompt-toolkit",
+    "rich",
+    "click",
+    "holidays"
+]
 
 [tool.poetry.group.book]
 optional = true
 
 [tool.poetry.group.book.dependencies]
 jupyter-book = "^1.0.0"
-nbconvert = "^7.16.3"
 jupytext = "^1.13.8"
 plotly = "^5.20.0"
 jupyterlab = "^4.0.2"
 sympy = "^1.12"
 ipywidgets = "^8.0.7"
+sphinx-autodoc-typehints = "2.3.0"
+sphinx-autosummary-accessors = "^2023.4.0"
+sphinx-copybutton = "^0.5.2"
+autodocsumm = "^0.2.14"
 
 [tool.poetry.scripts]
 qf = "quantflow.cli.script:main"
@@ -85,6 +97,7 @@ warn_no_return = true
 [[tool.mypy.overrides]]
 module = [
     "asciichartpy.*",
+    "cache.*",
     "quantflow_tests.*",
     "IPython.*",
     "pandas.*",

{quantflow-0.3.0 → quantflow-0.3.2}/quantflow/__init__.py

@@ -1,3 +1,3 @@
 """Quantitative analysis and pricing"""
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"

{quantflow-0.3.0 → quantflow-0.3.2}/quantflow/cli/app.py

@@ -4,8 +4,10 @@ from functools import partial
 from typing import Any
 
 import click
+from fluid.utils.http_client import HttpResponseError
 from prompt_toolkit import PromptSession
 from prompt_toolkit.completion import NestedCompleter
+from prompt_toolkit.formatted_text import HTML
 from prompt_toolkit.history import FileHistory
 from rich.console import Console
 from rich.text import Text
@@ -38,6 +40,7 @@ class QfApp:
                         self.prompt_message(),
                         completer=self.prompt_completer(),
                         complete_while_typing=True,
+                        bottom_toolbar=self.bottom_toolbar,
                     )
                 except KeyboardInterrupt:
                     break
@@ -80,5 +83,18 @@ class QfApp:
             click.exceptions.MissingParameter,
             click.exceptions.NoSuchOption,
             click.exceptions.UsageError,
+            HttpResponseError,
         ) as e:
             self.error(e)
+
+    def bottom_toolbar(self) -> HTML:
+        sections = "/".join([str(section.name) for section in self.sections])
+        back = (
+            (' <b><style bg="ansired">back</style></b> ' "to exit the current section,")
+            if len(self.sections) > 1
+            else ""
+        )
+        return HTML(
+            f"Your are in <strong>{sections}</strong>, type{back} "
+            '<b><style bg="ansired">exit</style></b> to exit'
+        )

{quantflow-0.3.0 → quantflow-0.3.2}/quantflow/cli/commands/base.py

@@ -12,6 +12,9 @@ if TYPE_CHECKING:
     from quantflow.cli.app import QfApp
 
 
+FREQUENCIES = tuple(FMP().historical_frequencies())
+
+
 class HistoricalPeriod(enum.StrEnum):
     day = "1d"
     week = "1w"
@@ -115,3 +118,17 @@ class options:
         show_default=True,
         help="Historical period",
     )
+    index = click.option(
+        "-i",
+        "--index",
+        type=int,
+        default=-1,
+        help="maturity index",
+    )
+    frequency = click.option(
+        "-f",
+        "--frequency",
+        type=click.Choice(FREQUENCIES),
+        default="",
+        help="Frequency of data - if not provided it is daily",
+    )

quantflow-0.3.2/quantflow/cli/commands/crypto.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import asyncio
+
+import click
+import pandas as pd
+from asciichartpy import plot
+from cache import AsyncTTL
+from ccy.cli.console import df_to_rich
+
+from quantflow.data.deribit import Deribit
+from quantflow.options.surface import VolSurface
+from quantflow.utils.numbers import round_to_step
+
+from .base import QuantContext, options, quant_group
+from .stocks import get_prices
+
+
+@quant_group()
+def crypto() -> None:
+    """Crypto currencies commands"""
+    ctx = QuantContext.current()
+    if ctx.invoked_subcommand is None:
+        ctx.set_as_section()
+
+
+@crypto.command()
+@click.argument("currency")
+@options.length
+@options.height
+@options.chart
+def volatility(currency: str, length: int, height: int, chart: bool) -> None:
+    """Provides information about historical volatility for given cryptocurrency"""
+    ctx = QuantContext.current()
+    df = asyncio.run(get_volatility(ctx, currency))
+    df["volatility"] = df["volatility"].map(lambda p: round_to_step(p, "0.01"))
+    if chart:
+        data = df["volatility"].tolist()[:length]
+        ctx.qf.print(plot(data, {"height": height}))
+    else:
+        ctx.qf.print(df_to_rich(df))
+
+
+@crypto.command()
+@click.argument("currency")
+def term_structure(currency: str) -> None:
+    """Provides information about the term structure for given cryptocurrency"""
+    ctx = QuantContext.current()
+    vs = asyncio.run(get_vol_surface(currency))
+    ts = vs.term_structure().round({"ttm": 4})
+    ts["open_interest"] = ts["open_interest"].map("{:,d}".format)
+    ts["volume"] = ts["volume"].map("{:,d}".format)
+    ctx.qf.print(df_to_rich(ts))
+
+
+@crypto.command()
+@click.argument("currency")
+@options.index
+@options.height
+@options.chart
+def implied_vol(currency: str, index: int, height: int, chart: bool) -> None:
+    """Display the Volatility Surface for given cryptocurrency
+    at a given maturity index
+    """
+    ctx = QuantContext.current()
+    vs = asyncio.run(get_vol_surface(currency))
+    index_or_none = None if index < 0 else index
+    vs.bs(index=index_or_none)
+    df = vs.options_df(index=index_or_none)
+    if chart:
+        data = (df["implied_vol"] * 100).tolist()
+        ctx.qf.print(plot(data, {"height": height}))
+    else:
+        df[["ttm", "moneyness", "moneyness_ttm"]] = df[
+            ["ttm", "moneyness", "moneyness_ttm"]
+        ].map("{:.4f}".format)
+        df["implied_vol"] = df["implied_vol"].map("{:.2%}".format)
+        df["price"] = df["price"].map(lambda p: round_to_step(p, vs.tick_size_options))
+        df["forward_price"] = df["forward_price"].map(
+            lambda p: round_to_step(p, vs.tick_size_forwards)
+        )
+        ctx.qf.print(df_to_rich(df))
+
+
+@crypto.command()
+@click.argument("symbol")
+@options.height
+@options.length
+@options.chart
+@options.frequency
+def prices(symbol: str, height: int, length: int, chart: bool, frequency: str) -> None:
+    """Fetch OHLC prices for given cryptocurrency"""
+    ctx = QuantContext.current()
+    df = asyncio.run(get_prices(ctx, symbol, frequency))
+    if df.empty:
+        raise click.UsageError(
+            f"No data for {symbol} - are you sure the symbol exists?"
+        )
+    if chart:
+        data = list(reversed(df["close"].tolist()[:length]))
+        ctx.qf.print(plot(data, {"height": height}))
+    else:
+        ctx.qf.print(
+            df_to_rich(
+                df[["date", "open", "high", "low", "close", "volume"]].sort_values(
+                    "date"
+                )
+            )
+        )
+
+
+async def get_volatility(ctx: QuantContext, currency: str) -> pd.DataFrame:
+    async with Deribit() as client:
+        return await client.get_volatility(params=dict(currency=currency))
+
+
+@AsyncTTL(time_to_live=10)
+async def get_vol_surface(currency: str) -> VolSurface:
+    async with Deribit() as client:
+        loader = await client.volatility_surface_loader(currency)
+        return loader.surface()

{quantflow-0.3.0 → quantflow-0.3.2}/quantflow/cli/commands/stocks.py

@@ -11,13 +11,10 @@ from ccy import period as to_period
 from ccy.cli.console import df_to_rich
 from ccy.tradingcentres import prevbizday
 
-from quantflow.data.fmp import FMP
 from quantflow.utils.dates import utcnow
 
 from .base import HistoricalPeriod, QuantContext, options, quant_group
 
-FREQUENCIES = tuple(FMP().historical_frequencies())
-
 
 @quant_group()
 def stocks() -> None:
@@ -56,13 +53,7 @@ def search(text: str) -> None:
 @click.argument("symbol")
 @options.height
 @options.length
-@click.option(
-    "-f",
-    "--frequency",
-    type=click.Choice(FREQUENCIES),
-    default="",
-    help="Frequency of data - if not provided it is daily",
-)
+@options.frequency
 def chart(symbol: str, height: int, length: int, frequency: str) -> None:
     """Symbol chart"""
     ctx = QuantContext.current()

{quantflow-0.3.0 → quantflow-0.3.2}/quantflow/cli/script.py

@@ -4,11 +4,11 @@ dotenv.load_dotenv()
 
 try:
     from .app import QfApp
-except ImportError:
+except ImportError as ex:
     raise ImportError(
         "Cannot run qf command line, "
         "quantflow needs to be installed with cli & data extras, "
         "pip install quantflow[cli, data]"
-    ) from None
+    ) from ex
 
 main = QfApp()

{quantflow-0.3.0 → quantflow-0.3.2}/quantflow/data/deribit.py

@@ -1,12 +1,13 @@
 from datetime import datetime, timezone
+from decimal import Decimal
 from typing import Any, cast
 
 import pandas as pd
 from dateutil.parser import parse
-from fluid.utils.http_client import AioHttpClient, HttpResponse
+from fluid.utils.http_client import AioHttpClient, HttpResponse, HttpResponseError
 
 from quantflow.options.surface import VolSecurityType, VolSurfaceLoader
-from quantflow.utils.numbers import round_to_step
+from quantflow.utils.numbers import round_to_step, to_decimal
 
 
 def parse_maturity(v: str) -> datetime:
@@ -14,6 +15,13 @@ def parse_maturity(v: str) -> datetime:
 
 
 class Deribit(AioHttpClient):
+    """Deribit API client
+
+    Fetch market and static data from `Deribit`_.
+
+    .. _Deribit: https://docs.deribit.com/
+    """
+
     url = "https://www.deribit.com/api/v2"
 
     async def get_book_summary_by_instrument(self, **kw: Any) -> list[dict]:
@@ -38,7 +46,7 @@ class Deribit(AioHttpClient):
         return await self.get_path("public/get_historical_volatility", **kw)
 
     async def volatility_surface_loader(self, currency: str) -> VolSurfaceLoader:
-        """Create the volatility surface loader for a given crypto-currency"""
+        """Create a :class:`.VolSurfaceLoader` for a given crypto-currency"""
         loader = VolSurfaceLoader()
         futures = await self.get_book_summary_by_currency(
             params=dict(currency=currency, kind="future")
@@ -48,12 +56,13 @@ class Deribit(AioHttpClient):
         )
         instruments = await self.get_instruments(params=dict(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"]
                 meta = instrument_map[name]
-                tick_size = meta["tick_size"]
+                tick_size = to_decimal(meta["tick_size"])
+                min_tick_size = min(min_tick_size, tick_size)
                 bid = round_to_step(bid_, tick_size)
                 ask = round_to_step(ask_, tick_size)
                 if meta["settlement_period"] == "perpetual":
@@ -78,12 +87,15 @@ class Deribit(AioHttpClient):
                         open_interest=int(future["open_interest"]),
                         volume=int(future["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"]
                 meta = instrument_map[name]
-                tick_size = meta["tick_size"]
+                tick_size = to_decimal(meta["tick_size"])
+                min_tick_size = min(min_tick_size, tick_size)
                 loader.add_option(
                     VolSecurityType.option,
                     strike=round_to_step(meta["strike"], tick_size),
@@ -96,7 +108,7 @@ class Deribit(AioHttpClient):
                     bid=round_to_step(bid_, tick_size),
                     ask=round_to_step(ask_, tick_size),
                 )
-
+        loader.tick_size_options = min_tick_size
         return loader
 
     # Internal methods
@@ -106,6 +118,8 @@ class Deribit(AioHttpClient):
 
     async def to_result(self, response: HttpResponse) -> list[dict]:
         data = await response.json()
+        if "error" in data:
+            raise HttpResponseError(response, data["error"])
         return cast(list[dict], data["result"])
 
     async def to_df(self, response: HttpResponse) -> pd.DataFrame:

quantflow-0.3.2/quantflow/data/fed.py

@@ -0,0 +1,91 @@
+import io
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from fluid.utils.http_client import AioHttpClient
+
+URL = (
+    "https://www.federalreserve.gov/datadownload/Output.aspx?"
+    "rel=H15&series=bf17364827e38702b42a58cf8eaa3f78&lastobs=&"
+)
+
+maturities = [
+    "month_1",
+    "month_3",
+    "month_6",
+    "year_1",
+    "year_2",
+    "year_3",
+    "year_5",
+    "year_7",
+    "year_10",
+    "year_20",
+    "year_30",
+]
+
+
+@dataclass
+class FederalReserve(AioHttpClient):
+    """Federal Reserve API client.
+
+    This class is used to fetch yield curves from the Federal Reserve at
+    https://www.federalreserve.gov/datadownload/
+    """
+
+    url: str = "https://www.federalreserve.gov/datadownload/Output.aspx"
+    default_params: dict[str, Any] = field(
+        default_factory=lambda: {
+            "from": "",
+            "to": "",
+            "lastobs": "",
+            "filetype": "csv",
+            "label": "include",
+            "layout": "seriescolumn",
+            "type": "package",
+        }
+    )
+
+    async def yield_curves(self, **params: Any) -> pd.DataFrame:
+        """Get treasury constant maturities rates"""
+        params.update(series="bf17364827e38702b42a58cf8eaa3f78", rel="H15")
+        data = await self._get_text(params)
+        df = pd.read_csv(data, header=5, index_col=None, parse_dates=True)
+        df.columns = ["date"] + maturities  # type: ignore
+        df = df.set_index("date").replace("ND", np.nan)
+        return df.dropna(axis=0, how="all").reset_index()
+
+    async def ref_rates(self, **params: Any) -> pd.DataFrame:
+        """Get policy rates
+
+        Prior to 2021-07-08 it is the rate on excess reserves (IOER rate)
+        After 2021-07-08 it is the rate on reserve balances (IORB rate)
+
+        The IOER rate was the primary tool used by the Federal Reserve to set
+        a floor on the federal funds rate.
+        While the Interest rate on required reserves (IORR rate) existed,
+        the IOER rate had a more direct impact on market rates,
+        as banks typically held far more excess reserves than required reserves.
+        Therefore, the IOER rate was more influential
+        in the Fed's monetary policy implementation.
+        """
+        params.update(series="c27939ee810cb2e929a920a6bd77d9f6", rel="PRATES")
+        data = await self._get_text(params)
+        df = pd.read_csv(data, header=5, index_col=None, parse_dates=True)
+        ioer = df["RESBME_N.D"]
+        iorb = df["RESBM_N.D"]
+        rate = iorb.combine_first(ioer)
+        return pd.DataFrame(
+            {
+                "date": df["Time Period"],
+                "rate": rate,
+            }
+        )
+
+    async def _get_text(self, params: dict[str, Any]) -> io.StringIO:
+        """Get parameters for the request."""
+        params = {**self.default_params, **params}
+        response = await self.get(self.url, params=params, callback=True)
+        data = await response.text()
+        return io.StringIO(data)

{quantflow-0.3.0 → quantflow-0.3.2}/quantflow/data/fmp.py

@@ -8,15 +8,21 @@ from typing import Any, Iterator, cast
 import inflection
 import pandas as pd
 from fluid.utils.data import compact_dict
+from fluid.utils.http_client import AioHttpClient
 
 from quantflow.utils.dates import isoformat
 from quantflow.utils.numbers import to_decimal
 
-from .client import AioHttpClient
-
 
 @dataclass
 class FMP(AioHttpClient):
+    """Financial Modeling Prep API client
+
+    Fetch market and financial data from `Financial Modeling Prep`_.
+
+    .. _Financial Modeling Prep: https://financialmodelingprep.com/developer/docs/
+    """
+
     url: str = "https://financialmodelingprep.com/api"
     key: str = field(default_factory=lambda: os.environ.get("FMP_API_KEY", ""))
 

{quantflow-0.3.0 → quantflow-0.3.2}/quantflow/data/fred.py

@@ -4,12 +4,18 @@ from enum import StrEnum
 from typing import Any, cast
 
 import pandas as pd
-
-from .client import AioHttpClient
+from fluid.utils.http_client import AioHttpClient
 
 
 @dataclass
 class Fred(AioHttpClient):
+    """Federal Reserve Economic Data API client
+
+    Fetch economic data from `FRED`_.
+
+    .. _FRED: https://fred.stlouisfed.org/
+    """
+
     url: str = "https://api.stlouisfed.org/fred"
     key: str = field(default_factory=lambda: os.environ.get("FRED_API_KEY", ""))
 
@@ -25,15 +31,19 @@ class Fred(AioHttpClient):
         a = "a"
 
     async def categiories(self, **kw: Any) -> dict:
+        """Get categories"""
         return await self.get_path("category", **kw)
 
     async def subcategories(self, **kw: Any) -> dict:
+        """Get subcategories of a given category"""
         return await self.get_path("category/children", **kw)
 
     async def series(self, **kw: Any) -> dict:
+        """Get series of a given category"""
         return await self.get_path("category/series", **kw)
 
     async def serie_data(self, *, to_date: bool = False, **kw: Any) -> pd.DataFrame:
+        """Get series data frame"""
         data = await self.get_path("series/observations", **kw)
         df = pd.DataFrame(data["observations"])
         df["value"] = pd.to_numeric(df["value"])

{quantflow-0.3.0 → quantflow-0.3.2}/quantflow/data/vault.py

@@ -2,6 +2,7 @@ from pathlib import Path
 
 
 class Vault:
+    """Keeps key-value pairs in a file."""
 
     def __init__(self, path: str | Path) -> None:
         self.path = Path(path)
@@ -17,22 +18,27 @@ class Vault:
         return data
 
     def add(self, key: str, value: str) -> None:
+        """Add a key-value pair to the vault."""
         self.data[key] = value
         self.save()
 
     def delete(self, key: str) -> bool:
+        """Delete a key-value pair from the vault."""
         if self.data.pop(key, None) is not None:
             self.save()
             return True
         return False
 
     def get(self, key: str) -> str | None:
+        """Get the value of a key if available otherwise None."""
         return self.data.get(key)
 
     def keys(self) -> list[str]:
+        """Get the keys in the vault."""
         return sorted(self.data)
 
     def save(self) -> None:
+        """Save the data to the file."""
         with open(self.path, "w") as file:
             for key in sorted(self.data):
                 value = self.data[key]