Indicators Framework

Relevant source files

The following files were used as context for generating this wiki page:

• vectorbt/indicators/factory.py
• vectorbt/generic/stats_builder.py
• vectorbt/generic/plots_builder.py
• tests/test_plotting.py
• README.md
• rust/README.md
• benchmarks/bench_matrix.py

The Indicators Framework in vectorbt is a high-performance system designed for building, running, and analyzing technical indicators at scale. It leverages a vectorized approach, allowing thousands of parameter combinations to be processed simultaneously across multiple assets. The framework centers around the IndicatorFactory, which automates the creation of standalone indicator classes from User Defined Functions (UDFs).

Sources: vectorbt/indicators/factory.py:1-40, README.md:1-50

This framework integrates deeply with Numba and an optional Rust engine to accelerate calculations. It provides a standardized pipeline for broadcasting inputs, managing parameter grids, and concatenating results into pandas-ready formats, while supporting advanced features like caching, statistical analysis, and interactive visualization.

Sources: vectorbt/indicators/factory.py:42-60, rust/README.md:1-30

Core Architecture

The framework utilizes a factory pattern to generate indicator classes. The architecture is built to handle the transition from raw NumPy/Numba arrays to labeled Pandas objects through an internal pipeline.

The Indicator Pipeline

The run_pipeline function serves as the engine's core, executing a sequence of data transformation steps:

1. Input Broadcasting: Synchronizes shapes of multiple inputs (e.g., OHLCV).
2. Parameter Preparation: Broadcasts parameter grids to match input dimensions.
3. Calculation Execution: Runs the provided UDF (NumPy, Numba, or Rust).
4. Result Stacking: Concatenates results into a single array with multi-index columns.
5. Pandas Wrapping: Re-attaches metadata (index and columns) to the results.

Sources: vectorbt/indicators/factory.py:344-480

Framework Components Diagram

The following diagram illustrates the relationship between the Factory, the generated Indicator class, and the execution engines.

IndicatorFactory Features

The IndicatorFactory provides various methods to wrap external libraries or custom logic into the vectorbt ecosystem.

Calculation Methods

Method	Description	Source
from_apply_func	Simplest way to build indicators by providing a function that calculates one parameter at a time.	factory.py:1184
from_custom_func	Offers full flexibility, requiring the user to handle their own concatenation and looping logic.	factory.py:898
from_talib	Wraps TA-Lib functions, automatically identifying inputs and parameters.	factory.py:1419
from_pandas_ta	Wraps pandas-ta indicators for vectorized execution.	factory.py:1550
from_ta	Integrates indicators from the ta library.	factory.py:1707

Parameter Management

The factory supports complex parameter grids, including Cartesian products (param_product=True) and column-wise application (per_column=True). It also implements run_unique to prevent redundant calculations when parameters repeat across a grid.

Sources: vectorbt/indicators/factory.py:140-200, vectorbt/indicators/factory.py:530-550

Engines and Optimization

The framework supports multiple execution backends to optimize performance based on the complexity of the calculation.

Numba and Rust Integration

While Numba provides Just-In-Time (JIT) compilation for Python functions, the Rust engine offers precompiled speed without JIT overhead. Users can toggle the engine per call or globally via vbt.settings["engine"].

# Per call engine selection
out = vbt.MA.run(close, window=20, engine="rust")

# Global engine setting
vbt.settings["engine"] = "rust"

Sources: rust/README.md:65-85

Benchmarking Parity

Benchmarks compare Numba kernels with Rust implementations to ensure correctness and measure speedups. The framework uses best-of-repeat timing to emphasize steady-state performance.
Sources: benchmarks/bench_matrix.py:30-60, rust/README.md:110-120

Analysis and Visualization

Indicators generated by the framework inherit mixins for statistical analysis and plotting.

Statistics Builder

The StatsBuilderMixin allows indicators to calculate performance metrics across columns or groups.

• Metrics: Predefined or custom calculations (e.g., total_return, win_rate).
• Aggregation: Ability to aggregate stats across assets using functions like np.mean.
  Sources: vectorbt/generic/stats_builder.py:40-100

Subplot Builder

The PlotsBuilderMixin enables the creation of complex, multi-row interactive figures using Plotly.

• Subplots: Preconfigured views such as orders, cum_returns, or drawdowns.
• Trace Updating: Wrappers like Scatter, Bar, and Heatmap handle data updates within subplots.
  Sources: vectorbt/generic/plots_builder.py:50-120, tests/test_plotting.py:380-450

Visualization Flow

Summary

The Indicators Framework is a modular system that abstracts the complexities of vectorized backtesting. By centralizing the logic for broadcasting, engine dispatching, and pandas integration in the IndicatorFactory, it enables developers to focus on signal logic while the framework handles the scalability and performance requirements of processing large datasets.

Sources: vectorbt/indicators/factory.py:1-60, README.md:1-20