pyalloq-backtest 0.1.10__tar.gz

pyalloq_backtest-0.1.10/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.3
+Name: pyalloq-backtest
+Version: 0.1.10
+Summary: Zero-lookahead historical simulation engines and metrics for PyAlloq.
+Author: Siddeshkanth
+Author-email: Siddeshkanth <pyalloq-info@alloq-alpha.com>
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyalloq-core
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# pyalloq-backtest
+
+`pyalloq-backtest` provides zero-lookahead historical simulation engines, rolling window splitters, transaction cost modeling, and quantitative performance metrics for **PyAlloq**.
+
+## Key Modules
+
+- **`BacktestEngine`**: Executes walk-forward strategy evaluation with periodic rebalancing, transaction cost deduction, and turnover tracking.
+- **`splitters`**: Provides time-series train/test splitters and expanding/rolling window generators for cross-validation.
+- **`costs`**: Transaction cost functions (linear bps costs, fixed fee per trade, slippage models).
+- **`metrics`**: Comprehensive performance metrics including Sharpe ratio, Sortino ratio, Max Drawdown, CAGR, Annualized Volatility, and Turnover.
+
+## Quick Example
+
+```python
+from pyalloq_backtest.engine import BacktestEngine
+from pyalloq_backtest.costs import linear_cost
+
+# Initialize zero-lookahead backtest engine
+engine = BacktestEngine(
+    rebalance_frequency=21,  # Monthly rebalancing (21 trading days)
+    cost_model=linear_cost(bps=10.0)  # 10 bps transaction cost
+)
+
+# Run historical simulation on MarketData and StrategyPipeline
+# results = engine.run(market_data, strategy_pipeline)
+```

pyalloq_backtest-0.1.10/README.md

@@ -0,0 +1,26 @@
+# pyalloq-backtest
+
+`pyalloq-backtest` provides zero-lookahead historical simulation engines, rolling window splitters, transaction cost modeling, and quantitative performance metrics for **PyAlloq**.
+
+## Key Modules
+
+- **`BacktestEngine`**: Executes walk-forward strategy evaluation with periodic rebalancing, transaction cost deduction, and turnover tracking.
+- **`splitters`**: Provides time-series train/test splitters and expanding/rolling window generators for cross-validation.
+- **`costs`**: Transaction cost functions (linear bps costs, fixed fee per trade, slippage models).
+- **`metrics`**: Comprehensive performance metrics including Sharpe ratio, Sortino ratio, Max Drawdown, CAGR, Annualized Volatility, and Turnover.
+
+## Quick Example
+
+```python
+from pyalloq_backtest.engine import BacktestEngine
+from pyalloq_backtest.costs import linear_cost
+
+# Initialize zero-lookahead backtest engine
+engine = BacktestEngine(
+    rebalance_frequency=21,  # Monthly rebalancing (21 trading days)
+    cost_model=linear_cost(bps=10.0)  # 10 bps transaction cost
+)
+
+# Run historical simulation on MarketData and StrategyPipeline
+# results = engine.run(market_data, strategy_pipeline)
+```

pyalloq_backtest-0.1.10/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "pyalloq-backtest"
+version = "0.1.10"
+description = "Zero-lookahead historical simulation engines and metrics for PyAlloq."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "pyalloq-core",
+]
+
+[[project.authors]]
+name = "Siddeshkanth"
+email = "pyalloq-info@alloq-alpha.com"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

pyalloq_backtest-0.1.10/pyproject.toml.orig

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "pyalloq-backtest"
+version = "0.1.10"
+description = "Zero-lookahead historical simulation engines and metrics for PyAlloq."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Siddeshkanth", email = "pyalloq-info@alloq-alpha.com" }]
+
+dependencies = [
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "pyalloq-core",
+]
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.11"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

pyalloq_backtest-0.1.10/src/pyalloq_backtest/costs.py

