bagelquant-bt 0.1.0__tar.gz

bagelquant_bt-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.3
+Name: bagelquant-bt
+Version: 0.1.0
+Summary: Backtesting and factor evaluation for the BagelQuant ecosystem
+Author: BagelQuant
+License: Apache-2.0
+Requires-Dist: numpy>=2.4.0
+Requires-Dist: plotly>=6.0.0
+Requires-Dist: polars>=1.35.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# bagelquant-bt
+
+`bagelquant-bt` provides backtesting, factor evaluation, performance metrics, and
+Plotly visualization for long-form Polars panels.
+
+The public input shape is always explicit:
+
+- prices: `time`, `asset_id`, `price`
+- weights: `time`, `asset_id`, `weight`
+- factors: `time`, `asset_id`, `factor`
+
+Weights at `time=t` earn each asset's close-to-close return from `t` to the next
+available observation.
+
+```python
+import polars as pl
+
+from bagelquant_bt import BacktestConfig, run_backtest
+
+prices = pl.DataFrame(
+    {
+        "time": ["2024-01-02", "2024-01-03"],
+        "asset_id": ["AAA", "AAA"],
+        "price": [100.0, 102.0],
+    }
+)
+weights = pl.DataFrame(
+    {"time": ["2024-01-02"], "asset_id": ["AAA"], "weight": [1.0]}
+)
+
+result = run_backtest(
+    weights,
+    prices,
+    kind="weights",
+    config=BacktestConfig(initial_capital=1_000_000),
+)
+
+print(result.returns)
+print(result.summary)
+```
+
+Factor evaluation computes daily cross-sectional IC, quantile returns, a
+top-minus-bottom spread, and a TOP N equal-weight backtest.
+
+Visualization helpers return Plotly figures:
+
+```python
+from bagelquant_bt.visualization import plot_cumulative_returns
+
+fig = plot_cumulative_returns(result)
+fig.write_html("cumulative_returns.html")
+```
+
+## Development
+
+```bash
+uv run ruff check .
+uv run pytest
+```

bagelquant_bt-0.1.0/README.md

@@ -0,0 +1,59 @@
+# bagelquant-bt
+
+`bagelquant-bt` provides backtesting, factor evaluation, performance metrics, and
+Plotly visualization for long-form Polars panels.
+
+The public input shape is always explicit:
+
+- prices: `time`, `asset_id`, `price`
+- weights: `time`, `asset_id`, `weight`
+- factors: `time`, `asset_id`, `factor`
+
+Weights at `time=t` earn each asset's close-to-close return from `t` to the next
+available observation.
+
+```python
+import polars as pl
+
+from bagelquant_bt import BacktestConfig, run_backtest
+
+prices = pl.DataFrame(
+    {
+        "time": ["2024-01-02", "2024-01-03"],
+        "asset_id": ["AAA", "AAA"],
+        "price": [100.0, 102.0],
+    }
+)
+weights = pl.DataFrame(
+    {"time": ["2024-01-02"], "asset_id": ["AAA"], "weight": [1.0]}
+)
+
+result = run_backtest(
+    weights,
+    prices,
+    kind="weights",
+    config=BacktestConfig(initial_capital=1_000_000),
+)
+
+print(result.returns)
+print(result.summary)
+```
+
+Factor evaluation computes daily cross-sectional IC, quantile returns, a
+top-minus-bottom spread, and a TOP N equal-weight backtest.
+
+Visualization helpers return Plotly figures:
+
+```python
+from bagelquant_bt.visualization import plot_cumulative_returns
+
+fig = plot_cumulative_returns(result)
+fig.write_html("cumulative_returns.html")
+```
+
+## Development
+
+```bash
+uv run ruff check .
+uv run pytest
+```

