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

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

pwb_toolbox/backtest/risk_models/__init__.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from typing import Dict, Iterable
+
+
+class RiskManagementModel:
+    """Base class for risk management models."""
+
+    def evaluate(self, weights: Dict[str, float], prices: Dict[str, float]) -> Dict[str, float]:
+        """Return adjusted target weights based on risk rules."""
+        raise NotImplementedError
+
+
+class TrailingStopRiskManagementModel(RiskManagementModel):
+    """Close positions if price falls a percentage from the peak."""
+
+    def __init__(self, percent: float = 0.1):
+        self.percent = percent
+        self._highs: Dict[str, float] = {}
+
+    def evaluate(self, weights: Dict[str, float], prices: Dict[str, float]) -> Dict[str, float]:
+        out = dict(weights)
+        for symbol, weight in weights.items():
+            price = prices.get(symbol)
+            if price is None:
+                continue
+            high = self._highs.get(symbol, price)
+            if price > high:
+                high = price
+            self._highs[symbol] = high
+            if weight != 0 and price <= high * (1 - self.percent):
+                out[symbol] = 0.0
+        return out
+
+
+class MaximumDrawdownPercentPerSecurity(TrailingStopRiskManagementModel):
+    """Alias of trailing stop for per-security drawdown."""
+
+    def __init__(self, max_drawdown: float = 0.1):
+        super().__init__(percent=max_drawdown)
+
+
+class MaximumDrawdownPercentPortfolio(RiskManagementModel):
+    """Flatten portfolio if total drawdown exceeds a threshold."""
+
+    def __init__(self, max_drawdown: float = 0.2):
+        self.max_drawdown = max_drawdown
+        self._high: float | None = None
+
+    def evaluate(self, weights: Dict[str, float], prices: Dict[str, float]) -> Dict[str, float]:
+        nav = sum(weights.get(s, 0.0) * prices.get(s, 0.0) for s in weights)
+        if self._high is None:
+            self._high = nav
+        if nav > self._high:
+            self._high = nav
+        if self._high and nav <= self._high * (1 - self.max_drawdown):
+            return {s: 0.0 for s in weights}
+        return weights
+
+
+class MaximumUnrealizedProfitPercentPerSecurity(RiskManagementModel):
+    """Take profit once unrealized gain exceeds threshold."""
+
+    def __init__(self, max_profit: float = 0.2):
+        self.max_profit = max_profit
+        self._entry: Dict[str, float] = {}
+
+    def evaluate(self, weights: Dict[str, float], prices: Dict[str, float]) -> Dict[str, float]:
+        out = dict(weights)
+        for symbol, weight in weights.items():
+            price = prices.get(symbol)
+            if price is None:
+                continue
+            if weight == 0:
+                self._entry.pop(symbol, None)
+                continue
+            entry = self._entry.get(symbol)
+            if entry is None:
+                self._entry[symbol] = price
+                continue
+            if weight > 0:
+                profit = (price - entry) / entry
+            else:
+                profit = (entry - price) / entry
+            if profit >= self.max_profit:
+                out[symbol] = 0.0
+                self._entry.pop(symbol, None)
+        return out
+
+
+class MaximumTotalPortfolioExposure(RiskManagementModel):
+    """Scale weights so total gross exposure stays below a limit."""
+
+    def __init__(self, max_exposure: float = 1.0):
+        self.max_exposure = max_exposure
+
+    def evaluate(self, weights: Dict[str, float], prices: Dict[str, float] | None = None) -> Dict[str, float]:
+        gross = sum(abs(w) for w in weights.values())
+        if gross <= self.max_exposure or gross == 0:
+            return weights
+        scale = self.max_exposure / gross
+        return {s: w * scale for s, w in weights.items()}
+
+
+class SectorExposureRiskManagementModel(RiskManagementModel):
+    """Limit exposure by sector."""
+
+    def __init__(self, sector_map: Dict[str, str], limit: float = 0.3):
+        self.sector_map = sector_map
+        self.limit = limit
+
+    def evaluate(self, weights: Dict[str, float], prices: Dict[str, float] | None = None) -> Dict[str, float]:
+        out = dict(weights)
+        exposures: Dict[str, float] = {}
+        for symbol, weight in weights.items():
+            sector = self.sector_map.get(symbol)
+            if sector is None:
+                continue
+            exposures[sector] = exposures.get(sector, 0.0) + abs(weight)
+        for sector, exposure in exposures.items():
+            if exposure > self.limit and exposure != 0:
+                factor = self.limit / exposure
+                for symbol, weight in weights.items():
+                    if self.sector_map.get(symbol) == sector:
+                        out[symbol] = weight * factor
+        return out
+
+
+class MaximumOrderQuantityPercentPerSecurity(RiskManagementModel):
+    """Cap the change in weight for each security per evaluation call."""
+
+    def __init__(self, max_percent: float = 0.1):
+        self.max_percent = max_percent
+        self._prev: Dict[str, float] = {}
+
+    def evaluate(self, weights: Dict[str, float], prices: Dict[str, float] | None = None) -> Dict[str, float]:
+        out = {}
+        for symbol, target in weights.items():
+            prev = self._prev.get(symbol, 0.0)
+            diff = target - prev
+            if diff > self.max_percent:
+                new = prev + self.max_percent
+            elif diff < -self.max_percent:
+                new = prev - self.max_percent
+            else:
+                new = target
+            out[symbol] = new
+            self._prev[symbol] = new
+        return out
+
+
+class CompositeRiskManagementModel(RiskManagementModel):
+    """Combine multiple risk models sequentially."""
+
+    def __init__(self, models: Iterable[RiskManagementModel]):
+        self.models = list(models)
+
+    def evaluate(self, weights: Dict[str, float], prices: Dict[str, float]) -> Dict[str, float]:
+        out = dict(weights)
+        for model in self.models:
+            out = model.evaluate(out, prices)
+        return out
+
+
+__all__ = [
+    "RiskManagementModel",
+    "TrailingStopRiskManagementModel",
+    "MaximumDrawdownPercentPerSecurity",
+    "MaximumDrawdownPercentPortfolio",
+    "MaximumUnrealizedProfitPercentPerSecurity",
+    "MaximumTotalPortfolioExposure",
+    "SectorExposureRiskManagementModel",
+    "MaximumOrderQuantityPercentPerSecurity",
+    "CompositeRiskManagementModel",
+]

