oq-backtest 0.1.0__py3-none-any.whl

oq_backtest/__init__.py

@@ -0,0 +1,91 @@
+"""``oq-backtest``: honest, vectorized backtester for Indian equities."""
+
+from oq_backtest.costs import (
+    DHAN_DELIVERY,
+    DHAN_INTRADAY,
+    FULL_SERVICE_DELIVERY,
+    FYERS_DELIVERY,
+    FYERS_INTRADAY,
+    PRESETS,
+    UPSTOX_DELIVERY,
+    UPSTOX_INTRADAY,
+    ZERODHA_DELIVERY,
+    ZERODHA_INTRADAY,
+    CostBreakdown,
+    CostConfig,
+    TaxConfig,
+    compute_costs,
+    resolve_config,
+)
+from oq_backtest.engine import backtest
+from oq_backtest.intraday import (
+    NSE_CLOSE,
+    NSE_OPEN,
+    IntradayConfig,
+    apply_square_off,
+    backtest_intraday,
+    intraday_summary,
+    is_intraday_preset,
+)
+from oq_backtest.result import BacktestResult
+from oq_backtest.slippage import (
+    FixedBpsSlippage,
+    SlippageModel,
+    SpreadSlippage,
+    VolumeParticipationSlippage,
+    resolve_slippage,
+)
+from oq_backtest.strategies import (
+    equal_weight,
+    mean_reversion_signal,
+    momentum_signal,
+    rebalance_dates,
+    synthetic_universe,
+)
+from oq_backtest.tax import TaxBreakdown, estimate_taxes
+from oq_backtest.walkforward import Fold, train_test_split, walk_forward
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DHAN_DELIVERY",
+    "DHAN_INTRADAY",
+    "FULL_SERVICE_DELIVERY",
+    "FYERS_DELIVERY",
+    "FYERS_INTRADAY",
+    "NSE_CLOSE",
+    "NSE_OPEN",
+    "PRESETS",
+    "UPSTOX_DELIVERY",
+    "UPSTOX_INTRADAY",
+    "ZERODHA_DELIVERY",
+    "ZERODHA_INTRADAY",
+    "BacktestResult",
+    "CostBreakdown",
+    "CostConfig",
+    "FixedBpsSlippage",
+    "Fold",
+    "IntradayConfig",
+    "SlippageModel",
+    "SpreadSlippage",
+    "TaxBreakdown",
+    "TaxConfig",
+    "VolumeParticipationSlippage",
+    "__version__",
+    "apply_square_off",
+    "backtest",
+    "backtest_intraday",
+    "compute_costs",
+    "equal_weight",
+    "estimate_taxes",
+    "intraday_summary",
+    "is_intraday_preset",
+    "mean_reversion_signal",
+    "momentum_signal",
+    "rebalance_dates",
+    "resolve_config",
+    "resolve_slippage",
+    "synthetic_universe",
+    "train_test_split",
+    "walk_forward",
+]

oq_backtest/costs.py

