quantskills/agent-quantspace/backtest

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

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

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

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

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

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

OutputOptions

uv run qs backtest run

Execute target weights through VectorBacktester with costs and metrics.

Priority: P0. Side effects: writes-output.

Shared parameters: PanelSource.

Output data fields: metrics, annual_returns, activity, rows, start, end.

Inspect schemas: uv run qs schema backtest.run (add --part input|output or --file-field FIELD).

uv run qs backtest weigh

Convert a vote matrix into portfolio weights.

Priority: P1. Side effects: writes-output.

Shared parameters: PanelSource, OutputOptions.

Output data fields: method, rows, columns, start, end, preview.

Inspect schemas: uv run qs schema backtest.weigh (add --part input|output or --file-field FIELD).

uv run qs backtest overlay

Scale weights with market breadth, index trend, or volatility targeting.

Priority: P2. Side effects: writes-output.

Shared parameters: PanelSource, OutputOptions.

Output data fields: method, rows, columns, start, end, preview.

Inspect schemas: uv run qs schema backtest.overlay (add --part input|output or --file-field FIELD).

uv run qs backtest combine

Blend strategy return streams with StrategyCombiner.

Priority: P2. Side effects: writes-output.

Shared parameters: OutputOptions.

Output data fields: strategies, weights, metrics, rows.

Inspect schemas: uv run qs schema backtest.combine (add --part input|output or --file-field FIELD).

uv run qs backtest cost

Look up the A-share trigger-time cost layer and single T PnL.

Priority: P2. Side effects: read-only.

Output data fields: time, layer, cost_bp, gross_bp, net_bp.

Inspect schemas: uv run qs schema backtest.cost (add --part input|output or --file-field FIELD).

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