@@ -0,0 +1,68 @@
+import pandas as pd
+import torch
+from typing import Union, cast, Any
+from abc import ABC, abstractmethod
+
+CostData = Union[pd.Series, pd.DataFrame, torch.Tensor]
+
+
+class BaseCostModel(ABC):
+    @abstractmethod
+    def calculate_costs(
+        self,
+        weights_delta: CostData,
+        features_slice: dict[str, CostData] | None = None,
+    ) -> CostData:
+        """Returns the cost in percentage terms for each asset."""
+        ...
+
+
+class FlatBpsCostModel(BaseCostModel):
+    "Standard flat fee (Retail / Small AUM)"
+
+    def __init__(self, bps: float = 10.0) -> None:
+        self.cost_pct = bps / 10000.0
+
+    def calculate_costs(
+        self,
+        weights_delta: CostData,
+        features_slice: dict[str, CostData] | None = None,
+    ) -> CostData:
+        return weights_delta.abs() * self.cost_pct
+
+
+class AlmgrenChrissCostModel(BaseCostModel):
+    """"""
+
+    def __init__(
+        self, portfolio_aum: float, spread_bps: float = 2.0, gamma: float = 0.1
+    ) -> None:
+        self.aum = portfolio_aum
+        self.spread = spread_bps / 10000.0
+        self.gamma = gamma
+
+    def calculate_costs(
+        self,
+        weights_delta: CostData,
+        features_slice: dict[str, CostData] | None = None,
+    ) -> CostData:
+        if features_slice is None or "volume" not in features_slice:
+            raise ValueError(
+                "Almgren-Chriss requires 'volume' in data.features['volume']."
+            )
+
+        delta = cast(Any, weights_delta)
+        daily_volume = cast(Any, features_slice["volume"])
+
+        # Non-linear market impact math based on trade size relative to daily volume
+        trade_dollar_size = delta.abs() * self.aum
+
+        # Safe for torch usage
+        safe_volume = daily_volume + 1e-8
+        safe_trade = trade_dollar_size + 1e-8
+
+        # Fixed Spread + Impact Cost (Gamma * sqrt(Trade Size / Volume))
+        impact_cost = self.gamma * (safe_trade / safe_volume).pow(0.5)  # type: ignore[operator]
+        total_cost_pct = (self.spread + impact_cost) * weights_delta.abs()  # type: ignore[operator]
+
+        return total_cost_pct

pyalloq_backtest-0.1.10/src/pyalloq_backtest/engine.py

@@ -0,0 +1,71 @@
+import pandas as pd
+from typing import Any, cast
+from pyalloq_core.pipeline import StrategyPipeline
+from pyalloq_backtest.splitters import BaseWindowSplitter, RollingWindowSplitter
+from pyalloq_backtest.costs import BaseCostModel, FlatBpsCostModel
+from pyalloq_backtest.metrics import MetricsTearSheet
+from pyalloq_core.data import MarketData
+from pyalloq_backtest.costs import CostData
+
+
+class WalkForwardEngine:
+    def __init__(
+        self,
+        pipeline: StrategyPipeline,
+        splitter: BaseWindowSplitter | None = None,
+        cost_model: BaseCostModel | None = None,
+        rebalance_freq: str = "ME",
+    ) -> None:
+        self.pipeline = pipeline
+        self.rebalance_freq = rebalance_freq
+
+        self.splitter = splitter or RollingWindowSplitter(lookback_window=252)
+        self.cost_model = cost_model or FlatBpsCostModel(bps=10.0)
+
+    def run(
+        self,
+        data: MarketData,
+    ) -> dict[str, Any]:
+        asset_returns = data.prices.pct_change().dropna()
+
+        raw_index = data.prices.resample(self.rebalance_freq).last().index
+        rebalance_dates = pd.DatetimeIndex(raw_index)
+
+        weights_history = []
+        for current_date, data_window in self.splitter.split(data, rebalance_dates):
+            weights = self.pipeline.generate_weights(data_window)
+            weights.name = current_date
+            weights_history.append(weights)
+
+        df_weights = pd.DataFrame(weights_history)
+        df_weights_daily = df_weights.reindex(data.prices.index).ffill().shift(1)
+
+        weight_changes = df_weights.diff().fillna(df_weights)
+        turnover_costs_daily = pd.Series(0.0, index=data.prices.index)
+
+        for raw_date, row in weight_changes.iterrows():
+            date = pd.Timestamp(cast(Any, raw_date))
+
+            if date in data.prices.index:
+                daily_feats: dict[str, CostData] | None = None
+
+                if data.features:
+                    daily_feats = {}
+                    for k, v in data.features.items():
+                        daily_feats[k] = v.loc[date]
+
+                costs = self.cost_model.calculate_costs(row, features_slice=daily_feats)
+                turnover_costs_daily.loc[date] = costs.sum()  # type: ignore[call-overload]
+
+        portfolio_returns = (df_weights_daily * asset_returns).sum(
+            axis=1
+        ) - turnover_costs_daily
+        portfolio_returns = portfolio_returns.dropna()
+
+        tear_sheet = MetricsTearSheet.generate(portfolio_returns)
+
+        return {
+            "returns": portfolio_returns,
+            "weights": df_weights_daily,
+            "tear_sheet": tear_sheet,
+        }

pyalloq_backtest-0.1.10/src/pyalloq_backtest/metrics.py

