Global Configuration & Settings
Relevant source files
The following files were used as context for generating this wiki page:
VectorBT utilizes a centralized, nested configuration system to manage global behaviors across the library. This system governs everything from computational engines (Numba vs. Rust) to plotting themes, data handling, and backtesting defaults. The configuration is primarily accessed and modified through the vectorbt.settings object, which provides a consistent interface for both getting and setting parameters that affect the library's state at runtime.
The settings system is built upon a hierarchy of Config objects, allowing for granular control over sub-packages (e.g., data), modules (e.g., array_wrapper), and specific builder classes (e.g., stats_builder). Changes to these settings typically take effect immediately, though their impact depends on whether the target component resolves settings at call-time or instantiation.
Sources: vectorbt/_settings.py:5-30, vectorbt/init.py:12-14
Architecture and Components
The configuration architecture is centered around the SettingsConfig class, which extends the base Config utility. It is designed to be a nested structure where specific keys are "frozen" to maintain the integrity of the configuration tree while allowing the values within those keys to remain mutable.
Core Configuration Classes
- Config: The base class for handling dictionary-like configuration data with support for nested updates and persistence.
- SettingsConfig: A specialized subclass used for the global
settingsobject. It includes methods for managing Plotly themes and templates. - StatsBuilderMixin / PlotsBuilderMixin: These mixins integrate with the global settings to provide default metrics and subplots for analysis objects.
The following class diagram illustrates the relationship between the global settings and the underlying configuration utilities:
The diagram shows how SettingsConfig inherits from the base Config and serves as the data provider for performance building mixins.
Sources: vectorbt/_settings.py:101-118, vectorbt/generic/stats_builder.py:44-53, vectorbt/utils/config.py
Key Configuration Modules
The settings object is partitioned into several functional areas. Each area contains sub-configs relevant to specific vectorbt operations.
| Sub-Config | Description | Key Parameters |
|---|---|---|
engine | Primary computation engine. | auto, numba, rust |
caching | Global caching behavior for wrappers and decorators. | enabled, whitelist, blacklist |
broadcasting | Logic for aligning indices and columns across arrays. | align_index, index_from, drop_redundant |
data | Defaults for data downloading and preprocessing. | tz_localize, missing_index, api_key |
plotting | Global visualization settings and themes. | color_schema, layout, themes |
portfolio | Default parameters for backtesting simulations. | init_cash, fees, slippage, size_type |
Sources: vectorbt/_settings.py:126-300
Computation Engine Management
VectorBT supports multiple execution backends. The engine setting determines which backend is prioritized for high-performance kernels.
The flow shows the resolution logic for selecting the computational backend based on the global engine configuration.
Sources: vectorbt/_settings.py:127, rust/README.md:65-75
Theming and Visualization Settings
The plotting sub-config handles the visual representation of data. It includes pre-defined themes (light, dark, seaborn) and template management via Plotly.
Theme Registration Logic
When vbt.settings.set_theme(theme) is called, the system performs several actions:
- Registers the theme's JSON template with
plotly.io.templates. - Updates the active
color_schemawithin the configuration. - Sets the default Plotly layout template to the new
vbt_prefixed theme.
Sources: vectorbt/_settings.py:104-118, vectorbt/templates/light.json
Integration with Performance Builders
The StatsBuilderMixin and PlotsBuilderMixin use the global configuration to resolve default behaviors for the stats() and plots() methods. They merge local instance settings with the defaults found in vbt.settings['stats_builder'] and vbt.settings['plots_builder'].
Settings Resolution Flow
- Defaults Retrieval: Mixins pull
stats_defaultsorplots_defaultsfrom global settings. - User Overrides: User-provided arguments in the method call are merged with defaults.
- Self-Resolution: The mixin resolves its own state (e.g., handling grouping or column selection) based on the merged settings.
- Filter Application: Metrics or subplots are filtered based on criteria defined in the configuration (e.g.,
has_freq).
Sources: vectorbt/generic/stats_builder.py:75-80, vectorbt/generic/plots_builder.py:46-51, vectorbt/generic/stats_builder.py:228-260
Persistence and Documentation
Configurations can be serialized to disk using the save method and reloaded into an existing settings object using load_update. For documentation purposes, the vectorbt.utils.docs module provides utilities like to_doc() to convert complex nested configurations into readable JSON strings.
# Saving and loading settings
vbt.settings.save('my_custom_config')
vbt.settings['caching']['enabled'] = False
vbt.settings.load_update('my_custom_config')
Sources: vectorbt/_settings.py:75-84, vectorbt/utils/docs.py:45-55
Summary
The Global Configuration & Settings system provides a robust framework for managing the state and behavior of the vectorbt library. By centralizing parameters for computation, data, and visualization, it allows users to define consistent environments for large-scale backtesting and research. The nested structure and mixin integration ensure that default behaviors remain flexible yet predictable across different modules.