pwb-toolbox 0.1.6__py3-none-any.whl → 0.1.8__py3-none-any.whl

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

@@ -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:
@@ -877,7 +880,7 @@ def __extend_etfs(df_etfs):
     )
 
 
-ALLOWED_FIELDS = {"open", "high", "low", "close"}
+ALLOWED_FIELDS = {"open", "high", "low", "close", "volume"}
 
 
 def get_pricing(

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