quantstack-lab 0.1.0__py3-none-any.whl

quantstack/__init__.py

@@ -0,0 +1 @@
+"""quant-stack: adapters and studies that wire sppricer, volsurface, btlab, lobkit and risklab together."""

quantstack/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters: the only place where objects from two of the libraries meet."""

quantstack/adapters/costs.py

@@ -0,0 +1,80 @@
+"""lobkit order-book measurements as a btlab cost model (Link D).
+
+btlab's SpreadImpactCost charges, per unit of NAV traded in asset i,
+
+    half_spread_bps / 1e4  +  Y * vol_i * sqrt(trade_value / ADV_i)
+
+with vol_i the return volatility per bar, ADV_i the traded value per bar and Y the square-root-law
+coefficient (Almgren et al. 2005; Toth et al. 2011). lobkit.calibrate_costs measures a recording or a
+simulated book in its own units. The conversions:
+
+    half_spread_bps   = cal["half_spread_bps"]                      already relative, in basis points
+    vol per bar       = cal["mid_vol_per_sqrt_sec"] * sqrt(bar_seconds)     diffusive scaling in time
+    ADV per bar       = cal["volume_per_sec"] * cal["mid_price"] * bar_seconds   units/s -> quote ccy
+    Y                 matched to the measured OFI impact at a reference order size q_ref:
+                      beta * q_ref / mid  =  Y * sigma_b * sqrt(q_ref / V_b)
+                      beta: price change per unit of net order flow over one OFI bucket of b seconds
+                      (Cont, Kukanov & Stoikov 2014); sigma_b, V_b: vol and volume over that bucket;
+                      q_ref: the mean top-of-book depth, an order that just clears the best level.
+
+The Y calibration is a modelling choice: OFI's impact is linear in flow and measured over seconds,
+the square-root law is concave in size and meant for orders worked over a day. Matching them at one
+size gives the right order of magnitude, not a precise coefficient; S4 reports results for a range.
+Passing impact_coef (e.g. the textbook Y = 1) overrides the calibration.
+
+Fees. An order book shows the spread and the impact, not the venue's fee schedule, which is usually
+the largest cost of trading a liquid crypto pair: Binance's published base spot taker fee is 0.10%
+(10 bp) per trade, against a BTCUSDT half-spread under 0.001 bp. fee_bps is charged per unit traded,
+like the half-spread, so it is added to SpreadImpactCost's linear term.
+Clock: calibrate_costs uses the frames' timestamps (lobkit.load_recording puts quotes and trades on
+the local receive clock), so per-second rates are wall-clock rates.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import numpy as np
+import pandas as pd
+from btlab import SpreadImpactCost
+
+SECONDS_PER_DAY_24H = 86_400.0   # crypto trades around the clock
+
+
+def impact_coefficient(cal: Mapping, ofi_bucket_seconds: float = 10.0) -> float:
+    """Square-root-law Y implied by the OFI impact slope at an order of the mean top-of-book size."""
+    q_ref = cal["mean_depth"]
+    linear = cal["ofi_impact_beta"] * q_ref / cal["mid_price"]               # relative move for q_ref
+    sigma_b = cal["mid_vol_per_sqrt_sec"] * np.sqrt(ofi_bucket_seconds)
+    volume_b = cal["volume_per_sec"] * ofi_bucket_seconds
+    return float(linear / (sigma_b * np.sqrt(q_ref / volume_b)))
+
+
+def bar_inputs(cal: Mapping, bar_seconds: float) -> dict:
+    """Vol per bar and traded value (ADV) per bar, in the units SpreadImpactCost expects."""
+    return {"vol": cal["mid_vol_per_sqrt_sec"] * np.sqrt(bar_seconds),
+            "adv": cal["volume_per_sec"] * cal["mid_price"] * bar_seconds}
+
+
+def cost_model_from_book(cal: Mapping | Mapping[str, Mapping], bar_seconds: float, capital: float,
+                         impact_coef: float | None = None, ofi_bucket_seconds: float = 10.0,
+                         fee_bps: float = 0.0) -> SpreadImpactCost:
+    """SpreadImpactCost from one calibrate_costs dict, or from {asset: dict} for per-asset costs.
+
+    With several assets, half-spread and Y are taken per asset and averaged for Y (SpreadImpactCost has one
+    coefficient); vol and ADV stay per asset. impact_coef overrides the calibrated Y; fee_bps (exchange fee per
+    unit traded) is added to the half-spread.
+    """
+    per_asset = all(isinstance(v, Mapping) for v in cal.values())
+    cals = dict(cal) if per_asset else {"_": cal}
+    ys = [impact_coefficient(c, ofi_bucket_seconds) for c in cals.values()]
+    y = float(np.mean(ys)) if impact_coef is None else impact_coef
+    if not per_asset:
+        inp = bar_inputs(cal, bar_seconds)
+        return SpreadImpactCost(cal["half_spread_bps"] + fee_bps, y, inp["adv"], inp["vol"], capital)
+    inputs = {a: bar_inputs(c, bar_seconds) for a, c in cals.items()}
+    spreads = [c["half_spread_bps"] for c in cals.values()]
+    # ponytail: one half-spread for all assets (SpreadImpactCost takes a scalar); the max is the cautious
+    # choice. Make half_spread_bps accept a per-asset Series in btlab if spreads differ a lot.
+    return SpreadImpactCost(max(spreads) + fee_bps, y, pd.Series({a: v["adv"] for a, v in inputs.items()}),
+                            pd.Series({a: v["vol"] for a, v in inputs.items()}), capital)

