Theming & Templates
Relevant source files
The following files were used as context for generating this wiki page:
Theming and Templates in vectorbt provide a robust framework for customizing the visual representation of data and the logic of performance analysis. This system is split into two primary layers: Visual Theming, which handles Plotly-based aesthetics via JSON templates and CSS, and Functional Templates, which utilize string substitution and object resolution to dynamically build plots and statistics.
Sources: vectorbt/templates/dark.json, vectorbt/generic/plots_builder.py:1
Visual Theming
Visual themes are primarily defined using JSON files that adhere to the Plotly template schema. These templates control the data (trace defaults) and layout (canvas aesthetics) of generated figures.
Core Templates
The project includes several built-in JSON templates:
- Light: The default bright theme using a standard colorway and light grey plot backgrounds. Sources: vectorbt/templates/light.json:445-446
- Dark: A high-contrast theme designed for dark mode interfaces, using a
#1f2536background and light grey text. Sources: vectorbt/templates/dark.json:461-463 - Seaborn: A theme inspired by the Seaborn library, characterized by a grey grid and specific color palette. Sources: vectorbt/templates/seaborn.json:7-18
Theme Configuration Parameters
Templates define granular control over visual elements:
| Component | Description | Example Configuration |
|---|---|---|
| Colorway | A list of colors used sequentially for new traces. | ["#1f77b4", "#ff7f0e", ...] |
| Grid | Color and width of axis grid lines. | gridcolor: "white", gridwidth: 2 |
| Colorscales | Sequential and diverging maps for heatmaps/contours. | Viridis-like scales in light.json |
| Paper/Plot BG | Colors for the outer canvas and internal plot area. | #1f2536 in dark.json |
Sources: vectorbt/templates/dark.json:459-470, vectorbt/templates/light.json:444-455
Functional Templates & Substitution
Functional templates allow for dynamic value resolution during the construction of plots and statistics. This is handled by the vectorbt.utils.template module and integrated into the PlotsBuilderMixin.
Template Types
The system supports several specialized template classes for different substitution needs:
Sub: Performs string-based token substitution (e.g.,$hello).Rep: Replaces a key with a specific value from a mapping.RepEval: Evaluates a string expression within a provided context.RepFunc: Executes a callback function to determine the final value.
Sources: tests/test_utils.py:1085-1100
Logic Flow for Subplot Generation
The plots method uses deep_substitute to resolve template values in layout and subplot settings before the figure is rendered.
A brief explanation shows the hierarchy of substitution: global settings are substituted first, followed by specific subplot overrides during the plotting loop. Sources: vectorbt/generic/plots_builder.py:109-150
Plots & Subplots Architecture
The PlotsBuilderMixin is the core component for building complex dashboards. It manages a subplots configuration that defines how different metrics should be visualized.
Subplot Definition
Each subplot in the subplots Config can contain:
title: The display name of the subplot.plot_func: The function responsible for drawing the trace.xaxis_kwargs/yaxis_kwargs: Specific axis overrides.tags: Metadata for filtering which subplots to display.
Sources: vectorbt/generic/plots_builder.py:84-105
Relationship Diagram
The diagram shows that PlotsBuilderMixin depends on Wrapping and uses a Config object to manage the registry of available subplots. Sources: vectorbt/generic/plots_builder.py:27-50
CSS Theming for Web Applications
For web-based interfaces (such as the Candlestick Patterns app), themes are extended via CSS variables. This allows for a "Modern UI" theme that synchronizes Dash components with the underlying Plotly figures.
Standardized UI Variables
| Variable | Value | Description |
|---|---|---|
--primary | #2563EB | The main accent color for buttons and active states. |
--surface | #ffffff | Background color for card-like containers. |
--text | #0f172a | Primary font color for readability. |
--radius-md | 12px | Standard corner rounding for containers. |
Sources: apps/candlestick-patterns/assets/style.css:7-30
CSS Logic Flow
The CSS architecture uses a :root selector to propagate theme variables through components like app-shell, pretty-container, and input-control.
Sources: apps/candlestick-patterns/assets/style.css:40-100
Conclusion
Theming in vectorbt is a multi-layered system that ensures aesthetic consistency across static plots and interactive web applications. By combining JSON-based Plotly templates, Python-side substitution logic via PlotsBuilderMixin, and CSS-driven UI styling, developers can create sophisticated, brandable financial research dashboards. The use of functional templates further allows these visuals to remain dynamic, responding to underlying data changes and user-defined parameters at runtime.
Sources: vectorbt/generic/plots_builder.py:326-350, vectorbt/templates/dark.json:1-10