pwb-toolbox 0.1.6__py3-none-any.whl → 0.1.8__py3-none-any.whl

pwb_toolbox/backtest/__init__.py

@@ -0,0 +1,57 @@
+from .base_strategy import BaseStrategy
+
+from .insight import Direction, Insight
+
+from .portfolio_models import (
+    PortfolioConstructionModel,
+    EqualWeightingPortfolioConstructionModel,
+    InsightWeightingPortfolioConstructionModel,
+    MeanVarianceOptimizationPortfolioConstructionModel,
+    BlackLittermanOptimizationPortfolioConstructionModel,
+    RiskParityPortfolioConstructionModel,
+    UnconstrainedMeanVariancePortfolioConstructionModel,
+    TargetPercentagePortfolioConstructionModel,
+    DollarCostAveragingPortfolioConstructionModel,
+    InsightRatioPortfolioConstructionModel,
+)
+from .ib_connector import IBConnector, run_ib_strategy
+from .example.engine import run_backtest, run_ib_backtest
+
+__all__ = [
+    "Direction",
+    "Insight",
+    "PortfolioConstructionModel",
+    "EqualWeightingPortfolioConstructionModel",
+    "InsightWeightingPortfolioConstructionModel",
+    "MeanVarianceOptimizationPortfolioConstructionModel",
+    "BlackLittermanOptimizationPortfolioConstructionModel",
+    "RiskParityPortfolioConstructionModel",
+    "UnconstrainedMeanVariancePortfolioConstructionModel",
+    "TargetPercentagePortfolioConstructionModel",
+    "DollarCostAveragingPortfolioConstructionModel",
+    "InsightRatioPortfolioConstructionModel",
+    "RiskManagementModel",
+    "TrailingStopRiskManagementModel",
+    "MaximumDrawdownPercentPerSecurity",
+    "MaximumDrawdownPercentPortfolio",
+    "MaximumUnrealizedProfitPercentPerSecurity",
+    "MaximumTotalPortfolioExposure",
+    "SectorExposureRiskManagementModel",
+    "MaximumOrderQuantityPercentPerSecurity",
+    "CompositeRiskManagementModel",
+    "IBConnector",
+    "run_ib_strategy",
+    "run_backtest",
+    "run_ib_backtest",
+]
+from .risk_models import (
+    RiskManagementModel,
+    TrailingStopRiskManagementModel,
+    MaximumDrawdownPercentPerSecurity,
+    MaximumDrawdownPercentPortfolio,
+    MaximumUnrealizedProfitPercentPerSecurity,
+    MaximumTotalPortfolioExposure,
+    SectorExposureRiskManagementModel,
+    MaximumOrderQuantityPercentPerSecurity,
+    CompositeRiskManagementModel,
+)

pwb_toolbox/backtest/base_strategy.py

@@ -0,0 +1,33 @@
+import backtrader as bt
+from tqdm import tqdm
+
+
+class BaseStrategy(bt.Strategy):
+    """Base strategy providing progress logging utilities."""
+
+    params = (("total_days", 0),)
+
+    def __init__(self):
+        super().__init__()
+        self.pbar = tqdm(total=self.params.total_days)
+        self.log_data = []
+
+    def is_tradable(self, data):
+        """Return True if the instrument's price is not constant."""
+        if len(data.close) < 3:
+            return False
+        return data.close[0] != data.close[-2]
+
+    def __next__(self):
+        """Update progress bar and log current value."""
+        self.pbar.update(1)
+        self.log_data.append(
+            {
+                "date": self.datas[0].datetime.date(0).isoformat(),
+                "value": self.broker.getvalue(),
+            }
+        )
+
+    def get_latest_positions(self):
+        """Get a dictionary of the latest positions."""
+        return {data._name: self.broker.getposition(data).size for data in self.datas}

pwb_toolbox/backtest/execution_models/__init__.py