quantstack/adapters/notes.py

@@ -0,0 +1,169 @@
+"""sppricer notes as risklab positions (Link B).
+
+risklab values a position by asking value(scenario) for a batch of scenarios (spot multipliers per
+underlying, vol shift, skew shift, elapsed time). StructuredNotePosition answers by repricing the note
+with sppricer's Monte Carlo; GridNotePosition answers from a precomputed price grid, which is what makes
+thousands of VaR scenarios affordable.
+
+Common random numbers. Every repricing uses the same seed and the same number and order of draws, so
+the difference between two scenarios reflects the shock, not Monte Carlo noise. A scenario changes
+only inputs (spots, vols, the schedule's distance from today), never the shape of the draw.
+
+Elapsed time. Moving a live note forward changes its schedule and, once an observation passes, its
+coupon memory and autocall state. This adapter does the conservative thing: elapsed time must be
+shorter than the time to the first observation date, so the schedule only shifts closer and no state
+changes. Longer horizons raise ValueError.
+"""
+
+from __future__ import annotations
+
+from dataclasses import fields, replace
+
+import numpy as np
+from risklab import Scenario
+from scipy.interpolate import RegularGridInterpolator
+from sppricer import GBMModel, LocalVolModel, Market, price_mc
+
+from quantstack.adapters.surface import SurfaceLocalVol
+
+_SCHEDULE_FIELDS = ("observation_times", "coupon_times", "maturity")
+SPOT_GRID = tuple(np.linspace(0.6, 1.4, 17))
+VOL_GRID = tuple(np.linspace(-0.10, 0.15, 11))   # 2.5 vol-point steps: note prices are convex in vol
+
+
+def shift_schedule(product, elapsed: float):
+    """The same product seen `elapsed` years later; every date must still be in the future."""
+    if elapsed == 0:
+        return product
+    changes = {}
+    for f in fields(product):
+        if f.name in _SCHEDULE_FIELDS:
+            t = np.atleast_1d(np.asarray(getattr(product, f.name), dtype=float))
+            if elapsed >= t[0]:
+                raise ValueError(f"elapsed {elapsed:.4f}y reaches the first date {t[0]:.4f}y of {f.name}; "
+                                 "observation state (memory, autocall) is not modelled, so shorten the horizon")
+            shifted = t - elapsed
+            changes[f.name] = float(shifted[0]) if f.name == "maturity" else tuple(shifted)
+    return replace(product, **changes)
+
+
+class _PayOn:
+    """A 'market' whose discount factor is 1 on one date and 0 elsewhere, to read off a single cash flow."""
+
+    def __init__(self, t: float):
+        self.t = t
+
+    def discount(self, t):
+        return float(np.isclose(t, self.t))
+
+
+def realised_cashflows(product, levels) -> np.ndarray:
+    """Cash flow the note pays on each observation date if the underlyings print `levels` (n_dates x n_assets).
+
+    Runs the product's own payoff on the one realised path, so coupons, memory and autocall follow exactly
+    the rules used for pricing. Only for European barrier monitoring: a knock-in watched between dates
+    needs the whole path, not the observation levels.
+    """
+    if getattr(product, "barrier_monitoring", "european") != "european":
+        raise ValueError("realised_cashflows needs barrier_monitoring='european'")
+    path = np.asarray(levels, dtype=float).reshape(1, len(product.simulation_times), -1)
+    return np.array([product.discounted_payoff(path, _PayOn(t))[0] for t in product.simulation_times])
+
+
+class StructuredNotePosition:
+    """`quantity` units of an sppricer product, revalued by Monte Carlo in each scenario.
+
+    Flat-vol mode (surfaces=None): GBM on `market`; vol_shift adds to each underlying's vol and
+    skew_shift is not available (a flat vol has no skew). Local-vol mode: `surfaces` (volsurface,
+    one per underlying, matching market.curves) drive sppricer's LocalVolModel; vol_shift and
+    skew_shift reshape them with surface.shifted, which rejects shifts that create arbitrage.
+    Under local vol a spot shock is sticky-strike: the surface stays put in absolute strike.
+    Prices are per the product's notional; value = quantity * price.
+    """
+
+    def __init__(self, product, market: Market, quantity: float = 1.0, n_paths: int = 20_000, seed: int = 7,
+                 surfaces=None, dt: float = 1 / 252):
+        self.product, self.market, self.quantity = product, market, quantity
+        self.n_paths, self.seed, self.surfaces, self.dt = n_paths, seed, surfaces, dt
+
+    def price(self, spot_mult, vol_shift: float = 0.0, skew_shift: float = 0.0, elapsed: float = 0.0):
+        """(price, standard error) in one market state; spot_mult has one entry per underlying."""
+        m = self.market
+        for i, (u, x) in enumerate(zip(m.underlyings, np.broadcast_to(spot_mult, (m.n_assets,)), strict=True)):
+            m = m.with_spot(i, u.spot * float(x))
+            if self.surfaces is None and vol_shift:
+                m = m.with_vol(i, max(u.vol + vol_shift, 1e-4))
+        if self.surfaces is None:
+            if skew_shift:
+                raise ValueError("skew_shift needs local-vol mode (surfaces)")
+            model = GBMModel()
+        else:
+            surfs = self.surfaces if not (vol_shift or skew_shift) else \
+                [s.shifted(vol_shift, skew_shift) for s in self.surfaces]
+            model = LocalVolModel([SurfaceLocalVol(s) for s in surfs], dt=self.dt)
+        res = price_mc(shift_schedule(self.product, elapsed), m, self.n_paths, seed=self.seed, model=model)
+        return res.price, res.std_error
+
+    def value(self, scenario: Scenario) -> np.ndarray:
+        n = len(scenario)
+        mults = np.column_stack([scenario.spot(i) * np.ones(n) for i in range(self.market.n_assets)])
+        vs = np.broadcast_to(scenario.vol_shift, (n,))
+        ks = np.broadcast_to(scenario.skew_shift, (n,))
+        return self.quantity * np.array([self.price(mults[j], vs[j], ks[j], scenario.elapsed)[0]
+                                         for j in range(n)])
+
+
+class GridNotePosition:
+    """A StructuredNotePosition priced from a grid over (spot multiplier per underlying, vol shift).
+
+    The grid is computed at one horizon `elapsed` (the VaR horizon) and interpolated linearly, which is
+    monotone and does not overshoot near barriers. value() of the unshocked, elapsed=0 scenario (the
+    base risklab subtracts) is repriced directly, so P&L still includes time decay.
+    """
+
+    def __init__(self, position: StructuredNotePosition, elapsed: float,
+                 spot_mults=SPOT_GRID, vol_shifts=VOL_GRID):
+        # ponytail: linear interpolation on a fixed grid; refine near the barrier or go cubic if validate()
+        # shows errors above ~2 SE where the book's tail scenarios land.
+        self.position, self.elapsed = position, elapsed
+        self.spot_mults, self.vol_shifts = np.asarray(spot_mults, float), np.asarray(vol_shifts, float)
+        n = position.market.n_assets
+        axes = [self.spot_mults] * n + [self.vol_shifts]
+        prices = np.empty([len(a) for a in axes])
+        for idx in np.ndindex(*prices.shape):
+            prices[idx] = position.price([axes[a][i] for a, i in enumerate(idx[:n])], self.vol_shifts[idx[n]],
+                                         elapsed=elapsed)[0]
+        self.grid = RegularGridInterpolator(axes, prices, bounds_error=False, fill_value=None)
+        self.base = position.price(np.ones(n))[0]
+
+    def _points(self, scenario: Scenario) -> np.ndarray:
+        n_assets, n = self.position.market.n_assets, len(scenario)
+        cols = [scenario.spot(i) * np.ones(n) for i in range(n_assets)]
+        return np.column_stack(cols + [np.broadcast_to(scenario.vol_shift, (n,))])
+
+    def value(self, scenario: Scenario) -> np.ndarray:
+        if np.any(np.asarray(scenario.skew_shift) != 0):
+            raise ValueError("the price grid has no skew dimension")
+        pts = self._points(scenario)
+        if scenario.elapsed == 0 and np.allclose(pts[:, :-1], 1.0) and np.allclose(pts[:, -1], 0.0):
+            return self.position.quantity * np.full(len(pts), self.base)
+        if not np.isclose(scenario.elapsed, self.elapsed):
+            raise ValueError(f"grid built for elapsed={self.elapsed}, scenario has {scenario.elapsed}")
+        lo, hi = self.spot_mults[[0, -1]]
+        if np.any((pts[:, :-1] < lo) | (pts[:, :-1] > hi)):
+            raise ValueError(f"scenario spot multipliers leave the grid [{lo}, {hi}]")
+        return self.position.quantity * self.grid(pts)
+
+    def validate(self, n_points: int = 25, seed: int = 0) -> dict:
+        """Grid vs direct Monte Carlo at random in-grid points: max |error| in price and in standard errors."""
+        rng = np.random.default_rng(seed)
+        n_assets = self.position.market.n_assets
+        lo, hi = self.spot_mults[[0, -1]]
+        pts = np.column_stack([rng.uniform(lo + 0.1, hi - 0.1, (n_points, n_assets)),
+                               rng.uniform(self.vol_shifts[0], self.vol_shifts[-1], n_points)])
+        direct = np.array([self.position.price(p[:-1], p[-1], elapsed=self.elapsed) for p in pts])
+        err = self.grid(pts) - direct[:, 0]
+        noisy = direct[:, 1] > 1e-6        # deep in or out of the money a payoff can be riskless: SE ~ 0
+        in_se = np.abs(err[noisy] / direct[noisy, 1]).max() if noisy.any() else 0.0
+        return {"max_abs_error": float(np.abs(err).max()), "max_error_in_se": float(in_se),
+                "mean_abs_error": float(np.abs(err).mean()), "points": pts, "errors": err}

