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

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

@@ -1,19 +1,23 @@
 Metadata-Version: 2.4
 Name: pwb-toolbox
-Version: 0.1.6
+Version: 0.1.8
 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
 Requires-Dist: pandas
+Requires-Dist: ibapi
+Requires-Dist: ib_insync
 Dynamic: license-file
 
 <div align="center">
@@ -31,6 +35,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 +121,77 @@ 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
+from pwb_toolbox.backtest.execution_models import ImmediateExecutionModel
+from pwb_toolbox.backtest.risk_models import MaximumTotalPortfolioExposure
+from pwb_toolbox.backtest.universe_models import ManualUniverseSelectionModel
+
+run_backtest(
+    ManualUniverseSelectionModel(["SPY", "QQQ"]),
+    GoldenCrossAlpha(),
+    EqualWeightPortfolio(),
+    execution=ImmediateExecutionModel(),
+    risk=MaximumTotalPortfolioExposure(max_exposure=1.0),
+    start="2015-01-01",
+)
+```
+
+## Performance Analysis
+
+After running a backtest you can analyze the returned equity series using the
+`pwb_toolbox.performance` module.
+
+```python
+from pwb_toolbox.backtest.examples import GoldenCrossAlpha, EqualWeightPortfolio
+from pwb_toolbox.backtest import run_backtest
+from pwb_toolbox.backtest.execution_models import ImmediateExecutionModel
+from pwb_toolbox.performance import total_return, cagr
+from pwb_toolbox.performance.plots import plot_equity_curve
+
+result, equity = run_backtest(
+    ManualUniverseSelectionModel(["SPY", "QQQ"]),
+    GoldenCrossAlpha(),
+    EqualWeightPortfolio(),
+    execution=ImmediateExecutionModel(),
+    start="2015-01-01",
+)
+
+print("Total return:", total_return(equity))
+print("CAGR:", cagr(equity))
+
+plot_equity_curve(equity)
+```
+
+Plotting utilities require `matplotlib`; some metrics also need `pandas`.
+
+## Live trading with Interactive Brokers
+
+`run_ib_strategy` streams Interactive Brokers data and orders. Install `ibapi` and either `atreyu-backtrader-api` or `ib_insync`.
+
+```python
+from pwb_toolbox.backtest import IBConnector, run_ib_strategy
+from pwb_toolbox.backtest.example.engine import SimpleIBStrategy
+
+data_cfg = [{"dataname": "AAPL", "name": "AAPL"}]
+run_ib_strategy(
+    SimpleIBStrategy,
+    data_cfg,
+    host="127.0.0.1",
+    port=7497,
+    client_id=1,
+)
+```
+
+Configure `host`, `port`, and `client_id` to match your TWS or Gateway settings. Test with an Interactive Brokers paper account before trading live.
+
 ## 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 +226,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.8}/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,77 @@ 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
+from pwb_toolbox.backtest.execution_models import ImmediateExecutionModel
+from pwb_toolbox.backtest.risk_models import MaximumTotalPortfolioExposure
+from pwb_toolbox.backtest.universe_models import ManualUniverseSelectionModel
+
+run_backtest(
+    ManualUniverseSelectionModel(["SPY", "QQQ"]),
+    GoldenCrossAlpha(),
+    EqualWeightPortfolio(),
+    execution=ImmediateExecutionModel(),
+    risk=MaximumTotalPortfolioExposure(max_exposure=1.0),
+    start="2015-01-01",
+)
+```
+
+## Performance Analysis
+
+After running a backtest you can analyze the returned equity series using the
+`pwb_toolbox.performance` module.
+
+```python
+from pwb_toolbox.backtest.examples import GoldenCrossAlpha, EqualWeightPortfolio
+from pwb_toolbox.backtest import run_backtest
+from pwb_toolbox.backtest.execution_models import ImmediateExecutionModel
+from pwb_toolbox.performance import total_return, cagr
+from pwb_toolbox.performance.plots import plot_equity_curve
+
+result, equity = run_backtest(
+    ManualUniverseSelectionModel(["SPY", "QQQ"]),
+    GoldenCrossAlpha(),
+    EqualWeightPortfolio(),
+    execution=ImmediateExecutionModel(),
+    start="2015-01-01",
+)
+
+print("Total return:", total_return(equity))
+print("CAGR:", cagr(equity))
+
+plot_equity_curve(equity)
+```
+
+Plotting utilities require `matplotlib`; some metrics also need `pandas`.
+
+## Live trading with Interactive Brokers
+
+`run_ib_strategy` streams Interactive Brokers data and orders. Install `ibapi` and either `atreyu-backtrader-api` or `ib_insync`.
+
+```python
+from pwb_toolbox.backtest import IBConnector, run_ib_strategy
+from pwb_toolbox.backtest.example.engine import SimpleIBStrategy
+
+data_cfg = [{"dataname": "AAPL", "name": "AAPL"}]
+run_ib_strategy(
+    SimpleIBStrategy,
+    data_cfg,
+    host="127.0.0.1",
+    port=7497,
+    client_id=1,
+)
+```
+
+Configure `host`, `port`, and `client_id` to match your TWS or Gateway settings. Test with an Interactive Brokers paper account before trading live.
+
 ## 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 +204,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.8/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-0.1.8/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.8/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.8/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-0.1.8/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