Skip to content

Backtesting

Savvas Leousis edited this page Sep 26, 2026 · 2 revisions

Backtesting

The backtester replays history bar by bar and trades a SimulatedBroker. The lab uses it for every score and test. It shares the Broker protocol with production, so strategy code does not change. It can also run the tick's construction pipeline when BacktestConfig.construction is set, but the lab and API do not set it yet.

sequenceDiagram
  participant E as Engine
  participant S as Strategy
  participant B as SimulatedBroker
  loop every bar t
    E->>B: apply splits and dividends with ex-date t
    E->>B: fill queued orders at bar t open
    E->>B: set prices to bar t close
    alt rebalance bar
      E->>S: estimate_return for each ticker
      E->>S: decide(picks, portfolio, prices)
      S-->>E: orders (queued for bar t+1)
    end
    E->>E: mark equity at closes
  end
Loading

Rules

  • No look-ahead: signals at bar t see data up to t's close.
  • Fills at next bar open: orders decided at t fill at the open of the next bar that ticker trades.
  • Replaced, not stacked: unfilled queued orders are replaced by the next decision.
  • Always decide: decide runs even with no picks, so exits happen.
  • Marking: equity is valued at each bar's close. A ticker with no bar at that time keeps its last close.
  • Corporate actions: a split multiplies held shares (and queued orders); a cash dividend is credited, minus [production] dividend_withholding_rate. Signals read adjusted prices; fills and marks use raw prices.
  • Long-only: sells are clipped to the held quantity.
  • Interval-aware: any interval (1m to 1w). rebalance_every_bars counts bars, not days.

Costs and fills

Costs are set under [backtest.costs] and are realistic by default. The simulated tick uses the same model.

Setting Effect
fee_flat, fee_bps Fee per fill: flat plus basis points of notional
half_spread_bps Half the bid-ask spread, paid on every fill
impact_bps, max_impact_bps Market impact by the square root of order size against bar volume, capped
[backtest.costs.asset_classes.<class>] Override per asset class, e.g. crypto

The fill model decides how much fills and at what price. The default fills every order in full at the open. A bar-range model (participation cap, partial fills, limit and stop orders from the bar's high and low, a gap guard) exists in code but is not wired to config yet.

Annualization

Sharpe is annualized by the number of bars in a year for the universe's calendar: 252 sessions of 6.5 hours for equity, commodity and bond, 365 days of 24 hours for crypto. A mixed universe uses the densest calendar present. CAGR uses real elapsed time.

Report metrics

Metric Meaning
final_return, cagr Total return and compound annual growth
sharpe, sortino, calmar Return per unit of risk (see Glossary)
max_drawdown, max_dd_duration_bars Deepest fall from a peak and how long it lasted
ulcer_index, upi Depth and length of drawdowns, and CAGR per unit of it
var_95, es_95 Typical bad day and the average of the worse days
skew, kurtosis, lower_tail_ratio Shape of the return distribution
trades, trade_stats FIFO round trips: win rate, profit factor, expectancy, holding time
turnover, costs paid How much it trades and what that cost
benchmark stats Beta, alpha, information ratio and tracking error against [lab].benchmark

Running one

From the CLI, backtests run inside stonks lab run. A tear sheet (strategy against benchmark, drawdowns, rolling Sharpe, monthly returns, trade stats):

uv run stonks report --backtest momentum --start 2023-01-01 --end 2026-09-01 \
  --tickers AAPL.US,MSFT.US --out data/reports/momentum.html

The API has a direct job, POST /api/lab/backtests; MCP exposes it as run_backtest.

Clone this wiki locally