QuantJourney Backtester

A Python-native backtesting engine for reproducible portfolio research.

QuantJourney Backtester turns strategy ideas into auditable research packets: signals become target weights or explicit orders, orders become simulated fills, fills update cash and positions, and NAV is reconstructed from portfolio state.

It is designed for researchers who need more than an equity curve: execution assumptions, costs, slippage, rebalancing rules, crisis behavior, walk-forward validation, optimization diagnostics, metrics, plots, and run metadata from one repeatable run.

Installation

pip install quantjourney-bt

Current PyPI release: 0.12.4. The public package supports Python 3.11 and newer.

Why It Exists

Most backtests stop at signal x returns. That is fast, but it hides the questions that matter before a strategy can be trusted:

• Was there look-ahead?
• What happened to missing bars?
• How were weights converted into trades?
• Did costs and turnover destroy the edge?
• Did parameters generalize out of sample?
• Which crisis regimes broke the strategy?
• Can the run be reproduced and reviewed later?

QuantJourney Backtester makes these assumptions explicit.

Two Research Modes

Weight mode is for portfolio research: factor portfolios, rotation models, long/cash strategies, long/short books, risk overlays, volatility targeting, and scheduled rebalancing.

Order mode is for execution-aware research: market, limit, stop, stop-limit, trailing stop, bracket, and OCO orders with commissions, slippage, volume participation, fills, positions, cash, NAV, and trade blotters.

Fast weight execution solves transaction costs recursively on one post-cost capital path: NAV, implied quantities, trade notionals, booked costs and reported positions reconcile to the same self-financing ledger. Use weight_execution="orders" when discrete fills and cash movements matter. For fills at the open, range-sensitive slippage sees only the previous completed bar and volume capacity is forecast from lagged observations; the engine does not use that day's later high, low, close or full-day volume.

Engine Contract

Data -> Features -> Signals -> Target Weights / Orders -> Fills -> Positions -> NAV -> Metrics -> Report Packet

Each stage is explicit. Data is transformed into features, features drive signals, signals become either target weights or orders, execution assumptions turn those decisions into fills, and portfolio state is used to reconstruct NAV, metrics, plots, and run metadata.

What you want to do -> what to use

| I want to... | Use | |---|---| | Generate long / flat / short or ranking intent | _compute_signals() | | Convert intent into target portfolio exposure | _compute_weights() | | Apply caps, vol targeting, inverse vol, or risk parity | risk_model=... | | Trade only on calendar, drift, signal, or turnover triggers | RebalancePolicy(...) | | Submit market / limit / stop / trailing / bracket / OCO orders | execution_mode="orders" + _compute_orders(...) | | Model spread, impact, and commission assumptions | slippage & commission models | | Validate parameters out of sample | walk-forward / Optuna |

The repository examples and tests demonstrate these engine semantics locally.

What You Get From One Run

Each local run can produce metrics, plots, equity curves, drawdowns, rolling risk, optimization evidence, walk-forward results, CSV/JSON artifacts, a static HTML dashboard, and run metadata. The hosted platform adds crisis diagnostics, interactive dashboards, execution traces, and PDF tear sheets.

What Stays Local

Your strategy code, signals, portfolio accounting, order simulation, metrics, plots, generated reports, and run artifacts stay local. QuantJourney Cloud is used for market-data preparation and authentication.

What It Is Not

This is not a broker, not a live trading system, not investment advice, and not a guarantee that a strategy will work out of sample. Some examples intentionally simplify assumptions such as borrow cost, financing, liquidity and market impact. Those assumptions are documented so they can be changed, not hidden.

Example Output

Every run produces a review-ready research packet — equity curves, monthly returns heatmaps, drawdowns, risk and rolling statistics, and walk-forward / optimization summaries (see Reports for the exact file list). A few examples:

Cumulative returns vs benchmark

Monthly returns heatmap

Crisis analysis across historical stress periods (hosted platform report pack)

Walk-forward out-of-sample equity (hosted platform report pack)

The first two charts come from the open-source report pack in this repository. Charts marked hosted platform report pack — crisis analysis, trade blotters, execution traces, PDF factsheets, and interactive dashboards — are generated by the hosted QuantJourney platform on top of the same engine results. More examples at backtester.quantjourney.cloud.

Install

pip install quantjourney-bt

With uv:

uv pip install quantjourney-bt

Optional extras: pip install "quantjourney-bt[wf]" or uv pip install "quantjourney-bt[data,wf]" adds Optuna for the walk-forward optimization examples (WF05); [data] adds the yfinance benchmark fallback.

For local development:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev,data]"
pytest

Do not install dependencies into the Homebrew/system Python. Use a virtual environment; otherwise macOS/Homebrew may raise an externally-managed-environment error and the launcher may miss packages such as quantjourney_ti.

Reproducible Demo Without API Key

Run the first strategy against deterministic bundled sample data:

./strategy.sh example_weights_01_sma_daily --sample-data --output /tmp/qj-sample

The sample dataset is intentionally small and reproducible. It is useful for install checks, report generation, and reading the engine flow without creating an account. For real market data, set QuantJourney API credentials and run the same strategy without --sample-data.

qj-bt Data Catalog

Open the optional keyboard-driven browser in an interactive terminal:

qj-bt data

Use deterministic section commands in scripts, CI, or an agent workflow:

qj-bt data overview
qj-bt data sources
qj-bt data granularities
qj-bt data datasets
qj-bt data asset-classes
qj-bt data universes
qj-bt data example-symbols
qj-bt data sources --json

qj-bt data uses the public metadata endpoints without reading or transmitting an API key. When no section is supplied, it opens the interactive browser only when stdin and stdout are attached to a terminal; otherwise it emits the overview table. The example-symbol index is illustrative and is not an exhaustive market-data availability catalog.

Repository Layout

backtester/               Runtime package imported as backtester
strategies/               Runnable strategy examples
strategy.sh               macOS/Linux strategy launcher
strategy.bat              Windows strategy launcher
strategy.py               Shared cross-platform launcher logic
benchmarks/               Benchmark-suite notes
skills/                   Strategy-authoring skill materials
tests/                    Import, packaging, and report smoke checks
docs/                     Roadmap and supporting documentation
CHANGELOG.md              Release history

The public runtime includes the shared execution simulator, contract-aware portfolio ledger, portfolio-of-strategies book, and pre-trade risk controls. Hosted data, orchestration, and extended report packs remain outside this repository; see Public Scope.

The tests/ directory is intentionally kept. It is not required at runtime, but it gives the package a quick install/import/report safety check before release.

Documentation

• Windows setup - native Windows installation and strategy.bat usage without WSL.
• Roadmap - direction of travel by theme, without delivery dates or ordering commitments.
• Strategy catalog - runnable examples with source and result links.
• Contributing - how to add example strategies, fixes, and docs (fork, branch, pull request).
• Performance refactor in 0.12.4 - benchmark results, implementation details, and parity checks for the faster engine paths.
• Release process - clean-tag publishing and exact artifact boundary checks.

AI Co-Pilot Skills

The skills/ directory holds guidance packs for AI-assisted research. When you work with an AI coding