@@ -0,0 +1,153 @@
+"""Execution models for order placement using Backtrader."""
+
+from __future__ import annotations
+
+from typing import Dict
+import backtrader as bt
+
+
+class ExecutionModel:
+    """Base execution model class."""
+
+    def execute(self, strategy: bt.Strategy, weights: Dict[str, float]):
+        """Place orders on the given strategy."""
+        raise NotImplementedError
+
+
+class ImmediateExecutionModel(ExecutionModel):
+    """Immediately send market orders using ``order_target_percent``."""
+
+    def execute(self, strategy: bt.Strategy, weights: Dict[str, float]):
+        for data in strategy.datas:
+            target = weights.get(data._name, 0.0)
+            strategy.order_target_percent(data=data, target=target)
+
+
+class StandardDeviationExecutionModel(ExecutionModel):
+    """Only trade when recent volatility exceeds a threshold."""
+
+    def __init__(self, lookback: int = 20, threshold: float = 0.01):
+        self.lookback = lookback
+        self.threshold = threshold
+
+    def execute(self, strategy: bt.Strategy, weights: Dict[str, float]):
+        prices = strategy.prices
+        for data in strategy.datas:
+            symbol = data._name
+            series = prices[symbol]["close"] if (symbol, "close") in prices.columns else prices[symbol]
+            if len(series) < self.lookback:
+                continue
+            vol = series.pct_change().rolling(self.lookback).std().iloc[-1]
+            if vol is not None and vol > self.threshold:
+                target = weights.get(symbol, 0.0)
+                strategy.order_target_percent(data=data, target=target)
+
+
+class VolumeWeightedAveragePriceExecutionModel(ExecutionModel):
+    """Split orders evenly over a number of steps to approximate VWAP."""
+
+    def __init__(self, steps: int = 3):
+        self.steps = steps
+        self._progress: Dict[str, int] = {}
+
+    def execute(self, strategy: bt.Strategy, weights: Dict[str, float]):
+        for data in strategy.datas:
+            symbol = data._name
+            step = self._progress.get(symbol, 0)
+            if step >= self.steps:
+                continue
+            target = weights.get(symbol, 0.0) * (step + 1) / self.steps
+            strategy.order_target_percent(data=data, target=target)
+            self._progress[symbol] = step + 1
+
+
+class VolumePercentageExecutionModel(ExecutionModel):
+    """Execute only a percentage of the target each call."""
+
+    def __init__(self, percentage: float = 0.25):
+        self.percentage = percentage
+        self._filled: Dict[str, float] = {}
+
+    def execute(self, strategy: bt.Strategy, weights: Dict[str, float]):
+        for data in strategy.datas:
+            symbol = data._name
+            current = self._filled.get(symbol, 0.0)
+            target = weights.get(symbol, 0.0)
+            remaining = target - current
+            if abs(remaining) < 1e-6:
+                continue
+            step_target = current + remaining * self.percentage
+            self._filled[symbol] = step_target
+            strategy.order_target_percent(data=data, target=step_target)
+
+
+class TimeProfileExecutionModel(ExecutionModel):
+    """Execute orders based on a predefined time profile (e.g. TWAP)."""
+
+    def __init__(self, profile: Dict[int, float] | None = None):
+        self.profile = profile or {0: 1.0}
+        self._called = 0
+
+    def execute(self, strategy: bt.Strategy, weights: Dict[str, float]):
+        factor = self.profile.get(self._called, 0.0)
+        for data in strategy.datas:
+            target = weights.get(data._name, 0.0) * factor
+            strategy.order_target_percent(data=data, target=target)
+        self._called += 1
+
+
+class TrailingLimitExecutionModel(ExecutionModel):
+    """Use trailing limit orders for execution."""
+
+    def __init__(self, trail: float = 0.01):
+        self.trail = trail
+
+    def execute(self, strategy: bt.Strategy, weights: Dict[str, float]):
+        prices = strategy.prices
+        for data in strategy.datas:
+            symbol = data._name
+            price = prices[symbol]["close"].iloc[-1] if (symbol, "close") in prices.columns else prices[symbol].iloc[-1]
+            target = weights.get(symbol, 0.0)
+            if target > 0:
+                strategy.buy(data=data, exectype=bt.Order.Limit, price=price * (1 - self.trail))
+            elif target < 0:
+                strategy.sell(data=data, exectype=bt.Order.Limit, price=price * (1 + self.trail))
+
+
+class AdaptiveExecutionModel(ExecutionModel):
+    """Switch between immediate and VWAP execution based on volatility."""
+
+    def __init__(self, threshold: float = 0.02, steps: int = 3):
+        self.threshold = threshold
+        self.vwap = VolumeWeightedAveragePriceExecutionModel(steps=steps)
+        self.immediate = ImmediateExecutionModel()
+
+    def execute(self, strategy: bt.Strategy, weights: Dict[str, float]):
+        prices = strategy.prices
+        for data in strategy.datas:
+            symbol = data._name
+            series = prices[symbol]["close"] if (symbol, "close") in prices.columns else prices[symbol]
+            if len(series) < 2:
+                continue
+            vol = series.pct_change().iloc[-1]
+            if abs(vol) > self.threshold:
+                self.immediate.execute(strategy, {symbol: weights.get(symbol, 0.0)})
+            else:
+                self.vwap.execute(strategy, {symbol: weights.get(symbol, 0.0)})
+
+
+class BufferedExecutionModel(ExecutionModel):
+    """Only execute when target differs sufficiently from last order."""
+
+    def __init__(self, buffer: float = 0.05):
+        self.buffer = buffer
+        self._last: Dict[str, float] = {}
+
+    def execute(self, strategy: bt.Strategy, weights: Dict[str, float]):
+        for data in strategy.datas:
+            symbol = data._name
+            target = weights.get(symbol, 0.0)
+            last = self._last.get(symbol)
+            if last is None or abs(target - last) > self.buffer:
+                strategy.order_target_percent(data=data, target=target)
+                self._last[symbol] = target

