Walk-Forward & Splitters
Relevant source files
The following files were used as context for generating this wiki page:
Walk-forward optimization and data splitting are core components of the vectorbt framework used for robustness testing and machine learning workflows. This system allows users to partition time-series data into multiple training and testing windows (ranges) to validate strategy performance across different market regimes.
Sources: README.md:47
Architecture Overview
The system is built upon a high-performance backend implemented in Rust, which manages the identification and calculation of temporal ranges. These ranges are then wrapped in Python classes that utilize mixins for statistical analysis and interactive visualization.
The flow demonstrates how raw data is transformed into structured range records in the backend before being presented through analytical mixins.
Sources: rust/src/generic.rs:71-125, vectorbt/generic/plots_builder.py:38-50, vectorbt/generic/stats_builder.py:44-55
Range Detection and Records
At the lowest level, ranges are represented by the RangeRecord structure. This structure tracks the lifecycle of a split or a specific window within the data.
RangeRecord Data Model
| Field | Type | Description |
|---|---|---|
id | i64 | Unique identifier for the range. |
col | i64 | The column index the range belongs to. |
start_idx | i64 | Starting position in the time series. |
end_idx | i64 | Ending position in the time series. |
status | i64 | Indicates if the range is Open (0) or Closed (1). |
Sources: rust/src/generic.rs:71-77, rust/src/generic.rs:13-14
Range Identification Logic
The detection engine (find_ranges) scans 2D arrays to identify contiguous blocks of valid data separated by a defined gap_value (often NaN). This logic is used by splitters to determine available windows for training and testing.
This flowchart illustrates the logic implemented in the Rust backend for identifying contiguous ranges within a dataset.
Sources: rust/src/generic.rs:1044-1110
Analytical Metrics
Once ranges are identified, the system calculates several key metrics to evaluate the splitting configuration:
- Duration: Calculated as
end_idx - start_idxfor closed ranges, orend_idx - start_idx + 1for open ranges. - Coverage: Determines the percentage of the total index covered by the identified ranges.
- Overlapping: A boolean flag to calculate metrics specifically for regions where multiple ranges intersect.
- Mask Generation: The ability to convert a collection of ranges back into a boolean mask for array filtering.
Sources: rust/src/generic.rs:1112-1118, rust/src/generic.rs:1121-1158
Statistics and Plotting Integration
The range system integrates with vectorbt's mixin architecture to provide standardized interfaces for data inspection.
Statistics Builder
The StatsBuilderMixin enables the calculation of metrics across all ranges. Key metrics include:
- Start/End: The timestamps of the range boundaries.
- Period: The total duration of the range.
- Custom Metrics: Users can define
calc_functo compute specific values for each training/testing split.
Sources: vectorbt/generic/stats_builder.py:72-83
Interactive Visualization
The PlotsBuilderMixin allows for the visual representation of walk-forward splits. The standard plotting implementation creates a multi-trace Plotly figure.
The sequence shows how the plotting orchestrator combines different trace types and shapes to visualize data splits.
Sources: tests/test_plotting.py:539-556, vectorbt/generic/plots_builder.py:302-340
Visual Components
| Component | Trace Type | Purpose |
|---|---|---|
| Start | go.Scatter | Marks the beginning of a split window. |
| Closed | go.Scatter | Marks the end of a finalized testing/training window. |
| Open | go.Scatter | Marks the current progress of an active window. |
| Zones | layout.shapes | Rectangular boxes highlighting the duration of the range. |
Sources: tests/test_plotting.py:545-573
Summary
The Walk-Forward and Splitters system provides a high-performance framework for time-series validation. By leveraging a Rust backend for range detection and Python mixins for analysis, it ensures that strategy optimization remains both fast and interpretable. The integration with PlotsBuilderMixin and StatsBuilderMixin allows developers to easily transition from raw data splits to comprehensive robustness reports.
Sources: rust/src/generic.rs:1044, README.md:15, vectorbt/generic/stats_builder.py:100