quantstack/adapters/surface.py

@@ -0,0 +1,56 @@
+"""volsurface surfaces as sppricer local-vol sources (Link A).
+
+Units. sppricer simulates absolute spot levels S_t in years t and asks a source
+for local_vol(K, T) at K = S_t, T = t. volsurface surfaces take the same absolute
+K and T and convert internally to log-moneyness k = ln(K / F(T)) on their own
+forward curve F, the curve implied from the chain by put-call parity. So no
+rescaling is needed, provided the simulation starts from the curve's spot and
+drifts along the same curve. local_vol_setup builds the Market that way.
+
+Safety. Paths reach strikes far outside the quoted range, where Dupire's formula
+divides by numbers near zero. The adapter evaluates local vol with volsurface's
+safe path: flat in k beyond the fitted range, NaN (arbitrage) replaced by implied
+vol, clipped to [floor, cap]; surface.n_clamped / n_local_vol report how often.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from sppricer import LocalVolModel, Market, Underlying
+from volsurface import VolSurface
+
+
+class SurfaceLocalVol:
+    """A volsurface surface seen through sppricer's LocalVolSource protocol."""
+
+    def __init__(self, surface: VolSurface, floor: float = 0.01, cap: float = 3.0):
+        self.surface, self.floor, self.cap = surface, floor, cap
+
+    @property
+    def curve(self):
+        return self.surface.curve
+
+    def local_vol(self, K, T):
+        return self.surface.local_vol(K, T, floor=self.floor, cap=self.cap, extrapolate="flat")
+
+    @property
+    def clamped_share(self) -> float:
+        s = self.surface
+        return s.n_clamped / s.n_local_vol if s.n_local_vol else 0.0
+
+
+def local_vol_setup(surfaces: list[VolSurface], correlation=None, dt: float = 1 / 252,
+                    names: list[str] | None = None, flat_vols=None) -> tuple[Market, LocalVolModel]:
+    """(Market, LocalVolModel) whose spots and discounting come from the surfaces' own curves.
+
+    Spot of asset i = surfaces[i].curve.spot; each asset's forward curve is its
+    surface's curve (Market.curves), and discounting uses the first surface's
+    curve. flat_vols, one per asset, sets the Underlying vols used by GBM on the
+    same curves: the flat-vol benchmark.
+    """
+    names = names or [f"S{i}" for i in range(len(surfaces))]
+    vols = flat_vols if flat_vols is not None else [0.2] * len(surfaces)
+    market = Market(tuple(Underlying(n, s.curve.spot, v) for n, s, v in zip(names, surfaces, vols, strict=True)),
+                    rate=0.0, correlation=None if correlation is None else np.asarray(correlation, dtype=float),
+                    curves=tuple(s.curve for s in surfaces), discount_curve=surfaces[0].curve)
+    return market, LocalVolModel([SurfaceLocalVol(s) for s in surfaces], dt=dt)

