Labels Generation
Relevant source files
The following files were used as context for generating this wiki page:
Labels Generation in vectorbt provides a specialized framework for building look-ahead indicators and target labels, primarily used for machine learning workflows and strategy robustness testing. This module allows developers to transform raw price data into categorized or numerical signals based on future price movements, a process often referred to as "labeling" in financial data science.
The system is built upon the IndicatorFactory, which abstracts the underlying Numba or Rust kernels into high-level Python objects. These generators support complex broadcasting, allowing for the simultaneous generation of labels across thousands of parameter combinations and multiple assets.
Sources: vectorbt/labels/generators.py:1-10, README.md:52-53
Architecture and Components
The Label Generation module utilizes a hierarchical structure where high-level generators interface with optimized dispatchers. These dispatchers subsequently execute high-performance kernels written in Numba or Rust.
Component Relationship
The following diagram illustrates how label generators are constructed and how they interact with the broader vectorbt ecosystem:
The label generation system inherits from Wrapping, enabling it to utilize StatsBuilderMixin for performance metrics and PlotsBuilderMixin for visual analysis.
Sources: vectorbt/labels/generators.py:12-19, vectorbt/generic/stats_builder.py:38-40, vectorbt/generic/plots_builder.py:38-40
Look-Ahead Indicators
Look-ahead indicators are a subset of label generation that calculate statistical values based on a forward-looking window. These are essential for creating "ground truth" values in predictive modeling.
| Indicator | Description | Parameters |
|---|---|---|
FMEAN | Future Mean: Calculates the mean of prices in a future window. | window, ewm, wait, adjust |
FSTD | Future Standard Deviation: Calculates the volatility in a future window. | window, ewm, wait, adjust, ddof |
FMIN | Future Minimum: Identifies the lowest price in a future window. | window, wait |
FMAX | Future Maximum: Identifies the highest price in a future window. | window, wait |
Sources: vectorbt/labels/generators.py:12-61, vectorbt/labels/init.py:8-11
Label Generators
Label generators transform data into discrete or continuous target variables based on specific logic, such as trend detection or breakout identification.
Fixed and Mean Labels
FIXLB and MEANLB provide fundamental labeling based on fixed horizons or moving averages.
- FIXLB: Generates fixed labels based on a look-ahead of
nperiods. - MEANLB: Generates labels based on the future mean relative to the current price, supporting Exponential Weighted Moving (EWM) configurations.
Sources: vectorbt/labels/generators.py:72-101
Advanced Labeling Logic
Vectorbt provides more complex generators for capturing specific market regimes:
- LEXLB (Local Extrema): Labels data points as local maxima or minima based on positive (
pos_th) and negative (neg_th) thresholds. - TRENDLB (Trend Labels): Identifies market trends. It supports different modes, such as
TrendMode.Binary, to categorize price action as uptrends or downtrends. - BOLB (Breakout Labels): Detects price breakouts relative to a look-back window and specific thresholds.
Sources: vectorbt/labels/generators.py:103-162, vectorbt/labels/init.py:8-9
Visualization and Analysis
Every label generator produced by the IndicatorFactory includes a standard plot method. This method overlays the original close price data with a heatmap representing the generated labels, allowing for immediate visual verification of the labeling logic.
def _plot(self, column=None, **kwargs):
self_col = self.select_one(column=column, group_by=False)
return self_col.close.rename("close").vbt.overlay_with_heatmap(
self_col.labels.rename("labels"), **kwargs)
Sources: vectorbt/labels/generators.py:66-70
Integration with Stats and Plots Builders
Label generators utilize the StatsBuilderMixin and PlotsBuilderMixin to provide structured analysis:
- StatsBuilderMixin: Implements the
stats()method, allowing users to compute various performance metrics on the generated labels. It uses aConfigobject to define supported metrics likestart,end, andperiod. - PlotsBuilderMixin: Implements the
plots()method, which can aggregate multiple subplots into a single interactive figure.
Sources: vectorbt/generic/stats_builder.py:64-74, vectorbt/generic/plots_builder.py:64-74
Summary
Labels Generation in vectorbt is a high-performance framework for creating predictive targets. By leveraging IndicatorFactory and optimized backends (Numba/Rust), it allows for large-scale generation of statistical and categorical labels across massive datasets. The integration with StatsBuilderMixin and PlotsBuilderMixin ensures that generated labels are not only computed quickly but are also easily analyzed and visualized within the standard vectorbt workflow.