pwb_toolbox/backtest/universe_models/__init__.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import date
+from typing import Callable, Dict, Iterable, List, Sequence
+
+import pandas as pd
+
+from ...datasets import load_dataset
+
+
+class UniverseSelectionModel(ABC):
+    """Base class for universe selection models."""
+
+    @abstractmethod
+    def symbols(self, as_of: date | str | None = None) -> List[str]:
+        """Return the active list of symbols."""
+        raise NotImplementedError
+
+
+class ManualUniverseSelectionModel(UniverseSelectionModel):
+    """Universe defined by a static list of tickers."""
+
+    def __init__(self, symbols: Sequence[str]):
+        self._symbols = list(symbols)
+
+    def symbols(self, as_of: date | str | None = None) -> List[str]:
+        return list(self._symbols)
+
+
+class ScheduledUniverseSelectionModel(UniverseSelectionModel):
+    """Switch universe based on a schedule of dates."""
+
+    def __init__(self, schedule: Dict[date | str, Sequence[str]]):
+        self.schedule = {
+            (pd.Timestamp(k).date() if not isinstance(k, date) else k): list(v)
+            for k, v in schedule.items()
+        }
+
+    def symbols(self, as_of: date | str | None = None) -> List[str]:
+        if not self.schedule:
+            return []
+        dt = pd.Timestamp(as_of or date.today()).date()
+        valid = [d for d in self.schedule if d <= dt]
+        if not valid:
+            return []
+        last = max(valid)
+        return self.schedule[last]
+
+
+class CoarseFundamentalUniverseSelectionModel(UniverseSelectionModel):
+    """Universe filtered using coarse fundamental data."""
+
+    def __init__(
+        self,
+        selector: Callable[[pd.DataFrame], Iterable[str]],
+        dataset: str = "Stocks-Quarterly-BalanceSheet",
+    ):
+        self.selector = selector
+        self.dataset = dataset
+
+    def symbols(self, as_of: date | str | None = None) -> List[str]:
+        df = load_dataset(self.dataset)
+        return list(self.selector(df))
+
+
+class FineFundamentalUniverseSelectionModel(UniverseSelectionModel):
+    """Universe filtered using fine fundamental data."""
+
+    def __init__(
+        self,
+        selector: Callable[[pd.DataFrame], Iterable[str]],
+        dataset: str = "Stocks-Quarterly-Earnings",
+    ):
+        self.selector = selector
+        self.dataset = dataset
+
+    def symbols(self, as_of: date | str | None = None) -> List[str]:
+        df = load_dataset(self.dataset)
+        return list(self.selector(df))
+
+
+class ETFConstituentsUniverseSelectionModel(UniverseSelectionModel):
+    """Universe containing constituents of a given ETF."""
+
+    def __init__(self, etf: str):
+        self.etf = etf
+
+    def symbols(self, as_of: date | str | None = None) -> List[str]:
+        df = load_dataset("ETF-Constituents")
+        if "etf" in df.columns:
+            col = "etf"
+        else:
+            col = df.columns[0] if df.columns else "etf"
+        if df.empty:
+            return []
+        return list(df[df[col] == self.etf]["symbol"].unique())
+
+
+class IndexConstituentsUniverseSelectionModel(UniverseSelectionModel):
+    """Universe of constituents for a specified index."""
+
+    def __init__(self, index: str):
+        self.index = index
+
+    def symbols(self, as_of: date | str | None = None) -> List[str]:
+        df = load_dataset("Index-Constituents")
+        if df.empty:
+            return []
+        col = "index" if "index" in df.columns else df.columns[0]
+        return list(df[df[col] == self.index]["symbol"].unique())
+
+
+class OptionUniverseSelectionModel(UniverseSelectionModel):
+    """Universe consisting of options for the given underlyings."""
+
+    def __init__(self, underlying_symbols: Sequence[str]):
+        self.underlyings = list(underlying_symbols)
+
+    def symbols(self, as_of: date | str | None = None) -> List[str]:
+        return list(self.underlyings)
+
+
+class ADRUniverseSelectionModel(UniverseSelectionModel):
+    """Universe of American Depositary Receipts."""
+
+    def __init__(self, dataset: str = "ADR-Listings"):
+        self.dataset = dataset
+
+    def symbols(self, as_of: date | str | None = None) -> List[str]:
+        df = load_dataset(self.dataset)
+        if df.empty:
+            return []
+        return list(df["symbol"].unique())
+
+
+class CryptoUniverseSelectionModel(UniverseSelectionModel):
+    """Universe built from cryptocurrency tickers."""
+
+    def __init__(self, top_n: int | None = None):
+        self.top_n = top_n
+
+    def symbols(self, as_of: date | str | None = None) -> List[str]:
+        df = load_dataset("Cryptocurrencies-Daily-Price")
+        syms = list(dict.fromkeys(df["symbol"]))
+        if self.top_n is not None:
+            syms = syms[: self.top_n]
+        return syms
+
+
+class UniverseSelectionModelChain(UniverseSelectionModel):
+    """Combine multiple universe selection models."""
+
+    def __init__(self, models: Iterable[UniverseSelectionModel]):
+        self.models = list(models)
+
+    def symbols(self, as_of: date | str | None = None) -> List[str]:
+        all_syms: List[str] = []
+        for m in self.models:
+            all_syms.extend(m.symbols(as_of))
+        seen = set()
+        uniq = []
+        for s in all_syms:
+            if s not in seen:
+                seen.add(s)
+                uniq.append(s)
+        return uniq
+
+
+__all__ = [
+    "UniverseSelectionModel",
+    "ManualUniverseSelectionModel",
+    "ScheduledUniverseSelectionModel",
+    "CoarseFundamentalUniverseSelectionModel",
+    "FineFundamentalUniverseSelectionModel",
+    "ETFConstituentsUniverseSelectionModel",
+    "IndexConstituentsUniverseSelectionModel",
+    "OptionUniverseSelectionModel",
+    "ADRUniverseSelectionModel",
+    "CryptoUniverseSelectionModel",
+    "UniverseSelectionModelChain",
+]
+

