pwb-toolbox 0.1.7__py3-none-any.whl → 0.1.9__py3-none-any.whl

pwb_toolbox/backtest/__init__.py

@@ -1,51 +1,3 @@
 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,
-)
+from .engine import run_strategy
+from .ib_connector import IBConnector, run_ib_strategy

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