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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pwb-toolbox
-Version: 0.1.7
+Version: 0.1.9
 Summary: A toolbox library for quant traders
 Home-page: https://github.com/paperswithbacktest/pwb-toolbox
 Author: Your Name
@@ -16,6 +16,8 @@ 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">
@@ -128,10 +130,68 @@ 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",
+)
 
-run_backtest(["SPY", "QQQ"], GoldenCrossAlpha(), EqualWeightPortfolio(), 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:

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

@@ -108,10 +108,68 @@ 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",
+)
 
-run_backtest(["SPY", "QQQ"], GoldenCrossAlpha(), EqualWeightPortfolio(), 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:

pwb_toolbox-0.1.9/pwb_toolbox/backtest/__init__.py

@@ -0,0 +1,3 @@
+from .base_strategy import BaseStrategy
+from .engine import run_strategy
+from .ib_connector import IBConnector, run_ib_strategy

{pwb_toolbox-0.1.7 → pwb_toolbox-0.1.9}/pwb_toolbox/backtest/base_strategy.py

@@ -18,7 +18,7 @@ class BaseStrategy(bt.Strategy):
             return False
         return data.close[0] != data.close[-2]
 
-    def __next__(self):
+    def next(self):
         """Update progress bar and log current value."""
         self.pbar.update(1)
         self.log_data.append(

pwb_toolbox-0.1.9/pwb_toolbox/backtest/engine.py

@@ -0,0 +1,33 @@
+import backtrader as bt
+import pandas as pd
+import pwb_toolbox.datasets as pwb_ds
+
+
+def run_strategy(signal, signal_kwargs, portfolio, symbols, start_date, leverage, cash):
+    """Run a tactical asset allocation strategy with Backtrader."""
+    # Load the data from https://paperswithbacktest.com/datasets
+    pivot_df = pwb_ds.get_pricing(
+        symbol_list=symbols,
+        fields=["open", "high", "low", "close"],
+        start_date=start_date,
+        extend=True,  # Extend the dataset with proxy data
+    )
+    # Create trading-day index (optional but keeps Cerebro happy)
+    trading_days = pd.bdate_range(pivot_df.index.min(), pivot_df.index.max())
+    pivot_df = pivot_df.reindex(trading_days)
+    pivot_df.ffill(inplace=True)  # forward-fill holidays
+    pivot_df.bfill(inplace=True)  # back-fill leading IPO gaps
+    cerebro = bt.Cerebro()
+    for symbol in symbols:
+        data = bt.feeds.PandasData(dataname=pivot_df[symbol].copy())
+        cerebro.adddata(data, name=symbol)
+    cerebro.addstrategy(
+        portfolio,
+        total_days=len(trading_days),
+        leverage=0.9,
+        signal_cls=signal,
+        signal_kwargs=signal_kwargs,
+    )
+    cerebro.broker.set_cash(cash)
+    strategy = cerebro.run()[0]
+    return strategy

pwb_toolbox-0.1.9/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.7 → pwb_toolbox-0.1.9}/pwb_toolbox/datasets/__init__.py

@@ -6,9 +6,12 @@ import re
 import datasets as ds
 import pandas as pd
 
-HF_ACCESS_TOKEN = os.environ["HF_ACCESS_TOKEN"]
-if not HF_ACCESS_TOKEN:
-    raise ValueError("Hugging Face access token not found in environment variables")
+
+def _get_hf_token() -> str:
+    token = os.getenv("HF_ACCESS_TOKEN")
+    if not token:
+        raise ValueError("HF_ACCESS_TOKEN not set")
+    return token
 
 
 DAILY_PRICE_DATASETS = [
@@ -552,7 +555,7 @@ def load_dataset(
     to_usd=True,
     rate_to_price=True,
 ):
-    dataset = ds.load_dataset(f"paperswithbacktest/{path}", token=HF_ACCESS_TOKEN)
+    dataset = ds.load_dataset(f"paperswithbacktest/{path}", token=_get_hf_token())
     df = dataset["train"].to_pandas()
 
     if path in DAILY_PRICE_DATASETS or path in DAILY_FINANCIAL_DATASETS:

pwb_toolbox-0.1.9/pwb_toolbox/performance/__init__.py

@@ -0,0 +1,123 @@
+from .metrics import (
+    total_return,
+    cagr,
+    returns_table,
+    rolling_cumulative_return,
+    annualized_volatility,
+    max_drawdown,
+    ulcer_index,
+    ulcer_performance_index,
+    parametric_var,
+    parametric_expected_shortfall,
+    tail_ratio,
+    sharpe_ratio,
+    sortino_ratio,
+    calmar_ratio,
+    omega_ratio,
+    information_ratio,
+    capm_alpha_beta,
+    skewness,
+    kurtosis,
+    variance_ratio,
+    acf,
+    pacf,
+    fama_french_3factor,
+    fama_french_5factor,
+    cumulative_excess_return,
+)
+
+from .trade_stats import (
+    hit_rate,
+    average_win_loss,
+    expectancy,
+    profit_factor,
+    trade_duration_distribution,
+    turnover,
+    trade_implementation_shortfall,
+    cumulative_implementation_shortfall,
+    slippage_stats,
+    latency_stats,
+)
+
+__all__ = [
+    "total_return",
+    "cagr",
+    "returns_table",
+    "rolling_cumulative_return",
+    "annualized_volatility",
+    "max_drawdown",
+    "ulcer_index",
+    "ulcer_performance_index",
+    "parametric_var",
+    "parametric_expected_shortfall",
+    "tail_ratio",
+    "sharpe_ratio",
+    "sortino_ratio",
+    "calmar_ratio",
+    "omega_ratio",
+    "information_ratio",
+    "capm_alpha_beta",
+    "skewness",
+    "kurtosis",
+    "variance_ratio",
+    "acf",
+    "pacf",
+    "fama_french_3factor",
+    "fama_french_5factor",
+    "cumulative_excess_return",
+    "hit_rate",
+    "average_win_loss",
+    "expectancy",
+    "profit_factor",
+    "trade_duration_distribution",
+    "turnover",
+    "trade_implementation_shortfall",
+    "cumulative_implementation_shortfall",
+    "slippage_stats",
+    "latency_stats",
+]
+
+try:  # pragma: no cover - optional plotting deps
+    from .plots import (
+        plot_equity_curve,
+        plot_return_heatmap,
+        plot_underwater,
+        plot_rolling_volatility,
+        plot_rolling_var,
+        plot_rolling_sharpe,
+        plot_rolling_sortino,
+        plot_return_scatter,
+        plot_cumulative_excess_return,
+        plot_factor_exposures,
+        plot_trade_return_hist,
+        plot_return_by_holding_period,
+        plot_exposure_ts,
+        plot_cumulative_shortfall,
+        plot_alpha_vs_return,
+        plot_qq_returns,
+        plot_rolling_skewness,
+        plot_rolling_kurtosis,
+    )
+
+    __all__ += [
+        "plot_equity_curve",
+        "plot_return_heatmap",
+        "plot_underwater",
+        "plot_rolling_volatility",
+        "plot_rolling_var",
+        "plot_rolling_sharpe",
+        "plot_rolling_sortino",
+        "plot_return_scatter",
+        "plot_cumulative_excess_return",
+        "plot_factor_exposures",
+        "plot_trade_return_hist",
+        "plot_return_by_holding_period",
+        "plot_exposure_ts",
+        "plot_cumulative_shortfall",
+        "plot_alpha_vs_return",
+        "plot_qq_returns",
+        "plot_rolling_skewness",
+        "plot_rolling_kurtosis",
+    ]
+except Exception:  # pragma: no cover - matplotlib may be missing
+    pass