bagelquant_bt-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "bagelquant-bt"
+version = "0.1.0"
+description = "Backtesting and factor evaluation for the BagelQuant ecosystem"
+readme = "README.md"
+requires-python = ">=3.13"
+license = { text = "Apache-2.0" }
+authors = [{ name = "BagelQuant" }]
+dependencies = [
+    "numpy>=2.4.0",
+    "plotly>=6.0.0",
+    "polars>=1.35.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.0",
+    "ruff>=0.14.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.0,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "RUF"]

bagelquant_bt-0.1.0/src/bagelquant_bt/__init__.py

@@ -0,0 +1,32 @@
+"""Backtesting and factor evaluation for the BagelQuant ecosystem."""
+
+from .config import BacktestConfig, TransactionCostConfig
+from .engine import run_weight_backtest
+from .exceptions import (
+    BacktestConfigError,
+    BagelQuantBacktestError,
+    InputValidationError,
+)
+from .factor import run_factor_evaluation
+from .reporting import summary_report
+from .results import (
+    BacktestResult,
+    FactorEvaluationResult,
+    PerformanceSummary,
+    TransactionCostBreakdown,
+)
+
+__all__ = [
+    "BacktestConfig",
+    "BacktestConfigError",
+    "BacktestResult",
+    "BagelQuantBacktestError",
+    "FactorEvaluationResult",
+    "InputValidationError",
+    "PerformanceSummary",
+    "TransactionCostBreakdown",
+    "TransactionCostConfig",
+    "run_factor_evaluation",
+    "run_weight_backtest",
+    "summary_report",
+]

bagelquant_bt-0.1.0/src/bagelquant_bt/config.py

@@ -0,0 +1,47 @@
+"""Configuration objects for backtesting and factor evaluation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .exceptions import BacktestConfigError
+
+
+@dataclass(frozen=True, slots=True)
+class TransactionCostConfig:
+    """Per-trade transaction cost settings."""
+
+    rate: float = 0.00015
+    min_fee: float = 5.0
+
+    def __post_init__(self) -> None:
+        if self.rate < 0:
+            raise BacktestConfigError("transaction cost rate must be nonnegative")
+        if self.min_fee < 0:
+            raise BacktestConfigError("transaction cost min_fee must be nonnegative")
+
+
+@dataclass(frozen=True, slots=True)
+class BacktestConfig:
+    """Shared backtest and factor evaluation configuration."""
+
+    initial_capital: float
+    transaction_cost: TransactionCostConfig = field(
+        default_factory=TransactionCostConfig
+    )
+    annualization: int = 252
+    ic_method: str = "spearman"
+    quantiles: int = 5
+    top_n: int = 50
+
+    def __post_init__(self) -> None:
+        if self.initial_capital <= 0:
+            raise BacktestConfigError("initial_capital must be positive")
+        if self.annualization <= 0:
+            raise BacktestConfigError("annualization must be positive")
+        if self.ic_method not in {"spearman", "pearson"}:
+            raise BacktestConfigError("ic_method must be 'spearman' or 'pearson'")
+        if self.quantiles < 2:
+            raise BacktestConfigError("quantiles must be at least 2")
+        if self.top_n <= 0:
+            raise BacktestConfigError("top_n must be positive")

bagelquant_bt-0.1.0/src/bagelquant_bt/costs.py

@@ -0,0 +1,31 @@
+"""Transaction cost and turnover calculations."""
+
+from __future__ import annotations
+
+import polars as pl
+
+from .inputs import ASSET_ID, TIME
+
+
+def turnover(weights: pl.DataFrame) -> pl.DataFrame:
+    """Compute daily absolute weight turnover."""
+
+    return (
+        weights.sort([ASSET_ID, TIME])
+        .with_columns(
+            pl.col("weight")
+            .fill_null(0.0)
+            .shift(1)
+            .over(ASSET_ID)
+            .fill_null(0.0)
+            .alias("previous_weight")
+        )
+        .with_columns(
+            (pl.col("weight").fill_null(0.0) - pl.col("previous_weight"))
+            .abs()
+            .alias("weight_delta")
+        )
+        .group_by(TIME)
+        .agg(pl.col("weight_delta").sum().alias("turnover"))
+        .sort(TIME)
+    )

bagelquant_bt-0.1.0/src/bagelquant_bt/engine.py

@@ -0,0 +1,207 @@
+"""Backtest orchestration."""
+
+from __future__ import annotations
+
+import polars as pl
+
+from .config import BacktestConfig
+from .costs import turnover
+from .exceptions import BacktestConfigError, InputValidationError
+from .inputs import ASSET_ID, TIME, validate_prices, validate_weights
+from .performance import summarize_performance
+from .results import BacktestResult, TransactionCostBreakdown
+from .returns import (
+    _expand_portfolio_weights,
+    asset_close_to_close_returns,
+    cumulative_returns,
+    portfolio_returns,
+)
+
+
+def run_weight_backtest(
+    weights: pl.DataFrame,
+    prices: pl.DataFrame,
+    *,
+    config: BacktestConfig | None = None,
+) -> BacktestResult:
+    """Backtest a long-form portfolio weight frame."""
+
+    resolved_config = _require_config(config)
+    aligned_weights = validate_weights(weights)
+    aligned_prices = validate_prices(prices)
+    return backtest_weight_frame(
+        aligned_weights,
+        aligned_prices,
+        config=resolved_config,
+    )
+
+
+def backtest_weight_frame(
+    weights: pl.DataFrame,
+    prices: pl.DataFrame,
+    *,
+    config: BacktestConfig,
+) -> BacktestResult:
+    """Backtest an already materialized long-form weight frame."""
+
+    aligned_weights = validate_weights(weights)
+    aligned_prices = validate_prices(prices)
+    forward_returns = asset_close_to_close_returns(aligned_prices)
+    return _backtest_weight_frame_with_forward_returns(
+        aligned_weights,
+        aligned_prices,
+        forward_returns,
+        config=config,
+    )
+
+
+def _backtest_weight_frame_with_forward_returns(
+    weights: pl.DataFrame,
+    prices: pl.DataFrame,
+    forward_returns: pl.DataFrame,
+    *,
+    config: BacktestConfig,
+) -> BacktestResult:
+    """Backtest a weight frame with a precomputed forward-return panel."""
+
+    executable_weights = _expand_portfolio_weights(weights, prices, forward_returns)
+    if executable_weights.is_empty():
+        raise InputValidationError("at least two overlapping price times are required")
+
+    gross_returns = portfolio_returns(executable_weights, forward_returns)
+    turn = turnover(executable_weights)
+    costs, returns, value = _simulate_cost_adjusted_returns(
+        weights=executable_weights,
+        gross_returns=gross_returns,
+        config=config,
+    )
+    summary, performance = summarize_performance(
+        returns=returns,
+        turnover=turn,
+        costs=costs,
+        initial_capital=config.initial_capital,
+        annualization=config.annualization,
+    )
+    return BacktestResult(
+        weights=executable_weights,
+        asset_returns=forward_returns,
+        returns=returns,
+        value=value,
+        turnover=turn,
+        transaction_costs=costs,
+        summary=summary,
+        performance=performance,
+    )
+
+
+def _simulate_cost_adjusted_returns(
+    *,
+    weights: pl.DataFrame,
+    gross_returns: pl.DataFrame,
+    config: BacktestConfig,
+) -> tuple[TransactionCostBreakdown, pl.DataFrame, pl.DataFrame]:
+    trade_summary = _trade_summary(weights)
+    gross_by_time = {
+        row[TIME]: float(row["gross_return"] or 0.0)
+        for row in gross_returns.iter_rows(named=True)
+    }
+
+    current_value = float(config.initial_capital)
+    cost_rows: list[dict[str, object]] = []
+    return_rows: list[dict[str, object]] = []
+    value_rows: list[dict[str, object]] = []
+
+    for row in trade_summary.iter_rows(named=True):
+        time = row[TIME]
+        weight_deltas = [float(delta) for delta in row["weight_deltas"]]
+        traded_asset_count = len(weight_deltas)
+        weight_delta = sum(weight_deltas)
+        traded_notional = weight_delta * current_value
+        raw_fee = traded_notional * config.transaction_cost.rate
+        total_fee = sum(
+            max(
+                delta * current_value * config.transaction_cost.rate,
+                config.transaction_cost.min_fee,
+            )
+            for delta in weight_deltas
+        )
+
+        cost_return = total_fee / current_value if current_value else 0.0
+        gross_return = gross_by_time.get(time, 0.0)
+        net_return = gross_return - cost_return
+        gross_value = current_value * (1.0 + gross_return)
+        current_value *= 1.0 + net_return
+        cost_rows.append(
+            {
+                TIME: time,
+                "traded_asset_count": traded_asset_count,
+                "traded_notional": traded_notional,
+                "raw_fee": raw_fee,
+                "min_fee_adjustment": total_fee - raw_fee,
+                "total_fee": total_fee,
+                "cost_return": cost_return,
+            }
+        )
+        return_rows.append(
+            {TIME: time, "gross_return": gross_return, "net_return": net_return}
+        )
+        value_rows.append(
+            {TIME: time, "gross_value": gross_value, "net_value": current_value}
+        )
+
+    returns = pl.DataFrame(return_rows).sort(TIME)
+    value = (
+        pl.DataFrame(value_rows)
+        .sort(TIME)
+        .join(
+            cumulative_returns(returns, "gross_return"),
+            on=TIME,
+        )
+        .join(
+            cumulative_returns(returns, "net_return"),
+            on=TIME,
+        )
+    )
+    return TransactionCostBreakdown(pl.DataFrame(cost_rows).sort(TIME)), returns, value
+
+
+def _trade_summary(weights: pl.DataFrame) -> pl.DataFrame:
+    return (
+        weights.sort([ASSET_ID, TIME])
+        .with_columns(
+            pl.col("weight")
+            .fill_null(0.0)
+            .shift(1)
+            .over(ASSET_ID)
+            .fill_null(0.0)
+            .alias("previous_weight")
+        )
+        .with_columns(
+            (pl.col("weight").fill_null(0.0) - pl.col("previous_weight"))
+            .abs()
+            .alias("weight_delta")
+        )
+        .group_by(TIME)
+        .agg(
+            pl.col("weight_delta")
+            .filter(pl.col("weight_delta") > 0.0)
+            .alias("weight_deltas"),
+        )
+        .sort(TIME)
+    )
+
+
+def _require_config(config: BacktestConfig | None) -> BacktestConfig:
+    if config is None:
+        raise BacktestConfigError(
+            "config is required because initial_capital is needed for minimum fees"
+        )
+    return config
+
+
+def _partition_key(key: object) -> object:
+    if isinstance(key, tuple):
+        return key[0]
+    if isinstance(key, list):
+        return key[0]
+    return key

bagelquant_bt-0.1.0/src/bagelquant_bt/exceptions.py

@@ -0,0 +1,13 @@
+"""Package-specific exceptions for bagelquant-bt."""
+
+
+class BagelQuantBacktestError(Exception):
+    """Base exception for bagelquant-bt."""
+
+
+class InputValidationError(BagelQuantBacktestError):
+    """Raised when user-provided tabular inputs are invalid."""
+
+
+class BacktestConfigError(BagelQuantBacktestError):
+    """Raised when backtest configuration values are invalid."""