QuantRail

Every backtest lies a little. QuantRail tells you where.
Data governance · ledger-accurate simulation · research discipline

繁體中文 · Architecture · Decisions · Contributing

Status: early development (v0.x); APIs will change. Nothing here is investment advice.

Why QuantRail?

Most backtests are easy to make look good and hard to trust:

• positions are multiplied by adjusted returns, so dividends, splits and settlement are approximated or double-counted;
• nobody records which data version, licence or availability time a result depended on;
• the many variants tried before the "winner" are forgotten, so overfitting goes unmeasured.

QuantRail is built around three pillars:

Quickstart

import tempfile

import numpy as np
import pandas as pd

import quantrail as qr
from quantrail.markets.generic import ProportionalCosts

# Any price table you have: only a date and a close are required.
days = pd.bdate_range("2024-01-01", periods=250)
returns = np.random.default_rng(0).normal(0.0004, 0.01, 250)
prices = pd.DataFrame({"date": days, "close": 100 * np.exp(np.cumsum(returns))})

store = tempfile.mkdtemp()
data = qr.ingest(prices, root=store, dataset_id="my-prices", version="v1", instrument="X:ABC")

asset = qr.Instrument("X:ABC", "X", "equity", "USD")
result = qr.backtest(data, instrument=asset, capital=10_000,
                     costs=ProportionalCosts(commission_rate="0.001"))
print(result.report())

The report starts with what QuantRail could not verify, because nothing was declared:

Trust report:
  [!] SOURCE_UNKNOWN: Data source is not recorded.
  [!] LICENCE_UNKNOWN: Licence is unknown: private research only; ...
  [!] PRICE_BASIS_UNKNOWN: Prices may be raw or adjusted; ...
  [!] ACCOUNTING_APPROXIMATE: Ledger-accurate accounting needs raw prices plus dividend and split events.
  [!] AVAILABILITY_UNVERIFIED: Availability time is not declared; ...
  [!] NO_OPEN_PRICES: No open prices: next-open execution cannot be modelled.
  [!] EXECUTION_NEXT_CLOSE_PROXY: No open prices: orders fill at the next session's close.
  [i] CALENDAR_FROM_PRICES: Sessions are inferred from price dates; ...

Declare provenance (qr.Provenance), price basis and availability (qr.Declaration), add open prices and corporate actions, and the caveats disappear one by one.

Verified to the cent

The engine and the Taiwan equity module were ported from a private research implementation and must reproduce it exactly. On eight years of a Taiwan ETF (1,953 sessions, 16 cash dividends, one 4-for-1 split and a trading suspension), QuantRail matches the daily net asset value of five reference runs with zero difference: buy-and-hold, and three rules that sell (87 sells with securities transaction tax, including runs with a no-trade band and with doubled slippage). Units, cash, receivables, payables, commission, tax and slippage all match.

That reference was itself checked independently: its buy-and-hold ledger was reconciled against a total-return index, with every difference explained by cash drag, costs and timing, and against a second data source. The data is not distributed; tests/test_reference_parity.py reruns the comparison when you point it at your own copy.

Markets

QuantRail ships no market data. You bring your own, or fetch it with your own credentials from sources whose terms allow it. There is no broker connectivity or live trading in this repository.

Architecture

Read the architecture and the decision records for the reasoning.

Install

pip install quantrail

For development:

git clone https://github.com/ting-hong-shieh/quantrail.git
cd quantrail
uv sync
uv run pytest

Contributing

Correctness comes before features: accounting and statistics changes need tests with independently computed expectations. Every commit is signed off (DCO). See CONTRIBUTING.md.

Licence

Apache-2.0. See LICENSE and NOTICE. Data you use with QuantRail remains subject to its own source's terms.