
Event-driven backtesting for quantitative strategies with configurable execution, accounting, risk, and framework-parity validation.
Repo ml4t/backtest, read from GitHub 1 min ago. ml4t has not joined Take My Repo.
ml4t/backtest is a public repo on GitHub by ml4t. Event-driven backtesting for quantitative strategies with configurable execution, accounting, risk, and framework-parity validation. It declares the MIT license on GitHub. It is written mainly in Python, has 49 stars and last changed on 2026-11-20. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-22.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
Event-driven backtesting for quantitative strategies with configurable execution, accounting, risk, and framework-parity validation.
This library is one of six interconnected libraries supporting the machine learning for trading workflow described in Machine Learning for Trading:
Together they cover data infrastructure, feature engineering, modeling, signal evaluation, strategy backtesting, and live deployment.
Backtesting requires accurate simulation of order execution, position tracking, and risk management. ml4t-backtest provides:
price, bid, ask, midpoint, and side-aware sourcesThe same Strategy class used in backtesting works unchanged in ml4t-live for production deployment.
ml4t-backtest supports CPython 3.12, 3.13, and 3.14 on Linux, macOS, and Windows.
uv add ml4t-backtest
The core package and quick start require no external service or special hardware. Optional extras are isolated by capability:
uv add 'ml4t-backtest[viz]' # Plotly, Matplotlib, and Dash reporting uv add 'ml4t-backtest[advanced]' # Graph routing and portfolio optimization uv add 'ml4t-backtest[comparison]' # Public framework-comparison dependencies
The comparison extra does not include licensed VectorBT Pro or the containerized LEAN engine. Those validation environments require their own repository access or container runtime and are not part of normal library use. See the installation guide for supported setup paths.
The first backtest uses bundled synthetic data and explains every fill. The tutorial sequence then covers orders, multi-asset portfolios, costs, account rules, risk, and results.
from datetime import datetime import polars as pl from ml4t.backtest import Engine, Strategy, BacktestConfig, DataFeed class SignalStrategy(Strategy): def on_data(self, timestamp, data, context, broker): for asset, bar in data.items(): signal = bar.get("signals", {}).get("prediction", 0) price = bar.get("price", bar.get("close", 0)) position = broker.get_position(asset) if position is None and signal > 0.5: shares = (broker.get_account_value() * 0.10) / price if shares > 0: broker.submit_order(asset, shares) elif position is not None and signal < -0.5: broker.close_position(asset) timestamps = [datetime(2024, 1, day) for day in (2, 3, 4, 5)] prices = pl.DataFrame( { "timestamp": timestamps, "asset": ["AAPL"] * 4, "close": [100.0, 101.0, 103.0, 102.0], } ) signals = pl.DataFrame( { "timestamp": timestamps, "asset": ["AAPL"] * 4, "prediction": [1.0, 1.0, -1.0, -1.0], } ) config = BacktestConfig(initial_cash=100_000) feed = DataFeed(prices_df=prices, signals_df=signals) engine = Engine(feed, SignalStrategy(), config) result = engine.run() print(f"Total Return: {result.metrics['total_return_pct']:.2f}%") print(f"Sharpe Ratio: {result.metrics['sharpe']:.2f}") print(result.to_fills_dataframe().head())
Each Engine instance is single-use. Create a new instance for every independent run.
bar["price"] follows FeedSpec.price_col when you provide one, so the same strategy works for close-based bars and quote-aware feeds.
Position-level exit rules:
from ml4t.backtest import Strategy, StopLoss, TakeProfit, TrailingStop, RuleChain class MyStrategy(Strategy): def on_start(self, broker): broker.set_position_rules(RuleChain([ StopLoss(pct=0.05), TakeProfit(pct=0.15), TrailingStop(pct=0.03), ]))
Portfolio-level controls:
from ml4t.backtest.risk.portfolio.limits import MaxDrawdownLimit, DailyLossLimit
Built-in profiles configure the behavioral semantics used by major backtesting frameworks:
from ml4t.backtest import BacktestConfig # Match VectorBT behavior (same-bar close fills, fractional shares) config = BacktestConfig.from_preset("vectorbt") # Match Backtrader behavior (next-bar open fills, integer shares) config = BacktestConfig.from_preset("backtrader") # Match the documented Zipline comparison protocol (next-bar open, no default costs) config = BacktestConfig.from_preset("zipline") # Match the frozen LEAN daily US-equity protocol (next-session open, integer shares) config = BacktestConfig.from_preset("lean") # Conservative production settings (higher costs, cash buffer) config = BacktestConfig.from_preset("realistic")
Each profile sets 40+ behavioral knobs, including fill timing, execution price, share type, commission model, and order processing. Current exact-match evidence appears below.
from ml4t.backtest import ExecutionMode, StopFillMode # Same-bar fills (VectorBT style) config = BacktestConfig( execution_mode=ExecutionMode.SAME_BAR, stop_fill_mode=StopFillMode.STOP_PRICE, ) # Next-bar fills (Backtrader style) config = BacktestConfig( execution_mode=ExecutionMode.NEXT_BAR, stop_fill_mode=StopFillMode.STOP_PRICE, )
from ml4t.backtest import BacktestConfig, DataFeed from ml4t.backtest.config import ExecutionPrice feed = DataFeed( prices_df=quotes, price_col="mid_price", bid_col="bid", ask_col="ask", bid_size_col="bid_size", ask_size_col="ask_size", ) config = BacktestConfig( execution_price=ExecutionPrice.QUOTE_SIDE, mark_price=ExecutionPrice.QUOTE_SIDE, )
With QUOTE_SIDE, buys fill at the ask and sells fill at the bid when quotes are present. mark_price is configured separately, so you can trade on one source and mark the book on another.
Quote-aware runs also preserve the microstructure context in the result surface:
result.to_fills_dataframe() includes bid/ask/midpoint/spread/size contextresult.to_trades_dataframe() includes nullable entry/exit quote summariesresult.to_portfolio_state_dataframe() reflects the configured mark source over timeresult.to_predictions_dataframe() preserves the raw model/input surface for downstream
diagnosticsBacktestConfig is also the serializable backtest preset surface. You can keep
input configs sparse, then persist the fully resolved config that actually ran.
config = BacktestConfig.from_yaml("config/my_backtest.yaml") result = Engine(feed, strategy, config).run() resolved_config = result.config.to_dict() runtime_spec = result.to_spec_dict() written = result.to_parquet("results/run_001")
The exported result directory includes:
config.yaml for the replayable resolved config payloadspec.yaml for the richer runtime snapshot with library version and realized run windowUse top-level feed in BacktestConfig for generic feed semantics and top-level
metadata for user-defined provenance like input paths or strategy ids.
from ml4t.backtest import BacktestConfig, CommissionType from ml4t.backtest.config import SlippageType, SpreadConvention config = BacktestConfig( commission_rate=0.001, # 10 bps percentage slippage_rate=0.0005, # 5 bps slippage stop_slippage_rate=0.001, # Additional slippage for stop exits ) # Or per-share (Interactive Brokers style) config = BacktestConfig( commission_type=CommissionType.PER_SHARE, commission_per_share=0.005, commission_minimum=1.0, ) # Or bar-only spread approximation in currency units config = BacktestConfig( slippage_type=SlippageType.SPREAD, slippage_spread=0.02, slippage_spread_convention=SpreadConvention.FULL_SPREAD, )
from ml4t.backtest import Strategy, TargetWeightExecutor, RebalanceConfig class WeightStrategy(Strategy): def __init__(self): self.executor = TargetWeightExecutor(RebalanceConfig( min_trade_value=100, # Optional: skip tiny dollar trades min_weight_change=0.01, # Optional: skip tiny weight changes )) self.bar_count = 0 def on_data(self, timestamp, data, context, broker): self.bar_count += 1 if self.bar_count % 21 != 1: # Monthly rebalance return # ML predictions → portfolio weights weights = {} for asset, bar in data.items(): signal = bar.get("signals", {}).get("prediction", 0) if signal and signal > 0: weights[asset] = signal if weights: total = sum(weights.values()) weights = {a: w / total for a, w in weights.items()} self.executor.execute(weights, data, broker)
RebalanceConfig defaults both min_trade_value and min_weight_change to
0.0, so these filters are opt-in.
BacktestConfig() defaults to neutral costs: commission_type=NONE and
slippage_type=NONE. Broker-specific fee models and synthetic slippage are
opt-in.
The primary audit uses frozen data and targets from ETF allocation, CME futures, crypto perpetual-funding, FX, and US equity-panel case studies. Profiles configure framework-specific execution behavior, and only genuinely supported framework and asset combinations are required. The real-strategy gate covers 17 required pairs and records eight unsupported pairs separately.
The scenario matrix and 250-asset workload remain useful synthetic diagnostic and stress tests. They do not establish realistic strategy equivalence.
17/17 required pairs pass; 8 pairs are declared unsupported. The audit uses five real-data strategy workloads with frozen historical market data and model-derived targets. A pass requires identical valuation timestamp coverage, complete fill streams with quantities equal at 1e-5 and prices equal at 1e-8, and account monetary values that round to the same cent. The FX workload uses the USD-quoted pairs in its frozen target stream so every required engine uses native USD valuation.
The parity protocol disables transaction costs and position rules on both sides. It tests target sizing, order sequencing, fills, cash and margin behavior, funding where applicable, and valuation. It does not claim to reproduce each selected case-study production result with its original costs and risk overlays.
| Real strategy | Pinned framework | Current result | Evidence |
|---|---|---|---|
| ETF allocation | VectorBT Pro 2026.6.27 | fills equal at declared field precision; 1,995 valuations and terminal exact at 1e-8 | real-strategy evidence |
| ETF allocation | VectorBT OSS 1.1.0 | fills equal at declared field precision; 1,995 valuations and terminal exact at 1e-8 | real-strategy evidence |
| ETF allocation | Backtrader 1.9.78.123 | fills equal at declared field precision; 1,995 valuations and terminal exact at 1e-8 | real-strategy evidence |
| ETF allocation | Zipline Reloaded 3.1.1 | fills equal at declared field precision; 1,995 valuations and terminal exact at 1e-8 | real-strategy evidence |
| ETF allocation | LEAN 18001 | fills equal at declared field precision; 1,995 valuations and terminal exact at 1e-8 | real-strategy evidence |
| CME futures | VectorBT Pro 2026.6.27 | fills equal at declared field precision; 1,595 valuations within $0.01 (max raw gap $0.00000010); terminal within $0.01 (raw gap $0.00000007) | real-strategy evidence |
| CME futures | Backtrader 1.9.78.123 | fills equal at declared field precision; 1,595 valuations within $0.01 (max raw gap $0.00000015); terminal within $0.01 (raw gap $0.00000015) | real-strategy evidence |
| Crypto perpetual funding | LEAN 18001 | fills equal at declared field precision; 2,426 valuations and terminal exact at 1e-8 | real-strategy evidence |
| FX allocation (USD-quoted pairs) | VectorBT Pro 2026.6.27 | fills equal at declared field precision; 2,108 valuations and terminal exact at 1e-8 | real-strategy evidence |
| FX allocation (USD-quoted pairs) | VectorBT OSS 1.1.0 | fills equal at declared field precision; 2,108 valuations and terminal exact at 1e-8 | real-strategy evidence |
| FX allocation (USD-quoted pairs) | Backtrader 1.9.78.123 | fills equal at declared field precision; 2,108 valuations and terminal exact at 1e-8 | real-strategy evidence |
| FX allocation (USD-quoted pairs) | LEAN 18001 | fills equal at declared field precision; 2,108 valuations and terminal exact at 1e-8 | real-strategy evidence |
| US equity panel | VectorBT Pro 2026.6.27 | fills equal at declared field precision; 4,146 valuations within $0.01 (max raw gap $0.00001950); terminal within $0.01 (raw gap $0.00001880) | real-strategy evidence |
| US equity panel | VectorBT OSS 1.1.0 | fills equal at declared field precision; 4,146 valuations within $0.01 (max raw gap $0.00001910); terminal within $0.01 (raw gap $0.00001870) | real-strategy evidence |
| US equity panel | Backtrader 1.9.78.123 | fills equal at declared field precision; 4,146 valuations within $0.01 (max raw gap $0.00000170); terminal within $0.01 (raw gap $0.00000160) | real-strategy evidence |
| US equity panel | Zipline Reloaded 3.1.1 | fills equal at declared field precision; 4,027 valuations within $0.01 (max raw gap $0.00000190); terminal within $0.01 (raw gap $0.00000030) | real-strategy evidence |
| US equity panel | LEAN 18001 | fills equal at declared field precision; 4,027 valuations within $0.01 (max raw gap $0.00000460); terminal within $0.01 (raw gap $0.00000420) | real-strategy evidence |
The table reports engine-call wall time for all 17 correctness-passing pairs. The ratio is framework median / ML4T median; values above 1 mean ML4T completed the engine call faster.
| Real strategy | Pinned framework | Framework median (95% CI), s | ML4T median (95% CI), s | Framework / ML4T median |
|---|---|---|---|---|
| ETF allocation | VectorBT Pro 2026.6.27 | 0.317 (0.297-0.330) | 0.456 (0.452-0.460) | 0.695x |
| ETF allocation | VectorBT OSS 1.1.0 | 0.173 (0.170-0.175) | 0.451 (0.448-0.455) | 0.383x |
| ETF allocation | Backtrader 1.9.78.123 | 9.408 (9.378-9.537) | 0.475 (0.473-0.478) | 19.802x |
| ETF allocation | Zipline Reloaded 3.1.1 | 3.846 (3.841-3.867) | 0.741 (0.737-0.747) | 5.191x |
| ETF allocation | LEAN 18001 | 2.571 (2.515-2.635) | 0.874 (0.868-0.879) | 2.942x |
| CME futures | VectorBT Pro 2026.6.27 | 0.286 (0.283-0.291) | 0.527 (0.524-0.537) | 0.542x |
| CME futures | Backtrader 1.9.78.123 | 2.475 (2.465-2.535) | 0.542 (0.537-0.548) | 4.570x |
| Crypto perpetual funding | LEAN 18001 | 2.793 (2.751-2.871) | 0.744 (0.736-0.753) | 3.753x |
| FX allocation (USD-quoted pairs) | VectorBT Pro 2026.6.27 | 0.291 (0.283-0.294) | 0.159 (0.159-0.161) | 1.828x |
| FX allocation (USD-quoted pairs) | VectorBT OSS 1.1.0 | 0.146 (0.138-0.152) | 0.159 (0.158-0.162) | 0.919x |
| FX allocation (USD-quoted pairs) | Backtrader 1.9.78.123 | 0.439 (0.434-0.447) | 0.163 (0.160-0.164) | 2.701x |
| FX allocation (USD-quoted pairs) | LEAN 18001 | 0.961 (0.935-0.979) | 0.170 (0.168-0.172) | 5.656x |
| US equity panel | VectorBT Pro 2026.6.27 | 0.865 (0.851-1.004) | 24.782 (24.511-24.923) | 0.035x |
| US equity panel | VectorBT OSS 1.1.0 | 17.246 (17.166-17.345) | 25.313 (25.119-25.615) | 0.681x |
| US equity panel | Backtrader 1.9.78.123 | 505.641 (499.073-515.494) | 29.242 (28.887-29.792) | 17.292x |
| US equity panel | Zipline Reloaded 3.1.1 | 110.874 (105.635-113.330) | 25.622 (25.400-26.416) | 4.327x |
| US equity panel | LEAN 18001 | 49.967 (48.757-50.759) | 31.049 (30.472-31.514) | 1.609x |
Backtest measured 2026-10-21; reference measurements dated 2026-10-13 were retained unchanged. Host: Linux-7.0.0-38-generic-x86_64-with-glibc2.43 with 24 logical CPUs. Each side used one isolated warm-up process and ten isolated measured processes. The timer includes only the engine call; it excludes input loading, model inference, target construction, adapter preparation, result extraction, serialization, reporting. These measurements apply only to the named strategy, framework version, frozen input bundle, and machine. Raw samples and bootstrap intervals are retained in real-strategy performance evidence.
A performance-impact review retains these measurements for engine source 6feac2a993ae. The measured source, locked dependencies, review rationale and current correctness evidence are recorded with the raw samples. Measurements are repeated when changes materially affect timed execution; a new source revision alone does not require a benchmark rerun. Dependency validation checks selected packages and artifacts; allowing prereleases without changing those selections does not invalidate the measurements.
The scenario matrix contains synthetic conformance tests. "Exact" means terminal values, ordered closed trades, and ordered fills match after 1e-8 quantization. Each record declares whether a surface is native, reconstructed, aggregate-only, input-only, or unavailable. These results test isolated conventions, not realistic strategy equivalence.
| Profile | Pinned framework | Required scenarios | Evidence |
|---|---|---|---|
vectorbt_strict |
VectorBT Pro 2026.6.27 | 17/17 exact | scenario evidence |
vectorbt_oss_strict |
VectorBT OSS 1.1.0 | 16/16 exact | scenario evidence |
backtrader_strict |
Backtrader 1.9.78.123 | 17/17 exact | scenario evidence |
zipline_strict |
Zipline Reloaded 3.1.1 | 16/16 exact | scenario evidence |
The synthetic stress workload contains 250 assets and 5,040 daily sessions (1,260,000 bars). Every row has zero canonical gap for target intents, native fills, closed trades reconstructed from those fills, and terminal state reconstructed from the fill ledger and final marks. Fill records use 1e-8 precision; monetary totals use cent precision.
| Profile | Current framework | Target intents | Native fills | Fill-derived closed trades | Terminal value | Evidence |
|---|---|---|---|---|---|---|
vectorbt_strict |
VectorBT Pro 2026.6.27 | 427,790 | 423,313 | 222,751 | 1,285,886.320000 | scale evidence |
vectorbt_oss_strict |
VectorBT OSS 1.1.0 | 427,790 | 417,941 | 211,322 | 1,345,348.850000 | scale evidence |
backtrader_strict |
Backtrader 1.9.78.123 | 427,790 | 343,813 | 182,019 | -9,166,273.560000 | scale evidence |
zipline_strict |
Zipline Reloaded 3.1.1 | 427,790 | 427,696 | 226,434 | 10,504,095.900000 | scale evidence |
lean |
LEAN 18001 | 427,790 | 361,297 | 191,297 | 184,538.130000 | scale evidence |
See validation/README.md for methodology and detailed results.
Release-gate commands:
# Fast parity contract gate (scenario 01 across vectorbt/backtrader/zipline) ML4T_COMPARISON_INPROC=1 uv run pytest tests/contracts/test_cross_engine_contracts.py -q # Full correctness runner (selected scenarios) python validation/run_all_correctness.py --framework vectorbt_oss --scenarios 01,03,05,09 python validation/run_all_correctness.py --framework backtrader --scenarios 01,03,05,09 python validation/run_all_correctness.py --framework zipline --scenarios 01,03,05,09
Release performance evidence covers deterministic single-asset, 250-asset daily, quote-aware,
rebalance, and partial-fill workloads. Each workload runs three times in a fresh child process.
The 250-asset workload periodically enters and exits a 50-position portfolio.
The evidence separates setup from Engine.run(), measures peak RSS over the whole child process,
reports runtime and memory sample spread, and verifies retained financial-output checksums and
counts. The dedicated instrument-free hotpath benchmark enforces the runtime regression limit.
Run the release baselines and the instrument-free feed regression check locally:
uv run python validation/performance_baseline.py --output release-performance-evidence.json uv run pytest tests/benchmark/test_hotpath_benchmarks.py::test_optimized_feed_runtime_vs_legacy_baseline --no-cov
Workload definitions and expected checksums are retained in
validation/performance_baselines.json. These ML4T-only measurements are regression baselines,
not cross-machine performance claims.
Cross-framework performance evidence uses a common 50-asset, 252-session controlled workload. Each runner receives one isolated warm-up followed by ten isolated measurements. The retained artifact contains raw samples, whole-process wall time, process-tree peak RSS, deterministic 95% bootstrap intervals, output checksums, framework identities, and semantic disclosures for the idiomatic view. This controlled synthetic workload remains supporting audit evidence rather than the basis for the published real-strategy comparison above.
The real-strategy performance artifact times only engine execution for correctness-passing pairs. Inputs, model inference, target construction, adapter preparation, extraction, and reporting are excluded. The table above publishes the measured ratios with their date, versions, workload, host, and uncertainty. They describe those executions and do not establish a hardware-independent speed ranking.
For the optional NautilusTrader equity and pysystemtrade futures workloads, see the reference comparison commands.
price_col, quote columns, and feed wiringon_prepare receives configuration but no future feed timestampsgit clone https://github.com/ml4t/backtest.git
cd backtest
uv sync --dev --extra docs --locked
uv run ruff check src/ tests/ validation/
uv run ruff format --check src/ tests/ validation/
uv run ty check
uv run pytest tests/ -q
uv run mkdocs build --strictRelease-critical validation files are listed in
validation/release_checks.txt. CI runs the supported gate set,
including compatibility, security, parity, and artifact qualification.
Read CONTRIBUTING.md before filing an issue or pull request.
See LIMITATIONS.md for documented assumptions:
ml4t-live contractML4T Backtest uses the MIT License.
ml4t/backtest is a public repo on GitHub by ml4t. Event-driven backtesting for quantitative strategies with configurable execution, accounting, risk, and framework-parity validation.
It declares the MIT license on GitHub.
Its maker tagged it for macOS, Windows and Linux, or as Docker or cross-platform. That is declared by the maker; Take My Repo has not tested it.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-11-20. GitHub counts 6 open issues and pull requests. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.
"Vibe-Trading: Your Personal Trading Agent"
Dapr is a portable runtime for building distributed applications across cloud and edge, combining event-driven architecture with workflow orchestration.
Qlib is an AI-oriented Quant investment platform that aims to use AI tech to empower Quant Research, from exploring ideas to implementing productions. Qlib supports diverse ML modeling paradigms, including supervised learning, market dynamics modeling, and RL, and is now equipped with https://github.com/microsoft/RD-Agent to automate R&D process.
An asynchronous event driven PHP socket framework. Supports HTTP, Websocket, SSL and other custom protocols.
Market data acquisition, storage, and update workflows for machine learning for trading.

Signal diagnostics, statistical validation, and backtest evaluation for quantitative trading workflows.
Agent skills for Machine Learning for Algorithmic Trading: leakage-safe quant ML, backtesting, validation, and autonomous research workflows.
Feature engineering, labeling, alternative bars, and leakage-safe datasets for financial ML.
Live trading runtime for ML4T strategies with broker integrations, risk checks, and shadow mode.

Finance-specific models for asset pricing, prediction, and portfolio learning.
This page is also available as structured data, with the same sources and dates.
/api/v1/resources/gh/ml4t/backtestTake My Repo has not tested this on your machine. Requirements come from the project's own documentation.