Signals Framework
Relevant source files
The following files were used as context for generating this wiki page:
The Signals Framework in vectorbt provides a specialized toolset for generating, manipulating, and analyzing boolean signal series (typically representing entry and exit points in a trading strategy). It is built upon the library's core vectorized architecture, leveraging NumPy and Numba (with optional Rust acceleration) to process thousands of signal combinations simultaneously across matrices of data.
At its core, the framework treats signals as boolean NumPy arrays where True indicates the presence of a signal. These arrays are enhanced with custom pandas accessors (vbt.signals) that provide high-level methods for signal cleaning, random generation, ranking, and statistical performance evaluation. This infrastructure is a critical precursor to the Portfolio Management system, which consumes these signals to simulate trades.
Sources: vectorbt/signals/accessors.py:1-40, README.md:12-25
Signal Accessors
The framework extends pandas Series and DataFrames via the SignalsSRAccessor and SignalsDFAccessor. These accessors require the underlying data to be of boolean type (np.bool_). They provide a unified interface for operations that would otherwise require complex manual boolean masking.
Core Architecture
The following class diagram illustrates the relationship between the signal accessors and the generic library infrastructure:
The accessors implement logic for broadcasting across columns and handle Numba-compiled dispatching for heavy computational tasks.
Sources: vectorbt/signals/accessors.py:105-125, vectorbt/generic/stats_builder.py:30-45
Signal Generation
Signals can be generated manually using factory functions, randomly based on probabilities, or dynamically based on price action (e.g., stops).
Random Signal Generation
The framework supports generating random signals either by specifying the total number of signals (n) per column or by a specific probability (prob) for each time step.
| Method | Parameter | Description |
|---|---|---|
generate_random | n | Generates exactly n signals at random indices. |
generate_random | prob | Each index has prob chance of being True. |
generate_random_both | entry_prob/exit_prob | Generates paired entry/exit chains randomly. |
Sources: vectorbt/signals/accessors.py:382-415, vectorbt/signals/accessors.py:465-490
Stop Signal Generation
One of the most powerful features is the ability to generate exit signals based on price hitting specific thresholds relative to an entry price.
- OHLC Stops: Generates exits based on High/Low/Close prices hitting Take Profit (TP), Stop Loss (SL), or Trailing Stop Loss thresholds.
- Standard Stops: Generates exits when a single time series (e.g., closing price) crosses a fixed or trailing percentage threshold.
Sources: vectorbt/signals/accessors.py:643-680, vectorbt/portfolio/nb.py:1082-1105
Signal Analysis and Ranking
Once signals are generated, the framework provides tools to rank them within their respective "partitions" (sequences of consecutive True values).
Ranking Logic
Ranking allows developers to filter signals (e.g., only take the first signal of a cluster).
| Function | Description |
|---|---|
pos_rank | Assigns an incremental rank to every True value in a sequence. |
partition_pos_rank | Ranks entire clusters of signals rather than individual points. |
first | Filters the array to keep only the first signal of every partition (pos_rank == 0). |
nth | Selects specific signals in a sequence. |
Sources: vectorbt/signals/accessors.py:900-930, vectorbt/signals/accessors.py:1020-1045
Statistical Metrics
The stats() method provides a comprehensive summary of signal distribution and frequency.
Key metrics include:
- Rate %: The percentage of indices that contain a signal.
- Norm Avg Index: Measures signal location relative to the middle of the column (-1 to 1).
- Total Overlapping: Calculates how many signals coincide with a second "other" signal array.
Sources: vectorbt/signals/accessors.py:1158-1250, vectorbt/generic/stats_builder.py:90-120
Integration with Portfolio Modeling
The ultimate consumer of signals is the portfolio simulation engine. Signals are cleaned and resolved before being converted into orders.
Signal Resolution Pipeline
When signals are passed to Portfolio.from_signals, they undergo a resolution process to handle conflicts:
- Conflict Resolution: If both an entry and an exit occur at the same time step, the framework applies a
ConflictMode(e.g., ignore exit, ignore entry, or choose based on current position). - Direction Resolution: Handles conflicts between long and short signals using
DirectionConflictMode. - Opposite Entry: Determines behavior when a short entry signal occurs while in a long position (e.g., ignore, close, or reverse).
Sources: vectorbt/portfolio/nb.py:1130-1160, vectorbt/portfolio/nb.py:1195-1225
Conclusion
The Signals Framework provides the necessary abstraction for high-performance signal research. By treating signals as vectorized boolean masks and providing specialized accessors, it allows developers to build complex entry/exit logic that can be tested across thousands of parameters. Its tight integration with Numba-accelerated kernels ensures that signal cleaning, ranking, and stop-loss generation remain efficient even with massive datasets.
Sources: README.md:25-35, vectorbt/signals/accessors.py:20-50