backtest

Files (10)

• SKILL.md
• __init__.py
• combiner.py
• cost_model.py
• exit_analysis.py
• filters.py
• overlay_metrics.py
• protocols.py
• vector.py
• weighting.py

SKILL.md (first lines)

# Backtest

Backtest is the shared portfolio execution and construction boundary. Strategy
domains should produce date x symbol weights; this skill turns those weights
into executed weights, returns, costs, diagnostics, and report-ready metrics.

## Public API

```python
from skills.backtest import VectorBacktester, annual_return_metrics
from skills.backtest.weighting import WEIGHT_METHODS, risk_parity
from skills.backtest.filters import apply_portfolio_filters
from skills.backtest.cost_model import cost_bp_for_trigger_time
from skills.backtest.exit_analysis import evaluate_exit_factor
from skills.backtest.overlay_metrics import overlay_alpha
```

## Components

| Module | Purpose |
|--------|---------|
| `skills.backtest.vector` | `VectorBacktester`, `BacktestResult`, annual/activity/benchmark metrics |
| `skills.backtest.weighting` | Equal weight, risk parity, inverse variance, EPO, `WEIGHT_METHODS` |
| `skills.backtest.filters` | Market breadth, index trend, and volatility targeting overlays |
| `skills.backtest.combiner` | Blend multiple strategy return streams |
| `skills.backtest.cost_model` | A-share trigger-time cost layers and single-trade PnL helpers |
| `skills.backtest.exit_analysis` | Baseline vs filtered exit A/B evaluation |
| `skills.backtest.overlay_metrics` | Overlay alpha, win rate, drawdown, Sharpe, and regime metrics |

`VectorBacktester` requires explicit `commission` and `slippage_bp` (a missing
value raises `ValueError`). Each date's executed weight always earns the
next bar's return, which is the safe convention for close-derived signals.

## Recipes

**Run weights through the shared vectorized backtester**

```python
from skills.backtest import VectorBacktester

result = VectorBacktester(
    data=panel,
    trade_at="close",
    signal_lag=1,
    commission=0.0002,
    slippage_bp=2.0,
).run(weights_df)
```

**Convert votes to risk-aware weights**

```python
from skills.backtest.weighting import risk_parity

weights = risk_parity(votes_df, returns_df=returns_df, lookback=60, min_periods=20)
```

**Evaluate an exit filter**

```python
from skills.backtest.exit_analysis import evaluate_exit_factor
from skills.strategy.cross_sectional import ModularBacktester

result = evaluate_exit_factor(
    data,
    factor_configs,
    exit_filter,
    backtester_cls=ModularBacktester,
    commission=0.0002,
    slippage_bp=2.0,
)
```

## CLI command reference

<!-- BEGIN GENERATED: qs commands -->

Transport: `--input-json FILE|-`, `--preview N`, and `--log-level LEVEL`; flags override JSON. Use `--print-template [FIELD]` for fillable templates.

### Shared parameter groups

#### `PanelSource`

| Option | Type / default | Description |
|---|---|---|
| `--panel` | `path?` / `null` | Parquet/CSV panel, mutually exclusive with symbols or symbols-file. |
| `--symbols` | `list[string]` / `factory` | QuantSpace symbols such as SHSE.510300; repeat flag or comma-separate. |
| `--symbols-file` | `path?` / `null` | Text lines or JSON list of QuantSpace symbols. |
| `--frequency` | `string` / `1d` | Market store directory under data/market, for example 1d or 1d_adj. |
| `--data-root` | `path?` / `null` | Managed data root; otherwise QUANTSPACE_DATA_ROOT or repository data/. |
| `--start` | `string?` / `null` | Inclusive start date: YYYY-MM-DD or YYYYMMDD. |
| `--end` | `string?` / `null` | Inclusive end date: YYYY-MM-DD or YYYYMMDD. |
| `--fields` | `list[string]` / `factory` | Optional panel field subset. |

#### `OutputOptions`

| Option | Type / default | Description |
|---|---|---|
| `--output` | `path?` / `null` | Explicit output path outside managed store namespaces. |
| `--overwrite` | `boolean` / `false` | Allow replacing an existing output artifact. |
| `--data-root` | `path?` / `null` | Managed data root; otherwise QUANTSPACE_DATA_ROOT or repository data/. |

### `uv run qs backtest run`

Execute target weights through VectorBacktester with costs and metrics.

Priority: P0. Side effects: writes-output.

Shared parameters: `PanelSource`.

| Option | Type / default | Description |
|---|---|---|
| `--start` | `string?` / `null` | First result date (start_date); earlier bars still load. Pass a trimmed --panel from `qs store read` to limit history. |
| `--end` | `string?` / `null` | Last result date (end_date); later bars still load. Pass a trimmed --panel from `qs store read` to limit history. |
| `--weights` | `path` / `required` | Date by symbol target weights table (eob index or column). |
| `--commission` | `number` / `required` | One-way commission rate, e.g. 0.0002. |
| `--slippage-bp` | `number` / `required` | One-way slippage in basis points. |
| `--trade-at` | `open\|close` / `close` | Execution price field. |
| `--signal-lag` | `integer` / `1` | Bars between signal and execution. |

From quantskills/agent-quantspace, GPL-3.0.

More from quantskills/agent-quantspace