@@ -0,0 +1,277 @@
+"""Indian equity cost engine.
+
+Implements the regulatory and broker charges that a real Indian equity trade
+incurs, and exposes a small set of broker presets so a user can swap a single
+string in :func:`oq_backtest.backtest` and get a realistic net P&L.
+
+All rates are expressed as decimal fractions of notional (``0.001`` == 0.1%).
+Rates are calibrated against published charge sheets as of 2024-2025; consumers
+should treat them as a baseline and override via :class:`CostConfig` for exact
+broker / state / segment specifics.
+
+References
+----------
+* SEBI charges: Rs. 10 per crore of turnover (1e-6 of notional).
+* NSE cash exchange transaction charge (revised Oct 2024): 0.00297%.
+* GST: 18% on (brokerage + exchange + SEBI) charges only.
+* STT delivery: 0.1% on both buy and sell legs.
+* STT intraday: 0.025% on sell leg only.
+* Stamp duty (delivery, buy only): 0.015%. Intraday buy: 0.003%.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+
+Side = Literal["buy", "sell"]
+
+
+@dataclass(frozen=True, slots=True)
+class CostConfig:
+    """Per-leg cost configuration for an Indian equity broker.
+
+    All ``*_rate`` fields are decimal fractions of order notional. Brokerage
+    additionally supports a per-order ``min`` floor and ``max`` ceiling in
+    INR (matching the "0.03% or Rs. 20, whichever lower" convention).
+    """
+
+    brokerage_rate: float = 0.0
+    brokerage_min: float = 0.0
+    brokerage_max: float = float("inf")
+    stt_buy_rate: float = 0.001
+    stt_sell_rate: float = 0.001
+    exchange_rate: float = 0.0000297
+    sebi_rate: float = 1e-6
+    stamp_duty_buy_rate: float = 0.00015
+    gst_rate: float = 0.18
+    is_intraday: bool = False
+
+    def __post_init__(self) -> None:
+        for name in (
+            "brokerage_rate",
+            "stt_buy_rate",
+            "stt_sell_rate",
+            "exchange_rate",
+            "sebi_rate",
+            "stamp_duty_buy_rate",
+            "gst_rate",
+        ):
+            value = getattr(self, name)
+            if value < 0:
+                raise ValueError(f"{name} must be >= 0, got {value}")
+        if self.brokerage_min < 0:
+            raise ValueError("brokerage_min must be >= 0")
+        if self.brokerage_max < self.brokerage_min:
+            raise ValueError("brokerage_max must be >= brokerage_min")
+
+
+@dataclass(frozen=True, slots=True)
+class CostBreakdown:
+    """Per-rebalance cost decomposition in INR."""
+
+    brokerage: float = 0.0
+    stt: float = 0.0
+    exchange: float = 0.0
+    sebi: float = 0.0
+    gst: float = 0.0
+    stamp_duty: float = 0.0
+
+    @property
+    def total(self) -> float:
+        return self.brokerage + self.stt + self.exchange + self.sebi + self.gst + self.stamp_duty
+
+    def as_dict(self) -> dict[str, float]:
+        return {
+            "brokerage": self.brokerage,
+            "stt": self.stt,
+            "exchange": self.exchange,
+            "sebi": self.sebi,
+            "gst": self.gst,
+            "stamp_duty": self.stamp_duty,
+            "total": self.total,
+        }
+
+    def __add__(self, other: CostBreakdown) -> CostBreakdown:
+        if not isinstance(other, CostBreakdown):
+            return NotImplemented
+        return CostBreakdown(
+            brokerage=self.brokerage + other.brokerage,
+            stt=self.stt + other.stt,
+            exchange=self.exchange + other.exchange,
+            sebi=self.sebi + other.sebi,
+            gst=self.gst + other.gst,
+            stamp_duty=self.stamp_duty + other.stamp_duty,
+        )
+
+
+ZERODHA_DELIVERY = CostConfig()
+
+ZERODHA_INTRADAY = CostConfig(
+    brokerage_rate=0.0003,
+    brokerage_max=20.0,
+    stt_buy_rate=0.0,
+    stt_sell_rate=0.00025,
+    stamp_duty_buy_rate=0.00003,
+    is_intraday=True,
+)
+
+UPSTOX_DELIVERY = CostConfig()
+
+UPSTOX_INTRADAY = CostConfig(
+    brokerage_rate=0.0005,
+    brokerage_max=20.0,
+    stt_buy_rate=0.0,
+    stt_sell_rate=0.00025,
+    stamp_duty_buy_rate=0.00003,
+    is_intraday=True,
+)
+
+FYERS_DELIVERY = CostConfig()
+
+FYERS_INTRADAY = CostConfig(
+    brokerage_rate=0.0003,
+    brokerage_max=20.0,
+    stt_buy_rate=0.0,
+    stt_sell_rate=0.00025,
+    stamp_duty_buy_rate=0.00003,
+    is_intraday=True,
+)
+
+DHAN_DELIVERY = CostConfig()
+
+DHAN_INTRADAY = CostConfig(
+    brokerage_rate=0.0003,
+    brokerage_max=20.0,
+    stt_buy_rate=0.0,
+    stt_sell_rate=0.00025,
+    stamp_duty_buy_rate=0.00003,
+    is_intraday=True,
+)
+
+FULL_SERVICE_DELIVERY = CostConfig(
+    brokerage_rate=0.005,
+    brokerage_min=0.0,
+    brokerage_max=float("inf"),
+)
+
+
+PRESETS: Mapping[str, CostConfig] = {
+    "zerodha": ZERODHA_DELIVERY,
+    "zerodha_intraday": ZERODHA_INTRADAY,
+    "upstox": UPSTOX_DELIVERY,
+    "upstox_intraday": UPSTOX_INTRADAY,
+    "fyers": FYERS_DELIVERY,
+    "fyers_intraday": FYERS_INTRADAY,
+    "dhan": DHAN_DELIVERY,
+    "dhan_intraday": DHAN_INTRADAY,
+    "full_service": FULL_SERVICE_DELIVERY,
+    "zero": CostConfig(
+        brokerage_rate=0.0,
+        stt_buy_rate=0.0,
+        stt_sell_rate=0.0,
+        exchange_rate=0.0,
+        sebi_rate=0.0,
+        stamp_duty_buy_rate=0.0,
+        gst_rate=0.0,
+    ),
+}
+
+
+def resolve_config(costs: str | CostConfig) -> CostConfig:
+    """Look up a preset by name, or return a :class:`CostConfig` unchanged."""
+    if isinstance(costs, CostConfig):
+        return costs
+    if isinstance(costs, str):
+        key = costs.lower()
+        if key not in PRESETS:
+            raise KeyError(f"unknown cost preset {costs!r}; known presets: {sorted(PRESETS)}")
+        return PRESETS[key]
+    raise TypeError(f"costs must be str or CostConfig, got {type(costs).__name__}")
+
+
+def _brokerage_per_order(notionals: np.ndarray, cfg: CostConfig) -> np.ndarray:
+    """Apply per-order min/max brokerage to an array of per-symbol notionals."""
+    raw = notionals * cfg.brokerage_rate
+    if cfg.brokerage_min > 0:
+        raw = np.where(notionals > 0, np.maximum(raw, cfg.brokerage_min), raw)
+    if np.isfinite(cfg.brokerage_max):
+        raw = np.where(notionals > 0, np.minimum(raw, cfg.brokerage_max), raw)
+    return raw
+
+
+def compute_costs(
+    buy_notionals: np.ndarray | float,
+    sell_notionals: np.ndarray | float,
+    cfg: CostConfig,
+) -> CostBreakdown:
+    """Compute the full Indian-market cost breakdown for one rebalance.
+
+    Parameters
+    ----------
+    buy_notionals, sell_notionals:
+        Per-order absolute notional values in INR. May be scalars or arrays.
+        Each element is treated as an independent order for brokerage min/max.
+    cfg:
+        Cost configuration; build one yourself or use :data:`PRESETS`.
+    """
+    buys = np.atleast_1d(np.asarray(buy_notionals, dtype=float))
+    sells = np.atleast_1d(np.asarray(sell_notionals, dtype=float))
+
+    buy_total = float(buys.sum())
+    sell_total = float(sells.sum())
+
+    brokerage_buy = float(_brokerage_per_order(buys, cfg).sum())
+    brokerage_sell = float(_brokerage_per_order(sells, cfg).sum())
+    brokerage = brokerage_buy + brokerage_sell
+
+    stt = buy_total * cfg.stt_buy_rate + sell_total * cfg.stt_sell_rate
+    exchange = (buy_total + sell_total) * cfg.exchange_rate
+    sebi = (buy_total + sell_total) * cfg.sebi_rate
+    gst = (brokerage + exchange + sebi) * cfg.gst_rate
+    stamp = buy_total * cfg.stamp_duty_buy_rate
+
+    return CostBreakdown(
+        brokerage=brokerage,
+        stt=stt,
+        exchange=exchange,
+        sebi=sebi,
+        gst=gst,
+        stamp_duty=stamp,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class TaxConfig:
+    """Indian equity capital gains tax estimator.
+
+    Not investment advice. Holding period thresholds and rates are based on
+    rules as of FY2024-25. Override when legislation changes.
+    """
+
+    short_term_days: int = 365
+    stcg_rate: float = 0.15
+    ltcg_rate: float = 0.125
+    ltcg_exempt_inr: float = 125_000.0
+
+
+__all__ = [
+    "DHAN_DELIVERY",
+    "DHAN_INTRADAY",
+    "FULL_SERVICE_DELIVERY",
+    "FYERS_DELIVERY",
+    "FYERS_INTRADAY",
+    "PRESETS",
+    "UPSTOX_DELIVERY",
+    "UPSTOX_INTRADAY",
+    "ZERODHA_DELIVERY",
+    "ZERODHA_INTRADAY",
+    "CostBreakdown",
+    "CostConfig",
+    "TaxConfig",
+    "compute_costs",
+    "resolve_config",
+]

oq_backtest/engine.py

@@ -0,0 +1,187 @@
+"""Vectorized daily-frequency portfolio backtest engine.
+
+The engine consumes a ``signals`` DataFrame of target weights and a
+``prices`` DataFrame of close prices, both indexed by date with symbols as
+columns. It produces gross and net equity curves, per-rebalance cost
+attribution, and the realized weights and trades, all wrapped in a
+:class:`BacktestResult`.
+
+Design choices
+--------------
+* **Close-to-close**: signals dated ``t`` are executed at the close of ``t``
+  and earn the close-to-close return from ``t`` to ``t+1``. To avoid look-
+  ahead, generate your signals from data up to and including ``t``'s close
+  (typical research practice) and let the engine handle the lag.
+* **Weights, not lot sizes**: positions are stored as fractions of portfolio
+  value. Lot-size rounding belongs in execution, not research.
+* **Costs come out of the portfolio**: net equity at each step is gross
+  equity minus the regulatory + slippage charges incurred at the rebalance.
+* **NaN-tolerant**: a NaN price for a symbol on a date means "no quote" and
+  forces the prior weight forward without a return contribution. A NaN
+  signal is treated as 0 (no allocation).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from oq_backtest.costs import CostConfig, compute_costs, resolve_config
+from oq_backtest.result import BacktestResult
+from oq_backtest.slippage import SlippageModel, resolve_slippage
+
+
+def _align(signals: pd.DataFrame, prices: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame]:
+    symbols = signals.columns.intersection(prices.columns)
+    if symbols.empty:
+        raise ValueError("signals and prices share no symbols in common")
+    s = signals[symbols].copy()
+    p = prices[symbols].copy()
+    s.index = pd.DatetimeIndex(s.index)
+    p.index = pd.DatetimeIndex(p.index)
+    common = s.index.intersection(p.index)
+    if common.empty:
+        raise ValueError("signals and prices share no dates in common")
+    s = s.loc[common].sort_index()
+    p = p.loc[common].sort_index()
+    s = s.fillna(0.0)
+    return s, p
+
+
+def _validate_weights(signals: pd.DataFrame, allow_short: bool, max_leverage: float) -> None:
+    if not allow_short and (signals.to_numpy() < -1e-9).any():
+        raise ValueError(
+            "signals contain negative weights but allow_short=False; "
+            "pass allow_short=True or clip to >= 0"
+        )
+    gross = signals.abs().sum(axis=1)
+    if (gross > max_leverage + 1e-9).any():
+        bad = gross[gross > max_leverage + 1e-9]
+        raise ValueError(
+            f"signals exceed max_leverage={max_leverage:g} on "
+            f"{len(bad)} dates; first offender: {bad.index[0].date()} = {bad.iloc[0]:.4f}"
+        )
+
+
+def backtest(
+    signals: pd.DataFrame,
+    prices: pd.DataFrame,
+    costs: str | CostConfig = "zerodha",
+    slippage: SlippageModel | float | int = 5.0,
+    initial_capital: float = 1_000_000.0,
+    allow_short: bool = False,
+    max_leverage: float = 1.0,
+) -> BacktestResult:
+    """Run an honest, cost-aware backtest of a weight-based strategy.
+
+    Parameters
+    ----------
+    signals:
+        DataFrame of target portfolio weights, indexed by date, columns are
+        symbols. A row summing to 1.0 is fully invested; 0.5 is half cash.
+    prices:
+        DataFrame of close prices in INR, indexed by date, columns are
+        symbols. Must overlap with ``signals``.
+    costs:
+        Either a preset name from :data:`oq_backtest.costs.PRESETS`
+        (``"zerodha"``, ``"upstox"``, ``"fyers"``, ``"dhan"``,
+        ``"full_service"``, ``"zero"``, and ``*_intraday`` variants) or a
+        :class:`CostConfig` instance.
+    slippage:
+        A :class:`SlippageModel` instance or a number interpreted as fixed
+        bps via :class:`FixedBpsSlippage`. Default is 5 bps.
+    initial_capital:
+        Starting portfolio value in INR. Default 10 lakhs.
+    allow_short:
+        If False, negative weights raise. Default False (cash-account safe).
+    max_leverage:
+        Maximum gross exposure (sum of absolute weights). Default 1.0.
+
+    Returns
+    -------
+    :class:`BacktestResult`
+    """
+    if initial_capital <= 0:
+        raise ValueError("initial_capital must be > 0")
+    if max_leverage <= 0:
+        raise ValueError("max_leverage must be > 0")
+
+    cfg = resolve_config(costs)
+    slip = resolve_slippage(slippage)
+    cost_label = costs if isinstance(costs, str) else "custom"
+
+    s, p = _align(signals, prices)
+    _validate_weights(s, allow_short=allow_short, max_leverage=max_leverage)
+
+    symbols = s.columns
+    dates = s.index
+    n_dates = len(dates)
+
+    rets = p.pct_change().fillna(0.0).to_numpy(dtype=float)
+    target = s.to_numpy(dtype=float)
+
+    gross_equity = np.empty(n_dates, dtype=float)
+    net_equity = np.empty(n_dates, dtype=float)
+    realised_weights = np.zeros_like(target)
+    trade_buys = np.zeros_like(target)
+    trade_sells = np.zeros_like(target)
+
+    cost_rows: list[dict[str, float]] = []
+
+    pv_gross = initial_capital
+    pv_net = initial_capital
+    prev_w = np.zeros(len(symbols), dtype=float)
+
+    for i in range(n_dates):
+        r = rets[i] if i > 0 else np.zeros(len(symbols))
+        day_ret = float(prev_w @ r)
+        pv_gross *= 1.0 + day_ret
+        pv_net *= 1.0 + day_ret
+
+        new_w = target[i]
+        delta = new_w - prev_w
+        buy_per = np.clip(delta, 0.0, None) * pv_net
+        sell_per = np.clip(-delta, 0.0, None) * pv_net
+
+        cost_bd = compute_costs(buy_per, sell_per, cfg)
+        slip_cost = slip.slippage_cost(dates[i].date(), symbols, buy_per, sell_per)
+        total_cost = cost_bd.total + slip_cost
+        pv_net -= total_cost
+
+        gross_equity[i] = pv_gross
+        net_equity[i] = pv_net
+        realised_weights[i] = new_w
+        trade_buys[i] = buy_per
+        trade_sells[i] = sell_per
+
+        cost_rows.append(
+            {
+                "brokerage": cost_bd.brokerage,
+                "stt": cost_bd.stt,
+                "exchange": cost_bd.exchange,
+                "sebi": cost_bd.sebi,
+                "gst": cost_bd.gst,
+                "stamp_duty": cost_bd.stamp_duty,
+                "slippage": slip_cost,
+                "total": total_cost,
+            }
+        )
+
+        prev_w = new_w
+
+    costs_df = pd.DataFrame(cost_rows, index=dates)
+    weights_df = pd.DataFrame(realised_weights, index=dates, columns=symbols)
+    trades_df = pd.DataFrame(trade_buys - trade_sells, index=dates, columns=symbols)
+
+    return BacktestResult(
+        gross_equity=pd.Series(gross_equity, index=dates, name="gross_equity"),
+        net_equity=pd.Series(net_equity, index=dates, name="net_equity"),
+        weights=weights_df,
+        costs=costs_df,
+        trades=trades_df,
+        initial_capital=float(initial_capital),
+        cost_label=cost_label,
+    )
+
+
+__all__ = ["backtest"]