pwb_toolbox/datasets/__init__.py

@@ -813,65 +813,71 @@ def __extend_etfs(df_etfs):
     symbols = df_etfs.symbol.unique()
     mapping = {k: v for k, v in mapping.items() if k in symbols}
 
-    grouped_path_symbols = defaultdict(list)
-    for value in mapping.values():
-        grouped_path_symbols[value[0]].append(value[1])
-    grouped_path_symbols = dict(grouped_path_symbols)
-    df_others = pd.concat(
-        [
-            load_dataset(path, symbols, to_usd=True)
-            for path, symbols in grouped_path_symbols.items()
-        ]
-    )
+    # Nothing to extend → just return the input
+    if not mapping:
+        return df_etfs.copy()
+
+    # ------------------------------------------------------------------ step 2
+    grouped = defaultdict(list)  # {path: [proxy1, proxy2, ...]}
+    for _, (path, proxy) in mapping.items():
+        grouped[path].append(proxy)
+
+    # Load each dataset only if there's at least one proxy symbol
+    other_frames = []
+    for path, proxies in grouped.items():
+        if proxies:  # skip empty lists
+            other_frames.append(load_dataset(path, proxies, to_usd=True))
 
+    # If no proxy data could be loaded, fall back to raw ETF data
+    if not other_frames:
+        return df_etfs.copy()
+
+    df_others = pd.concat(other_frames, ignore_index=True)
+
+    # ------------------------------------------------------------------ step 3
     frames = []
