pwb-toolbox 0.1.6__tar.gz → 0.1.7__tar.gz

{pwb_toolbox-0.1.6 → pwb_toolbox-0.1.7}/PKG-INFO

@@ -1,15 +1,17 @@
 Metadata-Version: 2.4
 Name: pwb-toolbox
-Version: 0.1.6
+Version: 0.1.7
 Summary: A toolbox library for quant traders
 Home-page: https://github.com/paperswithbacktest/pwb-toolbox
 Author: Your Name
 Author-email: hello@paperswithbacktest.com
 License: MIT
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: datasets
@@ -31,6 +33,7 @@ To install the pwb-toolbox package:
 ```bash
 pip install pwb-toolbox
 ```
+This package requires Python 3.10 or higher.
 
 To login to Huggingface Hub with Access Token
 
@@ -116,6 +119,19 @@ df = pwb_ds.load_dataset(
 )
 ```
 
+## Backtest engine
+
+The `pwb_toolbox.backtest` module offers simple building blocks for running
+Backtrader simulations. Alpha models generate `Insight` objects which are turned
+into portfolio weights and executed via Backtrader orders.
+
+```python
+from pwb_toolbox.backtest.examples import GoldenCrossAlpha, EqualWeightPortfolio
+from pwb_toolbox.backtest import run_backtest
+
+run_backtest(["SPY", "QQQ"], GoldenCrossAlpha(), EqualWeightPortfolio(), start="2015-01-01")
+```
+
 ## Contributing
 
 Contributions to the `pwb-toolbox` package are welcome! If you have any improvements, new datasets, or strategy ideas to share, please follow these guidelines:
@@ -150,5 +166,4 @@ The `pwb-toolbox` package is released under the MIT license. See the LICENSE fil
 ## Contact
 
 For any questions, issues, or suggestions regarding the `pwb-toolbox` package, please contact the maintainers or create an issue on the repository. We appreciate your feedback and involvement in improving the package.
-
 Happy trading!

{pwb_toolbox-0.1.6 → pwb_toolbox-0.1.7}/README.md

@@ -13,6 +13,7 @@ To install the pwb-toolbox package:
 ```bash
 pip install pwb-toolbox
 ```
+This package requires Python 3.10 or higher.
 
 To login to Huggingface Hub with Access Token
 
@@ -98,6 +99,19 @@ df = pwb_ds.load_dataset(
 )
 ```
 
+## Backtest engine
+
+The `pwb_toolbox.backtest` module offers simple building blocks for running
+Backtrader simulations. Alpha models generate `Insight` objects which are turned
+into portfolio weights and executed via Backtrader orders.
+
+```python
+from pwb_toolbox.backtest.examples import GoldenCrossAlpha, EqualWeightPortfolio
+from pwb_toolbox.backtest import run_backtest
+
+run_backtest(["SPY", "QQQ"], GoldenCrossAlpha(), EqualWeightPortfolio(), start="2015-01-01")
+```
+
 ## Contributing
 
 Contributions to the `pwb-toolbox` package are welcome! If you have any improvements, new datasets, or strategy ideas to share, please follow these guidelines:
@@ -132,5 +146,4 @@ The `pwb-toolbox` package is released under the MIT license. See the LICENSE fil
 ## Contact
 
 For any questions, issues, or suggestions regarding the `pwb-toolbox` package, please contact the maintainers or create an issue on the repository. We appreciate your feedback and involvement in improving the package.
-
-Happy trading!
+Happy trading!

pwb_toolbox-0.1.7/pwb_toolbox/backtest/__init__.py

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

pwb_toolbox-0.1.7/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-0.1.7/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-0.1.7/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-0.1.7/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