Replay & Historical Backtesting
Relevant source files
The following files were used as context for generating this wiki page:
Replay and Historical Backtesting form the core simulation engine of the platform, enabling the evaluation of trading strategies against historical market data. The system allows developers to observe market data in a deterministic fashion, making structured trade decisions (e.g., buy_to_open) and logging reasoning for review or optimization. Integrated replaying capabilities allow for the simulation of historical trades for a given agent by streaming data bar-by-bar to mimic live market conditions.
Sources: PLAN.md:12-19, README.md:39-44, PLANNING.md:4-8
Core Architecture and Data Flow
The backtesting architecture is built around the Cerebro engine, which coordinates data feeds, strategies, and brokers. During a backtest, data is either loaded "all-at-once" for performance or "step-by-step" to facilitate complex logic during strategy evaluation. The replaying mechanism works by adding filters to a data clone, transforming a smaller timeframe (like ticks or daily bars) into a larger timeframe (like weekly or monthly) while updating the strategy at every sub-bar interval.
Sources: README.md:42-43, samples/data-multitimeframe/data-multitimeframe.py:108-124
The Simulation Loop
The simulation follows a structured lifecycle where the strategy's next() method is called for every bar of data. The engine maintains a system clock via the datetime line, ensuring all indicators and data feeds are synchronized.
The diagram above illustrates the iterative flow of a historical backtest where data is processed bar-by-bar through the strategy logic.
Sources: backtrader/strategy.py:270-300, backtrader/strategy.py:469-480
Data Replaying and Resampling
Data replaying is a specialized form of backtesting where the engine simulates the building of a bar. Unlike resampling, which simply aggregates data, replaying provides the strategy with updates as the bar develops. This is critical for strategies that need to make decisions based on intraday price action before a bar closes.
| Feature | Replaying | Resampling |
|---|---|---|
| Primary Goal | Simulate bar building for live-like execution | Aggregate lower frequency data to higher frequency |
| Logic Execution | Executes on every sub-bar tick/update | Executes only when the new bar is completed |
| Classes Used | ReplayerDaily, ReplayerWeekly, ReplayerMonthly | ResamplerDaily, ResamplerWeekly, ResamplerMonthly |
Sources: samples/data-multitimeframe/data-multitimeframe.py:17-26, samples/data-multitimeframe/data-multitimeframe.py:112-124
Data Source Integration
The system supports multiple historical data formats, including CSV, HDF5, and SQL databases. The rewrite-data.py tool demonstrates the ability to convert various formats (Yahoo, MT4, SierraChart, etc.) into the native Backtrader CSV format for standardized backtesting.
Sources: tools/rewrite-data.py:31-43, arbitrage/JM_J_strategy_CUSUM.py:284-295
Strategy Execution and Notifications
In a backtesting environment, the strategy acts as the decision-maker. It receives notifications regarding order status and trade completion, allowing it to manage positions dynamically.
Sequence of interactions between the engine, strategy, and broker during a single bar update.
Key Strategy Components
- Analyzers: Classes that provide technical evaluation of the backtest, such as
SharpeRatio,DrawDown, andReturns. - Observers: Visual components that track
Cash,Trades, andValueover the course of the simulation. - Throttling: A mechanism used to limit trade frequency, ensuring the strategy does not overtrade during volatile periods.
Sources: arbitrage/JM_J_strategy_CUSUM.py:311-325, backtrader/strategy.py:96-120, samples/vctest/vctest.py:46-75
Backtesting Modes
| Mode | Description |
|---|---|
| Standard Backtest | Processes historical data as fast as possible to calculate P&L and metrics. |
| Replay Mode | Streams historical data to simulate the timing and arrival of market ticks. |
| Optimization | Runs the strategy multiple times with varying parameters to find the most effective settings. |
Sources: PLAN.md:31-35, arbitrage/JM_J_strategy_CUSUM.py:340-360
Conclusion
Replay and Historical Backtesting provide a deterministic environment for strategy development. By utilizing modular agents and structured data feeds, the system ensures that trading decisions are explainable and reproducible. The integration of specialized filters for replaying and resampling allows for high-fidelity simulations that closely mirror live trading conditions, encompassing complex order types and broker simulations.
Sources: PLAN.md:52-57, README.md:55-64