Interactive Plotting
Relevant source files
The following files were used as context for generating this wiki page:
Interactive Plotting in vectorbt provides a high-level framework for generating complex, multi-panel visualizations of financial data and backtesting results. It leverages Plotly as the primary engine to create responsive charts that support zooming, hovering, and dynamic updates within Jupyter environments or web applications. Sources: README.md:1-25, apps/candlestick-patterns/app.py:1-60
The system is built on a "Plots Builder" architecture that allows developers to compose figures from reusable subplot definitions. This enables the generation of comprehensive dashboards—such as portfolio performance overviews—with a single function call, while maintaining fine-grained control over layout, themes, and trace interactions. Sources: vectorbt/generic/plots_builder.py:20-50, vectorbt/generic/accessors.py:1700-1750
Core Architecture
The plotting system follows a mixin-based architecture centered around the PlotsBuilderMixin. This mixin provides the plots() method, which acts as an orchestrator for resolving subplot configurations, managing figure layout, and executing individual plotting functions. Sources: vectorbt/generic/plots_builder.py:28-40
Plot Composition Flow
The following diagram illustrates how vectorbt transforms high-level subplot requests into a final interactive Plotly figure:
The flow ensures that settings are merged from global defaults down to specific subplot overrides before the actual rendering occurs. Sources: vectorbt/generic/plots_builder.py:100-350
Plots Builder Mixin
The PlotsBuilderMixin defines the infrastructure for any object (like a Portfolio or Indicator) to support automated multi-plotting. It relies on a subplots configuration object—a Config instance that maps subplot names to their respective plotting functions and default settings. Sources: vectorbt/generic/plots_builder.py:35-70
Configuration Parameters
Subplots are defined using a dictionary with several functional keys:
| Key | Description |
|---|---|
title | The display title for the subplot. |
plot_func | The callable (or attribute path) responsible for adding traces to the figure. |
xaxis_kwargs | Layout parameters for the subplot's X-axis (e.g., titles, grid). |
yaxis_kwargs | Layout parameters for the subplot's Y-axis. |
tags | Meta-information used to filter subplots during batch generation. |
resolve_plot_func | Boolean indicating if the function should be resolved via attribute traversal. |
Sources: vectorbt/generic/plots_builder.py:105-140
Subplot Generation and Logic
The plots() method handles the complexities of subplot placement, including shared axes and spacing. It automatically calculates the height and width of the figure based on the number of rows and columns required. Sources: vectorbt/generic/plots_builder.py:260-310
Logic Components
- Tag Filtering: Users can request subplots by tags (e.g.,
tags='orders'), allowing for thematic views of data. Sources: vectorbt/generic/plots_builder.py:160-170, tests/test_plotting.py:530-540 - Attribute Resolution: The system can "request" arguments for its
plot_funcby inspecting the function signature. It can automatically pass the object itself (self), the currentcolumn, or layout-specific references likexrefandyref. Sources: vectorbt/generic/plots_builder.py:375-410 - Legend Management: To prevent cluttered interfaces, the builder identifies identical traces across different subplots and can hide redundant legend entries or group them using
legendgroup. Sources: vectorbt/generic/plots_builder.py:440-470
Figure Utilities and Customization
vectorbt uses customized factory functions to initialize Plotly figures, ensuring they adhere to project-wide settings and themes. Sources: vectorbt/utils/figure.py:1-50
make_figure and make_subplots
make_figure: Initializes aFigureorFigureWidget(for Jupyter) with default layouts including margins and sizes defined in the global settings. Sources: tests/test_plotting.py:115-135make_subplots: A wrapper around Plotly's subplot utility that integrates with vectorbt's theme system (e.g., "light", "dark", or "seaborn"). Sources: vectorbt/utils/figure.py:10-30, vectorbt/templates/light.json:1-50
Visual Consistency
The system supports multiple templates (JSON-based) that define colorscales, font colors, and grid styles. For example, the light.json template defines a specific colorway for traces to ensure distinct visualization of multiple data series. Sources: vectorbt/templates/light.json:410-450, apps/candlestick-patterns/app.py:80-100
Interactive Dash Integration
Beyond static or Jupyter-based plots, vectorbt facilitates the creation of interactive web dashboards via frameworks like Dash. Sources: apps/candlestick-patterns/app.py:50-100
Application Components
- Dynamic Callbacks: Visualizations are updated in real-time based on user inputs (e.g., changing a ticker or pattern recognition parameters). Sources: apps/candlestick-patterns/app.py:440-480
- Graph Interaction: Users can interact with OHLCV charts via tools like "Box Select" or "Lasso Select" to filter signals, which then triggers a re-simulation of the backtest. Sources: apps/candlestick-patterns/app.py:150-160, apps/candlestick-patterns/app.py:610-630
Summary
Interactive Plotting in vectorbt is a structured framework that bridges the gap between raw data analysis and visual storytelling. By combining a flexible subplot composition engine (PlotsBuilderMixin) with specialized trace wrappers (Scatter, Bar, Heatmap) and deep integration with the Plotly/Dash ecosystem, it enables scalable and insightful financial visualizations. Sources: vectorbt/generic/plots_builder.py:20-50, tests/test_plotting.py:20-50