From a strategy idea to an auditable portfolio result.

The 60-second mental model

A backtest is a chain of contracts. Market data becomes features; the strategy produces a decision; accounting turns that decision into positions and NAV; reporting exposes the assumptions and result. QJ keeps the two most common strategy contracts separate instead of pretending weights and orders are the same thing.

Choose the strategy contract

Start with the simplest model that can answer the research question. Extra execution state is useful only when it changes the decision you are testing.

Data and indicators

The constructor defines the universe, date range, source and granularity. Data is normalized into instrument frames; declarative indicator configuration adds named features that both strategy modes can consume.

import pandas as pd

from backtester import Backtester


class DailySMATrend(Backtester):
    def _compute_signals(self) -> pd.DataFrame:
        fast = self.instruments_data.get_feature("SMA_50_close")
        slow = self.instruments_data.get_feature("SMA_200_close")
        valid = fast.notna() & slow.notna()
        return (fast > slow).astype(float).where(valid, 0.0)

    def _compute_weights(self) -> pd.DataFrame:
        active = self.signals == 1.0
        counts = active.sum(axis=1)
        return active.div(counts, axis=0).fillna(0.0).clip(upper=0.25)

The strategy does not download data inside its signal hook and does not recompute hidden indicators on every bar. It reads named, aligned features and handles the warmup region explicitly.

How weight mode becomes NAV

Target weights are intent, not final positions. Before they earn returns, QJ moves them through a causal timing boundary and portfolio controls.

strategy = DailySMATrend(
    strategy_name="DailySMATrend",
    initial_capital=100_000,
    instruments=["AAPL", "MSFT", "NVDA", "GOOGL", "AMZN"],
    backtest_period={"start": "2015-01-01", "end": "2025-01-01"},
    source="yfinance",
    execution_mode="weights",
    max_position_size=0.25,
    rebalance_policy=RebalancePolicy(frequency="D"),
    indicators_config=[
        {"function": "SMA", "price_cols": ["close"],
         "params": {"periods": [50, 200]}},
    ],
    save_text_reports=True,
    save_portfolio_plots=True,
)

await strategy.run_strategy()

How order mode works

Order mode receives the current date, bars, positions and NAV. Strategy code submits instructions; FillEngine owns the pending book and decides whether each order fills, remains active, expires, is rejected or is cancelled.

from backtester.execution.order_types import (
    BracketSpec, Order, OrderSide, OrderType,
)


class BracketTrend(Backtester):
    def _compute_orders(self, date, bars, current_positions, nav):
        fast = self.instruments_data.get_feature("SMA_20_close")
        slow = self.instruments_data.get_feature("SMA_50_close")

        for instrument in self.instruments:
            if fast.loc[date, instrument] <= slow.loc[date, instrument]:
                continue
            if current_positions.get(instrument, 0.0) != 0:
                continue

            close = bars[instrument].close
            quantity = int(nav * 0.15 / close)
            bracket = BracketSpec(
                take_profit_price=round(close * 1.06, 2),
                stop_loss_price=round(close * 0.97, 2),
            )
            self.fill_engine.submit(
                Order(instrument, OrderSide.BUY, quantity,
                      OrderType.BRACKET, bracket=bracket)
            )

The engine also supports DAY/GTD/GTC time-in-force, expiration by date or number of bars, volume-participation caps and order/fill histories. These are bar-based execution mechanics—not a queue-position or tick-level exchange simulator.

Rebalancing and drift

Rebalancing decides when target weights are allowed to replace realized, drifted weights. Calendar triggers are only the first layer; policies can also react to drift, tracking error, signal changes, drawdown and turnover budget.

from backtester.portfolio.rebalance import RebalancePolicy

policy = RebalancePolicy(
    frequency="BME",              # business month-end
    drift_threshold=0.05,         # or when a weight drifts by 5%
    max_annual_turnover=4.0,      # rolling turnover budget
    partial_rebalance=True,       # touch only positions outside the band
)

strategy = MyStrategy(..., rebalance_policy=policy)

Month-start and month-end are different strategies, not formatting aliases. Exchange holidays are snapped within the intended calendar period, and calendar conventions should be sensitivity-tested.

Risk, slippage and commissions

Risk adjustment sits between raw target weights and rebalancing. In order mode, slippage changes the fill price and commissions reduce cash on every fill.

from backtester.risk import (
    PositionLimitModel,
    RiskModelChain,
    VolTargetModel,
)

risk = RiskModelChain([
    VolTargetModel(target_vol=0.15, lookback=63, max_leverage=1.5),
    PositionLimitModel(max_weight=0.25),
])

strategy = MyStrategy(..., risk_model=risk)

from backtester.execution.commission import PerShareCommission
from backtester.execution.slippage import FixedBpsSlippage

strategy = MyOrderStrategy(
    ...,
    execution_mode="orders",
    slippage_model=FixedBpsSlippage(bps=5.0),
    commission_scheme=PerShareCommission(
        cost_per_share=0.005,
        min_per_order=1.0,
    ),
)

Contract-aware instruments

A futures contract, FX lot and equity share do not turn the same price move into the same P&L. ContractSpec carries multiplier, tick, margin, lot and currency semantics into execution-aware accounting.

from backtester.execution.contract_spec import AssetClass, ContractSpec

specs = {
    "ES=F": ContractSpec(
        symbol="ES=F",
        asset_class=AssetClass.FUTURE,
        multiplier=50.0,
        tick_size=0.25,
        margin=12_000.0,
    ),
}

strategy = MyStrategy(..., contract_specs=specs)

Walk-forward and optimization

A strong in-sample result is only a hypothesis. QJ provides rolling, expanding and anchored folds, explicit pre-OOS purge controls, grid or Optuna search and diagnostics such as Sharpe decay, deflated Sharpe and rolling rank stability.

from backtester.walkforward import WalkForwardConfig, WalkForwardEngine

config = WalkForwardConfig(
    scheme="rolling",
    train_months=24,
    test_months=6,
    step_months=6,
    purge_days=5,
    extra_pre_oos_purge_pct=0.01,
)

engine = WalkForwardEngine(
    config=config,
    initial_capital=100_000,
    backtester_factory=build_strategy_for_fold,
)
result = await engine.run_async(strategy.portfolio_data)

What one run produces

The public package creates a local evidence packet that can be inspected without a hosted dashboard. The exact files depend on report flags and strategy mode.

What ships where

The website should never blur a public engine capability with a hosted service. These are the current product boundaries for the v0.10.0 public repository.

Module map

Users do not need to know every source file, but advanced researchers should be able to identify which layer owns an assumption.

Where to go next