More docs

Author: lsbardel

notebooks/api/data/deribit.rst

@@ -0,0 +1,11 @@
+================
+Deribit
+================
+
+.. currentmodule:: quantflow.data.deribit
+
+.. autoclass:: Deribit
+   :members:
+   :member-order: groupwise
+   :autosummary:
+   :autosummary-nosignatures:

notebooks/api/data/fmp.rst

@@ -0,0 +1,11 @@
+================
+FMP
+================
+
+.. currentmodule:: quantflow.data.fmp
+
+.. autoclass:: FMP
+   :members:
+   :member-order: groupwise
+   :autosummary:
+   :autosummary-nosignatures:

notebooks/api/data/fred.rst

@@ -0,0 +1,11 @@
+================
+Fred
+================
+
+.. currentmodule:: quantflow.data.fred
+
+.. autoclass:: Fred
+   :members:
+   :member-order: groupwise
+   :autosummary:
+   :autosummary-nosignatures:

notebooks/api/data/index.rst

@@ -4,3 +4,15 @@ Data fetching
 
 .. currentmodule:: quantflow.data
 
+The :mod:`quantflow.data` module provides classes and functions for fetching data from various sources.
+To use the module the package must be installed with the optional `data` extra.
+```
+pip install quantflow[data]
+```
+
+.. toctree::
+    :maxdepth: 1
+
+    fmp
+    fred
+    deribit

notebooks/api/sp/heston.rst

@@ -10,3 +10,9 @@ Heston process
    :autosummary:
    :autosummary-nosignatures:
 
+
+.. autoclass:: HestonJ
+   :members:
+   :member-order: groupwise
+   :autosummary:
+   :autosummary-nosignatures:

notebooks/reference/glossary.md

@@ -45,9 +45,20 @@ Moneyness is used in the context of option pricing and it is defined as
 
 where $K$ is the strike and $F$ is the Forward price. A positive value implies strikes above the forward, which means put options are in the money and call options are out of the money.
 
-```{code-cell}
 
-```
+## Moneyness Time Adjusted
+
+The time-adjusted moneyness is used in the context of option pricing in order to compare options with different maturities. It is defined as
+
+\begin{equation}
+    \frac{1}{\sqrt{T}}\ln\frac{K}{F}
+\end{equation}
+
+where $K$ is the strike and $F$ is the Forward price and $T$ is the time to maturity.
+
+The key reason for dividing by the square root of time-to-maturity is related to how volatility and price movement behave over time.
+The price of the underlying asset is subject to random fluctuations, if these fluctuations follow a Brownian motion than the
+standard deviation of the price movement will increase with the square root of time.
 
 ## Probability Density Function (PDF)
 

poetry.lock

@@ -24,6 +24,7 @@ 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"
@@ -37,7 +38,14 @@ isort = "^5.13.2"
 
 [tool.poetry.extras]
 data = ["aio-fluid"]
-cli = ["asciichartpy", "prompt-toolkit", "rich", "click", "holidays"]
+cli = [
+    "asciichartpy",
+    "async-cache",
+    "prompt-toolkit",
+    "rich",
+    "click",
+    "holidays"
+]
 
 [tool.poetry.group.book]
 optional = true
@@ -89,6 +97,7 @@ warn_no_return = true
 [[tool.mypy.overrides]]
 module = [
     "asciichartpy.*",
+    "cache.*",
     "quantflow_tests.*",
     "IPython.*",
     "pandas.*",

pyproject.toml

@@ -115,3 +115,10 @@ class options:
         show_default=True,
         help="Historical period",
     )
+    index = click.option(
+        "-i",
+        "--index",
+        type=int,
+        default=-1,
+        help="maturity index",
+    )

quantflow/cli/commands/base.py

@@ -5,9 +5,11 @@
 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 .base import QuantContext, options, quant_group
 
@@ -36,6 +38,48 @@ def volatility(currency: str, length: int, height: int, chart: bool) -> None:
         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)
+    df["implied_vol"] = df["implied_vol"] * 100
+    df = df.round({"ttm": 4, "moneyness": 4, "moneyness_ttm": 4, "implied_vol": 5})
+    if chart:
+        data = df["implied_vol"].tolist()
+        ctx.qf.print(plot(data, {"height": height}))
+    else:
+        ctx.qf.print(df_to_rich(df))
+
+
 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/cli/commands/crypto.py

@@ -14,6 +14,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 +45,7 @@ async def get_volatility(self, **kw: Any) -> pd.DataFrame:
         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")

quantflow/data/client.py

@@ -8,15 +8,21 @@
 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/data/deribit.py

@@ -4,12 +4,18 @@
 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 freq(StrEnum):
         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/data/fmp.py

@@ -456,7 +456,7 @@ def bs(
         index: int | None = None,
         initial_vol: float = INITIAL_VOL,
     ) -> list[OptionPrice]:
-        """calculate Black-Scholes implied volatilities for all options
+        """calculate Black-Scholes implied volatility for all options
         in the surface"""
         d = self.as_array(
             select=select, index=index, initial_vol=initial_vol, converged=False

quantflow/data/fred.py

@@ -80,12 +80,29 @@ def sample_from_draws(self, path1: Paths, *args: Paths) -> Paths:
 
 
 class HestonJ(Heston):
+    r"""The Heston stochastic volatility model with jumps
+
+    The Heston model with jumps is an extension of the classical square-root
+    stochastic volatility model of Heston (1993) with the addition of jump
+    processes. The jumps are modeled as compound Poisson processes with
+    exponential jump sizes.
+
+    .. math::
+        d x_t &= d w^1_t + d N^+_t - d N^-_t\\
+        d v_t &= \kappa (\theta - v_t) dt + \nu \sqrt{v_t} dw^2_t \\
+        \rho dt &= {\tt E}[dw^1 dw^2]
+    """
+
     jumps_up: CompoundPoissonProcess[Exponential] = Field(
         description="positive jumps process"
     )
+    """Positive jumps process driven by a compound Poisson process with jumps
+    sizes which follow an exponential distribution"""
     jumps_down: CompoundPoissonProcess[Exponential] = Field(
         description="negative jumps process"
     )
+    """jumps process driven by a compound Poisson process with jumps
+    sizes which follow an exponential distribution"""
 
     @classmethod
     def create(
@@ -99,6 +116,7 @@ def create(
         jump_fraction: float = 0.1,  # percentage of variance due to jumps
         jump_asymmetry: float = 1,
     ) -> HestonJ:
+        """Create an Heston model with jumps by specifying the jump parameters"""
         if jump_fraction <= 0 or jump_fraction >= 1:
             raise ValueError("jump_percentage must be between 0 and 1")
         total_variance = vol * vol
@@ -127,6 +145,8 @@ def create(
         )
 
     def characteristic_exponent(self, t: FloatArrayLike, u: Vector) -> Vector:
+        """The characteristic exponent is given by the sum of the exponent of the
+        classic Heston model and the exponent of the jumps"""
         return (
             super().characteristic_exponent(t, u)
             + self.jumps_up.characteristic_exponent(t, u)

quantflow/options/surface.py

@@ -25,6 +25,9 @@ pip install quantflow
 * [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