-    for etf, other in mapping.items():
-        other_symbol = other[1]
-        # Get the ETF & Index data
+    for etf, (__, proxy) in mapping.items():
         etf_data = df_etfs[df_etfs["symbol"] == etf]
-        if etf_data.empty:
-            continue
-        other_data = df_others[df_others["symbol"] == other_symbol]
-        if other_data.empty:
-            continue
-
-        # Find the first overlapping date
-        common_dates = etf_data["date"].isin(other_data["date"])
-        first_common_date = etf_data.loc[common_dates, "date"].min()
+        proxy_data = df_others[df_others["symbol"] == proxy]
 
-        if pd.isnull(first_common_date):
-            print(f"No common date found for {etf} and {other_symbol}")
+        if etf_data.empty or proxy_data.empty:
+            frames.append(etf_data)  # keep raw ETF if proxy missing
             continue
 
-        etf_first_common = etf_data[etf_data["date"] == first_common_date]
-        other_first_common = other_data[other_data["date"] == first_common_date]
+        # Find first overlapping date
+        first_common = etf_data.loc[
+            etf_data["date"].isin(proxy_data["date"]), "date"
+        ].min()
+        if pd.isna(first_common):
+            frames.append(etf_data)  # no overlap → keep raw ETF
+            continue
 