quantstack_lab-0.1.0.dist-info/METADATA

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: quantstack-lab
+Version: 0.1.0
+Summary: A connected quantitative finance research stack: structured product pricing, volatility surfaces, honest backtesting, market microstructure and risk, linked into end-to-end studies.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/hossainyousuf751/quant-stack
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sppricer<0.3,>=0.2.1
+Requires-Dist: volsurface-lab<0.3,>=0.2.1
+Requires-Dist: btlab<0.5,>=0.4.0
+Requires-Dist: lobkit<0.4,>=0.3.0
+Requires-Dist: marketrisk-lab<0.5,>=0.4.1
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: matplotlib>=3.7; extra == "dev"
+Dynamic: license-file
+
+# quant-stack
+
+> A connected quantitative finance research stack: structured product pricing, volatility
+> surfaces, honest backtesting, market microstructure and risk, linked into end-to-end studies.
+
+quant-stack holds five independent libraries as git submodules, pinned to tagged releases. It
+connects them through small adapters and runs cross-project studies on top. No library imports
+another, and none imports quant-stack. Each still installs, tests and releases on its own.
+
+| Project | `pip install` (import) | What it does |
+|---|---|---|
+| [sp-pricer](https://github.com/hossainyousuf751/sp-pricer) | `sppricer` | Monte Carlo pricing of Phoenix autocallables and reverse convertibles, Greeks, barrier monitoring; Dupire local vol and term structure from v0.2 |
+| [volsurface](https://github.com/hossainyousuf751/volsurface) | `volsurface-lab` (`volsurface`) | Arbitrage-free implied vol surfaces (SVI, SSVI, eSSVI, arbitrage-free SVI) from raw quotes, Dupire local vol, scenario shifts |
+| [backtest-lab](https://github.com/hossainyousuf751/backtest-lab) | `btlab` | Backtesting with look-ahead tests, Deflated Sharpe, PBO, walk-forward, pluggable cost models, covariance strategies |
+| [microstructure-lab](https://github.com/hossainyousuf751/microstructure-lab) | `lobkit` | Order-book reconstruction, order-flow imbalance, micro-price, Avellaneda–Stoikov; cost calibration and bars |
+| [risk-lab](https://github.com/hossainyousuf751/risk-lab) | `marketrisk-lab` (`risklab`) | VaR/ES models and backtests, DCC-GARCH, shrinkage, HRP; scenario full-revaluation VaR and stress tests |
+
+## How the pieces connect
+
+```mermaid
+flowchart LR
+    VS[volsurface] -->|"local_vol(K, T), curve<br/>adapters/surface.py"| SP[sp-pricer]
+    SP -->|"value(scenario)<br/>adapters/notes.py"| RL[risk-lab]
+    VS -->|"shifted surfaces, vol_fn"| RL
+    RL -->|"estimators and allocators<br/>(plain callables)"| BT[backtest-lab]
+    MS[microstructure-lab] -->|"calibrate_costs to SpreadImpactCost<br/>adapters/costs.py"| BT
+    subgraph quant-stack
+      A[adapters, studies S1-S7, integration tests]
+    end
+```
+
+Every arrow is a **protocol, not an import**. The library on the receiving end of an arrow defines a
+small interface:
+
+- sp-pricer's `LocalVolSource` is anything with `local_vol(K, T)` and a `curve`.
+- risk-lab's `Position` is anything with `value(scenario)`.
+- btlab's `CostModel` is anything with `cost(trade, date, context)`.
+
+quant-stack wires real objects into those interfaces in [`src/quantstack/adapters/`](https://github.com/hossainyousuf751/quant-stack/tree/main/src/quantstack/adapters), and
+nowhere else.
+
+The libraries also duplicate a few small pieces on purpose instead of sharing a core package: three
+Black-Scholes implementations and two yfinance loaders. [`tests/test_consistency.py`](https://github.com/hossainyousuf751/quant-stack/blob/main/tests/test_consistency.py)
+asserts that the duplicates agree to 1e-12 on a grid of inputs and return the same data format.
+
+## Studies
+
+| Study | Question | Headline result |
+|---|---|---|
+| [S1](https://github.com/hossainyousuf751/quant-stack/blob/main/studies/s1_skew_autocallable.py) skew and the autocallable | What does pricing off the smile do to a Phoenix? | On the 2026-10-30 SPX/NDX close, local vol lowers the worst-of note from 100.44 to 96.44 per 100 (−4.00 ± 0.04 SE). The synthetic notes fall by 3.4 and 5.8 |
+| [S2](https://github.com/hossainyousuf751/quant-stack/blob/main/studies/s2_note_book_risk.py) risk of a structured-note book | Where do linear VaR approximations break? | Delta-normal VaR of the delta-hedged book is 0, against 90 under full revaluation. Delta-gamma-vega overstates it at 152 |
+| [S3](https://github.com/hossainyousuf751/quant-stack/blob/main/studies/s3_risk_portfolios_backtest.py) risk-based portfolios, honestly backtested | Do risk-lab's rankings survive costs, lag and selection? | Long-only minimum variance keeps the lowest true risk (9.5% vs 15.1% for 1/N) after lag and costs. Best of 24 configurations: Deflated Sharpe 0.94, walk-forward out-of-sample Sharpe 0.59. HRP's turnover barely falls with the window on synthetic data but falls 4× on real ETFs |
+| [S4](https://github.com/hossainyousuf751/quant-stack/blob/main/studies/s4_costs_from_order_book.py) costs from the order book | Does a strong same-second order-flow relationship survive as a trade? | OFI (R² 0.59) loses after the spread alone. Queue imbalance survives spread, 1–5 s latency and the recorded book at small size, but covers at most 0.24 bp per unit traded, so any exchange taker fee kills it |
+| [S5](https://github.com/hossainyousuf751/quant-stack/blob/main/studies/s5_skew_option_var.py) skew in option VaR | How much does the smile's behaviour under spot moves change option VaR? | Sticky moneyness more than doubles a short straddle's 1-day VaR against sticky strike (0.82 vs 0.38 synthetic, 0.84 vs 0.32 SPX) |
+| [S6](https://github.com/hossainyousuf751/quant-stack/blob/main/studies/s6_autocallable_investors.py) how did autocallable investors do? | A SPY Phoenix issued monthly since 2005 at a model fair value of 98: what did investors actually receive? | Realised cash flows were worth 101.20 at the issue rate, +3.20 ± 0.72 (Newey-West) above the model. 94% autocalled, none lost capital, and the excess return over the 3-year rate was +1.1% ± 0.7% a year |
+| [S7](https://github.com/hossainyousuf751/quant-stack/blob/main/studies/s7_market_maker_risk.py) market-maker inventory risk | How bad is a bad session for an Avellaneda–Stoikov quoter in the order book, and do standard VaR models know? | Symmetric quotes earn 46–65% more but carry 5–13× the 97.5% ES. Normal VaR fails 4 of 6 books (32–47 exceptions against 15), and RiskMetrics EWMA finds none on the inventory books because it assumes zero-mean P&L. Historical and FHS pass |
+
+Each study prints its tables to [`docs/`](https://github.com/hossainyousuf751/quant-stack/tree/main/docs) (`s*_output.txt`, plus plots). All seeds are fixed.
+
+### S1: skew and the autocallable
+
+![Price vs barrier](https://raw.githubusercontent.com/hossainyousuf751/quant-stack/main/docs/s1_price_vs_barrier_spx.png)
+
+The note is sp-pricer's README note: 3 years, quarterly, a 2% memory coupon, autocall at 100% from
+year 1, and 60% European protection. Every product here is short a down-and-in put, so the put skew
+drives its value. Three models price the same note on the same forward curves and random numbers:
+
+| SPX/NDX worst-of, ρ = 0.9 | Fair value | vs flat ATM | P(autocall at year 1) | P(knocked in) |
+|---|---|---|---|---|
+| flat ATM vol (18.2% / 23.8%) | 100.44 | | 47.0% | 7.7% |
+| flat vol at the 60% strike | 94.15 | −6.29 ± 0.04 | 42.4% | 17.7% |
+| Dupire local vol (arbitrage-free SVI) | **96.44** | **−4.00 ± 0.04** | 57.4% | 11.2% |
+
+The local-vol pipeline is validated first, in [`tests/test_link_a.py`](https://github.com/hossainyousuf751/quant-stack/blob/main/tests/test_link_a.py). Monte
+Carlo prices of 20 vanillas under sp-pricer's `LocalVolModel` imply back the volsurface surface's
+own vols within 2.5 standard errors. Flat ATM vol misses the same targets by up to 940.
+
+The S1 numbers also reproduce volsurface's earlier, independent simulator: 100.41, 96.14 and 96.42.
+Halving or doubling the time step moves the worst-of note by no more than its standard error (96.23,
+96.30 and 96.15, each ± 0.07).
+
+### S2: risk of a structured-note book
+
+![P&L profile](https://raw.githubusercontent.com/hossainyousuf751/quant-stack/main/docs/s2_pnl_profile.png)
+
+A dealer is short four notes on two underlyings and may delta-hedge with shares. Each method gives a
+10-day 99% VaR (lognormal scenarios, with implied vol falling 0.8 points per 1% rise in A):
+
+| Book | Delta-normal | Delta-gamma-vega | Full revaluation (price grid) |
+|---|---|---|---|
+| unhedged | 89.9 | 222.4 | 154.4 |
+| delta-hedged | **0.0** | 152.2 | **90.0** |
+
+Full revaluation reprices every note in every scenario. To make 20,000 scenarios affordable, it
+interpolates on a price grid validated against direct repricing at random points: the mean error is
+0.02 per 100 and the largest is 2.2 Monte Carlo standard errors.
+The same pattern holds under fat-tailed DCC-t scenarios.
+
+### S5: skew in option VaR
+
+risk-lab Study 3's books, priced off a fitted smile instead of one flat vol, with full revaluation only:
+
+| 1-day 99% VaR | flat ATM | sticky strike | sticky moneyness |
+|---|---|---|---|
+| covered call | 1.97 | 2.05 | 1.92 |
+| protective put | 1.86 | 1.83 | 2.04 |
+| short ATM straddle | 0.38 | 0.38 | **0.82** |
+
+(Synthetic SSVI surface; the SPX snapshot gives the same ordering.)
+
+### S6: how did autocallable investors actually do?
+
+![Realised vs fair](https://raw.githubusercontent.com/hossainyousuf751/quant-stack/main/docs/s6_fair_vs_realised.png)
+
+A 3-year SPY Phoenix is issued on the first trading day of every month from 2005 to 2025: quarterly
+observations, a memory coupon above 70%, autocall at 100% from year 1, and 60% European protection.
+The coupon is set at issue, from that day's VIX and Treasury yields only, so that sp-pricer's fair value
+is 98 (a 2-point margin). The realised SPY path, from btlab's loader, then gives each note's actual cash
+flows, read off by the product's own payoff code.
+
+| 250 notes, 2005-01 to 2025-10 | Value |
+|---|---|
+| coupon set at issue, per year | mean 3.23%, from −0.32% (2013) to 28.4% (Nov 2008) |
+| model fair value at issue | 98.00 |
+| realised cash flows, PV at the issue rate | **101.20** (+3.20 ± 0.72) |
+| realised IRR minus the 3-year rate | +1.13% ± 0.69% a year |
+| outcomes | 94% autocalled (83% at year 1), 6% repaid at par, 0 losses |
+| VIX at issue vs realised vol over the note's life | 19.3% vs 17.0% |
+
+VIX stands in for a 3-year ATM vol, with no skew or term structure. The note is on SPY total return with
+zero dividend yield, and the rate carries no issuer funding spread. The 21 years of overlapping notes hold
+only about seven independent 3-year windows.
+
+### S7: market-maker inventory risk
+
+![Return vs ES](https://raw.githubusercontent.com/hossainyousuf751/quant-stack/main/docs/s7_mm_return_vs_es.png)
+
+microstructure-lab's Avellaneda–Stoikov quoter runs inside its order-book simulator for 2,500 independent
+5-minute sessions per setting. It uses the paper's inputs calibrated on the book, as in that repo's Study 4.
+risk-lab measures each P&L series and backtests its four VaR models over the last 1,500 sessions.
+
+| Session P&L (ticks) | Mean | Skew | Excess kurtosis | P(loss) | 99% VaR | 97.5% ES | Mean / ES |
+|---|---|---|---|---|---|---|---|
+| γ = 0.001, inventory | 31.6 | −0.57 | 0.8 | 9.9% | 37.0 | 37.7 | 0.84 |
+| γ = 0.001, symmetric | 46.2 | −1.29 | 6.3 | 16.7% | 169.0 | 182.9 | 0.25 |
+| **γ = 0.005, inventory** | **22.6** | −0.25 | 0.6 | **4.3%** | **10.0** | **11.9** | **1.90** |
+| γ = 0.005, symmetric | 36.8 | −1.03 | 4.9 | 17.8% | 143.0 | 149.3 | 0.25 |
+| γ = 0.02, inventory | 8.5 | −0.27 | 0.5 | 10.1% | 10.5 | 10.0 | 0.85 |
+| γ = 0.02, symmetric | 14.0 | −1.00 | 5.9 | 21.6% | 70.0 | 72.8 | 0.19 |
+
+| 99% VaR backtest, 6 books | Kupiec passes (p > 0.05) | Exceptions (15 expected) | 97.5% ES (Z2) |
+|---|---|---|---|
+| historical, 500 sessions | 6 of 6 | 13–21 | passes everywhere |
+| filtered historical (FHS), 1,000 | 5 of 6 | 11–24 | passes everywhere |
+| normal, 500 | 2 of 6, both at p = 0.054 | 23–47 | rejected on 4 books (−0.96 to −1.35) |
+| EWMA (RiskMetrics) | 3 of 6: symmetric books only | 0 on every inventory book | far too conservative on inventory books |
+
+In the paper's own fill model, not one of 2,500 sessions loses money (the worst is +43), so a loss VaR
+there is meaningless. Losses come from the order book's queue position and adverse selection.
+
+## What was surprising, what went wrong, and how it was diagnosed
+
+**S1: a "skew-aware" flat vol overshoots.** Pricing the note with flat vol taken at the barrier
+strike sounds like a cheap way to respect the skew, so I expected it to land near local vol. It lands
+well below it instead: −6.3 against −4.0 on SPX/NDX, and −8.1 against −5.8 on the synthetic worst-of.
+The autocall probabilities show why. A barrier-strike vol applies put-wing volatility everywhere,
+including near and above 100%, where local vol is low. So it understates the chance of an early
+call at year 1 (42% vs 57%) and overstates the chance of ending knocked in (18% vs 11%). Local vol
+is not "flat vol at the right strike"; it is a different vol in each region the path visits. The
+local-vol pipeline was validated before any of this: Monte Carlo vanillas reprice the surface within
+2.5 SE, and two independent simulators agree within error.
+
+**S2: delta-gamma-vega was worse than delta-normal, in the other direction.** I expected the
+second-order expansion to land between delta-normal and full revaluation. Instead it overstates the
+unhedged book's VaR by 44% (222 vs 154). To find out why, I repriced each note under parallel vol
+shifts. The notes' value is concave in vol: an 8-point fall in vol raises the single-asset Phoenix by
+3.8 per 100, while vega × shift says 4.9. The scenarios move vol against spot (−0.8 points per 1%),
+so the 10-day tail combines a rally with a large vol fall, exactly where linear vega overstates the
+dealer's loss. Delta-normal misses the other way: it reports zero risk for the delta-hedged book,
+which full revaluation puts at 90. Getting the full-revaluation number cheaply also took a second
+attempt. The first price grid missed direct repricing by up to 5.5 SE. That pointed at the vol axis
+rather than the spot axis, because tightening the spot spacing made no difference. Halving the vol
+step brought the worst point to 2.2 SE, and the VaR itself moved by only 2%.
+
+**S3: one finding confirmed, one refuted, one bug of my own.** On risk-lab's synthetic data, HRP's
+turnover barely falls as the estimation window grows (4.4 to 3.3 times a year, while minimum variance
+falls from 5.6 to 1.0), confirming risk-lab's result under a real backtest. On the 10 ETFs it falls
+4×, from 3.6 to 0.9. The block covariance's equal within-block correlations make HRP's ordering flip
+between near-ties, while stocks, bonds and commodities form stable clusters. FHS VaR, which passes
+every backtest on synthetic data, takes 44–53 exceptions against 37 expected on the ETF portfolios.
+A first run also reported "true" volatility well below realised volatility for every method. The
+cause was in my study code: it averaged in the warm-up rebalances that hold nothing. 24 empty
+rebalances out of 144 explained the gap exactly (12.6% vs 15.1% for 1/N).
+
+**S4: the edge that should not have survived, and what finally killed it.** The expected lesson was
+that a strong same-second relationship (OFI explains 59% of BTC's one-second mid changes) does not
+survive latency and spread. For OFI itself that holds: it trades about 2,000 times an hour, and the
+spread alone costs more than its gross edge, so its net Sharpe is negative at every lag. Queue
+imbalance did survive: positive net of spread and calibrated impact at lags of 1, 2 and 5 seconds,
+right on 90% of the mid's moves. I treated that as a bug until each candidate was ruled out:
+
+- The look-ahead check rebuilds features from quotes truncated at each cutoff, and it passes.
+- The spread at the trades' execution bars equals the median spread, so the edge is not a wide
+  spread being ignored.
+- Walking each trade through the recorded 10-level book at $100,000 cuts BTC's edge by a third but
+  leaves it positive. On the thinner ETH book the same size turns every variant negative; at $1,000
+  both survive.
+
+What kills it is the cost an order book does not show: exchange fees. The signal's gross edge
+covers at most about 0.24 bp per unit traded on BTC and on ETH, against Binance's
+published base taker fee of 10 bp. At any taker fee, every variant loses. A queue-imbalance edge
+belongs to whoever is paid to provide liquidity, not to whoever takes it. Two hours of data is one
+sample, so this is an illustration of the method rather than a result to trade on.
+
+**S6: investors beat the model, and the sample is why to be careful.** Priced at 98, the notes
+delivered 101.20 on average. Only 2% of issues came in below 98, and the gap survives dropping the 2008,
+2009 and 2020 vintages (+2.28 ± 0.38). The reason is in the outcomes: the fair value charges for a
+3-year fall of more than 40%, and since 2005 the lowest SPY level at any 3-year maturity was 72%. VIX
+also exceeded the volatility that followed for 65% of issues. Two results surprised me. First, for 13
+issues between 2013 and 2016 the coupon that prices the note at 98 is negative: with VIX near 12 and
+3-year rates under 1%, a note with no coupon is already worth more than 98. Real notes paid positive
+coupons then because issuers fund above Treasuries and the note references the price index, which has
+a lower forward; both are left out here and stated. Second, the first version used a fixed 8% coupon,
+which put fair values as high as 112, terms no issuer would sell; setting the coupon at issue fixed that.
+The study begins in 2005, as specified, so it leaves out 2000–2002, when SPY fell 48% peak to trough.
+I first wrote here that a note issued in 2000 would very likely have lost capital, then checked the same
+total-return series. It would not: the 2000 issues end at 60–85% of their initial level. The April 2000
+note matures at 60.4%, just 0.4 points above the barrier. None of them autocalls, so investors get par
+back after three years with most coupons missed. Seven independent windows cannot show that the model
+overprices the crash; they show that a crash deep enough to breach 60% at a maturity date did not occur.
+
+**S7: the model that failed for the opposite reason, and a library number that moved.** I expected
+normal VaR to fail on the symmetric quoter, whose P&L has excess kurtosis near 6 and a fat left tail, and it
+did, with 32–47 exceptions against 15. The surprise was RiskMetrics EWMA, which recorded zero exceptions on
+every inventory book. It assumes zero-mean returns, but these books earn 1.2–1.7 standard deviations per
+session on average. EWMA therefore reads the mean as volatility and sets VaR 2.6–5.7× too high (61 against 11
+at γ = 0.005). Fed into a limit framework, that would cap the safest quoter hardest. Sessions are
+independent by construction, so FHS has no clustering to exploit; it passes because its residuals are
+empirical. Its one Kupiec rejection (p = 0.032) is in line with 24 tests at a 5% level.
+
+Running 2,500 sessions instead of 200 also moved a number in microstructure-lab's README. Its γ = 0.005
+inventory row shows a mean P&L of 19.4. The first 200 sessions here reproduce that exactly, but the full
+2,500 average 22.6 ± 0.26, and five fresh blocks on unused seeds give 21.3–24.1. Seeds 0–199 were a
+low draw, about 3.5 standard errors under the mean. Inventory control costs 32–40% of mean P&L rather than
+the published 33–45%; the conclusion is unchanged. The library README is left as published until the
+owner approves a change.
+
+**Testing across versions.** The libraries promise numpy ≥ 1.24, pandas ≥ 2.0 and scipy ≥ 1.10. I
+ran every suite in an environment with exactly those versions. Every test passed except my new
+regression pins: optimiser-fitted values move by up to 1e-5 relative between scipy 1.10 and 1.17,
+and one penalised SVI fit settles on a different optimum (0.1815 vs 0.1790, both printed as 0.18).
+The pins now hold each figure to the precision the README actually prints.
+
+## Install
+
+```bash
+pip install quantstack-lab        # the adapters (import quantstack) and all five libraries from PyPI
+```
+
+`volsurface` and `risk-lab` are published as `volsurface-lab` and `marketrisk-lab`, because the names
+`volsurface` and `risklab` belong to unrelated projects on PyPI; their import names are unchanged. The
+studies, tests and plots are not part of the package. To run them, clone the repository as below.
+
+## Reproduce
+
+```bash
+git clone --recurse-submodules https://github.com/hossainyousuf751/quant-stack.git
+cd quant-stack
+for p in sp-pricer volsurface backtest-lab microstructure-lab risk-lab; do pip install -e "projects/$p"; done
+pip install -e ".[dev]"
+pytest                                   # consistency and integration tests, offline, about 1 minute
+python studies/s1_skew_autocallable.py   # each study writes docs/s*_output.txt-style tables and plots
+```
+
+What the studies need:
+
+- **S1 and S5** use volsurface's saved CBOE snapshot (`projects/volsurface/data/`, git-ignored; create it with
+  `projects/volsurface/examples/snapshot.py`) for their real-data parts, and skip those parts without it.
+- **S4** uses microstructure-lab's Binance recordings, likewise git-ignored and created with its recorder.
+- **S7** is fully offline (simulated order book), about 7 minutes.
+- **S3, S4 and S6** download Yahoo Finance prices on first run and cache them in `data/`. They skip those
+  parts when offline.
+
+Each library's own tests still run without the others installed: `cd projects/<repo> && pytest`.
+
+## Layout
+
+```
+quant-stack/
+├── projects/          the five libraries (git submodules, tagged releases)
+├── src/quantstack/
+│   └── adapters/      surface.py (Link A), notes.py (Link B), costs.py (Link D)
+├── studies/           S1-S7
+├── tests/             consistency and integration tests
+└── docs/              study outputs and plots; profile_README.md
+```
+
+Data is public or synthetic only: Yahoo Finance, CBOE delayed quotes, Binance public market data,
+and simulators.

quantstack_lab-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+quantstack/__init__.py,sha256=PA1QRuW40bn1LjnVHVUV5G0w11e1EPWJyI3WbS9JerA,108
+quantstack/adapters/__init__.py,sha256=eb1t39fV_Vo6NomuBZAmNHqN0HvBFdegfzR91euuqhM,77
+quantstack/adapters/costs.py,sha256=TKg0qbA71OK5qjAfAoJSx4N9TsoIiHiWBu77CQ4w5Vw,4767
+quantstack/adapters/notes.py,sha256=Q2Ygg6ZYIHUqxPyd_PaMHgDBdzgsKcpDeMGOpCwy-pY,9386
+quantstack/adapters/surface.py,sha256=DIrPo-bV3CBBzgQODBKFm9Q6N7sVLy327DoaDg6xAGU,2714
+quantstack_lab-0.1.0.dist-info/licenses/LICENSE,sha256=OAV_RTERHYKJrtHIxvr_VWUiM6k-1PKksx8ezi9wMmY,1079
+quantstack_lab-0.1.0.dist-info/METADATA,sha256=Rsm50SfwANCAvKwKjk2fzo_6huCVhpOLe7hnt3mFJkQ,22491
+quantstack_lab-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+quantstack_lab-0.1.0.dist-info/top_level.txt,sha256=plf1I8JuPOFml6zbDMp0A8_qLtg7ChacKDwmbipwe1U,11
+quantstack_lab-0.1.0.dist-info/RECORD,,

quantstack_lab-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

quantstack_lab-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yousuf Hossain Shafeen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantstack_lab-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+quantstack