@@ -0,0 +1,41 @@
+import pandas as pd
+import numpy as np
+
+
+class MetricsTearSheet:
+    @staticmethod
+    def generate(
+        portfolio_returns: pd.Series, risk_free_rate: float = 0.0
+    ) -> pd.DataFrame:
+        metrics = {}
+
+        ann_factor = 252
+
+        cum_return = (1 + portfolio_returns).cumprod()
+        metrics["total_return"] = cum_return.iloc[-1] - 1
+
+        n_years = len(portfolio_returns) / ann_factor
+        metrics["annualized_return"] = (1 + metrics["total_return"]) ** (
+            1 / n_years
+        ) - 1
+
+        metrics["annualized_volatility"] = portfolio_returns.std() * np.sqrt(ann_factor)
+
+        excess_return = metrics["annualized_return"] - risk_free_rate
+        metrics["sharpe_ratio"] = (
+            excess_return / metrics["annualized_volatility"]
+            if metrics["annualized_volatility"] > 0
+            else 0
+        )
+
+        rolling_max = cum_return.cummax()
+        drawdown = (cum_return - rolling_max) / rolling_max
+        metrics["maximum_drawdown"] = drawdown.min()
+
+        metrics["calmar_ratio"] = (
+            metrics["annualized_return"] / abs(metrics["maximum_drawdown"])
+            if metrics["maximum_drawdown"] != 0
+            else 0
+        )
+
+        return pd.DataFrame.from_dict(metrics, orient="index", columns=["Value"])

pyalloq_backtest-0.1.10/src/pyalloq_backtest/splitters.py

@@ -0,0 +1,113 @@
+import pandas as pd
+import numpy as np
+from abc import ABC, abstractmethod
+from typing import Generator
+from pyalloq_core.data import MarketData
+
+
+class BaseWindowSplitter(ABC):
+    @abstractmethod
+    def split(
+        self,
+        data: MarketData,
+        rebalance_dates: pd.DatetimeIndex,
+    ) -> Generator[tuple[pd.Timestamp, MarketData], None, None]:
+        """Yields (current date, sliced_market_data)"""
+        pass
+
+
+class RollingWindowSplitter(BaseWindowSplitter):
+    def __init__(self, lookback_window: int = 252) -> None:
+        self.lookback_window = lookback_window
+
+    def split(
+        self,
+        data: MarketData,
+        rebalance_dates: pd.DatetimeIndex,
+    ) -> Generator[tuple[pd.Timestamp, MarketData], None, None]:
+        for current_date in rebalance_dates:
+            data_window = data.slice_time(
+                end_date=current_date, lookback=self.lookback_window
+            )
+
+            if len(data_window.prices) >= self.lookback_window:
+                yield current_date, data_window
+
+
+class ExpandingWindowSplitter(BaseWindowSplitter):
+    def __init__(self, min_periods: int = 252) -> None:
+        self.min_periods = min_periods
+
+    def split(
+        self,
+        data: MarketData,
+        rebalance_dates: pd.DatetimeIndex,
+    ) -> Generator[tuple[pd.Timestamp, MarketData], None, None]:
+        for current_date in rebalance_dates:
+            data_window = data.slice_time(end_date=current_date, lookback=None)
+
+            if len(data_window.prices) >= self.min_periods:
+                yield current_date, data_window
+
+
+class PurgedKFoldSplitter:
+    """
+    Used strictly for Cross-Validation (Deep Learning / ML training).
+    Splits data into K folds, applying a purge and embargo to prevent data leakage.
+    """
+
+    def __init__(self, n_splits: int = 5, embargo_pct: float = 0.01) -> None:
+        self.n_splits = n_splits
+        self.embargo_pct = embargo_pct
+
+    def split(
+        self, data: MarketData
+    ) -> Generator[tuple[MarketData, MarketData], None, None]:
+        """Yields (train_data, test_data) for neural network training."""
+
+        total_length = len(data.prices)
+        fold_size = total_length // self.n_splits
+        embargo_size = int(total_length * self.embargo_pct)
+
+        indices = np.arange(total_length)
+        dates = data.prices.index
+
+        for i in range(self.n_splits):
+            test_start = i * fold_size
+            test_end = test_start + fold_size if i < self.n_splits - 1 else total_length
+
+            test_indices = indices[test_start:test_end]
+            train_indices_left = indices[: max(0, test_start - embargo_size)]
+            train_indices_right = indices[min(total_length, test_end + embargo_size) :]
+
+            train_indices = np.concatenate([train_indices_left, train_indices_right])
+
+            if len(train_indices) == 0:
+                continue
+
+            train_dates = dates[train_indices]
+            test_dates = dates[test_indices]
+
+            train_data = MarketData(
+                prices=data.prices.loc[train_dates],
+                features={k: v.loc[train_dates] for k, v in data.features.items()}
+                if data.features
+                else {},
+                cross_sectional=data.cross_sectional,
+                risk_free_rate=data.risk_free_rate.loc[train_dates]
+                if isinstance(data.risk_free_rate, pd.Series)
+                else data.risk_free_rate,
+            )
+
+            test_data = MarketData(
+                prices=data.prices.loc[test_dates],
+                features={k: v.loc[test_dates] for k, v in data.features.items()}
+                if data.features
+                else {},
+                cross_sectional=data.cross_sectional,
+                risk_free_rate=data.risk_free_rate.loc[test_dates]
+                if isinstance(data.risk_free_rate, pd.Series)
+                else data.risk_free_rate,
+            )
+
+            yield train_data, test_data