pwb_toolbox/backtest/ib_connector.py

@@ -0,0 +1,69 @@
+"""Lightweight helpers for running Interactive Brokers backtests."""
+
+from __future__ import annotations
+
+from typing import Iterable, Mapping, Type
+
+import backtrader as bt
+
+
+class IBConnector:
+    """Utility for creating Backtrader IB stores and data feeds."""
+
+    def __init__(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 7497,
+        client_id: int = 1,
+        store_class: Type[bt.stores.IBStore] | None = None,
+        feed_class: Type[bt.feeds.IBData] | None = None,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.client_id = client_id
+        self.store_class = store_class or bt.stores.IBStore
+        self.feed_class = feed_class or bt.feeds.IBData
+
+    def get_store(self) -> bt.stores.IBStore:
+        """Instantiate and return an ``IBStore``."""
+        return self.store_class(host=self.host, port=self.port, clientId=self.client_id)
+
+    def create_feed(self, **kwargs) -> bt.feeds.IBData:
+        """Create an ``IBData`` feed bound to the connector's store."""
+        store = kwargs.pop("store", None) or self.get_store()
+        return self.feed_class(store=store, **kwargs)
+
+
+def run_ib_strategy(
+    strategy: type[bt.Strategy],
+    data_config: Iterable[Mapping[str, object]],
+    **ib_kwargs,
+):
+    """Run ``strategy`` with Interactive Brokers data feeds.
+
+    Parameters
+    ----------
+    strategy:
+        The ``bt.Strategy`` subclass to execute.
+    data_config:
+        Iterable of dictionaries passed to ``IBData`` for each feed.
+    ib_kwargs:
+        Arguments forwarded to :class:`IBConnector`.
+    Examples
+    --------
+    >>> data_cfg = [{"dataname": "AAPL", "name": "AAPL", "what": "MIDPOINT"}]
+    >>> run_ib_strategy(MyStrategy, data_cfg, host="127.0.0.1")
+
+    """
+    connector = IBConnector(**ib_kwargs)
+    cerebro = bt.Cerebro()
+    store = connector.get_store()
+    cerebro.broker = store.getbroker()
+
+    for cfg in data_config:
+        data = connector.create_feed(store=store, **cfg)
+        name = cfg.get("name")
+        cerebro.adddata(data, name=name)
+
+    cerebro.addstrategy(strategy)
+    return cerebro.run()

pwb_toolbox/backtest/insight.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass
+from enum import Enum, auto
+from datetime import datetime
+
+
+class Direction(Enum):
+    """Possible directions for an Insight."""
+
+    UP = auto()
+    DOWN = auto()
+    FLAT = auto()
+
+
+@dataclass
+class Insight:
+    """Simple trading signal produced by an Alpha model."""
+
+    symbol: str
+    direction: Direction
+    timestamp: datetime
+    weight: float = 1.0

pwb_toolbox/backtest/portfolio_models/__init__.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Dict, Iterable
+import numpy as np
+import pandas as pd
+
+from .. import Insight, Direction
+
+
+class PortfolioConstructionModel(ABC):
+    """Abstract base class for portfolio construction models."""
+
+    @abstractmethod
+    def weights(
+        self,
+        insights: Iterable[Insight],
+        price_data: pd.DataFrame | None = None,
+    ) -> Dict[str, float]:
+        """Return target weights for each symbol."""
+        pass
+
+
+class EqualWeightingPortfolioConstructionModel(PortfolioConstructionModel):
+    """Allocate equal weight to all non-flat insights."""
+
+    def weights(
+        self,
+        insights: Iterable[Insight],
+        price_data: pd.DataFrame | None = None,
+    ) -> Dict[str, float]:
+        active = [i for i in insights if i.direction != Direction.FLAT]
+        if not active:
+            return {}
+        w = 1.0 / len(active)
+        return {i.symbol: (w if i.direction == Direction.UP else -w) for i in active}
+
+
+class InsightWeightingPortfolioConstructionModel(PortfolioConstructionModel):
+    """Weight positions according to insight weight attribute."""
+
+    def weights(
+        self,
+        insights: Iterable[Insight],
+        price_data: pd.DataFrame | None = None,
+    ) -> Dict[str, float]:
+        active = [i for i in insights if i.direction != Direction.FLAT]
+        if not active:
+            return {}
+        total = sum(abs(i.weight) for i in active)
+        if total == 0:
+            return {}
+        return {
+            i.symbol: (i.weight / total) * (1 if i.direction == Direction.UP else -1)
+            for i in active
+        }
+
+
+class RiskParityPortfolioConstructionModel(PortfolioConstructionModel):
+    """Simple risk parity based on inverse volatility."""
+
+    def __init__(self, lookback: int = 20):
+        self.lookback = lookback
+
+    def weights(
+        self,
+        insights: Iterable[Insight],
+        price_data: pd.DataFrame | None = None,
+    ) -> Dict[str, float]:
+        active = [i for i in insights if i.direction != Direction.FLAT]
+        if not active or price_data is None:
+            return {}
+        vols = {}
+        for ins in active:
+            prices = (
+                price_data[ins.symbol]["close"]
+                if (ins.symbol, "close") in price_data.columns
+                else price_data[ins.symbol]
+            )
+            if len(prices) < self.lookback:
+                return {}
+            vols[ins.symbol] = prices.pct_change().rolling(self.lookback).std().iloc[-1]
+        inv_vol = {s: 1.0 / v for s, v in vols.items() if v > 0}
+        total = sum(inv_vol.values())
+        if total == 0:
+            return {}
+        return {
+            s: (inv_vol[s] / total)
+            * (
+                1
+                if next(i for i in active if i.symbol == s).direction == Direction.UP
+                else -1
+            )
+            for s in inv_vol
+        }
+
+
+class MeanVarianceOptimizationPortfolioConstructionModel(PortfolioConstructionModel):
+    """Mean-variance optimization with weight normalization."""
+
+    def __init__(self, lookback: int = 60):
+        self.lookback = lookback
+
+    def weights(
+        self,
+        insights: Iterable[Insight],
+        price_data: pd.DataFrame | None = None,
+    ) -> Dict[str, float]:
+        active = [i for i in insights if i.direction != Direction.FLAT]
+        if not active or price_data is None:
+            return {}
+        symbols = [i.symbol for i in active]
+        df = price_data[symbols]
+        if isinstance(df.columns, pd.MultiIndex):
+            df = df.xs("close", axis=1, level=-1)
+        if len(df) < self.lookback:
+            return {}
+        rets = df.pct_change().dropna()
+        mu = rets.mean()
+        cov = rets.cov()
+        inv_cov = np.linalg.pinv(cov.values)
+        exp = np.array(
+            [
+                mu[s]
+                * (
+                    1
+                    if next(i for i in active if i.symbol == s).direction
+                    == Direction.UP
+                    else -1
+                )
+                for s in mu.index
+            ]
+        )
+        raw = inv_cov.dot(exp)
+        total = np.sum(np.abs(raw))
+        if total == 0:
+            return {}
+        w = raw / total
+        return {s: float(w[i]) for i, s in enumerate(mu.index)}
+
+
+class UnconstrainedMeanVariancePortfolioConstructionModel(PortfolioConstructionModel):
+    """Mean-variance optimization without normalization of weights."""
+
+    def __init__(self, lookback: int = 60):
+        self.lookback = lookback
+
+    def weights(
+        self,
+        insights: Iterable[Insight],
+        price_data: pd.DataFrame | None = None,
+    ) -> Dict[str, float]:
+        active = [i for i in insights if i.direction != Direction.FLAT]
+        if not active or price_data is None:
+            return {}
+        symbols = [i.symbol for i in active]
+        df = price_data[symbols]
+        if isinstance(df.columns, pd.MultiIndex):
+            df = df.xs("close", axis=1, level=-1)
+        if len(df) < self.lookback:
+            return {}
+        rets = df.pct_change().dropna()
+        mu = rets.mean()
+        cov = rets.cov()
+        inv_cov = np.linalg.pinv(cov.values)
+        exp = np.array(
+            [
+                mu[s]
+                * (
+                    1
+                    if next(i for i in active if i.symbol == s).direction
+                    == Direction.UP
+                    else -1
+                )
+                for s in mu.index
+            ]
+        )
+        raw = inv_cov.dot(exp)
+        return {s: float(raw[i]) for i, s in enumerate(mu.index)}
+
+
+class BlackLittermanOptimizationPortfolioConstructionModel(
+    MeanVarianceOptimizationPortfolioConstructionModel
+):
+    """Simplified Black-Litterman model using a blend of market and view returns."""
+
+    def __init__(self, lookback: int = 60, view_weight: float = 0.5):
+        super().__init__(lookback)
+        self.view_weight = view_weight
+
+    def weights(
+        self,
+        insights: Iterable[Insight],
+        price_data: pd.DataFrame | None = None,
+    ) -> Dict[str, float]:
+        active = [i for i in insights if i.direction != Direction.FLAT]
+        if not active or price_data is None:
+            return {}
+        symbols = [i.symbol for i in active]
+        df = price_data[symbols]
+        if isinstance(df.columns, pd.MultiIndex):
+            df = df.xs("close", axis=1, level=-1)
+        if len(df) < self.lookback:
+            return {}
+        rets = df.pct_change().dropna()
+        market_mu = rets.mean()
+        view_mu = pd.Series(
+            {i.symbol: (1 if i.direction == Direction.UP else -1) for i in active}
+        )
+        mu = (1 - self.view_weight) * market_mu + self.view_weight * view_mu
+        cov = rets.cov()
+        inv_cov = np.linalg.pinv(cov.values)
+        exp = mu.loc[market_mu.index].values
+        raw = inv_cov.dot(exp)
+        total = np.sum(np.abs(raw))
+        if total == 0:
+            return {}
+        w = raw / total
+        return {s: float(w[i]) for i, s in enumerate(market_mu.index)}
+
+
+class TargetPercentagePortfolioConstructionModel(PortfolioConstructionModel):
+    """Return predefined target portfolio percentages."""
+
+    def __init__(self, targets: Dict[str, float]):
+        self.targets = targets
+
+    def weights(
+        self,
+        insights: Iterable[Insight],
+        price_data: pd.DataFrame | None = None,
+    ) -> Dict[str, float]:
+        active_symbols = {
+            i.symbol: i for i in insights if i.direction != Direction.FLAT
+        }
+        return {
+            s: (
+                self.targets.get(s, 0.0)
+                * (1 if active_symbols[s].direction == Direction.UP else -1)
+            )
+            for s in active_symbols
+            if s in self.targets
+        }
+
+
+class DollarCostAveragingPortfolioConstructionModel(PortfolioConstructionModel):
+    """Allocate a fixed percentage to each new insight."""
+
+    def __init__(self, allocation: float = 0.1):
+        self.allocation = allocation
+
+    def weights(
+        self,
+        insights: Iterable[Insight],
+        price_data: pd.DataFrame | None = None,
+    ) -> Dict[str, float]:
+        active = [i for i in insights if i.direction != Direction.FLAT]
+        if not active:
+            return {}
+        return {
+            i.symbol: self.allocation * (1 if i.direction == Direction.UP else -1)
+            for i in active
+        }
+
+
+class InsightRatioPortfolioConstructionModel(PortfolioConstructionModel):
+    """Scale long and short exposure by the ratio of insights."""
+
+    def weights(
+        self,
+        insights: Iterable[Insight],
+        price_data: pd.DataFrame | None = None,
+    ) -> Dict[str, float]:
+        ups = [i for i in insights if i.direction == Direction.UP]
+        downs = [i for i in insights if i.direction == Direction.DOWN]
+        total = len(ups) + len(downs)
+        if total == 0:
+            return {}
+        up_share = len(ups) / total
+        down_share = len(downs) / total
+        weights = {}
+        if ups:
+            per = up_share / len(ups)
+            for i in ups:
+                weights[i.symbol] = per
+        if downs:
+            per = down_share / len(downs)
+            for i in downs:
+                weights[i.symbol] = -per
+        return weights