-        # Compute the adjustment factor (using closing prices for simplicity)
-        adjustment_factor = (
-            etf_first_common["close"].values[0] / other_first_common["close"].values[0]
+        # Compute adjustment factor on that date
+        k = (
+            etf_data.loc[etf_data["date"] == first_common, "close"].iloc[0]
+            / proxy_data.loc[proxy_data["date"] == first_common, "close"].iloc[0]
         )
 
-        # Adjust index data before the first common date
-        index_data_before_common = other_data[
-            other_data["date"] < first_common_date
-        ].copy()
-        for column in ["open", "high", "low", "close"]:
-            index_data_before_common.loc[:, column] *= adjustment_factor
-        index_data_before_common.loc[:, "symbol"] = etf
+        # Scale proxy history before the overlap
+        hist = proxy_data[proxy_data["date"] < first_common].copy()
+        hist[["open", "high", "low", "close"]] *= k
+        hist["symbol"] = etf
 
-        # Combine adjusted index data with ETF data
-        combined_data = pd.concat([index_data_before_common, etf_data])
-        frames.append(combined_data)
+        # Combine proxy history + actual ETF data
+        frames.append(pd.concat([hist, etf_data]))
 
-    symbols_not_in_mapping = set(symbols) - set(mapping.keys())
-    frames.append(df_etfs[df_etfs["symbol"].isin(symbols_not_in_mapping)])
+    # Add ETFs that were never in the mapping
+    untouched = set(symbols) - set(mapping)
+    frames.append(df_etfs[df_etfs["symbol"].isin(untouched)])
 
-    # Concatenate all frames to form the final dataframe
-    df = pd.concat(frames).sort_values(by=["date", "symbol"]).reset_index(drop=True)
-    return df
+    return (
+        pd.concat(frames, ignore_index=True)
+        .sort_values(["date", "symbol"])
+        .reset_index(drop=True)
+    )
 
 
-ALLOWED_FIELDS = {"open", "high", "low", "close"}
+ALLOWED_FIELDS = {"open", "high", "low", "close", "volume"}
 
 
 def get_pricing(
@@ -925,6 +931,7 @@ def get_pricing(
         ("Cryptocurrencies-Daily-Price", extend),
         ("Bonds-Daily-Price", extend),
         ("Commodities-Daily-Price", extend),
+        ("Forex-Daily-Price", extend),
         ("Indices-Daily-Price", False),  # indices generally have no proxy data
     ]
     remaining = set(symbol_list)  # symbols still to fetch

{pwb_toolbox-0.1.5.dist-info → pwb_toolbox-0.1.7.dist-info}/METADATA

@@ -1,15 +1,17 @@
 Metadata-Version: 2.4
 Name: pwb-toolbox
-Version: 0.1.5
+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.7.dist-info/RECORD

@@ -0,0 +1,14 @@
+pwb_toolbox/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pwb_toolbox/backtest/__init__.py,sha256=PnyGN0ZF2Apc1yPxQPHEAE7OtEvMza63zZqJPJTyIAg,1868
+pwb_toolbox/backtest/base_strategy.py,sha256=PQTO9vytnxeDplmaDUC8ORYwo9dTUbwhNrrmHlpDAAU,994
+pwb_toolbox/backtest/insight.py,sha256=NPrNr7ToNUpqHvgOjgtsP1g8p1Pn8yXuD6YSO-zYePg,394
+pwb_toolbox/backtest/execution_models/__init__.py,sha256=kMa-C7DPeCwB81pyOp3gjIUSYpI3EuCn1uO9vLTJK4Q,5996
+pwb_toolbox/backtest/portfolio_models/__init__.py,sha256=VDDDOUhu4kPxYJsOb9dH-qHTfM-Hj8O7hmzLXGuSxs8,9353
+pwb_toolbox/backtest/risk_models/__init__.py,sha256=Sbd4CeGGhxRFQfdsiMoL7ws-1NJq6IkhxQhXAnGacpY,6319
+pwb_toolbox/backtest/universe_models/__init__.py,sha256=-NXd_dhPKHgfBpynWjKJ4YxHLvagNhNPfU_JUreK7fc,5715
+pwb_toolbox/datasets/__init__.py,sha256=3TnI0mcjJywvkKbUdQ-dahD0Py7fjna7lG9cv07vGMg,22259
+pwb_toolbox-0.1.7.dist-info/licenses/LICENSE.txt,sha256=_Wjz7o7St3iVSPBRzE0keS8XSqSJ03A3NZ6cMlTaSK8,1079
+pwb_toolbox-0.1.7.dist-info/METADATA,sha256=wgpnREqh2IhIP7TOmAfkzznrXj-TNs-tzyPV-i1Xwoo,5237
+pwb_toolbox-0.1.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pwb_toolbox-0.1.7.dist-info/top_level.txt,sha256=TZcXcF2AMkKkibZOuq6AYsHjajPgddHAGjQUT64OYGY,12
+pwb_toolbox-0.1.7.dist-info/RECORD,,

pwb_toolbox-0.1.5.dist-info/RECORD

@@ -1,7 +0,0 @@
-pwb_toolbox/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pwb_toolbox/datasets/__init__.py,sha256=quP-eG9-ExUUwYFxvSwoFWmhzXH_2bfZLwTfdTHdds8,22155
-pwb_toolbox-0.1.5.dist-info/licenses/LICENSE.txt,sha256=_Wjz7o7St3iVSPBRzE0keS8XSqSJ03A3NZ6cMlTaSK8,1079
-pwb_toolbox-0.1.5.dist-info/METADATA,sha256=aoumC8jamm2AG8LDdqrCN13xuvS-UoDbzIMPLl0Uv9Q,4617
-pwb_toolbox-0.1.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pwb_toolbox-0.1.5.dist-info/top_level.txt,sha256=TZcXcF2AMkKkibZOuq6AYsHjajPgddHAGjQUT64OYGY,12
-pwb_toolbox-0.1.5.dist-info/RECORD,,