# Fundamentals (/documentation/fundamentals) VBT was designed to address common performance challenges present in many backtesting libraries. It is built on the idea that each trading strategy instance can be represented in a vectorized format. This method allows multiple strategy instances to be combined into a single multi-dimensional array, enabling highly efficient processing and straightforward analysis. ## Stack \[#stack] Since trading data is time-series based, most aspects of backtesting can be represented as arrays. In particular, VBT works with [NumPy arrays](https://numpy.org/doc/stable/user/quickstart.html), which are ***very fast*** thanks to optimized, pre-compiled C code. NumPy arrays are supported by many scientific packages in the dynamic Python ecosystem, including Pandas, NumPy, and Numba. There is a good chance you have already used some of these packages! While NumPy offers excellent performance, it is not always the most intuitive tool for time series analysis. Consider the following moving average example using NumPy: ```python >>> from vectorbtpro import * >>> def rolling_window(a, window): ... shape = a.shape[:-1] + (a.shape[-1] - window + 1, window) ... strides = a.strides + (a.strides[-1],) ... return np.lib.stride_tricks.as_strided(a, shape=shape, strides=strides) >>> np.mean(rolling_window(np.arange(10), 3), axis=1) array([1., 2., 3., 4., 5., 6., 7., 8.]) ``` While this approach is very fast, it can take some time to understand what is happening, and it requires experience to write such vectorized code correctly. What about other rolling functions used in more advanced indicators? And what about resampling, grouping, and other operations involving dates and times? This is where [Pandas](https://pandas.pydata.org/docs/getting_started/overview.html) comes to the rescue! Pandas offers rich time series features, data alignment, NA-friendly statistics, groupby, merge and join methods, and many other useful tools. It has two primary data structures: [Series](https://pandas.pydata.org/docs/reference/api/pandas.Series.html) (one-dimensional) and [DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) (two-dimensional). You can think of them as NumPy arrays enhanced with valuable information like timestamps and column names. Our moving average can be written in a single line: ```python >>> index = vbt.date_range("2020-01-01", periods=10) >>> sr = pd.Series(range(len(index)), index=index) >>> sr.rolling(3).mean() 2020-01-01 NaN 2020-01-02 NaN 2020-01-03 1.0 2020-01-04 2.0 2020-01-05 3.0 2020-01-06 4.0 2020-01-07 5.0 2020-01-08 6.0 2020-01-09 7.0 2020-01-10 8.0 Freq: D, dtype: float64 ``` VBT depends heavily on Pandas, but not in the way you might expect. Pandas has one major limitation for our purposes: it becomes slow when working with large datasets and user-defined functions. Many built-in functions like the rolling mean use [Cython](https://cython.org/) under the hood, making them fast enough. However, when you try to implement a more complex function, such as a rolling ranking metric involving multiple time series, things become complicated and slow. Additionally, what about functions that cannot be vectorized? For example, a portfolio strategy with money management cannot be simulated directly with vector calculations. In such cases, we need to write fast, iterative code that processes data element-by-element. What if I told you there is a Python package that lets you run for-loops at machine code speed? And that it works seamlessly with NumPy and does not require you to heavily modify your Python code? This would solve many of our problems: our code would become incredibly fast while remaining easy to read. This package is [Numba](https://numba.pydata.org/numba-doc/latest/user/5minguide.html). Numba converts a subset of Python and NumPy code into efficient machine code. ```python >>> @njit ... def moving_average_nb(a, window_len): ... b = np.empty_like(a, dtype=float_) ... for i in range(len(a)): ... window_start = max(0, i + 1 - window_len) ... window_end = i + 1 ... if window_end - window_start < window_len: ... b[i] = np.nan ... else: ... b[i] = np.mean(a[window_start:window_end]) ... return b >>> moving_average_nb(np.arange(10), 3) array([nan, nan, 1., 2., 3., 4., 5., 6., 7., 8.]) ``` Now we can clearly see what is happening: we loop over the time series one timestamp at a time, check if there is enough data in the window, and if so, calculate its mean. Not only does Numba help produce more readable and less error-prone code, it is also as fast as [C](https://en.wikipedia.org/wiki/C_\(programming_language\))! ```python >>> big_a = np.arange(1000000) >>> %timeit moving_average_nb.py_func(big_a, 10) # (1)! 6.54 s ± 142 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) >>> %timeit np.mean(rolling_window(big_a, 10), axis=1) # (2)! 24.7 ms ± 173 µs per loop (mean ± std. dev. of 7 runs, 10 loops each) >>> %timeit pd.Series(big_a).rolling(10).mean() # (3)! 10.2 ms ± 309 µs per loop (mean ± std. dev. of 7 runs, 100 loops each) >>> %timeit moving_average_nb(big_a, 10) # (4)! 5.12 ms ± 7.21 µs per loop (mean ± std. dev. of 7 runs, 100 loops each) ``` 1. Python. 2. NumPy. 3. Pandas. 4. Numba! !!! tip If you are curious about how VBT uses Numba, look for any directory or file named `nb`. [This sub-package](https://github.com/polakowo/vectorbt.pro/blob/main/vectorbtpro/generic/nb/) contains all the basic functions, while [this module](https://github.com/polakowo/vectorbt.pro/blob/main/vectorbtpro/portfolio/nb/from_order_func.py) handles some advanced topics (⚠️ adults only). So, where is the catch? Unfortunately, Numba only understands NumPy, not Pandas. This means we lose the datetime index and other features essential for time series analysis. This is where VBT comes in: it replicates many Pandas functions using Numba and even adds new features to them. As a result, we not only make a subset of Pandas faster, but also more powerful! Here is how it works: 1. Extract the NumPy array from the Pandas object. 2. Run a Numba-compiled function on this array. 3. Wrap the result back using Pandas. ```python >>> arr = sr.values >>> result = moving_average_nb(arr, 3) >>> new_sr = pd.Series(result, index=sr.index, name=sr.name) >>> new_sr 2020-01-01 NaN 2020-01-02 NaN 2020-01-03 1.0 2020-01-04 2.0 2020-01-05 3.0 2020-01-06 4.0 2020-01-07 5.0 2020-01-08 6.0 2020-01-09 7.0 2020-01-10 8.0 Freq: D, dtype: float64 ``` Or, using VBT: ```python >>> sr.vbt.rolling_mean(3) 2020-01-01 NaN 2020-01-02 NaN 2020-01-03 1.0 2020-01-04 2.0 2020-01-05 3.0 2020-01-06 4.0 2020-01-07 5.0 2020-01-08 6.0 2020-01-09 7.0 2020-01-10 8.0 Freq: D, dtype: float64 ``` ## Accessors \[#accessors] Notice how `vbt` is attached directly to the Series object? This is called [an accessor](https://pandas.pydata.org/docs/development/extending.html#registering-custom-accessors) – a convenient way to extend Pandas objects without subclassing them. With an accessor, you can easily switch between native Pandas and VBT functionality. In addition, each VBT method is flexible with inputs and can work on both Series and DataFrames. ```python >>> df = pd.DataFrame({'a': range(10), 'b': range(9, -1, -1)}) >>> df.vbt.rolling_mean(3) a b 0 NaN NaN 1 NaN NaN 2 1.0 8.0 3 2.0 7.0 4 3.0 6.0 5 4.0 5.0 6 5.0 4.0 7 6.0 3.0 8 7.0 2.0 9 8.0 1.0 ``` You can learn more about VBT's accessors in the API documentation. For example, `rolling_mean` is part of the accessor `GenericAccessor`, which you can access directly using `vbt`. Another popular accessor, `ReturnsAccessor`, is used for processing returns. It is a subclass of `GenericAccessor` and can be accessed using `vbt.returns`. ```python >>> ret = pd.Series([0.1, 0.2, -0.1]) >>> ret.vbt.returns.total() 0.18800000000000017 ``` !!! warning Each accessor expects the data to be in a ready-to-use format. For example, the accessor for working with returns expects the data to be returns, not prices! ## Multidimensionality \[#multidimensionality] Remember that VBT differs from traditional backtesters by handling trading data as multi-dimensional arrays. Specifically, VBT treats each column as a separate backtesting instance rather than a feature. Consider a simple OHLC DataFrame: ```python >>> p1 = pd.DataFrame({ ... 'open': [1, 2, 3, 4, 5], ... 'high': [2.5, 3.5, 4.5, 5.5, 6.5], ... 'low': [0.5, 1.5, 2.5, 3.5, 4.5], ... 'close': [2, 3, 4, 5, 6] ... }, index=vbt.date_range("2020-01-01", periods=5)) >>> p1 open high low close 2020-01-01 1 2.5 0.5 2 2020-01-02 2 3.5 1.5 3 2020-01-03 3 4.5 2.5 4 2020-01-04 4 5.5 3.5 5 2020-01-05 5 6.5 4.5 6 ``` Here, the columns are separate features describing the same abstract object: price. Although it may feel natural to pass this DataFrame to VBT (as you might with [scikit-learn](https://scikit-learn.org/stable/) and other ML tools that expect DataFrames with features as columns), this approach has several drawbacks in backtesting: 1. Features of different lengths or types are difficult to concatenate with NumPy. 2. Optional features cannot be properly represented as arrays. 3. Multiple backtests could be stacked into a 3-dimensional array (cube), but Pandas would not handle this correctly. 4. Non-changing features and constants would need to be converted into arrays and replicated across all backtests, resulting in memory waste. VBT manages this variability of features by processing them as separate arrays. So, instead of passing one large DataFrame, you provide each feature independently: ```python >>> single_pf = vbt.Portfolio.from_holding( ... open=p1['open'], ... high=p1['high'], ... low=p1['low'], ... close=p1['close'] ... ) >>> single_pf.value 2020-01-01 100.0 2020-01-02 150.0 2020-01-03 200.0 2020-01-04 250.0 2020-01-05 300.0 Freq: D, dtype: float64 ``` Now, if you want to process multiple abstract objects, such as ticker symbols, you can simply pass DataFrames instead of Series: ```python >>> p2 = pd.DataFrame({ ... 'open': [6, 5, 4, 3, 2], ... 'high': [6.5, 5.5, 4.5, 3.5, 2.5], ... 'low': [4.5, 3.5, 2.5, 1.5, 0.5], ... 'close': [5, 4, 3, 2, 1] ... }, index=vbt.date_range("2020-01-01", periods=5)) >>> p2 open high low close 2020-01-01 6 6.5 4.5 5 2020-01-02 5 5.5 3.5 4 2020-01-03 4 4.5 2.5 3 2020-01-04 3 3.5 1.5 2 2020-01-05 2 2.5 0.5 1 >>> multi_open = pd.DataFrame({ ... 'p1': p1['open'], ... 'p2': p2['open'] ... }) >>> multi_high = pd.DataFrame({ ... 'p1': p1['high'], ... 'p2': p2['high'] ... }) >>> multi_low = pd.DataFrame({ ... 'p1': p1['low'], ... 'p2': p2['low'] ... }) >>> multi_close = pd.DataFrame({ ... 'p1': p1['close'], ... 'p2': p2['close'] ... }) >>> multi_pf = vbt.Portfolio.from_holding( ... open=multi_open, ... high=multi_high, ... low=multi_low, ... close=multi_close ... ) >>> multi_pf.value p1 p2 2020-01-01 100.0 100.0 2020-01-02 150.0 80.0 2020-01-03 200.0 60.0 2020-01-04 250.0 40.0 2020-01-05 300.0 20.0 ``` Here, each column (sometimes called a "line" in VBT) in each feature DataFrame represents a separate backtesting instance and creates a separate equity curve. So, adding another backtest is as easy as adding another column to the features ✨ Keeping features separate has another major advantage: it lets us combine them easily. Even better, we can combine all backtesting instances at once using vectorization. For example, here we place an entry signal whenever the previous candle was green and an exit signal whenever the previous candle was red (this is a basic example for illustration): ```python >>> candle_green = multi_close > multi_open >>> prev_candle_green = candle_green.vbt.signals.fshift(1) >>> prev_candle_green p1 p2 2020-01-01 False False 2020-01-02 True False 2020-01-03 True False 2020-01-04 True False 2020-01-05 True False >>> candle_red = multi_close < multi_open >>> prev_candle_red = candle_red.vbt.signals.fshift(1) >>> prev_candle_red p1 p2 2020-01-01 False False 2020-01-02 False True 2020-01-03 False True 2020-01-04 False True 2020-01-05 False True ``` The Pandas objects `multi_close` and `multi_open` can be Series or DataFrames of any shape, and our micro-pipeline will continue to work as expected. ## Labels \[#labels] In the example above, we created our multi-OHLC DataFrames with two columns, `p1` and `p2`, so we can easily identify them later during the analysis phase. For this reason, VBT ensures that these columns are preserved throughout the entire backtesting pipeline, from signal generation to performance modeling. But what if individual columns represent more complex configurations, such as those involving multiple hyperparameter combinations? Storing complex objects as column labels would not work well in such cases. Fortunately, Pandas offers [hierarchical columns](https://pandas.pydata.org/pandas-docs/stable/user_guide/advanced.html), which are similar to regular columns but are stacked in multiple layers. Each level in this hierarchy can help us identify a specific input or parameter. Take a simple crossover strategy as an example: it depends on the lengths of the fast and slow windows. Each of these hyperparameters becomes an additional dimension for manipulating data and is stored as a separate column level. Below is a more complex example showing the column hierarchy of a MACD indicator: ```python >>> macd = vbt.MACD.run( ... multi_close, ... fast_window=2, ... slow_window=(3, 4), ... signal_window=2, ... macd_wtype="simple", ... signal_wtype="weighted" ... ) >>> macd.signal macd_fast_window 2 2 << fast window for MACD line macd_slow_window 3 4 << slow window for MACD line macd_signal_window 2 2 << window for signal line macd_macd_wtype simple simple << window type for MACD line macd_signal_wtype weighted weighted << window type for signal line p1 p2 p1 p2 << price 2020-01-01 NaN NaN NaN NaN 2020-01-02 NaN NaN NaN NaN 2020-01-03 NaN NaN NaN NaN 2020-01-04 0.5 -0.5 NaN NaN 2020-01-05 0.5 -0.5 1.0 -1.0 ``` The columns above represent two different backtesting configurations that can now be easily analyzed and compared using Pandas. This is a powerful way to analyze data. For example, you could group your performance by `macd_fast_window` to see how the size of the fast window affects your strategy's profitability. Pretty magical, right? ## Broadcasting \[#broadcasting] One of the most important concepts in VBT is broadcasting. Since VBT functions take time series as independent arrays, they need to know how to connect elements across those arrays so that there is 1) complete information, 2) across all arrays, and 3) at each time step. If all arrays are the same size, VBT can easily perform operations on an element-by-element basis. If any array is smaller in size, VBT tries to "stretch" it to match the length of the other arrays. This approach is heavily inspired by (and internally based on) [NumPy's broadcasting](https://numpy.org/doc/stable/user/basics.broadcasting.html). The main difference from NumPy is that one-dimensional arrays are always specified per row, since we are primarily working with time series data. Why is broadcasting important? Because it allows you to pass array-like objects of any shape to almost every function in VBT, whether they are constants or full DataFrames, and VBT will automatically determine where each element belongs. ```python >>> part_arrays = dict( ... close=pd.DataFrame({ # (1)! ... 'a': [1, 2, 3, 4], ... 'b': [4, 3, 2, 1] ... }), ... size=pd.Series([1, -1, 1, -1]), # (2)! ... direction=[['longonly', 'shortonly']], # (3)! ... fees=0.01 # (4)! ... ) >>> full_arrays = vbt.broadcast(part_arrays) >>> full_arrays['close'] a b 0 1 4 1 2 3 2 3 2 3 4 1 >>> full_arrays['size'] a b 0 1 1 1 -1 -1 2 1 1 3 -1 -1 >>> full_arrays['direction'] a b 0 longonly shortonly 1 longonly shortonly 2 longonly shortonly 3 longonly shortonly >>> full_arrays['fees'] a b 0 0.01 0.01 1 0.01 0.01 2 0.01 0.01 3 0.01 0.01 ``` 1. Specified per element. Does not broadcast. 2. Specified per row. Broadcasts along columns. 3. Specified per column. Broadcasts along rows. 4. Specified per entire array. Broadcasts along rows and columns. !!! tip As a rule of thumb: 1. If any array is a Pandas object, the output is always a Pandas object. 2. If any array is two-dimensional, the output is always a two-dimensional array. 3. If all arrays are constants or one-dimensional, the output is always a one-dimensional array. 4. If the array is a one-dimensional NumPy array or Series, it is always specified per row. 5. Lists and other sequences are converted to NumPy arrays before broadcasting. Unlike NumPy and Pandas, VBT knows how to broadcast labels: if columns or individual column levels in both objects are different, they are stacked together. For example, you can check whenever the fast moving average is higher than the slow moving average, using the following window combinations: (2, 3) and (3, 4). ```python >>> fast_ma = vbt.MA.run(multi_close, window=[2, 3], short_name='fast') >>> slow_ma = vbt.MA.run(multi_close, window=[3, 4], short_name='slow') >>> fast_ma.ma fast_window 2 2 3 3 p1 p2 p1 p2 2020-01-01 NaN NaN NaN NaN 2020-01-02 2.5 4.5 NaN NaN 2020-01-03 3.5 3.5 3.0 4.0 2020-01-04 4.5 2.5 4.0 3.0 2020-01-05 5.5 1.5 5.0 2.0 >>> slow_ma.ma slow_window 3 3 4 4 p1 p2 p1 p2 2020-01-01 NaN NaN NaN NaN 2020-01-02 NaN NaN NaN NaN 2020-01-03 3.0 4.0 NaN NaN 2020-01-04 4.0 3.0 3.5 3.5 2020-01-05 5.0 2.0 4.5 2.5 >>> fast_ma.ma > slow_ma.ma # (1)! ValueError: Can only compare identically-labeled DataFrame objects >>> fast_ma.ma.values > slow_ma.ma.values # (2)! array([[False, False, False, False], [False, False, False, False], [ True, False, False, False], [ True, False, True, False], [ True, False, True, False]]) >>> fast_ma.ma.vbt > slow_ma.ma # (3)! fast_window 2 2 3 3 slow_window 3 3 4 4 p1 p2 p1 p2 2020-01-01 False False False False 2020-01-02 False False False False 2020-01-03 True False False False 2020-01-04 True False True False 2020-01-05 True False True False ``` 1. Comparison with Pandas fails. 2. Comparison with NumPy succeeds. 3. Comparison with VBT succeeds. !!! tip Appending `.vbt` to a Pandas object on the left will broadcast both operands with VBT and execute the operation with NumPy/Numba. This gives you the ultimate combination of power and convenience 🧨 In contrast to Pandas, VBT broadcasts rows and columns by their absolute positions, not by their labels. This broadcasting style is very similar to how NumPy handles broadcasting: ```python >>> df1 = pd.DataFrame({'a': [0], 'b': [1]}) >>> df2 = pd.DataFrame({'b': [0], 'a': [1]}) >>> df1 + df2 # (1)! a b 0 1 1 >>> df1.values + df2.values array([[0, 2]]) >>> df1.vbt + df2 # (2)! a b b a 0 0 2 ``` 1. Pandas connects column `a` in `df1` with column `a` in `df2`. 2. VBT connects the first column in `df1` with the first column in `df2`, regardless of their labels. !!! warning If you pass multiple arrays of data to VBT, make sure that their columns line up positionally! If your columns are not properly ordered, you will notice the result has multiple column levels with identical labels but different orders. Another feature of VBT is its ability to broadcast objects with incompatible shapes but overlapping multi-index levels, meaning those that share the same name or values. Continuing with the previous example, let's check when the fast moving average is higher than the price: ```python >>> fast_ma.ma > multi_close # (1)! ValueError: Can only compare identically-labeled DataFrame objects >>> fast_ma.ma.values > multi_close.values # (2)! ValueError: operands could not be broadcast together with shapes (5,4) (5,2) >>> fast_ma.ma.vbt > multi_close # (3)! fast_window 2 2 3 3 p1 p2 p1 p2 2020-01-01 False False False False 2020-01-02 False True False False 2020-01-03 False True False True 2020-01-04 False True False True 2020-01-05 False True False True ``` 1. Comparison with Pandas fails. 2. Comparison with NumPy fails. 3. Comparison with VBT succeeds. And here is even more (stay with me): you can easily test multiple scalar-like hyperparameters by passing them as a Pandas Index. Let's see whether the price is within certain thresholds: ```python >>> above_lower = multi_close.vbt > vbt.Param([1, 2], name='lower') >>> below_upper = multi_close.vbt < vbt.Param([3, 4], name='upper') >>> above_lower.vbt & below_upper lower 1 1 2 2 upper 3 3 4 4 p1 p2 p1 p2 2020-01-01 True False False False 2020-01-02 False False True False 2020-01-03 False False False True 2020-01-04 False True False False 2020-01-05 False False False False ``` As you can see, smart broadcasting is 💎 when it comes to merging information. See `broadcast` to learn more about broadcasting principles and new ways to combine arrays. ## Flexible indexing \[#flexible-indexing] Broadcasting many large arrays can use a lot of RAM and eventually slow down processing. That's why VBT introduces the concept of "flexible indexing", which selects one element from a one-dimensional or two-dimensional array of any shape. For example, if a one-dimensional array has only one element and needs to be broadcast along 1000 rows, VBT will return that one element regardless of which row is being queried, since this array would broadcast against any shape: ```python >>> a = np.array([1]) >>> vbt.flex_select_1d_nb(a, 0) 1 >>> vbt.flex_select_1d_nb(a, 1) 1 >>> vbt.flex_select_1d_nb(a, 2) 1 ``` This is equivalent to: ```python >>> full_a = np.broadcast_to(a, (1000,)) >>> full_a[2] 1 ``` Two-dimensional arrays offer more flexibility. Consider an example where you want to process 1000 columns, and you have several parameters to apply to each element. Some parameters might be scalars that are the same for every element, some might be one-dimensional arrays that repeat for each column, and some might be the same for each row. Instead of broadcasting these arrays fully, you can simply keep the number of their elements and expand them to two dimensions as needed so they will broadcast correctly with NumPy: ```python >>> a = np.array([[0]]) # (1)! >>> b = np.array([[1, 2, 3]]) # (2)! >>> c = np.array([[4], [5], [6]]) # (3)! >>> vbt.flex_select_nb(a, 2, 1) # (4)! 0 >>> vbt.flex_select_nb(b, 2, 1) 2 >>> vbt.flex_select_nb(c, 2, 1) 6 ``` 1. Value per array. Same value for each element. 2. Value per column. Same values for each row. 3. Value per row. Same values for each column. 4. Query the element at the third row and second column. One nice feature of this approach is that such an operation adds almost no additional memory overhead and can broadcast in any direction, no matter how large the shape gets. This is one of the keys to how `Portfolio.from_signals` can broadcast more than 50 arguments without any loss of memory efficiency or performance 😉 # Documentation (/documentation) Welcome to our documentation hub, your central resource for in-depth information about VBT's main features and functionalities. Here, you will find a list of the major documentation sections: * [Fundamentals](/documentation/fundamentals) (Recommended): Understand VBT's vectorized architecture and its core concepts * [Building blocks](/documentation/building-blocks): Understand the core abstractions that support advanced workflows * [Data](/documentation/data): Retrieve, organize, update, and manage market data * [Indicators](/documentation/indicators): Build parameterized and analyzable indicator pipelines * [Portfolio](/documentation/portfolio): Simulate trading activity and analyze portfolio performance * [Rust](/documentation/rust): Use the optional Rust backend and its native kernels * [Benchmarks](/documentation/benchmarks): Measure backend performance and choose the right execution path * [Internals](/documentation/internals): Understand how the repository is organized and how new code is written # Features (/features) Build and test trading strategies in Python, from loading market data and calculating signals to simulating orders, analyzing trades, and checking results out of sample. VectorBT PRO lets you compare assets, parameter settings, and time periods in the same research workflow, using your own pandas data and trading rules. See the features in action through working Python examples, interactive plots, and real backtest results. Start with a strategy idea and explore the tools to develop it further. ## Find your starting point \[#find-your-starting-point] | What do you want to do? | Where to start | | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Turn buy and sell signals, order sizes, or custom rules into a backtest | [Backtesting](/features/backtesting/) covers simulation, execution, stops, costs, and portfolio accounting. | | Prepare data and build a strategy's inputs | [Data](/features/data/) covers sources, storage, and timeframes. [Indicators](/features/indicators/) covers calculations, signals, and machine learning labels. | | Understand trades, returns, drawdowns, and what drives a result | [Analysis](/features/analytics/) covers metrics, trade behavior, charts, and reports. | | Compare settings or allocations and test them on unseen data | [Optimization](/features/optimization/) covers parameter searches, walk-forward validation, robustness, and portfolio weights. | | See an entire strategy put together | [Strategies](/features/strategies/) covers pairs trading, cross-sectional ranking, and portfolios of strategies. | ## Research across assets, parameters, and time \[#research-across-assets-parameters-and-time] Start with one strategy, then compare its settings across symbols and time periods. Labeled results keep each combination attached to its signals, trades, and metrics, so you can select one backtest for inspection or compare the whole experiment. You can calculate signals in advance or make decisions as the simulation runs, using current cash, positions, and previous fills. The [Backtesting engine](/features/backtesting/backtesting-engine/) shows the available inputs, and [Event-driven backtesting](/features/backtesting/event-driven-backtesting/) shows how to add your own stateful logic. As the research grows, [Performance](/features/performance/) covers compiled calculations, optional Rust support, parallel execution, and benchmarks. The [Toolkit](/features/tooling/) helps with array operations, reusable configuration, saving results, and automation. [AI](/features/ai/) adds documentation search, chat, and tools for your coding assistant. ## Explore all feature areas \[#explore-all-feature-areas] VBT builds on the [features](https://vectorbt.dev/getting-started/features/) of open-source vectorbt and extends them in the areas below. Already use vectorbt? The [VectorBT PRO vs vectorbt comparison](https://vectorbt.pro/getting-started/vectorbt-pro-vs-vectorbt/) explains what PRO adds and how to move your code. * [Data](/features/data): Connect, store, update, transform, and combine local and remote market data * [Indicators and signals](/features/indicators): Compute indicators, build your own, stream updates, and turn them into signals * [Backtesting](/features/backtesting): Model orders, signals, leverage, stops, limits, cash flows, and simulation callbacks * [Analysis](/features/analytics): Measure returns and risk, dissect trades, chart results, and study market events * [Optimization and validation](/features/optimization): Search parameters, validate out of sample, test robustness, and allocate across assets * [Strategies](/features/strategies): Follow worked strategies that combine data, signals, simulation, and validation end to end * [Performance](/features/performance): Scale computation with chunking, caching, JIT compilation, and parallel execution * [Research toolkit](/features/tooling): Use labeled arrays, pandas extensions, persistence, automation, and developer tools * [AI](/features/ai): Get help with Python backtests, search VBT knowledge, and connect your coding assistant !!! info To keep pages concise, only a selection of the most interesting features from each release is highlighted. Full release notes are available exclusively to subscribers. If you are on the private website, navigate to *Getting started* → *Release notes*. Tags indicate releases where features were introduced for the first time. Please note that most features are continuously updated, so the following examples are intended to be run with the **latest** version of VBT installed ✍️ ```python title="Import required by code examples" from vectorbtpro import * # (1) ``` 1. To view what is imported, call `whats_imported()`. # Terms (/terms) Review the policies that govern this website, membership, and use of VectorBT PRO. * [Privacy policy](/terms/privacy-policy): Learn how VectorBT PRO handles personal data on this website * [Terms of use](/terms/terms-of-use): See the terms for VectorBT PRO membership and use * [Software license](/terms/software-license): Read the license that governs the VectorBT PRO source code * [Remarks](/terms/remarks): Understand how access is licensed and what happens when a license expires # Privacy policy (/terms/privacy-policy) **Last updated: September 11, 2026** This Privacy Policy explains how personal data is handled when you visit vectorbt.pro or members.vectorbt.pro (together, the **Site**), contact us, or start a VectorBT PRO membership purchase from the Site. ## 1. Who is responsible for your data? \[#1-who-is-responsible-for-your-data] Oleg Polakow, established in Ukraine, is the data controller for the processing described in this policy. For privacy questions or requests, email . Postal address: Henerala Chuprynky St, 6, L'viv, L'vivs'ka oblast, Ukraine, 79000. ## 2. What data do we process? \[#2-what-data-do-we-process] ### Site delivery and security \[#site-delivery-and-security] When you access the Site, the systems used to deliver it may process technical request data such as your IP address, date and time of access, requested URL, referring page, browser and device information, and error or security events. This data is needed to deliver the Site, maintain its reliability, diagnose problems, and prevent abuse. The Site is hosted and delivered through Cloudflare, which processes request and security data on our behalf. See [Cloudflare's Privacy Policy](https://www.cloudflare.com/privacypolicy/) for more information. ### Necessary browser storage \[#necessary-browser-storage] The Site stores your cookie-consent choice in the `vectorbt-pro-cookie-consent` cookie for 180 days. The Site may also store interface preferences, such as your selected theme, dismissed notices, or tab choices, in your browser. This preference data remains on your device and is used to provide the interface you requested. Documentation search runs in your browser. Search terms are not sent to a search service or included in analytics events. ### Member website access \[#member-website-access] The member website at members.vectorbt.pro requires you to sign in with GitHub. When you sign in, we process your GitHub user ID and username and check whether your account has access to the private VectorBT PRO repository. GitHub handles the sign-in interaction under its [Privacy Statement](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement). The member website uses the following strictly necessary cookies: | Cookie | Purpose | Duration | | ---------------------------------- | -------------------------------------------------------------------------- | ---------------- | | `__Host-vbt_members_oauth_state_*` | Secures the GitHub sign-in flow and prevents request forgery | Up to 10 minutes | | `__Host-vbt_members_session` | Keeps you signed in and allows the Site to periodically verify your access | Up to 30 days | These cookies are marked `HttpOnly`, `Secure`, and `SameSite=Lax`. They are required to provide and secure access to the member website, so they are not controlled by **Cookie settings**. ### Optional analytics \[#optional-analytics] With your consent, the Site uses Google Analytics 4, provided by Google Ireland Limited, to understand visits and improve the Site and its documentation. It may receive a pseudonymous browser identifier, pages viewed, links and other Site interactions, referrer information, browser and device information, approximate location derived from your IP address, and documentation search activity (whether search was used) without the search terms. Analytics is off unless you accept it. Advertising storage, Google Signals, and ad personalization are disabled. The Site does not use analytics data for targeted advertising. Google Analytics uses these first-party cookies: | Cookie | Purpose | Duration | | ---------------- | --------------------------------------------- | -------------- | | `_ga` | Distinguishes visits for aggregate analytics | Up to 180 days | | `_ga_0C5VNYCFHL` | Maintains the current analytics session state | Up to 180 days | You can withdraw consent at any time through **Cookie settings** in the Site footer. Withdrawing consent stops future analytics collection and removes the analytics cookies covered by the consent tool. It does not affect processing that took place before withdrawal. See [Google's privacy policy](https://policies.google.com/privacy) and [information about Google Analytics data safeguards](https://support.google.com/analytics/answer/6004245) for more information. ### Memberships and payments \[#memberships-and-payments] The Site offers payment choices through GitHub Sponsors, Ko-fi, Patreon, Stripe, Paddle, and Gumroad. If you follow a payment link, you leave the Site and the selected provider processes data under its own privacy policy. Paddle checkout can instead open on the Site; the Paddle script is loaded only when you prepare to use or request that checkout. Depending on the provider and payment method, the provider may collect your name, contact and billing details, account identifiers, payment details, IP address, and information about the product and transaction. We do not receive your full payment-card number. We may receive the details needed to confirm the purchase and provide membership access, such as your name or username, email address, plan, transaction identifier, payment status, and subscription dates. The payment providers act under their own terms and privacy notices for their payment, fraud-prevention, legal, and compliance activities: * [GitHub Privacy Statement](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement) * [Ko-fi Privacy Policy](https://more.ko-fi.com/privacy) * [Patreon Privacy Policy](https://privacy.patreon.com/policies) * [Stripe Privacy Center](https://stripe.com/privacy) * [Paddle Privacy Policy](https://www.paddle.com/legal/privacy) * [Gumroad Privacy Policy](https://gumroad.com/privacy) If you contact us about a cryptocurrency payment, we process the information you provide and the transaction details needed to arrange the payment, confirm it, and provide access. ### Communications \[#communications] If you email us or otherwise contact us, we process your contact details, the content of your message, related records, and any information you choose to provide so that we can respond, support you, and keep an appropriate record of the communication. ## 3. Why can we process this data? \[#3-why-can-we-process-this-data] Where the GDPR or similar law applies, we rely on the following legal bases: | Purpose | Legal basis | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Delivering, securing, and troubleshooting the Site | Legitimate interests in operating a reliable and secure Site | | Remembering consent and requested interface settings | Legitimate interests in providing the Site and, where applicable, compliance with legal obligations | | Providing and securing access to the member website | Performance of a contract and legitimate interests in restricting member content to authorized members | | Optional analytics | Consent | | Processing purchases and providing membership access | Steps requested before entering a contract and performance of a contract | | Tax, accounting, fraud prevention, disputes, and compliance | Legal obligations and legitimate interests in protecting the Services and legal rights | | Responding to messages and support requests | Steps requested before entering a contract, performance of a contract, or legitimate interests in communicating about the Services | When we rely on legitimate interests, we consider whether those interests are outweighed by your rights and interests. ## 4. Who receives your data? \[#4-who-receives-your-data] Personal data may be disclosed only as needed to: * Cloudflare, Inc., which hosts and delivers the Site and helps maintain its security; * Google Ireland Limited, if you consent to analytics; * the payment or membership provider you choose, and providers involved in completing that transaction; * professional advisers, auditors, insurers, or public authorities where reasonably necessary to comply with law or establish, exercise, or defend legal claims; and * a successor in connection with a sale, merger, or reorganization, subject to appropriate safeguards. We do not sell personal data or share it for cross-context behavioral advertising. ## 5. International transfers \[#5-international-transfers] Some recipients may process personal data outside your country, including outside the European Economic Area. Where required, transfers are based on a valid legal mechanism, such as an adequacy decision or standard contractual clauses, together with supplementary safeguards where appropriate. The linked provider privacy notices explain their locations and transfer safeguards. You may contact us for more information about safeguards relevant to your personal data. ## 6. How long do we keep data? \[#6-how-long-do-we-keep-data] We keep personal data only for as long as needed for the purposes described above, including legal, tax, accounting, security, and dispute-resolution requirements. * The consent cookie and Google Analytics cookies last for up to 180 days unless you remove them sooner. * The member website's GitHub sign-in state cookies last for up to 10 minutes, and its member session cookie lasts for up to 30 days unless you sign out or remove it sooner. * Google Analytics user-level and event-level data is retained for no longer than 14 months and may then be deleted or kept only in aggregated form. * Purchase, membership, and transaction records are kept for the duration of the membership and afterward for the period required by applicable tax, accounting, consumer-protection, and legal-claims rules. * Correspondence is kept until the request is resolved and afterward only as long as reasonably needed for support continuity, compliance, or legal claims. * Technical logs are kept for the period reasonably necessary for delivery, security, troubleshooting, and abuse prevention. Data may be kept longer when required by law, a dispute, or a valid legal hold. ## 7. Your choices and rights \[#7-your-choices-and-rights] Depending on where you live, you may have the right to request access to, correction of, deletion of, or restriction of your personal data; object to certain processing; receive portable data; and withdraw consent at any time. You may also have the right to appeal a decision about your request. To exercise a right, email . We may need to verify your identity before completing a request. Rights can be subject to legal conditions and exceptions. If you are in the European Economic Area, you may lodge a complaint with the data protection authority where you live, work, or believe an infringement occurred. The European Data Protection Board provides a [directory of national authorities](https://www.edpb.europa.eu/about-edpb/about-edpb/members_en). You are welcome to contact us first, but you do not have to do so. The Site does not make decisions about you based solely on automated processing that produce legal or similarly significant effects. ## 8. Children \[#8-children] The Site is not directed to children under 13, and we do not knowingly collect personal data from them. If you believe a child under 13 has provided personal data, contact us so that we can investigate and delete it where appropriate. ## 9. Security \[#9-security] We use reasonable technical and organizational measures intended to protect personal data. No method of transmission or storage is completely secure, so absolute security cannot be guaranteed. ## 10. External links \[#10-external-links] The Site links to third-party websites. Those third parties are responsible for their own privacy practices, and this policy does not cover data they collect when you visit their services, except for personal data they provide to us in connection with a membership or transaction. ## 11. Changes to this policy \[#11-changes-to-this-policy] We may update this policy when the Site, our practices, or legal requirements change. The date at the top shows the latest revision. If a change materially affects how we rely on consent, we will request consent again where required. # Remarks (/terms/remarks) VectorBT PRO (vectorbtpro or VBT) is hosted in a private repository on GitHub. Access to this repository is licensed and provided by invitation only on a paid basis. Users pay for ongoing access to the repository, which includes updates, support, and maintenance. If your license expires, your software or system will continue to function properly with the most recent version you have at that time. However, if you discontinue your paid license, you will no longer receive any updates or critical bug fixes released after that point. ## Important note \[#important-note] **It is illegal to vend, publish, distribute, or commercialize the vectorbtpro source code without separate permission. Violating the licensing terms will result in a ban and potential legal action.** Any licensed user, developer, team, or company that has obtained paid access to the vectorbtpro repository from us may use vectorbtpro as a dependency, subject to the terms and limitations of the paid subscription plans. Licensees may use, copy, and modify vectorbtpro as long as they do not vend, publish, distribute, or commercialize the source code of vectorbtpro. You may specify vectorbtpro as a dependency for your software, provided you do not include a copy of the vectorbtpro source code in your software. If you are a software developer, you should specify vectorbtpro as a requirement. The end user of your software is responsible for obtaining their own individual license. The best practice is to make this clear in your documentation or on your website. # Software license (/terms/software-license) ```text VECTORBT® PRO LICENSE Last Updated: January 5, 2025 This Software License ("License") is a legal agreement between the Copyright Holder and the Authorized User, governing the use of VECTORBT® PRO. By downloading, installing, or using the Software, you agree to be bound by this License. 1. DEFINITIONS 1.1 "Software" Refers to VECTORBT® PRO, including all related documentation, updates, and files provided under this License. 1.2 "Copyright Holder" Refers to Oleg Polakow, along with any successors, assigns, or authorized legal representatives. 1.3 "Authorized User" Means: (a) Individual: A single person who obtains the Software for personal, private, and non-commercial use ("Private Use"). (b) Organization: A legal entity that acquires the Software solely for internal, non-commercial purposes. Use is restricted to employees or direct contractors who are explicitly granted access to the Software as part of their duties for internal purposes. 1.4 "Private Use" / "Non-Commercial Use" Refers to any use of the Software where no direct or indirect monetary compensation, commercial advantage, or for-profit purpose is obtained. This includes: i. Individual Users: Personal, private use with no commercial intent. ii. Organizations (including for-profit entities): Internal, in-house usage for purposes such as evaluation, data analysis, prototyping, or research and development (R&D), provided it does not result in a commercial product, service, or outcome. Any use that contributes to or is integrated into a commercial offering requires a separate commercial license. 1.5 "Sell" Means to use, reproduce, distribute, host, monetize, or otherwise commercialize the Software—directly or indirectly—in exchange for payment or other compensation. This includes offering services that derive significant value from the Software’s core functionality. 2. LICENSE GRANT & SCOPE 2.1 License Grant The Copyright Holder grants the Authorized User a limited, revocable, non-exclusive, and non-transferable license to download, install, use, copy, and modify the Software exclusively for Private Use / Non-Commercial Use, as defined in Section 1.4. 2.2 Scope of Authorized Use (a) Individual Users: May use the Software on their personal devices solely for private, non-commercial purposes. (b) Organizations: May use the Software internally for non-commercial purposes. The Organization must ensure that only authorized employees or contractors access or interact with the Software. The Organization is responsible for preventing: i. Unauthorized internal sharing with unapproved employees or contractors. ii. Any external access by third parties unless explicitly permitted in writing by the Copyright Holder. 2.3 Modifications & Internal Sharing i. Authorized Users may create modifications or derivative works for Private Use / Non-Commercial Use only. ii. Modifications or derivative works may be shared among Authorized Users, provided they remain inaccessible to any party not covered by this License. iii. Modifications or improvements may be shared directly with the Copyright Holder without violating this License. 2.4 Updates & Versions i. All updates, patches, or new versions of the Software provided by the Copyright Holder are subject to this License unless otherwise specified. ii. The Copyright Holder reserves the right to modify the terms of this License for future versions. Continued use of any updated version indicates acceptance of the revised terms. Note: Any use outside the scope defined above—including but not limited to commercial use—requires a separate written agreement with the Copyright Holder. 3. RESTRICTIONS & LIMITATIONS 3.1 No Unauthorized Distribution or Sharing The Software must not be published, shared, uploaded to publicly accessible platforms, distributed, transmitted, or made available to any third party without prior written consent from the Copyright Holder. Exception: Internal hosting within an Organization’s private, secure network is permitted, provided it remains inaccessible to external parties or unauthorized personnel. 3.2 No Sublicensing or Commercial Use The Authorized User may not sublicense, Sell, or otherwise use the Software for commercial purposes. Clarification: "Sell" includes any form of monetization derived from the Software’s core functionality, such as hosting, consulting, or support services offered for a fee. 3.3 Retention of Copyright Notices All copies, modifications, or derivative works of the Software must retain the original copyright notice and this License. The removal or alteration of any proprietary notices is prohibited. 3.4 No Reverse Engineering The Authorized User may not decompile, decrypt, reverse engineer, disassemble, or otherwise attempt to derive the source code of the Software, except where permitted by applicable law. 3.5 Third-Party Components If the Software includes third-party components covered by separate licenses, those components are subject to their respective terms. This License does not override any third-party agreements. 4. ADDITIONAL RIGHTS REQUIRE WRITTEN CONSENT Any rights to distribute, sublicense, Sell, or otherwise commercially exploit the Software—whether modified or unmodified—must be explicitly granted through a separate written agreement with the Copyright Holder. No additional rights are implied or granted beyond those expressly stated in this License. 5. TERMINATION & RESERVATION OF RIGHTS 5.1 Termination This License automatically terminates if the Authorized User breaches any of its terms. Upon termination, the Authorized User must immediately cease all use of the Software and permanently delete all copies, including backups. 5.2 Reservation of Rights All rights not expressly granted under this License are reserved by the Copyright Holder. 6. DISCLAIMER & INDEMNIFICATION 6.1 Disclaimer of Warranty THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THE COPYRIGHT HOLDER SHALL NOT BE LIABLE FOR ANY CLAIMS, DAMAGES, OR LIABILITIES ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE, EXCEPT AS REQUIRED BY APPLICABLE LAW. 6.2 Indemnification The Authorized User agrees to indemnify, defend, and hold harmless the Copyright Holder from any claims, damages, liabilities, costs, or expenses (including reasonable attorneys’ fees) arising from the Authorized User’s use or misuse of the Software. 7. SEVERABILITY If any provision of this License is found by a court of competent jurisdiction to be invalid, illegal, or unenforceable, that provision shall be deemed modified to the minimum extent necessary to render it valid and enforceable. If modification is not possible, the provision shall be severed, and the remaining provisions shall continue in full force and effect. 8. TRADEMARK USAGE 8.1 Ownership "VECTORBT®" is a registered trademark owned by the Copyright Holder. 8.2 Limited Reference Rights This License permits limited use of the VECTORBT® trademark to refer to the Software in documentation or promotional materials, provided it does not suggest endorsement by the Copyright Holder. 8.3 Prohibited Uses You may not use, adopt, or register any trademark or domain name that is identical or confusingly similar to VECTORBT®. 8.4 No Endorsement Use of the VECTORBT® trademark may not imply endorsement or affiliation without explicit written authorization. [End of License] ``` # Terms of use (/terms/terms-of-use) **Last updated: August 24, 2026** These Terms of Use (the **Terms**) apply to vectorbt.pro, VectorBT PRO software and private content, the private GitHub repository, the private Discord community, and related services (together, the **Services**). The Services are provided by Oleg Polakow (**we**, **us**, or **our**). By using the public website, you agree to the provisions that apply to public use. By purchasing or using a membership, accessing private content, or downloading or using VectorBT PRO, you agree to the provisions that apply to those Services. If you act for an organization, you confirm that you have authority to bind it. ## 1. Membership \[#1-membership] An active membership provides access to the benefits described for the selected plan, which may include the private repository, private documentation, tutorials, updates, support, and the Discord community. Available plans may include: * **Monthly access**, which renews through the selected payment provider until canceled. * **12-month access**, which lasts for the stated paid term. * **Lifetime access**, which lasts for the commercial lifetime of VectorBT PRO while it continues to be offered and maintained by us. It does not guarantee that a particular third-party platform, integration, or community service will remain available forever. Membership is personal to the purchaser unless organization access has been agreed. You may not share private repository invitations, accounts, credentials, private content, or membership benefits with anyone who is not covered by your membership. GitHub Sponsors access is normally granted automatically. Access purchased through another route is normally granted within 24 hours after payment is confirmed and we have the information needed to identify your account. Contact us if access has not arrived within that time. ## 2. Payments, renewals, and cancellation \[#2-payments-renewals-and-cancellation] The plans page displays available payment providers. A provider may process the payment or act as the seller or reseller for the transaction. Its terms govern the payment, taxes, billing, subscription management, cancellation, and refunds it handles. These Terms govern your access to and use of the Services. The final price, currency, applicable taxes, renewal terms, and payment schedule are shown before you complete checkout. If those checkout details differ from a general price displayed on this website, the checkout details control. You may cancel a recurring membership through the payment provider at any time. Unless the provider states otherwise, cancellation prevents the next renewal and access continues until the end of the current paid term. Unless applicable law or the seller identified during checkout provides otherwise, purchases are final after access has been provided. Refunds and withdrawal rights are governed by applicable law and any additional policy offered by the seller or payment provider. If applicable consumer law gives you a cooling-off or withdrawal period, you may exercise that right by contacting the seller identified during checkout. If Oleg Polakow is identified as the seller, you may contact us at . If a payment provider or another party is identified as the seller, use the withdrawal process or contact details provided by that seller. If you expressly request immediate access to digital content or membership services, the consequences for your withdrawal right depend on the consent and acknowledgment collected during checkout and the law that applies to your purchase. Nothing in these Terms limits a refund, withdrawal, cancellation, or other right that cannot lawfully be excluded. If a purchase is refunded, access associated with it may be removed. ## 3. Software license \[#3-software-license] Your use of VectorBT PRO software is governed by the separate [Software License](/terms/software-license/). Membership gives you access to obtain the software; it does not transfer ownership of the software or its source code. When paid access ends, your access to private Services, new releases, updates, and support ends. Your use of a version already lawfully obtained remains subject to the Software License. Individual membership permits personal, non-commercial use. Internal organization use and any commercial use are permitted only to the extent stated in the Software License or separately agreed with us in writing. ## 4. Acceptable use \[#4-acceptable-use] You may use public content to learn about and evaluate VectorBT PRO and use private content as needed for your authorized use of the software. You must not: * share, publish, sell, sublicense, or distribute VectorBT PRO source code or private content; * give an unauthorized person access to private Services; * circumvent access controls, payment requirements, or technical restrictions; * use the Services unlawfully, fraudulently, or to harm others; * disrupt the Services, introduce malicious code, or place an unreasonable load on them; * systematically extract public or private content to reproduce the Services, create a competing content collection, or support a competing product; or * remove copyright, trademark, license, or other proprietary notices. Reasonable use of public documentation through ordinary browsers, search engines, coding agents, and interfaces we intentionally provide is allowed. This does not permit access to private content without authorization or redistribution of protected content. ## 5. Community and feedback \[#5-community-and-feedback] You remain responsible for content you post in the community or send to us. You retain ownership of your content. You give us the limited rights needed to display, transmit, store, moderate, and otherwise operate the relevant Service. Do not post unlawful, abusive, threatening, deceptive, infringing, or privacy-violating content. We may remove content or restrict community access when reasonably necessary to enforce these Terms or protect the community. If you voluntarily provide ideas or feedback, we may use them without restriction or compensation. Do not send confidential information as feedback. ## 6. Service changes and availability \[#6-service-changes-and-availability] We may update and improve the Services, replace third-party platforms, and change features when reasonably necessary for security, maintenance, legal compliance, technical development, or the continued operation of VectorBT PRO. We do not guarantee uninterrupted availability or that every feature, integration, data source, or third-party platform will remain unchanged. We will not materially reduce an existing prepaid membership without notice and any remedy required by applicable law. Trading, investment, and analytical results depend on data, assumptions, configuration, and market conditions. The Services are provided for software, research, and educational purposes. They are not financial, investment, tax, or legal advice, and they do not guarantee any trading result. ## 7. Suspension and termination \[#7-suspension-and-termination] We may suspend or terminate access when you materially breach these Terms or the Software License, fail to pay an amount due, compromise the security of the Services, or use the Services in a way that creates material legal or operational risk. Where appropriate, we will give you notice and a reasonable opportunity to correct the issue. Termination of membership does not give you permission to continue accessing private Services or to distribute the software. Provisions that by their nature should survive termination, including license restrictions, intellectual property rights, disclaimers, and liability limitations, remain in effect. ## 8. Disclaimers and liability \[#8-disclaimers-and-liability] To the extent permitted by applicable law, the Services are provided "as is" and "as available." We do not promise that they will be error-free, suitable for every purpose, or compatible with every system or third-party service. To the extent permitted by applicable law, we are not liable for indirect, incidental, special, or consequential loss, lost profits, lost revenue, lost opportunities, or loss of data arising from the Services. Our aggregate liability arising from a paid Service will not exceed the amount you paid for that Service during the 12 months before the event giving rise to the claim. Nothing in these Terms excludes or limits liability or customer rights that cannot lawfully be excluded or limited, including liability for fraud, intentional misconduct, gross negligence, or death or personal injury where such a limitation is prohibited. ## 9. Privacy and third-party services \[#9-privacy-and-third-party-services] Our [Privacy Policy](/terms/privacy-policy/) explains how personal data is handled in connection with the website and membership purchases. The Services link to and rely on third-party services such as GitHub, Discord, and payment providers. Their services are governed by their own terms and privacy policies. We are not responsible for third-party services, but this does not affect obligations that applicable law places directly on us. ## 10. Changes to these Terms \[#10-changes-to-these-terms] We may update these Terms to reflect changes to the Services, law, security requirements, or our business practices. The date above identifies the current version. Updated Terms apply to new purchases from their effective date. If a change materially affects an existing paid membership, we will provide reasonable notice and request acceptance where required. Changes do not retroactively remove rights already granted under an earlier agreement. If any provision of these Terms is unenforceable, the remaining provisions remain in effect. Any mandatory rights available to you under applicable law remain unaffected. ## 11. Contact \[#11-contact] Questions about the Services or these Terms can be sent to . Postal address: Henerala Chuprynky St, 6, L'viv, L'vivs'ka oblast, Ukraine, 79000. # Tutorials (/tutorials) Here you will find a comprehensive collection of guides and tutorials designed to help you master the powerful features of VBT. Whether you are a beginner looking to get started or an advanced user seeking to refine your skills, our tutorials cover everything from basic setup to complex strategy development. * [Basic RSI strategy](/tutorials/basic-rsi) (Recommended): Backtest a complete RSI strategy from signals to performance * [SuperFast SuperTrend](/tutorials/superfast-supertrend): Build a streaming, multithreaded SuperTrend indicator and backtest it * [Signal development](/tutorials/signal-development): Develop, clean, rank, and validate trading signals * [Stop signals](/tutorials/stop-signals): Test stop-loss, trailing-stop, and take-profit configurations * [MTF analysis](/tutorials/mtf-analysis): Align, aggregate, and analyze data across multiple timeframes * [Portfolio optimization](/tutorials/portfolio-optimization): Design, integrate, and dynamically rebalance optimized portfolios * [Pairs trading](/tutorials/pairs-trading): Build and optimize a pairs-trading strategy across hundreds of assets * [Patterns and projections](/tutorials/patterns-and-projections): Detect chart patterns and project their effect on future prices * [Cross-validation](/tutorials/cross-validation): Design robust cross-validation workflows for trading strategies * [From Python to Rust](/tutorials/from-python-to-rust): Take one strategy from vectorized Python to live, stateful Rust * [More tutorials](/tutorials/more-tutorials): Explore community tutorials, videos, and research # More tutorials (/tutorials/more-tutorials) ## PyQuant News \[#pyquant-news] *PyQuant News* is a place for practitioners to level up their Python skills for quant finance, algorithmic trading, and data analysis, featuring free quant code. [The PyQuant Newsletter](https://pyquantnews.com/the-pyquant-newsletter/) ![PyQuant News](/assets/partners/pqn.png) * [How to use VectorBT PRO to algorithmically find chart patterns](https://pyquantnews.com/vectorbt-pro-algorithmically-find-chart-patterns/) * [Forecast future price trends (with projections)](https://pyquantnews.com/forecast-future-price-trends-with-projections/) * [Easily cross-validate parameters to boost your trading strategy](https://pyquantnews.com/easily-cross-validate-parameters-boost-strategy/) * [Quickly make a pairs trading strategy with 500 stocks](https://www.pyquantnews.com/the-pyquant-newsletter/quickly-make-pairs-trading-strategy-500-stocks) * [Backtest powerful intraday trading strategies](https://www.pyquantnews.com/the-pyquant-newsletter/backtest-powerful-intraday-trading-strategies) * [Backtest intraday trading strategies with VectorBT PRO](https://www.pyquantnews.com/the-pyquant-newsletter/intraday-backtesting-with-vectorbt-pro) ## Qubit Quants \[#qubit-quants] *Qubit Quants* is an independent, professional, and open community dedicated to the research, development, and discussion of quantitative analytics, financial machine learning, and algorithmic trading. [VectorBT PRO - Tutorial Series](https://qubitquants.github.io/vbt-tuts-toc/index.html) ![Qubit Quants](/assets/partners/qubit-quants.png) * [Align MTF data](https://qubitquants.github.io/aligning-mtf-data/index.html) * [Strategy development](https://qubitquants.github.io/strategydev/index.html) * [Plot indicators and signals](https://qubitquants.github.io/vbt_plot_strategy/index.html) * [Multi-asset simulation](https://qubitquants.github.io/multi_asset_portfolio_simulation/index.html) * [Custom dashboard](https://qubitquants.github.io/vbt_dashboard/index.html) * [Discretionary signals](https://qubitquants.github.io/discretionary-signals-bactesting/index.html) * [Custom simulator basics](https://qubitquants.github.io/customsim_0/index.html) * [Custom candlestick simulator](https://qubitquants.github.io/customsim_1/index.html) * [Custom stops simulator](https://qubitquants.github.io/customsim_2/index.html) * [Partial profits simulator](https://qubitquants.github.io/customsim_3/index.html) * [VectorBT PRO tutorials code](https://github.com/QubitQuants/vectorbt_pro_tutorials) - [Discretionary Signals Backtesting using VectorBT PRO](https://youtu.be/EQjdWAE613A?si=J6plzFmdBDSWBZoz) - [VectorBT PRO - Custom Plotly Dashboard](https://youtu.be/Mek2Q6JZwTw?si=j7c_E_uPbo3m_y5m) ## Chad Thackray \[#chad-thackray] *Chad Thackray* creates educational programming content for traders on his YouTube channel. He provides in-depth tutorials, coding insights, and practical applications to help improve trading strategies. * [VectorBT PRO install guide and subscriber perks](https://youtu.be/GkJEQ4fm2_E) * [VectorBT PRO - Multi Strategy Portfolios](https://www.youtube.com/watch?v=q4W3fkjB1aw\&list=PLnSVMZC68_e6ZJOp__mNzPlNDgAYstsyy\&index=1) * [Take Profit Ladders In VectorBT PRO](https://youtu.be/u4RABJMXhXc?si=wHrBS2HEVZ7btYsq) * [Cross Validation in VectorBT PRO](https://youtu.be/_BSSPZplLHs?si=-22bt2hXW9pUBXvg) * [Multiple Timeframe Analysis in VectorBT PRO](https://youtu.be/L6g3mslaTwE?si=viqfxQjMRjXSBGy7) ## Trade Science \[#trade-science] *Trade Science* is a YouTube channel dedicated to realistic technical analysis, systematic trading systems, strategy and indicator reviews, and system optimization. * [How to do a Walk Forward Optimization in Python with Vectorbt](https://youtu.be/RKE1ZXm00NY?si=mPDXX-tSC4X8rAtV) ## Python Financial \[#python-financial] *Python Financial* publishes reviews, comparisons, and benchmarks of trading research tools. These pages cover VBT PRO directly: [Python Financial](https://python.financial/) ![Python Financial](/assets/partners/python-financial.png) * [VectorBT PRO](https://python.financial/tools/vectorbt-pro/) * [VectorBT PRO vs VectorBT](https://python.financial/comparisons/vectorbt-vs-vectorbt-pro/) * [VectorBT PRO vs Backtesting.py](https://python.financial/comparisons/vectorbt-pro-vs-backtesting-py/) * [VectorBT PRO vs NautilusTrader](https://python.financial/comparisons/vectorbt-pro-vs-nautilustrader/) * [VectorBT PRO vs LEAN and QuantConnect](https://python.financial/comparisons/vectorbt-pro-vs-quantconnect-lean/) * [Parameter-grid scaling benchmark](https://python.financial/benchmarks/parameter-sweeps/) ## Research \[#research] Below are research theses and papers that have utilized VBT: * [Improvements to Intraday Momentum Strategies Using Parameter Optimization and Different Exit Strategies](https://dx.doi.org/10.2139/ssrn.5095349) * [Automation of Financial Portfolio Management using Machine Learning-Based Algorithmic Trading](https://www.linkedin.com/in/martinandrovich/) ## Other resources \[#other-resources] Below are other resources that have utilized VBT: * [Trading Signal Analysis with Marimo and VectorBT Pro](https://financialnoob.substack.com/p/trading-signal-analysis-with-marimo) ## Contributing \[#contributing] If you have created a tutorial using VBT and would like to share it here, please post it in our [Discord](https://discord.gg/2Zs5j8m). Thanks to everyone who has contributed so far! 💜 # Realistic backtests (/features/backtesting/backtest-realism) Why does a backtest look better than live trading? An order may have filled before its signal existed, a daily value arrived before the day ended, or trading costs ate the profit. VBT lets you control order timing, align data by when it became available, model costs, and inspect individual fills. Here's how to use those tools to avoid look-ahead bias and build more realistic backtests in Python. ```python title="Fill a limit order on the bar that created it, then on the next bar" >>> data = vbt.BinanceData.pull( ... "BTCUSDT", start="2020-01-01", end="2025-01-01", timeframe="1h" ... ) >>> dip = data.close < data.close.vbt.rolling_mean(24) # (1) >>> limit_price = data.close * 0.99 >>> exits = dict( ... tp_stop=0.02, ... td_stop=24, ... time_delta_format="rows", ... stop_entry_price="fillprice", # (2) ... fees=0.001, ... ) >>> same_bar = vbt.PF.from_signals( # (3) ... data, entries=dip & (data.low <= limit_price), price=limit_price, **exits ... ) >>> next_bar = vbt.PF.from_signals( # (4) ... data, entries=dip, price=limit_price, order_type="limit", limit_tif=2, **exits ... ) >>> metrics = ["total_trades", "win_rate", "total_return", "sharpe_ratio"] >>> stats = {"same bar": same_bar.stats(metrics), "next bar": next_bar.stats(metrics)} >>> pd.DataFrame(stats).astype(float).round(2) same bar next bar Total Trades 802.00 663.00 Win Rate [%] 83.29 66.37 Total Return [%] 87489.57 -31.97 Sharpe Ratio 3.88 0.01 ``` 1. The signal uses each hour's close, so it exists only once that hour has closed. The buy limit sits 1% below that close. 2. Exit with a 2% profit measured from the limit fill, or after 24 hours. 3. A common mistake: treat the order as filled if the same hour's low touched the limit. That low happened before the close that produced the signal. 4. A limit order created at a price below the close cannot fill on its own bar. `limit_tif=2` keeps it for the next hour only, so it gets the same single chance to fill as the naive version. The same-bar version always buys the dip that already happened and then sells the rebound, so its trades reach the target sooner and it trades more often. It shows an 87,000% gain where the honest version loses 32%. The gap is a reason to inspect the order timing before spending time on a parameter search. ## Causal order timing \[#causal-order-timing] A decision can use only what was known when it was made, and an order can fill only then or later. In `vbt.PF.from_signals`, the `price` argument says where in the bar each order executes: | Setting | Signal uses | Order fills | | ----------------------------------------- | ---------------- | -------------------------------------------- | | `price="close"` (default) | The bar's close | At that close | | `price="nextopen"` | The bar's close | At the next bar's open | | `from_ago=1` | The previous bar | At this bar's price | | `order_type="limit"` with `price="close"` | The bar's close | From the next bar, when the limit is reached | Limit orders follow the same rule. Placed at the open, they can fill anywhere in the bar. Placed at the close, they wait for the next bar. Placed in between, they can only check the close. Stops are checked against each later bar's high and low, and `limit_delay` or order delays push fills further out. See [Orders and execution](/features/backtesting/orders-and-execution/) for every option, [Order delays](/features/backtesting/orders-and-execution/#order-delays) for latency, and [Realistic stop fills](/features/backtesting/stop-loss-and-take-profit/#realistic-stop-fills) for what happens when both a stop and a target fall inside one bar. ## Stop fills and data resolution \[#stop-fills-and-data-resolution] The high and the low have to be there to be checked. Passing only a close series, instead of the data object or `open`, `high`, and `low`, makes every stop wait for a close beyond its level: ```python title="Test a 3% trailing stop on closes only and on full bars" >>> btc = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2025-01-01") >>> entries = btc.close.vbt.crossed_above(btc.close.vbt.rolling_mean(20)) >>> pfs = { ... "close only": vbt.PF.from_signals(btc.close, entries, tsl_stop=0.03), ... "OHLC": vbt.PF.from_signals(btc, entries, tsl_stop=0.03), ... } >>> stop_metrics = ["total_trades", "win_rate", "total_return", "max_dd"] >>> pd.DataFrame({k: pf.stats(stop_metrics) for k, pf in pfs.items()}).astype(float).round(2) close only OHLC Total Trades 90.00 96.00 Win Rate [%] 38.89 41.67 Total Return [%] 530.06 213.53 Max Drawdown [%] 33.67 21.40 ``` On closes alone, a trade survives every intraday dip that ends the day above the stop, so it rides more rebounds and the return more than doubles. When the stop finally fires, the fill is the close, below the level, which deepens the drawdown. Neither number is what a stop order at the exchange would have done. ## Higher-timeframe alignment \[#higher-timeframe-alignment] Data from a longer timeframe has the same trap. A daily value is known only after the day closes, but aligning it to hourly bars with a plain forward fill hands each hour the close of its own day: ```python title="Align a daily trend filter to hourly bars, naively and safely" >>> daily_close = data.close.resample("1D").last() >>> daily_trend = daily_close > daily_close.vbt.rolling_mean(20) >>> naive_trend = daily_trend.reindex(data.index, method="ffill") # (1) >>> safe_trend = daily_trend.vbt.realign_closing(data.index, freq="1h") # (2) >>> safe_trend = safe_trend.fillna(False).astype(bool) >>> pfs = { ... "naive": vbt.PF.from_signals(data, naive_trend, ~naive_trend, fees=0.001), ... "safe": vbt.PF.from_signals(data, safe_trend, ~safe_trend, fees=0.001), ... } >>> pd.DataFrame({k: pf.stats(metrics) for k, pf in pfs.items()}).astype(float).round(2) naive safe Total Trades 107.00 107.00 Win Rate [%] 93.46 25.23 Total Return [%] 854502.66 315.56 Sharpe Ratio 4.41 0.87 ``` 1. Daily bars are labeled with the day's start, so each hour of the day gets the trend computed from that day's close. 2. Moves each daily value to the last hourly bar of its day, when the daily close is known. Equity of an hourly Bitcoin strategy using a daily trend filter aligned naively and safely, on a log scale from 2020 to 2024. [Figure data (JSON)](/assets/figures/features/backtesting/htf-alignment-equity.980edbc3a260.json) The same 107 trades won 93% of the time with the naive alignment and 25% with the safe one. The [Multi-timeframe analysis](/features/data/multi-timeframe-analysis/) page covers alignment and resampling in detail. ## Point-in-time universes \[#point-in-time-universes] A strategy tested only on stocks that are listed today never holds the companies that failed or left the index. To avoid this survivorship bias, keep every symbol that was ever part of the universe, and mask each one with NaN outside the dates it belonged, so the backtest sees the universe that existed on each date. VBT ignores signals on bars without a price, including exits, so close positions on the last bar a symbol belongs to. The [Data pipelines](/features/data/financial-data-pipelines/#universes-and-futures) page shows how to build the membership mask. ## Trading costs and available capital \[#trading-costs-and-available-capital] A strategy can use the right prices and still spend money it would not have. VBT applies fees and slippage when processing orders, so costs affect how much the portfolio can buy as well as its final return. Use percentage commissions, fixed fees, and slippage to test whether the strategy still works after trading costs. The [Fees, slippage, and leverage](/features/backtesting/fees-slippage-and-leverage/) page covers these settings and borrowing costs. When several assets compete for the same money, use a [shared cash balance](/features/backtesting/portfolio-accounting/#shared-cash). Size limits, whole-share or lot rounding, and partial-fill settings let you model orders that fit the account. See [Fills, limits, and rejections](/features/backtesting/orders-and-execution/#fills-limits-and-rejections) for an example of orders being capped, partially filled, and ignored. ## Backtest-to-live parity \[#backtest-to-live-parity] When live results differ from the backtest, compare them step by step. With the same inputs, settings, and random seed where randomness is used, you can reproduce a VBT simulation and find the first difference. * **Data:** check that the live bars match the historical ones, including the last, still-forming bar. * **Indicators and signals:** recompute them on the live data and compare values and timestamps. Platforms also define indicators differently, for example the smoothing and warm-up of RSI, so compare values bar by bar before comparing trades. * **Orders:** `pf.orders.readable` lists every order with its signal, creation, and fill bars, and stop type, which pinpoints where two runs diverge. * **Costs:** fees, slippage, and spreads that the backtest left out, covered on the [Fees, slippage, and leverage](/features/backtesting/fees-slippage-and-leverage/) page. For orders that reached execution but did not fill as requested, enable `log=True` and inspect `pf.logs.readable`. The logs show the requested order, the execution result, and the account state before and after it. That helps distinguish an unaffordable order from one reduced by a size limit, instead of guessing from the equity curve. The [Live simulation](/features/backtesting/live-simulation/) page continues a backtest bar by bar on new data, and the [Intraday and tick backtesting](/features/backtesting/intraday-and-tick-backtesting/) page tests fills on finer data inside each bar. !!! tip "When a result looks too good" Look at a few trades on a chart first. For fills at the exact low or high of a bar, check that the order existed before that price was reached. Win rates above 80% or returns that dwarf the market deserve a closer look, but neither alone proves the strategy saw the future. # Backtesting engine (/features/backtesting/backtesting-engine) Can you backtest your own trading logic in Python without giving up speed or control? VBT is a Python backtesting engine that simulates orders bar by bar in compiled code, runs every asset and parameter combination as a column of one vectorized simulation, and returns a portfolio where every order, trade, and position can be inspected. Start with entry and exit signals, replay an existing order list, or build custom logic that reacts to cash and positions as the simulation runs. Each approach gives you the same portfolio analysis tools. ```python title="Backtest four moving average pairs on two assets in one call" >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"], start="2021-01-01", end="2024-01-01") >>> fast = vbt.MA.run(data.close, window=[10, 10, 20, 20], short_name="fast") >>> slow = vbt.MA.run(data.close, window=[50, 100, 50, 100], short_name="slow") >>> entries = fast.ma_crossed_above(slow) >>> exits = fast.ma_crossed_below(slow) >>> pf = vbt.PF.from_signals(data, entries, exits, fees=0.001) # (1) >>> pf.total_return.unstack("symbol") symbol BTC-USD ETH-USD fast_window slow_window 10 50 0.346309 0.720064 100 0.577382 -0.151935 20 50 -0.139554 0.017887 100 0.365233 -0.110708 >>> pf[(10, 50, "ETH-USD")].plot(settings=dict(bm_returns=False)).show() # (2) ``` 1. Eight backtests run as eight labeled columns of one simulation, each with its own cash. 2. Select any column by its labels and analyze it like a single backtest. Each signal fills at the close of the bar it appears on, and every order pays a 0.1% fee. To act on the next bar instead, see [Causal order timing](/features/backtesting/backtest-realism/#causal-order-timing). ETH-USD 10 and 50 day moving average crossover orders, trade returns, and cumulative returns from 2021 to 2023. [Figure data (JSON)](/assets/figures/features/backtesting/backtesting-engine-grid-column.e01add8da42c.json) ## Three ways to simulate \[#three-ways-to-simulate] Every simulation method returns the same `Portfolio` object. They differ in how you describe the trading decisions: | Method | You provide | Use it for | | ------------------------ | --------------------------------------------- | ----------------------------------------- | | `vbt.PF.from_orders` | Size, price, and direction per bar | Rebalancing, target weights, order lists | | `vbt.PF.from_signals` | Entry and exit signals, plus stops and limits | Most rule-based strategies | | `vbt.PF.from_order_func` | A compiled function that returns orders | Logic that depends on the portfolio state | `from_orders` is the most direct: you supply order sizes and prices, and the engine handles cash and execution. For target weights combined with stops and limits, `from_signals` accepts them with `order_mode=True`, as shown in [Targets as signals](/features/backtesting/signal-backtesting/#targets-as-signals). Both methods fill at most one order per column and bar. To fill several, for example a buy at the open and a sell at the close, use a flexible order function, as shown in [Order functions](/features/backtesting/event-driven-backtesting/#order-functions). `from_orders` and `from_signals` accept arrays prepared before the simulation starts, while execution still responds to the current account. Target weights, for example, translate into order sizes using the portfolio value and existing positions. `from_signals` and `from_order_func` also accept callbacks, which decide during the simulation, as shown on the [Event-driven backtesting](/features/backtesting/event-driven-backtesting/) page. Static or dynamic, the methods share order execution rules. Here, the same long-only strategy expressed two ways gives the same orders: ```python title="Run one strategy through two simulation methods" >>> close = data.close["BTC-USD"] >>> entries = close.vbt.crossed_above(close.rolling(50).mean()) >>> exits = close.vbt.crossed_below(close.rolling(50).mean()) >>> pf_signals = vbt.PF.from_signals(close, entries, exits) >>> size = pd.Series(np.nan, index=close.index) # (1) >>> size[entries] = np.inf >>> size[exits] = -np.inf >>> pf_orders = vbt.PF.from_orders(close, size, direction="longonly") >>> cols = ["Index", "Size", "Price", "Side"] >>> a = pf_signals.orders.readable.rename(columns={"Fill Index": "Index"})[cols] >>> b = pf_orders.orders.readable[cols] >>> a.equals(b), len(a) (True, 51) ``` 1. `NaN` places no order, positive infinity buys with all cash, and negative infinity sells the whole position. Under the high-level methods sit compiled functions that take plain NumPy arrays. You can call them from your own Numba code, as shown on the [Signal backtesting](/features/backtesting/signal-backtesting/#calling-the-kernel-directly) page. ## Many backtests in one call \[#many-backtests-in-one-call] Inputs broadcast against each other. A signal array with eight columns, a price array with two, and a scalar fee produce eight backtests, and parameter values become column levels you can select, group, and plot by. Each column is an independent account by default. Grouping changes that. `group_by` combines columns into one portfolio for reporting, and `cash_sharing=True` makes them draw from one cash balance, which is how multi-asset portfolios are simulated. Grouping the first grid by its parameter levels turns eight single-asset backtests into four two-asset portfolios: ```python title="Turn the grid into four two-asset portfolios with shared cash" >>> pf = vbt.PF.from_signals( ... data, ... fast.ma_crossed_above(slow), ... fast.ma_crossed_below(slow), ... size=0.5, # (1) ... size_type="valuepercent", ... fees=0.001, ... group_by=["fast_window", "slow_window"], # (2) ... cash_sharing=True, ... ) >>> pf.total_return fast_window slow_window 10 50 0.570373 100 0.186409 20 50 -0.055170 100 0.133235 Name: total_return, dtype: float64 ``` 1. Each entry invests half of the group's current value, limited by the cash left. 2. Columns with the same parameter values form one group, so BTC and ETH share an account. The simulator carries cash and positions forward from one bar to the next within each group. Speed comes from compiled loops and from running many independent groups side by side. You can scale parameter sweeps with the options on the [Parallel execution and caching](/features/performance/parallel-execution-and-caching/) page. !!! tip "One position per column" A column holds one net position. You can add to it with [accumulation](/features/backtesting/signal-backtesting/#accumulation-and-entry-ladders), or run several independently managed trades on one instrument by putting each trade in its own column and grouping the columns, optionally with shared cash. [Signal unraveling](/features/indicators/trading-signals/#signal-unraveling) builds those columns from one signal array. ## Simulation windows \[#simulation-windows] Indicators need history before the first signal. Instead of slicing the data, pass `sim_start` and `sim_end`: indicators see the full history, while the simulation starts flat at the given bar and stops before the end bar. ```python title="Simulate only 2022 and 2023 while the indicator uses 2021" >>> pf = vbt.PF.from_signals(close, entries, exits, sim_start="2022-01-01") >>> pf.stats(["start_index", "end_index", "total_return", "total_trades"]) Start Index 2022-01-01 00:00:00+00:00 End Index 2023-12-31 00:00:00+00:00 Total Return [%] 25.991572 Total Trades 18 Name: BTC-USD, dtype: object ``` The window can differ per column, `sim_start="auto"` starts each column at its first signal, and a callback can end a group early. Metrics, records, and plots all respect the window, as the [Simulation ranges](#simulation-ranges) highlight below shows. You can also analyze different date ranges of an existing portfolio without rerunning the backtest. ## Inputs as records \[#inputs-as-records] Bring prices and signals straight from pandas Series or DataFrames with matching timestamps and asset columns. You can use your existing data pipeline or VBT's [market data integrations](/features/data/market-data-sources/). Some strategies come as a list of events: buy this symbol on that date. Building a dense array for them is easy with the data's wrapper, for example `data.symbol_wrapper.fill(False)` followed by assignments with `.loc`. You can also skip the array entirely and pass the events as records, as shown in the [Index records](#index-records) highlight below. Records also turn a fill log from a broker, a spreadsheet, or another backtester into a portfolio. Each column of the log names an argument of the simulation method: ```python title="Replay a year of manual stock trades from a fill log" >>> data = vbt.YFData.pull(["AAPL", "NVDA"], start="2024-01-01", end="2025-01-01") >>> fills = pd.DataFrame( ... [ ... ("2024-02-05", "AAPL", 50, 188.20, 1.0), ... ("2024-03-11", "NVDA", 100, 86.40, 1.0), ... ("2024-04-22", "AAPL", -50, 166.90, 1.0), ... ("2024-06-18", "NVDA", -60, 131.70, 1.0), ... ("2024-08-05", "NVDA", 60, 101.20, 1.0), ... ("2024-11-25", "NVDA", -100, 137.40, 1.0), ... ], ... columns=["date", "symbol", "size", "price", "fixed_fees"], # (1) ... ) >>> pf = vbt.PF.from_orders( ... data, ... records=fills, ... init_cash=20_000, ... group_by=True, ... cash_sharing=True, ... ) >>> pf.trades.readable[["Column", "Size", "Avg Entry Price", "Avg Exit Price", "PnL", "Return"]] Column Size Avg Entry Price Avg Exit Price PnL Return 0 AAPL 50.0 188.20 166.9 -1067.0 -0.113390 1 NVDA 60.0 86.40 131.7 2716.4 0.523997 2 NVDA 100.0 95.28 137.4 4209.6 0.441814 >>> pf.total_return np.float64(0.29294999999999993) ``` 1. `date` and `symbol` locate each order, and the other columns become `size`, `price`, and `fixed_fees` at that bar. The partial NVDA sale closes 60 shares as one trade, and the remaining 40 shares join the August buy at an average of 95.28. Once the log is a portfolio, you can inspect its metrics and charts, or replay the orders with different fees and exit dates to explore what-if scenarios. A timestamp that falls inside a bar maps to the next bar in the data, so floor intraday fill times to the bar start first, for example with `fills["date"].dt.floor("1D")` for daily bars. A later record for the same symbol and bar overwrites an earlier one, so combine fills that share a bar before passing them. ## Inspect before running \[#inspect-before-running] Before anything is simulated, a preparer converts your arguments: strings become enums, inputs broadcast to their final shape, templates are filled, and defaults are applied. Pass `return_prep_result=True` to get that result instead of a portfolio, check or change any argument, and run it afterwards. The [Portfolio preparers](#portfolio-preparers) highlight below walks through it. ## Compile once, rerun fast \[#compile-once-rerun-fast] Research means running the same simulation many times. A few settings keep that fast: * **Compile once.** Simulators with callbacks are compiled for each new Python session. With `staticized=True`, VBT writes a cacheable copy of the simulator for your callback, so later sessions skip compilation. The copy is regenerated automatically when the callback source, the simulation settings, or the VBT version changes. Edits to other modules that the callback imports are not detected, so pass `staticized=dict(override=True)` after changing them. Simulations without callbacks use simulators that are already cached, so they compile only once per installation. * **Save what you will read.** By default, the simulation stores orders and reconstructs balances and returns when you ask for them. `save_returns=True` and related flags compute them during the simulation instead, trading memory for speed. * **Mind the memory.** Each full `float64` array takes rows × columns × 8 bytes. Twenty years of daily crypto bars across 10,000 columns is about 580 MB per array, and a simulation keeps several. Split large grids into chunks, as described on the [Parallel execution and caching](/features/performance/parallel-execution-and-caching/) page. ## Results as attributes \[#results-as-attributes] Every result is an attribute of the portfolio. `pf.sharpe_ratio` returns the value with default settings and caches it, while `pf.get_sharpe_ratio(risk_free=0.02)` takes arguments. Attributes can also be computed from arrays you supply, so you can test a different benchmark or override a series without rerunning the simulation. To add your own metrics or behavior, subclass `vbt.Portfolio`. Class methods such as `from_signals` return an instance of your subclass. To relabel results, create a new portfolio with `pf.replace(wrapper=dict(columns=...), nested_=True)`. !!! info "Documentation" The members-only [Portfolio documentation](https://members.vectorbt.pro/documentation/portfolio/) covers the simulation lifecycle, from order execution to records and wrapping. ## Portfolio preparers \[#portfolio-preparers] New in 1.12.0 ✅ When you pass an argument to a simulation method such as `Portfolio.from_signals`, it goes through a complex preparation pipeline to convert it into a format suitable for Numba. This pipeline usually involves enum mapping, broadcasting, data type checks, template substitution, and many other steps. To make VBT more transparent, this pipeline has been moved to a separate class, giving you full control over the arguments that reach the Numba functions! You can even extend the preparers to automatically prepare arguments for your own simulators. ```python title="Get a prepared argument, modify it, and use in a new simulation" >>> data = vbt.YFData.pull("BTC-USD", end="2017-01") >>> prep_result = vbt.PF.from_holding( ... data, ... stop_ladder="uniform", ... tp_stop=vbt.Param([ ... [0.1, 0.2, 0.3, 0.4, 0.5], ... [0.4, 0.5, 0.6], ... ], keys=["tp_ladder_1", "tp_ladder_2"]), ... return_prep_result=True # (1) ... ) >>> prep_result.target_args["tp_stop"] # (2) array([[0.1, 0.4], [0.2, 0.5], [0.3, 0.6], [0.4, nan], [0.5, nan]]) >>> new_tp_stop = prep_result.target_args["tp_stop"] + 0.1 >>> new_prep_result = prep_result.replace(target_args=dict(tp_stop=new_tp_stop), nested_=True) # (3) >>> new_prep_result.target_args["tp_stop"] array([[0.2, 0.5], [0.3, 0.6], [0.4, 0.7], [0.5, nan], [0.6, nan]]) >>> pf = vbt.PF.from_signals(new_prep_result) # (4) >>> pf.total_return tp_stop tp_ladder_1 0.4 tp_ladder_2 0.6 Name: total_return, dtype: float64 >>> sim_out = new_prep_result.target_func(**new_prep_result.target_args) # (5) >>> pf = vbt.PF(sim_out=sim_out, **new_prep_result.pf_args) >>> pf.total_return tp_stop tp_ladder_1 0.4 tp_ladder_2 0.6 Name: total_return, dtype: float64 ``` 1. Returns the result of the preparation. 2. Contains two attributes: target arguments as `target_args` and portfolio arguments as `pf_args`. 3. Replace the argument. Since it is inside another dictionary (`target_args`), you need to enable `nested_`. The result is a new instance of `PFPrepResult`. 4. Pass the new preparation result as the first argument to the base simulation method. 5. Or simulate manually! ## Staticization \[#staticization] New in 1.11.0 ✅ One major limitation of Numba is that functions passed as arguments (that is, callbacks) make the main function uncacheable, forcing it to be recompiled in every new runtime, again and again. This especially affects the performance of simulator functions, as they can take up to a minute to compile. Thankfully, there is a new trick available: "staticization". Here is how it works. First, the source code of a function is annotated with a special syntax. The annotated code is then extracted (also called "cutting" ✂️), modified into a cacheable version by removing any callbacks from the arguments, and saved to a Python file. Once the function is called again, the cacheable version is executed. Sound complicated? Take a look below! ```python title="Define the signal function in a Python file, here signal_func_nb.py" from vectorbtpro import * @njit def signal_func_nb(ctx, fast_sma, slow_sma): # (1) long = vbt.pf_nb.iter_crossed_above_nb(ctx, fast_sma, slow_sma) short = vbt.pf_nb.iter_crossed_below_nb(ctx, fast_sma, slow_sma) return long, False, short, False ``` 1. Make sure the function is named exactly the same as the callback argument. ```python title="Run a staticized simulation. Running the script again won't re-compile." >>> data = vbt.YFData.pull("BTC-USD") >>> pf = vbt.PF.from_signals( ... data, ... signal_func_nb="signal_func_nb.py", # (1) ... signal_args=(vbt.Rep("fast_sma"), vbt.Rep("slow_sma")), ... broadcast_named_args=dict( ... fast_sma=data.run("sma", 20, hide_params=True, unpack=True), ... slow_sma=data.run("sma", 50, hide_params=True, unpack=True) ... ), ... staticized=True # (2) ... ) ``` 1. Path to the module where the function is located. 2. Handles all the magic ✨ ## Pre-computation \[#pre-computation] New in 1.0.10 ✅ There is a tradeoff between memory usage and execution speed: a dataset with 1000 columns is usually processed much faster than processing a 1-column dataset 1000 times. However, the first dataset also requires 1000 times more memory than the second. That's why, during the simulation phase, VBT primarily generates orders, while other portfolio attributes such as balances, equity, and returns are reconstructed later during the analysis phase if the user needs them. For cases where performance is the main concern, arguments are now available that let you pre-compute these attributes during simulation! ⏩ ```python title="Benchmark a random portfolio with 1000 columns without and with pre-computation" >>> data = vbt.YFData.pull("BTC-USD") ``` ```python >>> %%timeit # (1) >>> for n in range(1000): ... pf = vbt.PF.from_random_signals(data, n=n, seed=42, save_returns=False) ... pf.sharpe_ratio 15 s ± 829 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) ``` 1. Good for RAM, bad for performance. ```python >>> %%timeit >>> pf = vbt.PF.from_random_signals(data, n=np.arange(1000).tolist(), seed=42, save_returns=False) >>> pf.sharpe_ratio 855 ms ± 6.26 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) ``` ```python >>> %%timeit >>> pf = vbt.PF.from_random_signals(data, n=np.arange(1000).tolist(), seed=42, save_returns=True) >>> pf.sharpe_ratio 593 ms ± 7.07 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) ``` ## Flexible attributes \[#flexible-attributes] New in 1.0.0 ✅ Portfolio attributes can now be partially or even fully computed from user-defined arrays. This gives you greater control over post-simulation analysis, such as overriding some simulation data, testing hyperparameters without re-simulating the entire portfolio, or avoiding repeated reconstruction when caching is disabled. ```python title="Compute the net exposure by caching its components" >>> data = vbt.YFData.pull("BTC-USD") >>> pf = vbt.PF.from_random_signals(data.close, n=100, seed=42) >>> value = pf.get_value() # (1) >>> long_exposure = vbt.PF.get_gross_exposure( # (2) ... asset_value=pf.get_asset_value(direction="longonly"), ... value=value, ... wrapper=pf.wrapper ... ) >>> short_exposure = vbt.PF.get_gross_exposure( ... asset_value=pf.get_asset_value(direction="shortonly"), ... value=value, ... wrapper=pf.wrapper ... ) >>> del value # (3) >>> net_exposure = vbt.PF.get_net_exposure( ... long_exposure=long_exposure, ... short_exposure=short_exposure, ... wrapper=pf.wrapper ... ) >>> del long_exposure >>> del short_exposure >>> net_exposure Date 2014-09-17 00:00:00+00:00 1.0 2014-09-18 00:00:00+00:00 1.0 2014-09-19 00:00:00+00:00 1.0 2014-09-20 00:00:00+00:00 1.0 2014-09-21 00:00:00+00:00 1.0 ... 2023-02-08 00:00:00+00:00 0.0 2023-02-09 00:00:00+00:00 0.0 2023-02-10 00:00:00+00:00 0.0 2023-02-11 00:00:00+00:00 0.0 2023-02-12 00:00:00+00:00 0.0 Freq: D, Length: 3071, dtype: float64 ``` 1. Call the instance method to use the data stored in the portfolio. 2. Call the class method to provide all the data explicitly. 3. Delete the object as soon as it is no longer needed to free memory. ## Shortcut properties \[#shortcut-properties] New in 1.0.0 ✅ [In-place output arrays](/features/backtesting/event-driven-backtesting/#in-place-outputs) can be used to override regular portfolio attributes. The portfolio will automatically pick the pre-computed array and perform all future calculations using this array, avoiding redundant reconstruction. ```python title="Modify the returns from within the simulation" >>> data = vbt.YFData.pull("BTC-USD") >>> size = data.symbol_wrapper.fill(np.nan) >>> np.random.seed(42) >>> rand_indices = np.random.choice(np.arange(len(size)), 10) >>> size.iloc[rand_indices[0::2]] = -np.inf >>> size.iloc[rand_indices[1::2]] = np.inf >>> @njit ... def post_segment_func_nb(ctx): ... for col in range(ctx.from_col, ctx.to_col): ... return_now = ctx.last_return[col] ... return_now = 0.5 * return_now if return_now > 0 else return_now ... ctx.in_outputs.returns[ctx.i, col] = return_now >>> pf = vbt.PF.from_def_order_func( ... data.close, ... size=size, ... size_type="targetpercent", ... post_segment_func_nb=post_segment_func_nb, ... in_outputs=dict( ... returns=vbt.RepEval("np.empty_like(close)") ... ) ... ) >>> pf.returns # (1) Date 2014-09-17 00:00:00+00:00 0.000000 2014-09-18 00:00:00+00:00 0.000000 2014-09-19 00:00:00+00:00 0.000000 2014-09-20 00:00:00+00:00 0.000000 2014-09-21 00:00:00+00:00 0.000000 ... 2023-02-08 00:00:00+00:00 -0.015227 2023-02-09 00:00:00+00:00 -0.053320 2023-02-10 00:00:00+00:00 -0.008439 2023-02-11 00:00:00+00:00 0.005569 << modified 2023-02-12 00:00:00+00:00 0.001849 << modified Freq: D, Length: 3071, dtype: float64 >>> pf.get_returns() # (2) Date 2014-09-17 00:00:00+00:00 0.000000 2014-09-18 00:00:00+00:00 0.000000 2014-09-19 00:00:00+00:00 0.000000 2014-09-20 00:00:00+00:00 0.000000 2014-09-21 00:00:00+00:00 0.000000 ... 2023-02-08 00:00:00+00:00 -0.015227 2023-02-09 00:00:00+00:00 -0.053320 2023-02-10 00:00:00+00:00 -0.008439 2023-02-11 00:00:00+00:00 0.011138 2023-02-12 00:00:00+00:00 0.003697 Freq: D, Length: 3071, dtype: float64 ``` 1. Pre-computed returns. 2. Actual returns. ## Simulation ranges \[#simulation-ranges] New in v2024.5.15 ✅ Each simulation starts and ends at specific points, usually matching the first and last rows of your data. You can set a different simulation range beforehand, and now, you can also adjust this range during the simulation. This flexibility lets you stop the simulation when further processing is unnecessary. Additionally, the date range is saved in the portfolio object, so all metrics and subplots recognize it. Processing only the relevant dates speeds up execution and adds a new dimension to your analysis: isolated time windows 🔬 === "Example 1: Liquidation" ```python title="Simulate a quick liquidation scenario" >>> @njit ... def post_segment_func_nb(ctx): ... value = vbt.pf_nb.get_group_value_nb(ctx, ctx.group) ... if value <= 0: ... vbt.pf_nb.stop_group_sim_nb(ctx, ctx.group) # (1) >>> pf = vbt.PF.from_random_signals( ... "BTC-USD", ... n=10, ... seed=42, ... sim_start="auto", # (2) ... post_segment_func_nb=post_segment_func_nb, ... leverage=10, ... ) >>> pf.plot_value() # (3) ``` 1. Stop processing the current group when its equity is depleted. This callback stops the simulation without placing a liquidation order. 2. Start the simulation at the first signal. 3. Make sure all metrics and subplots use only data up to the liquidation point, even if the portfolio contains the full original data set (2014 → today). Seeded leveraged BTC-USD portfolio value through liquidation. [Figure data (JSON)](/assets/figures/features/analysis/liquidation.abff6a63de05.json) === "Example 2: Date range analysis" ```python title="Analyze a date range of an already simulated portfolio" >>> pf = vbt.PF.from_random_signals("BTC-USD", n=10, seed=42) >>> pf.get_sharpe_ratio(sim_start="2023", sim_end="2024") # (1) 1.7846214408154346 >>> pf.get_sharpe_ratio(sim_start="2023", sim_end="2024", rec_sim_range=True) # (2) 1.8377982089422782 >>> pf.returns_stats(settings=dict(sim_start="2023", sim_end="2024")) # (3) Start Index 2023-01-01 00:00:00+00:00 End Index 2023-12-31 00:00:00+00:00 Total Duration 365 days 00:00:00 Total Return [%] 84.715081 Benchmark Return [%] 155.417419 Annualized Return [%] 84.715081 Annualized Volatility [%] 38.49976 Max Drawdown [%] 20.057773 Max Drawdown Duration 102 days 00:00:00 Sharpe Ratio 1.784621 Calmar Ratio 4.223554 Omega Ratio 1.378076 Sortino Ratio 3.059933 Skew -0.39136 Kurtosis 13.607937 Tail Ratio 1.323376 Common Sense Ratio 1.823713 Value at Risk -0.028314 Alpha -0.103145 Beta 0.770428 dtype: object ``` 1. Consider only the returns within the specified date range when calculating the Sharpe ratio. Note that returns may still be affected by data outside the date range (such as open positions). 2. Recursively apply the date range to all metrics that the Sharpe ratio depends on, such as equity, cash, and orders, treating data outside the range as if it does not exist. 3. Make sure the date range is used consistently for all statistics. ## Index records \[#index-records] New in 1.12.0 ✅ How can you backtest time- and asset-anchored queries such as "Order X units of asset Y on date Z"? Typically, you would need to build a full array and set each detail manually. Now, there is a simpler way: with preparers and redesigned smart indexing, you can provide all information in a compressed record format! Behind the scenes, the record array is translated into a set of [index dictionaries](/features/tooling/multidimensional-research/#index-dictionaries), one for each argument. ```python title="Define a basic signal strategy using records" >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"], missing_index="drop") >>> records = [ ... dict(date="2022", symbol="BTC-USD", long_entry=True), # (1) ... dict(date="2022", symbol="ETH-USD", short_entry=True), ... dict(row=-1, exit=True), ... ] >>> pf = vbt.PF.from_signals(data, records=records) # (2) >>> pf.orders.readable Order Id Column Signal Index Creation Index 0 0 BTC-USD 2022-01-01 00:00:00+00:00 2022-01-01 00:00:00+00:00 \ 1 1 BTC-USD 2023-04-25 00:00:00+00:00 2023-04-25 00:00:00+00:00 2 0 ETH-USD 2022-01-01 00:00:00+00:00 2022-01-01 00:00:00+00:00 3 1 ETH-USD 2023-04-25 00:00:00+00:00 2023-04-25 00:00:00+00:00 Fill Index Size Price Fees Side Type 0 2022-01-01 00:00:00+00:00 0.002097 47686.812500 0.0 Buy Market \ 1 2023-04-25 00:00:00+00:00 0.002097 27534.675781 0.0 Sell Market 2 2022-01-01 00:00:00+00:00 0.026527 3769.697021 0.0 Sell Market 3 2023-04-25 00:00:00+00:00 0.026527 1834.759644 0.0 Buy Market Stop Type 0 None 1 None 2 None 3 None ``` 1. Every broadcastable argument is supported. Rows can be specified using "row", "index", "date", or "datetime". Columns can be specified with "col", "column", or "symbol". If you do not provide a row or column, the entire row or column will be set, respectively. If neither is provided, the whole array will be set. Rows and columns can be given as integer positions, labels, datetimes, or even complex indexers! 2. Arguments not used in records can still be provided as usual. Arguments used in records can also be provided to serve as defaults. # Event-driven backtesting (/features/backtesting/event-driven-backtesting) Some trading rules depend on what already happened in the portfolio: a cooldown after a stop, a cap on open positions, a daily loss limit. VBT supports event-driven backtesting in Python through compiled callbacks that run inside the simulation loop, see cash, positions, and fills on every bar, and still run at Numba speed. ```python title="Block re-entries for 10 bars after a stop loss" >>> @njit ... def cooldown_signal_nb(c, entries, exits, cooldown): # (1) ... is_exit = vbt.pf_nb.select_nb(c, exits) ... if c.i < c.in_outputs.blocked_until[c.col]: ... return False, is_exit, False, False ... return vbt.pf_nb.select_nb(c, entries), is_exit, False, False >>> @njit ... def cooldown_post_order_nb(c, cooldown): # (2) ... if vbt.pf_nb.order_closed_position_nb(c): ... if vbt.pf_nb.get_last_order_nb(c)["stop_type"] >= 0: ... wait = vbt.pf_nb.select_nb(c, cooldown) ... c.in_outputs.blocked_until[c.col] = c.i + 1 + wait >>> data = vbt.YFData.pull("BTC-USD", start="2022-01-01", end="2024-01-01") >>> sma = data.close.rolling(20).mean() >>> pf = vbt.PF.from_signals( ... data, ... signal_func_nb=cooldown_signal_nb, ... signal_args=(vbt.Rep("entries"), vbt.Rep("exits"), vbt.Rep("cooldown")), ... post_order_func_nb=cooldown_post_order_nb, ... post_order_args=(vbt.Rep("cooldown"),), ... broadcast_named_args=dict( ... entries=data.close > sma, ... exits=data.close < sma, ... cooldown=vbt.Param([0, 10]), # (3) ... ), ... in_outputs=dict( ... blocked_until=vbt.RepEval("np.zeros(wrapper.shape_2d[1], dtype=np.int_)") ... ), ... sl_stop=0.05, ... ) >>> pf.stats(["total_trades", "win_rate", "total_return", "max_dd"], agg_func=None) Total Trades Win Rate [%] Total Return [%] Max Drawdown [%] cooldown 0 44 22.727273 4.394750 38.506912 10 34 29.411765 34.063625 31.897484 >>> pf[10].orders.readable[["Fill Index", "Side", "Stop Type"]].iloc[2:6] Fill Index Side Stop Type 2 2022-02-28 00:00:00+00:00 Buy None 3 2022-03-04 00:00:00+00:00 Sell SL 4 2022-03-16 00:00:00+00:00 Buy None 5 2022-04-06 00:00:00+00:00 Sell None ``` 1. Called for every bar and column. It returns four flags: long entry, long exit, short entry, and short exit. Exits always pass, so a cooldown can never trap an open position. 2. Called after each processed order. It arms the cooldown only when this order closed the position and its record says a stop caused it. 3. Run the rule without and with the cooldown in one call. Each variant gets its own column and its own `blocked_until` slot. The 5% stop fired on March 4, 2022. Without the cooldown, the trend filter bought again on March 9 and was stopped out the next day. With it, the next entry waits until March 16. In this sample, the cooldown removed 10 trades and reduced the drawdown. The point is not the result but that the rule needs the simulation's own output, so it cannot be precomputed as a signal array. ## Choose how much to customize \[#choose-how-much-to-customize] You can add a rule to an existing signal strategy or take control of order generation. Choose the level that matches what your strategy needs: | What you want to do | Use | | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Keep signal arrays and adjust sizes or stops as the account changes | An adjustment callback with `from_signals` | | Decide whether to enter or exit using current positions, fills, or PnL | A signal callback with `from_signals` | | Choose each order directly, including several orders on one bar | An order function with `from_order_func`, using flexible mode for multiple orders | | Manage your own account states and simulation loop | A custom simulator built from VBT's execution primitives | Signal callbacks retain the signal simulator's sizing, stops, limits, and conflict handling. Order functions give you direct control over the orders. Both produce a portfolio you can inspect with the same trade records, metrics, and charts. These callbacks can process a full historical backtest in one call. To continue a simulation as new bars arrive, see [Live simulation](/features/backtesting/live-simulation/). ## Callbacks that see the portfolio \[#callbacks-that-see-the-portfolio] `vbt.PF.from_signals` accepts a signal function, `signal_func_nb`, that replaces the four signal arrays. It receives a context `c` with the current bar `c.i`, the column `c.col`, and the live simulation state, then returns the four signals for that bar. Everything else, from order sizing to stops and fees, works as usual. The context exposes the state you usually need: | State | Context field or helper | | -------------------------------------------- | -------------------------------------------------------------------------- | | Position, cash, and debt | `c.last_position`, `c.last_cash`, `c.last_debt` | | Portfolio value | `c.last_value`, `vbt.pf_nb.get_group_value_nb(c, c.group)` | | Open position: entry bar, price, PnL, return | `c.last_pos_info[c.col]` | | Pending stops and limit orders | `c.last_sl_info`, `c.last_tsl_info`, `c.last_tp_info`, `c.last_limit_info` | | Your own arrays at the current bar | `vbt.pf_nb.select_nb(c, array)` | | What the last order did | `vbt.pf_nb.order_closed_position_nb(c)`, `vbt.pf_nb.get_last_order_nb(c)` | Compute indicators before the simulation and select their current value inside the callback to reuse the work across bars. If the indicator itself needs to update during simulation, you can use [streaming indicators](/features/indicators/streaming-indicators/). For calendar rules, `c.index[c.i]` holds the bar's timestamp in nanoseconds. The simulator values the portfolio at the bar's open before it calls the signal function, so `c.last_value` and the PnL in `c.last_pos_info` reflect the open, not the close. To judge a position on the close, compute it from `vbt.pf_nb.select_nb(c, c.close)`. Both fields are recomputed by the simulator, so writing to them changes nothing. To change the outcome, return different signals or edit the pending stop and limit records. !!! warning "Timing inside callbacks" A signal function decides on the bar it is called for. To act on the previous bar's data at this bar's open, read your inputs at `c.i - 1` and pass `price="open"`. With `price="nextopen"`, the simulator labels each returned signal as the previous bar's and fills it at the current open, so a callback that reads the current bar's close trades before that close exists. !!! tip "Debugging a callback" Mistakes in compiled callbacks surface as Numba typing errors. The usual causes are a function without `@njit`, a branch that returns nothing instead of four flags, and `signal_args` that is not a tuple, such as `(0.1)` instead of `(0.1,)`. To step through the logic, remove `@njit` and pass `jitted=False`: the simulator then runs in Python, so `print` and breakpoints work. !!! info "Signal function or adjustment function" `adjust_func_nb` runs before the built-in signal functions to change stops or sizes while signals still come from arrays. Once you pass your own `signal_func_nb`, that call no longer happens automatically, so call the adjustment logic from inside your signal function. ## Stateful trading rules \[#stateful-trading-rules] Most stateful rules follow the same pattern: keep a little state, read it in the signal function, and update it after orders fill. Here is a limit of three concurrent positions across a 20-asset universe that shares one cash balance: ```python title="Hold at most three positions across 20 assets" >>> symbols = [f"S{i:02d}" for i in range(20)] >>> data = vbt.GBMOHLCData.pull(symbols, start="2024-01-01", end="2025-01-01", seed=42) >>> sma = data.close.rolling(20).mean() >>> @njit ... def max_positions_nb(c, entries, exits, max_positions): ... if c.in_outputs.bar_entries[0] != c.i: # (1) ... c.in_outputs.bar_entries[:] = (c.i, 0) ... if c.last_position[c.col] > 0: ... return False, vbt.pf_nb.select_nb(c, exits), False, False ... if vbt.pf_nb.select_nb(c, entries): ... n_open = vbt.pf_nb.get_n_active_positions_nb(c) ... if n_open + c.in_outputs.bar_entries[1] < max_positions: ... c.in_outputs.bar_entries[1] += 1 ... return True, False, False, False ... return False, False, False, False >>> pf = vbt.PF.from_signals( ... data, ... signal_func_nb=max_positions_nb, ... signal_args=(vbt.Rep("entries"), vbt.Rep("exits"), 3), ... broadcast_named_args=dict( ... entries=data.close.vbt.crossed_above(sma), ... exits=data.close.vbt.crossed_below(sma), ... ), ... in_outputs=dict(bar_entries=vbt.RepEval("np.full(2, -1, dtype=np.int_)")), ... size=0.3, ... size_type="valuepercent", ... group_by=True, # (2) ... cash_sharing=True, ... ) >>> print((pf.assets > 0).sum(axis=1).max()) 3 ``` 1. Count entries approved earlier on this bar. Orders execute after the signal function has run for every column of the bar, so open positions alone miss same-bar entries. 2. Put all 20 assets into one group so the callback sees all of their positions. Without the limit, the same signals hold up to seven positions at once. Without the same-bar counter, the limit leaks and reaches five. Rules built this way include: | Rule | State it reads | | ------------------------------------------ | ------------------------------------------------------------------ | | Cooldown after a stop, a loss, or any exit | Last order record and its stop type, closed position PnL | | Maximum concurrent positions | Open positions in the group plus entries approved this bar | | Minimum holding period | Entry bar of the open position in `c.last_pos_info` | | Daily trade or loss limit | Counters and a reference value reset on the first bar of each day | | Equity curve filter | Portfolio value history kept in your own array | | Portfolio-level stop | Group value compared with a threshold, then exits for every column | The signal function and `post_segment_func_nb` run on every bar. `post_order_func_nb` runs only when the simulator tries to execute an order, including one that is rejected, and not when a signal is ignored or only places a limit order. Bookkeeping that must advance on quiet bars, such as a daily counter or a settlement delay, belongs in the segment callback, or pass `skip_empty=False` to run the order callback on every bar too. !!! info "Tutorial" The members-only [From Python to Rust](https://members.vectorbt.pro/tutorials/from-python-to-rust/dynamic/) tutorial builds the stop cooldown on a four-asset portfolio and carries it into Numba kernels and native Rust. ## Order functions \[#order-functions] Signal callbacks still produce signals, and the signal simulator places at most one order per column and bar. `vbt.PF.from_order_func` removes that layer: your callback returns orders directly. With a flexible order function, it also picks the column and can return several orders on one bar. This one buys at the open after a gap down of more than 0.5% and sells at the close of the same day: ```python title="Buy the open and sell the close on gap-down days" >>> @njit ... def open_to_close_nb(c, gap_down): ... col = c.from_col ... if not gap_down[c.i, col]: ... return -1, vbt.pf_enums.NoOrder ... if c.call_idx == 0: # (1) ... return col, vbt.pf_nb.order_nb(size=1, price=c.open[c.i, col]) ... if c.call_idx == 1: ... return col, vbt.pf_nb.close_position_nb(price=c.close[c.i, col]) ... return -1, vbt.pf_enums.NoOrder # (2) >>> data = vbt.YFData.pull("SPY", start="2024-01-01", end="2024-02-01") >>> gap_down = data.open < data.close.shift(1) * 0.995 >>> pf = vbt.PF.from_order_func( ... data, ... flex_order_func_nb=open_to_close_nb, ... flex_order_args=(vbt.Rep("gap_down"),), ... broadcast_named_args=dict(gap_down=gap_down), ... max_order_records=len(data.index) * 2, # (3) ... ) >>> pf.orders.readable[["Index", "Side", "Price"]] Index Side Price 0 2024-01-09 00:00:00-05:00 Buy 456.917453 1 2024-01-09 00:00:00-05:00 Sell 458.863770 2 2024-01-17 00:00:00-05:00 Buy 456.869019 3 2024-01-17 00:00:00-05:00 Sell 457.324127 ``` 1. The function is called repeatedly within a bar, and `c.call_idx` counts the calls. 2. Returning column `-1` ends the bar. 3. Reserve room for two orders per bar. Order functions come with a full set of lifecycle hooks. `pre_sim_func_nb` and `post_sim_func_nb` wrap the whole run, the group and segment hooks run around each asset group and each bar, and `post_order_func_nb` sees every execution result. With `row_wise=True`, the simulator finishes one timestamp across all groups before moving to the next, so callbacks can coordinate groups. `vbt.pf_nb.stop_group_sim_nb` ends a group early once a strategy has nothing left to do. !!! warning "Order within a bar" A bar is a black box. Only its open and close have a known order in time, so a callback that trades on the high and the low of the same bar has to decide which came first. ## Memory and custom outputs \[#memory-and-custom-outputs] Callbacks share state through arrays you pass in. Named tuples keep several arrays in one argument, and `in_outputs` goes one step further: arrays created there are available as `c.in_outputs` in every callback and come back with the portfolio, wrapped with its index and columns. The examples above use them for the cooldown and the position counter, and the [In-place outputs](#in-place-outputs) section below records debt on every bar. You can also record the decisions behind a result: which entries a risk rule blocked, when a cooldown was active, or what exposure the strategy saw before an order. Keeping those arrays with the portfolio lets you inspect the rule alongside its trades instead of only seeing the final return. Inside compiled callbacks, preallocate arrays and keep an explicit count instead of growing them. For state with an unknown size, pass a Numba typed list as a callback argument. ## Custom simulators \[#custom-simulators] When even order functions are too rigid, for example for several account states per asset or many pending limit orders, write the simulation loop yourself. VBT exposes the same execution primitives its own simulators use, so the result is a regular portfolio with every metric and chart: ```python title="Write a dip-buying simulator from execution primitives" >>> @njit ... def dip_buyer_nb(close, init_cash, dip, rebound): ... order_records = np.empty(close.shape, dtype=vbt.pf_enums.order_dt) ... order_counts = np.zeros(close.shape[1], dtype=np.int_) ... for col in range(close.shape[1]): ... state = vbt.pf_enums.ExecState( # (1) ... init_cash, 0.0, 0.0, 0.0, init_cash, np.nan, np.nan ... ) ... peak = close[0, col] ... for i in range(close.shape[0]): ... price = close[i, col] ... peak = max(peak, price) ... if state.position == 0 and price <= peak * (1 - dip): ... order = vbt.pf_nb.order_nb(size=np.inf, price=price) ... elif state.position > 0 and price >= peak * (1 - rebound): ... order = vbt.pf_nb.close_position_nb(price=price) ... peak = price ... else: ... continue ... _, state = vbt.pf_nb.process_order_nb( # (2) ... col, col, i, state, order, ... order_records=order_records, order_counts=order_counts ... ) ... return vbt.nb.repartition_nb(order_records, order_counts) >>> data = vbt.YFData.pull("BTC-USD", start="2023-01-01", end="2024-01-01") >>> records = dip_buyer_nb(data.close.values[:, None], 100.0, 0.1, 0.02) >>> pf = vbt.PF( ... data.symbol_wrapper, ... close=data.close, ... order_records=records, ... init_cash=100.0 ... ) >>> pf.orders.readable[["Index", "Side", "Price"]] Index Side Price 0 2023-03-07 00:00:00+00:00 Buy 22219.769531 1 2023-03-14 00:00:00+00:00 Sell 24746.074219 2 2023-04-21 00:00:00+00:00 Buy 27276.910156 3 2023-06-21 00:00:00+00:00 Sell 30027.296875 4 2023-08-17 00:00:00+00:00 Buy 26664.550781 5 2023-10-23 00:00:00+00:00 Sell 33086.234375 ``` 1. Cash, position, debt, locked cash, free cash, valuation price, and value. 2. Validates the order against cash and position, fills it, writes the order record, and returns the new state. The simulator buys after a 10% drop from the running peak and sells once the price is back within 2% of it. The same building blocks support limit orders you manage yourself, multiple orders per bar, and accounts that share cash across positions. !!! info "Documentation" The members-only [Simulation](https://members.vectorbt.pro/documentation/portfolio/simulation/) guide builds a simulator from these primitives step by step. ## Full callback support \[#full-callback-support] New in v2025.12.31 ✅ Portfolio simulation method based on signals now fully supports callbacks at every step of the process. This includes pre-processing and post-processing callbacks for the simulation as a whole, as well as per-group and per-segment callbacks, and even an order modification callback. This allows you to customize the simulation behavior to a great extent. ```python title="DCA in $100 every month until 2x in profit, take out initial investment, and DCA out" >>> DCAMode = namedtuple("DCAMode", ["In", "Out"])(0, 1) # (1) >>> @njit ... def pre_group_func_nb(ctx): # (2) ... total_deposited = np.full(1, 0.0) ... dca_mode = np.full(1, DCAMode.In) ... return (total_deposited, dca_mode) >>> @njit ... def pre_segment_func_nb(ctx, total_deposited, dca_mode, cash_deposits, dca_amount): # (3) ... if ctx.i == 0 or vbt.dt_nb.month_nb(ctx.index[ctx.i - 1]) != vbt.dt_nb.month_nb(ctx.index[ctx.i]): ... dca_amount_now = vbt.pf_nb.select_from_group_nb(ctx, ctx.group, dca_amount) ... if dca_mode[0] == DCAMode.In and ctx.track_cash_deposits: ... cash_deposits[ctx.i, ctx.group] = dca_amount_now ... total_deposited[0] += dca_amount_now ... else: ... dca_amount_now = 0.0 ... return (total_deposited, dca_mode, dca_amount_now) >>> @njit ... def signal_func_nb(ctx, total_deposited, dca_mode, dca_amount_now, size): # (4) ... if dca_amount_now > 0: ... size[ctx.i, ctx.col] = dca_amount_now ... if dca_mode[0] == DCAMode.In: ... return True, False, False, False ... return False, True, False, False ... return False, False, False, False >>> @njit ... def post_order_func_nb(ctx, total_deposited, dca_mode, dca_amount_now): # (5) ... if dca_mode[0] == DCAMode.In: ... if vbt.pf_nb.order_increased_position_nb(ctx): ... tp_info = ctx.last_tp_info[ctx.col] ... tp_info["stop"] = 1.0 ... tp_info["init_price"] = ctx.last_pos_info[ctx.col]["entry_price"] ... tp_info["exit_size"] = total_deposited[0] ... tp_info["exit_size_type"] = vbt.pf_enums.SizeType.Value ... elif vbt.pf_nb.get_last_order_nb(ctx)["stop_type"] == vbt.pf_enums.StopType.TP: ... dca_mode[0] = DCAMode.Out >>> pf = vbt.PF.from_signals( ... vbt.YFData.pull("AAPL", start="2018"), ... pre_group_func_nb=pre_group_func_nb, ... pre_segment_func_nb=pre_segment_func_nb, ... pre_segment_args=( ... vbt.Rep("cash_deposits"), ... vbt.Rep("dca_amount") ... ), ... signal_func_nb=signal_func_nb, ... signal_args=( ... vbt.Rep("size"), ... ), ... post_order_func_nb=post_order_func_nb, ... broadcast_named_args=dict(dca_amount=100), ... arg_config=dict( ... cash_deposits=dict(full_shape=True), # (6) ... size=dict(full_shape=True) ... ), ... accumulate=True, ... size_type="value", ... cash_sharing=True ... ) >>> pf.plot_orders().show() ``` 1. Define DCA modes as an enum for better readability. 2. Pre-group callback to initialize group-level variables: total cash deposited and DCA mode. This callback is called before processing each group (asset in this case because grouping is disabled). The variables are returned as a tuple to be passed to the pre-segment callback. 3. Pre-segment callback to handle DCA deposits at the start of each month. This callback is called for each group at the beginning of each bar, before generating signals for each asset in the group. The variables that are required by either the signal or post-order callbacks are returned as a tuple. 4. Signal callback to generate buy or sell signals based on the DCA amount for the current segment. If in DCA-in mode, a buy signal is generated. Otherwise, a sell signal is generated. The order size is set to the DCA amount. 5. Post-order callback to handle take-profit orders and switch DCA modes. If a buy order was executed, our take-profit order is updated to exit the initial investment when the position doubles in price. If the take-profit order was executed, the DCA mode is switched to DCA-out. 6. Specify that cash deposits and size should have the full shape of the portfolio (number of bars x number of assets) such that they can be modified in the callbacks. AAPL OHLC with monthly DCA orders that recover the initial investment and then DCA out. [Figure data (JSON)](/assets/figures/features/portfolio/dca-callbacks.fd5b757bbe5a.json) !!! info "Documentation" The members-only [callbacks guide](https://members.vectorbt.pro/documentation/portfolio/from-signals/#callbacks) covers every callback that `from_signals` accepts. ## In-place outputs \[#in-place-outputs] New in 1.0.0 ✅ The portfolio can now accept and return any user-defined arrays filled during simulation, such as signals. In-place output arrays can broadcast together with regular arrays using templates and broadcastable named arguments. Additionally, VBT will (semi-)automatically determine how to correctly wrap and index each array, for example, whenever you select a column from the entire portfolio. ```python title="Track the debt of a random portfolio during the simulation" >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"], missing_index="drop") >>> size = data.symbol_wrapper.fill(np.nan) >>> np.random.seed(42) >>> rand_indices = np.random.choice(np.arange(len(size)), 10) >>> size.iloc[rand_indices[0::2]] = -np.inf >>> size.iloc[rand_indices[1::2]] = np.inf >>> @njit ... def post_segment_func_nb(ctx): ... for col in range(ctx.from_col, ctx.to_col): ... col_debt = ctx.last_debt[col] ... ctx.in_outputs.debt[ctx.i, col] = col_debt ... if col_debt > ctx.in_outputs.max_debt[col]: ... ctx.in_outputs.max_debt[col] = col_debt >>> pf = vbt.PF.from_def_order_func( ... data.close, ... size=size, ... post_segment_func_nb=post_segment_func_nb, ... in_outputs=dict( ... debt=vbt.RepEval("np.empty_like(close)"), ... max_debt=vbt.RepEval("np.full(close.shape[1], 0.)") ... ) # (1) ... ) >>> pf.get_in_output("debt") # (2) symbol BTC-USD ETH-USD Date 2017-11-09 00:00:00+00:00 0.000000 0.000000 2017-11-10 00:00:00+00:00 0.000000 0.000000 2017-11-11 00:00:00+00:00 0.000000 0.000000 2017-11-12 00:00:00+00:00 0.000000 0.000000 2017-11-13 00:00:00+00:00 0.000000 0.000000 ... ... ... 2023-02-08 00:00:00+00:00 43.746892 25.054571 2023-02-09 00:00:00+00:00 43.746892 25.054571 2023-02-10 00:00:00+00:00 43.746892 25.054571 2023-02-11 00:00:00+00:00 43.746892 25.054571 2023-02-12 00:00:00+00:00 43.746892 25.054571 [1922 rows x 2 columns] >>> pf.get_in_output("max_debt") # (3) symbol BTC-USD 75.890464 ETH-USD 25.926328 Name: max_debt, dtype: float64 ``` 1. Instruct the portfolio class to wait until all arrays are broadcast and create a new floating array of the final shape. 2. The portfolio instance knows how to properly wrap a custom NumPy array as a pandas object. 3. The same applies to reduced NumPy arrays. ## Signal callbacks \[#signal-callbacks] New in 1.4.0 ✅ Want to customize your simulation based on signals, or even generate signals dynamically according to the current backtesting environment? Two new callbacks now bring simulator flexibility to the next level: one lets you generate or override signals for each asset at every bar, and another allows you to compute user-defined metrics for the entire group at the end of each bar. Both accept a "context" that contains information about the current simulation state, enabling trading decisions to be made in a way similar to event-driven backtesters. ```python title="Backtest SMA crossover iteratively" >>> InOutputs = namedtuple("InOutputs", ["fast_sma", "slow_sma"]) >>> def initialize_in_outputs(target_shape): ... return InOutputs( ... fast_sma=np.full(target_shape, np.nan), ... slow_sma=np.full(target_shape, np.nan) ... ) >>> @njit ... def signal_func_nb(ctx, fast_window, slow_window): ... fast_sma = ctx.in_outputs.fast_sma ... slow_sma = ctx.in_outputs.slow_sma ... fast_start_i = ctx.i - fast_window + 1 ... slow_start_i = ctx.i - slow_window + 1 ... if fast_start_i >= 0 and slow_start_i >= 0: ... fast_sma[ctx.i, ctx.col] = np.nanmean(ctx.close[fast_start_i : ctx.i + 1]) ... slow_sma[ctx.i, ctx.col] = np.nanmean(ctx.close[slow_start_i : ctx.i + 1]) ... is_entry = vbt.pf_nb.iter_crossed_above_nb(ctx, fast_sma, slow_sma) ... is_exit = vbt.pf_nb.iter_crossed_below_nb(ctx, fast_sma, slow_sma) ... return is_entry, is_exit, False, False ... return False, False, False, False >>> pf = vbt.PF.from_signals( ... vbt.YFData.pull("BTC-USD"), ... signal_func_nb=signal_func_nb, ... signal_args=(50, 200), ... in_outputs=vbt.RepFunc(initialize_in_outputs), ... ) >>> fig = pf.get_in_output("fast_sma").vbt.plot() >>> pf.get_in_output("slow_sma").vbt.plot(fig=fig) >>> pf.orders.plot(plot_ohlc=False, plot_close=False, fig=fig) >>> fig.show() ``` BTC-USD iterative 50-day and 200-day SMA crossover with buy and sell orders. [Figure data (JSON)](/assets/figures/features/portfolio/signal-callbacks.c33e37edbfeb.json) # Fees, slippage, and leverage (/features/backtesting/fees-slippage-and-leverage) A strategy that looks good before costs can fail after them. VBT lets you backtest with fees and slippage, fixed and per-share commissions, leverage, and futures contract multipliers, and test several cost levels in one call to see how much margin your edge really has. ```python title="Test one strategy at four fee levels in one call" >>> data = vbt.YFData.pull("SPY", start="2015-01-01", end="2025-01-01") >>> fast = data.close.rolling(10).mean() >>> slow = data.close.rolling(30).mean() >>> pf = vbt.PF.from_signals( ... data, ... fast.vbt.crossed_above(slow), ... fast.vbt.crossed_below(slow), ... fees=vbt.Param([0, 0.0005, 0.001, 0.002]), # (1) ... init_cash=10_000, ... ) >>> metrics = ["total_return", "total_fees_paid", "sharpe_ratio", "total_trades"] >>> pf.stats(metrics, agg_func=None).round(2) Total Return [%] Total Fees Paid Sharpe Ratio Total Trades fees 0.0000 99.33 0.00 0.83 37 0.0005 92.09 476.16 0.78 37 0.0010 85.11 933.33 0.74 37 0.0020 71.91 1793.57 0.66 37 >>> pf.value.vbt.plot().show() ``` 1. 0, 5, 10, and 20 basis points of each order's value. SPY moving average crossover portfolio value from 2015 to 2024 at fees of 0, 5, 10, and 20 basis points. [Figure data (JSON)](/assets/figures/features/backtesting/fees-cost-sensitivity.6e3bd01c30da.json) With only 37 trades in ten years, 20 basis points per order still take 27 points of total return. A strategy that trades daily would lose far more, which is why every backtest should include realistic costs from the start. ## Fees and commissions \[#fees-and-commissions] `fees` is a fraction of each order's value and `fixed_fees` a flat amount per order. A per-share commission becomes a fraction by dividing it by the price: ```python title="Compare three commission models on a 100-share order" >>> close = pd.Series([50.0], index=pd.date_range("2026-01-01", periods=1)) >>> pf = vbt.PF.from_orders( ... close, ... size=100, ... fees=vbt.Param( ... [0.001, 0.0, 0.005 / 50], # (1) ... keys=["0.1% of value", "$1 per order", "$0.005 per share"], ... level=0, ... ), ... fixed_fees=vbt.Param([0.0, 1.0, 0.0], level=0), ... init_cash=10_000, ... ) >>> pf.orders.fees.to_pd().iloc[0].droplevel("fixed_fees") fees 0.1% of value 5.0 $1 per order 1.0 $0.005 per share 0.5 Name: 2026-01-01 00:00:00, dtype: float64 ``` 1. With real data, pass `0.005 / close` to apply the per-share rate on every bar. Fees are arrays like every other argument, so they can differ per asset and per bar. Negative fees model rebates. To charge maker and taker rates, fill the fee array by signal type, for example a lower fee where the entry is a limit order. When the order type that fills is not known in advance, as with stops, or when fees depend on recent volume tiers, set the fee in a callback before the order executes. ## Slippage \[#slippage] `slippage` moves market-order fills against you by a fraction of the price: buys fill higher and sells fill lower. In the signal simulator, limit orders use their [limit fill-price rules](/features/backtesting/orders-and-execution/#pending-limit-and-stop-entry-orders) instead. ```python title="Apply 10 basis points of slippage" >>> index = pd.date_range("2026-01-01", periods=2) >>> pf = vbt.PF.from_signals( ... pd.Series([100.0, 110.0], index=index), ... pd.Series([True, False], index=index), ... pd.Series([False, True], index=index), ... slippage=vbt.Param([0, 0.001]), ... ) >>> pf.orders.readable[["Column", "Side", "Price"]] Column Side Price 0 0.000 Buy 100.00 1 0.000 Sell 110.00 2 0.001 Buy 100.10 3 0.001 Sell 109.89 ``` Slippage is applied after the simulator has decided that an order fills. A stop at $100 with 10 basis points of slippage triggers when the price reaches $100 and fills at $99.90. Slippage can push a price outside the bar's range, which `price_area_vio_mode="cap"` prevents. You can pass slippage as an array, with different estimates for each asset and bar, or update it in a callback as conditions change. For example, use larger estimates for less liquid assets or volatile periods, then compare the strategy across several assumptions. If you have bid and ask data, the [execution-price example](/features/backtesting/orders-and-execution/#execution-price-and-timing) shows how to buy at the ask and sell at the bid. ## Leverage and borrowing \[#leverage-and-borrowing] Leverage decides how much of a position may be funded with borrowed money. It does not change the size of an order by itself, so a leveraged strategy asks for more than 100% of its equity and allows the account to borrow the rest: ```python title="Hold 200% of equity in SPY, rebalanced daily" >>> data = vbt.YFData.pull("SPY", start="2020-01-01", end="2025-01-01") >>> pf = vbt.PF.from_orders( ... data, ... size=2.0, ... size_type="targetpercent", ... leverage=vbt.Param([1, 2]), ... init_cash=10_000, ... ) >>> pd.DataFrame({ ... "shares": pf.assets.iloc[0], ... "total return": pf.total_return, ... "max drawdown": pf.max_drawdown, ... }).round(3) shares total return max drawdown leverage 1 33.853 0.946 -0.337 2 67.707 1.206 -0.586 ``` Without leverage, the account can only buy with its own cash and the 200% target is capped at 100%. With leverage 2, it holds twice as many shares, rebalanced every day like a leveraged ETF. Total return rose from 95% to 121%, and the maximum drawdown from 34% to 59%. The size type decides how much of the borrowing capacity an order asks for. With `leverage=3` and $1,000 of cash at $100 a share, `size=1.0` with `size_type="percent"` buys 30 shares, all of the leveraged buying power, while `"valuepercent"` buys 10 shares, 100% of equity. The default `leverage_mode="lazy"` borrows only once own cash runs out, while `"eager"` applies leverage to every order and uses only part of the available cash. Fees are paid from own cash. The account tracks debt, locked cash, and free cash on every bar. The engine does not liquidate positions when equity reaches zero. Orders stop filling, and you decide how to treat that point in the analysis. ## Borrowing costs and funding payments \[#borrowing-costs-and-funding-payments] Financing costs depend on how much you borrow and how long you hold the position. A callback can read the debt and charge interest as negative `cash_earnings`, even on days without a trade. Here eager leverage funds a $1,000 position with $500 of borrowed cash. A sample daily rate of 0.1% charges $0.50 for each day after entry: ```python title="Charge interest on borrowed cash each day" >>> close = pd.Series([100.0, 100.0, 100.0], index=pd.date_range("2026-01-01", periods=3)) >>> @njit ... def financing_nb(ctx, cash_earnings, daily_rate): ... cash_earnings[ctx.i, ctx.col] = -ctx.last_debt[ctx.col] * daily_rate >>> pf = vbt.PF.from_signals( ... close, ... entries=[True, False, False], ... size=10, ... init_cash=1000, ... leverage=2, ... leverage_mode="eager", ... save_state=True, ... cash_earnings=np.zeros(3), ... adjust_func_nb=financing_nb, ... adjust_args=(vbt.Rep("cash_earnings"), 0.001), ... ) >>> pd.DataFrame({"debt": pf.debt, "financing": pf.cash_earnings, "value": pf.value}) debt financing value 2026-01-01 500.0 0.0 1000.0 2026-01-02 500.0 -0.5 999.5 2026-01-03 500.0 -0.5 999.0 ``` The price stays flat, so the change in equity comes entirely from financing. The example keeps cash available to pay it. Negative cash earnings are limited to free cash, so a fully invested account cannot pay them. Funding payments on perpetual swaps work the same way: a callback multiplies the position value by the rate at each funding time. Set the payment's sign for the position's direction, and use your own rate series and schedule. VBT includes these cash flows in portfolio value and returns. ## Futures and unusual instruments \[#futures-and-unusual-instruments] A futures contract controls a multiple of its quoted price. `multiplier` applies that factor to order values, cash flows, and profit, so one E-mini S\&P 500 contract moves $50 per point. Prices may also be zero or negative, which happens with spreads and with crude oil futures in April 2020. The [Contract multiplier](#contract-multiplier) and [Negative price](#negative-price) highlights below show both on real data. Contract rolls are not handled for you: back-adjust a continuous series, or close the expiring contract and open the next one with your own signals. Profit and loss is realized when positions close, and equity marks open positions to market on every bar. Daily variation margin, where exchanges move unrealized profit into cash each day, is not modeled separately. For most strategy research the resulting equity curve is the same, but cash balances during open trades differ from a futures account statement. ## Multiple currencies \[#multiple-currencies] Cash and prices must be in the same currency. For a single currency pair, quote the price in your account currency, inverting the pair if necessary, together with any order price arrays. For holdings such as foreign stocks, convert each price series to the account currency before the simulation. That includes currency exposure in each asset's value. Separate currency balances, conversion costs, and conversion of leveraged FX profit and loss require custom accounting. ## Contract multiplier \[#contract-multiplier] New in v2026.4.7 ✅ All simulation entry points now accept a multiplier that scales every order by a constant factor, making it straightforward to model futures contracts and other derivatives where one contract represents multiple units of the underlying asset. === "Example 1: E-mini S&P 500 futures" ```python title="SMA crossover on E-mini S&P 500 futures" >>> data = vbt.YFData.pull("ES=F", start="2023", end="2024") # (1) >>> fast_sma = data.run("talib_func:sma", timeperiod=10) # (2) >>> slow_sma = data.run("talib_func:sma", timeperiod=30) >>> entries = fast_sma.vbt.crossed_above(slow_sma) >>> exits = fast_sma.vbt.crossed_below(slow_sma) >>> pf_stock = vbt.PF.from_signals( # (3) ... data, ... entries=entries, ... exits=exits, ... size=1, ... init_cash=500_000, ... ) >>> pf_futures = vbt.PF.from_signals( # (4) ... data, ... entries=entries, ... exits=exits, ... size=1, ... multiplier=50, ... init_cash=500_000, ... ) >>> print(pf_stock.total_profit) 627.25 >>> print(pf_futures.total_profit) # (5) 31362.5 >>> print(pf_futures.trades.readable[["Avg Entry Price", "Avg Exit Price", "PnL", "Return"]]) Avg Entry Price Avg Exit Price PnL Return 0 4057.50 4138.00 4025.0 0.019840 1 4212.00 4480.75 13437.5 0.063806 2 4490.25 4378.75 -5575.0 -0.024832 3 4430.50 4820.00 19475.0 0.087913 ``` 1. Pull daily E-mini S\&P 500 futures data for 2023 from Yahoo Finance. 2. Generate long entry/exit signals from a 10/30 SMA crossover. The same logic works for any instrument. Only the multiplier changes the dollar impact. 3. Simulate without a multiplier, as if trading a single share of a stock tracking the index. Each point move is worth exactly $1. 4. Add a multiplier to reflect the actual E-mini S\&P 500 contract spec, where one contract controls 50 times the index value, so each point move is worth $50. 5. Profit scales exactly 50x relative to the stock-like simulation. === "Example 2: Mixed futures portfolio" ```python title="SMA crossover on ES (x50) and NQ (x20) futures simultaneously" >>> data = vbt.YFData.pull( # (1) ... ["ES=F", "NQ=F"], ... start="2023", ... end="2024", ... ) >>> fast_sma = data.run("talib_func:sma", timeperiod=10) >>> slow_sma = data.run("talib_func:sma", timeperiod=30) >>> entries = fast_sma.vbt.crossed_above(slow_sma) >>> exits = fast_sma.vbt.crossed_below(slow_sma) >>> pf = vbt.PF.from_signals( # (2) ... data, ... entries=entries, ... exits=exits, ... size=1, ... multiplier=[50, 20], ... init_cash=1_000_000, ... ) >>> print(pf.total_profit) # (3) symbol ES=F 31362.5 NQ=F 55995.0 dtype: float64 ``` 1. Pull daily data for E-mini S\&P 500 (ES, x50) and E-mini Nasdaq-100 (NQ, x20) futures. 2. Pass multiplier as a list to assign the correct contract spec to each symbol. Signals and strategy logic are identical. Only the dollar value of a point differs. 3. Each column's PnL reflects its own multiplier, so profits are in dollars without any manual scaling. ## Negative price \[#negative-price] New in v2026.4.7 ✅ The simulation engine previously rejected negative prices at validation time, making it impossible to model instruments whose price can legally go below zero (such as the infamous April 2020 WTI crude oil event). Negative prices are now fully supported across the entire pipeline. ```python title="Hold WTI crude oil through its negative close in April 2020" >>> data = vbt.YFData.pull("CL=F", start="2020-02-01", end="2020-07-01") # (1) >>> entries = pd.Series(False, index=data.index) # (2) >>> exits = pd.Series(False, index=data.index) >>> entries["2020-03-03"] = True >>> exits["2020-05-04"] = True >>> pf = vbt.PF.from_signals( # (3) ... data, ... entries=entries, ... exits=exits, ... size=1, ... multiplier=1000, ... init_cash=200_000, ... ) >>> print(data.close[data.close < 0]) # (4) Date 2020-04-20 00:00:00-04:00 -37.630001 Name: Close, dtype: float64 >>> print(pf.trades.readable[["Avg Entry Price", "Avg Exit Price", "PnL", "Return"]]) Avg Entry Price Avg Exit Price PnL Return 0 47.18 20.389999 -26790.000916 -0.567825 >>> print(pf.value[["2020-03-03", "2020-03-09", "2020-04-20", "2020-05-04"]].round(2)) # (5) Date 2020-03-03 00:00:00-05:00 200000.0 2020-03-09 00:00:00-04:00 183950.0 2020-04-20 00:00:00-04:00 115190.0 2020-05-04 00:00:00-04:00 173210.0 Name: value, dtype: float64 ``` 1. Pull daily WTI crude oil futures. 2. Enter long on March 3 and exit on May 4, holding through the negative settlement. 3. One WTI contract controls 1,000 barrels. 4. Confirm the negative settlement is in the data. 5. Portfolio value drops significantly on the day of the negative settlement, but recovers as the price rebounds. ## Leverage \[#leverage] New in 1.9.0 ✅ Leverage is now an integral part of portfolio simulation. Supports two leverage modes: `lazy` (enables leverage only if there is not enough cash) and `eager` (enables leverage while using only part of the available cash). Allows setting leverage per order, and can also determine the optimal leverage value automatically to fulfill any order requirement! 🏋️ ```python title="Explore how leverage affects the equity curve in a random portfolio" >>> data = vbt.YFData.pull("BTC-USD", start="2020", end="2022") >>> pf = vbt.PF.from_random_signals( ... data, ... n=100, ... seed=42, ... leverage=vbt.Param([0.5, 1, 2, 3]), ... ) >>> pf.value.vbt.plot().show() ``` BTC-USD random portfolio equity curves at four leverage levels from 2020 through 2021. [Figure data (JSON)](/assets/figures/features/portfolio/leverage.560bae250dca.json) # Backtesting (/features/backtesting) Backtest trading strategies in Python and see exactly what they would have done. This section is for traders and researchers who want to turn signals, orders, or custom logic into a portfolio, model how orders fill and what they cost, and account for every position and cash flow. Each page covers one part of that workflow: the simulation engine, signals and compiled callbacks, continuing a backtest on new data, intraday fills, exits, sizing, costs, and the checks that keep a backtest honest. ## Start here \[#start-here] Begin with the [Backtesting engine](/features/backtesting/backtesting-engine/) page for the three ways to simulate and how many backtests run in one call. Or choose a starting point based on what you already have: | You have | Start with | | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Buy and sell signals from indicators or a model | [Signal backtesting](/features/backtesting/signal-backtesting/) for long and short positions, reversals, and adding to positions | | Order sizes or target portfolio weights | [Backtesting engine](/features/backtesting/backtesting-engine/#three-ways-to-simulate) for turning order arrays into a portfolio, then [Position sizing](/features/backtesting/position-sizing/) for amounts and allocation targets | | Rules that depend on current cash, positions, or previous fills | [Event-driven backtesting](/features/backtesting/event-driven-backtesting/) for callbacks that make decisions as the simulation runs | | A backtest you want to continue as new data arrives | [Live simulation](/features/backtesting/live-simulation/) for carrying the portfolio state into the next run | Signals can also use callbacks, so you can keep built-in stops and limits while adding custom decisions. The [Event-driven backtesting](/features/backtesting/event-driven-backtesting/) page shows how to choose between extending signal simulation and writing your own order logic. ## Explore backtesting features \[#explore-backtesting-features] * [Backtesting engine](/features/backtesting/backtesting-engine): Simulate orders, signals, and callbacks across many assets and parameters at once * [Signal backtesting](/features/backtesting/signal-backtesting): Turn entry and exit signals into long, short, reversing, and pyramided positions * [Event-driven backtesting](/features/backtesting/event-driven-backtesting): Write compiled callbacks for cooldowns, position limits, and custom simulators * [Live simulation](/features/backtesting/live-simulation): Continue backtests on new bars, chain runs, and feed an external trading system * [Intraday and tick backtesting](/features/backtesting/intraday-and-tick-backtesting): Backtest minute bars, ticks, and sessions, and resolve stops on finer data * [Realistic backtests](/features/backtesting/backtest-realism): Avoid look-ahead bias, impossible fills, and survivorship bias in your backtests * [Orders and execution](/features/backtesting/orders-and-execution): Simulate limit and stop-entry orders, fill prices, timing, rejections, and real fills * [Stop loss and take profit](/features/backtesting/stop-loss-and-take-profit): Backtest stop losses, trailing stops, take profits, time stops, and exit ladders * [Position sizing](/features/backtesting/position-sizing): Size trades in units, cash, percent of equity, target weights, or risk per trade * [Fees, slippage, and leverage](/features/backtesting/fees-slippage-and-leverage): Model commissions, slippage, leverage, futures multipliers, and negative prices * [Portfolio accounting](/features/backtesting/portfolio-accounting): Track shared cash, deposits, dividends, positions, records, and exposure per bar ## Model the account you want to trade \[#model-the-account-you-want-to-trade] For a multi-asset strategy, start with [shared cash](/features/backtesting/portfolio-accounting/#shared-cash) and [position sizing](/features/backtesting/position-sizing/) to decide how assets share the capital. Add [fees, slippage, and leverage](/features/backtesting/fees-slippage-and-leverage/) and track deposits, dividends, and existing holdings with [Portfolio accounting](/features/backtesting/portfolio-accounting/). For strategies where the fill matters, explore [Orders and execution](/features/backtesting/orders-and-execution/), [Stop loss and take profit](/features/backtesting/stop-loss-and-take-profit/), and [Intraday and tick backtesting](/features/backtesting/intraday-and-tick-backtesting/). [Realistic backtests](/features/backtesting/backtest-realism/) brings together signal timing, price assumptions, and checks for look-ahead bias. ## Inspect results and compare strategies \[#inspect-results-and-compare-strategies] Follow a run into [Trade analytics](/features/analytics/trade-analytics/) to inspect its trades, or [Performance and risk metrics](/features/analytics/performance-metrics/) to compare returns and risk. When you are ready to explore variations, [Parameter optimization](/features/optimization/strategy-optimization/) covers testing parameter combinations, and [Walk-forward and cross-validation](/features/optimization/time-series-cross-validation/) covers testing on unseen periods. For a closer look at the code, read the [Portfolio documentation](/documentation/portfolio/) for the simulation lifecycle, or work through the [Stop signals tutorial](/tutorials/stop-signals/) for a signal-driven example. # Intraday and tick backtesting (/features/backtesting/intraday-and-tick-backtesting) A bar only tells you its open, high, low, and close. For intraday strategies with tight stops, what happened inside the bar decides the result. VBT runs intraday and tick backtesting in Python on bars of any size, on irregular timestamps, and within trading sessions, and lets you resolve stops on finer data than the signals use. ```python title="Resolve the same stops on hourly and on minute bars" >>> minute_data = vbt.GBMOHLCData.pull( # (1) ... "SYN", ... start="2024-01-01", ... end="2024-02-01", ... timeframe="1min", ... std=0.0001, ... seed=42, ... ) >>> hourly_data = minute_data.resample("1h") >>> hourly_entries = hourly_data.symbol_wrapper.fill(False) >>> hourly_entries.iloc[::4] = True # (2) >>> minute_entries = minute_data.symbol_wrapper.fill(False) >>> entry_minutes = hourly_entries.index[hourly_entries] + pd.Timedelta(minutes=59) >>> minute_entries[entry_minutes] = True # (3) >>> kwargs = dict(sl_stop=0.002, tp_stop=0.002) >>> hourly_pf = vbt.PF.from_signals(hourly_data, hourly_entries, **kwargs) >>> minute_pf = vbt.PF.from_signals(minute_data, minute_entries, **kwargs) >>> def summary(pf): ... stop_types = pf.orders.readable["Stop Type"].value_counts() ... return pd.Series({ ... "trades": pf.trades.count(), ... "stop losses": stop_types.get("SL", 0), ... "take profits": stop_types.get("TP", 0), ... "win rate": round(pf.trades.win_rate, 3), ... "total return": round(pf.total_return, 3), ... }) >>> pd.DataFrame({"hourly bars": summary(hourly_pf), "minute bars": summary(minute_pf)}) hourly bars minute bars trades 186.000 186.000 stop losses 134.000 102.000 take profits 52.000 84.000 win rate 0.280 0.452 total return -0.152 -0.036 ``` 1. A month of seeded synthetic minute bars with a typical hourly range of about 0.8%. 2. Enter at the close of every fourth hour. 3. The same entries on the minute data: at the close of the last minute of each entry hour. Both runs take the same 186 trades with the same 0.2% stop loss and take profit. On hourly bars, many bars reach both levels, and with no way to know which came first the simulator assumes the stop loss. Minute bars resolve more of those cases, and the win rate moves from 28% to 45%, much closer to the 50% that symmetric stops on a random walk should produce. ## Ticks and irregular bars \[#ticks-and-irregular-bars] Nothing in the engine assumes a fixed bar size. Tick prices go in as `close`, each row is processed as its own moment, and the open, high, and low are not needed. Volume bars, range bars, dollar bars, and trade-count bars built elsewhere work the same way, because the index only needs to be sorted: ```python title="Trade on ticks with irregular timestamps" >>> index = pd.date_range("2024-01-01 09:30", periods=8, freq="1s").vbt.randomize( ... step="100ms", ... seed=42, ... ) >>> prices = [100.0, 100.2, 100.1, 100.4, 100.3, 100.6, 100.5, 100.7] >>> ticks = pd.Series(prices, index=index) >>> ticks.index.to_series().diff().dt.total_seconds().tolist() [nan, 0.8, 1.6, 1.2, 0.8, 0.6, 1.0, 1.0] >>> entries = pd.Series([True] + [False] * 7, index=index) >>> exits = pd.Series([False] * 6 + [True, False], index=index) >>> pf = vbt.PF.from_signals(ticks, entries, exits) >>> pf.orders.readable[["Fill Index", "Side", "Price"]] Fill Index Side Price 0 2024-01-01 09:30:00 Buy 100.0 1 2024-01-01 09:30:06 Sell 100.5 ``` Metrics that annualize, such as the Sharpe ratio, need a frequency, which an irregular index does not have. Pass `freq` explicitly, use `freq="index_mean"` to take the average spacing of the timestamps, or resample the portfolio's returns to a regular grid for analysis. Durations are counted as bars times this frequency, so with the average spacing they are estimates. How long a year is matters as well, as explained under [Returns](/features/analytics/performance-metrics/#returns). To build synthetic tick data for tests, `vbt.RandomOHLCData` and `vbt.GBMOHLCData` generate prices, and `.vbt.randomize()` turns a regular index into irregular timestamps as above. !!! warning "Windows on ticks count rows, not time" Most indicators take a window in rows. On ticks, a 20-row window can span a second or an hour depending on activity. Compute indicators on time bars, or use time-based windows such as `ticks.rolling("5min")`, and align the result back to the tick index. ## Inside the bar \[#inside-the-bar] There are three ways to see inside a bar. The first is the one above: compute signals on the bars you trade, and run the simulation on finer bars so stops and limits are checked at finer resolution. Results can be resampled back to the original timeframe for reporting. An hourly strategy can therefore use minute or tick prices for execution without changing its indicator windows to minutes or ticks. VBT's alignment tools let you place an hourly closing signal where that hour ends and make a daily trend filter available only after the day closes. See [Multi-timeframe analysis](/features/data/multi-timeframe-analysis/) for combining signals, filters, and prices from different timeframes. The second is to place several orders inside one bar. The signal simulator processes at most one order per column and bar. A flexible order function returns as many orders as you need, for example a buy at the open and a sell at the close of the same bar, as shown on the [Event-driven backtesting](/features/backtesting/event-driven-backtesting/#order-functions) page. The third keeps the signal simulator and splits each bar into sub-bars: one for the open, one for the range in between, and one for the close. Stops then fill in the first two, your own signals execute in the last, and a position can close and reopen within one original bar. `pf.resample` maps the result back to the original index. !!! info "Cookbook" The members-only [multiple actions per bar](https://members.vectorbt.pro/cookbook/portfolio/#perform-multiple-actions-per-bar) recipe builds the three sub-bars and resamples the portfolio back. !!! warning "What a bar cannot tell" Only the open and the close of a bar have a known order in time. When a strategy depends on whether the high came before the low, either use finer data or accept the pessimistic assumption. See [Realistic stop fills](/features/backtesting/stop-loss-and-take-profit/#realistic-stop-fills) for the exact rules. ## Trading sessions \[#trading-sessions] A session is a mask over the index. Restrict entries to the session, add an exit on the last bar of each session, and the strategy is flat every night: ```python title="Trade a New York session and be flat at every close" >>> data = minute_data.loc["2024-01-08":"2024-01-12"] >>> local_index = data.index.tz_convert("America/New_York") >>> local_time = local_index.time >>> in_session = (local_time >= pd.Timestamp("09:30").time()) & ( ... local_time < pd.Timestamp("16:00").time() ... ) >>> session_end = local_time == pd.Timestamp("15:59").time() >>> sma = data.close.rolling(30).mean() >>> entries = data.close.vbt.crossed_above(sma) & in_session & ~session_end >>> exits = data.close.vbt.crossed_below(sma) | session_end >>> pf = vbt.PF.from_signals(data, entries, exits) >>> print(pf.trades.count()) 91 >>> pf.assets.groupby(local_index.date).last().tolist() # (1) [0.0, 0.0, 0.0, 0.0, 0.0, 0.0] ``` 1. The position at the end of each local day. Rows without a price place no order. With `price="nextopen"`, a Friday signal whose next row is an empty weekend row never fills. Drop the rows where the market is closed, for example with `missing_index="drop"` when pulling several symbols, so the next row is the next session's open. Signals that appear while the market is closed need a rule. Either drop them, or carry them to the first bar of the next session so the live position matches the backtest. Rules such as "no exit on the day of entry" are masks as well, comparing each exit with the date of the entry before it. To build bars that only cover the session, for example a daily bar from 09:30 to 16:00 out of 24-hour data, filter the data to the session first or resample between custom bounds. You can also test sessions independently. Put equal-length sessions in separate columns to compare a strategy across days, with a fresh cash balance for each session. This is useful for strategies that close every day and for finding whether a few sessions account for most of the result. !!! info "Tutorial" The members-only [MTF analysis](https://members.vectorbt.pro/tutorials/mtf-analysis/aggregation/) tutorial aggregates intraday data into session bars with custom bounds. ## Longer intraday histories \[#longer-intraday-histories] Simulate on ticks, then zoom out to the bigger picture. Resample the finished portfolio to minute, hourly, or daily bars for analysis. VBT maps its order records to the new index and reconstructs portfolio values and returns at that frequency, so you can inspect the broader result with less data to process and plot. Keep the original portfolio for inspecting individual fills. For a history processed in successive batches, a portfolio can also continue on the next batch with its cash, positions, and stops carried forward. The same mechanism used for [Live simulation](/features/backtesting/live-simulation/) lets a historical run cross batch boundaries without closing positions at each boundary. # Live simulation (/features/backtesting/live-simulation) Can a backtest keep running as new bars arrive, without recomputing its history? VBT continues a portfolio from its last state: cash, positions, pending stops, and limit orders carry over, so each new bar advances the simulation from where it stopped. You can replay historical data, then keep the same simulated account running on new data for incremental backtests and paper trading in Python. ```python title="Replay the last 35 days of 2023 one bar at a time" >>> data = vbt.YFData.pull("BTC-USD", start="2023-01-01", end="2024-01-01") >>> def get_signals(data): ... sma = data.close.rolling(20).mean() ... return data.close.vbt.crossed_above(sma), data.close.vbt.crossed_below(sma) >>> history = data.iloc[:330] >>> entries, exits = get_signals(history) >>> pf = vbt.PF.from_signals( ... history, ... entries, ... exits, ... tsl_stop=0.05, ... attach_preparer=True, # (1) ... ) >>> emitted = [] >>> for i in range(330, len(data.index)): ... available = data.iloc[:i + 1] # (2) ... entries, exits = get_signals(available) ... pf = pf.update( # (3) ... available.iloc[-1:], ... entries=entries.iloc[-1:], ... exits=exits.iloc[-1:], ... ) ... orders = pf.orders.readable ... emitted.append(orders[orders["Fill Index"] == available.index[-1]]) # (4) >>> pd.concat(emitted)[["Fill Index", "Side", "Price", "Stop Type"]] Fill Index Side Price Stop Type 45 2023-12-11 00:00:00+00:00 Sell 42470.239844 TSL 46 2023-12-18 00:00:00+00:00 Buy 42623.539062 None 47 2023-12-26 00:00:00+00:00 Sell 42149.559180 TSL 48 2023-12-27 00:00:00+00:00 Buy 43442.855469 None 49 2023-12-28 00:00:00+00:00 Sell 42627.855469 None >>> entries, exits = get_signals(data) >>> full_pf = vbt.PF.from_signals(data, entries, exits, tsl_stop=0.05) # (5) >>> pf.orders.records.equals(full_pf.orders.records), pf.value.equals(full_pf.value) (True, True) ``` 1. Keep the simulation arguments so later updates reuse them. 2. Only the data up to the new bar exists. The signals are computed from it, as they would be live. 3. Simulate only the new bar, starting from the stored state, and append it to the history. 4. The orders this bar produced, ready to hand to an execution system. 5. Run the whole year at once to check the incremental result. The trailing stop that fired on December 11 belonged to a position opened before the replay began. Its peak price was carried through every update. After 35 single-bar updates, the orders and the equity curve match the one-shot backtest exactly. ## From research updates to live data \[#from-research-updates-to-live-data] Keep your research moving as new data arrives. Continuation connects historical backtests, incremental analysis, and simulated trading: | What you want to do | How VBT handles it | | ------------------------------------------------------- | ---------------------------------------------------- | | Update a strategy after another day of prices | Extend the portfolio with `pf.update` | | Replay a historical feed or monitor a simulated account | Process one new bar or a batch of bars at a time | | Retrain a model or change parameters between periods | Chain simulations while carrying the account forward | | Keep a native simulator running between incoming bars | Advance a Rust stepper and save checkpoints | The sections below cover both Python portfolio updates and native Rust stepping. Your data source and execution system can remain separate from the simulation. ## Continuing from the last state \[#continuing-from-the-last-state] `pf.update` takes new data and new inputs and continues from the portfolio's last state. That state includes cash, positions, debt, the valuation price, entry prices, pending limit orders, and every stop, including trailing peaks and time-stop counters. By default the result contains the full history. With `stack=False` it contains only the new segment, which is cheaper when you only need the latest orders. Continuation also works with custom trading rules. A cooldown after a loss, for example, can span several updates. Keep your callback's memory alongside the portfolio state and pass it into the next update. The [Event-driven backtesting](/features/backtesting/event-driven-backtesting/) page introduces these rules, and the live tutorial shows how to carry their memory forward. ## Resume after a restart \[#resume-after-a-restart] The state can also be stored. `save_state=True` keeps the cash and position series computed during the simulation, and `pf.last_state` holds the final state that a later run starts from. A portfolio built with `attach_preparer=True` can be written to disk with `pf.save(path)` and restored with `vbt.PF.load(path)` in a later session, ready for the next `pf.update`. For a complete live pipeline, also retain the indicator state and any custom strategy memory your application owns. The [Portfolio continuation](#portfolio-continuation) highlight below verifies a trailing stop and a time stop across updates. ## Chaining and hybrid runs \[#chaining-and-hybrid-runs] Some workflows need to stop the simulation on purpose: retrain a model every month, reoptimize weights, or change parameters between periods. Run the backtest in segments, start each segment from the previous one, and stack the segments into one history with `vbt.PF.row_stack`. The [Chaining simulations](#chaining-simulations) highlight below builds such a chain, and the same pattern lets a portfolio optimizer re-estimate weights at each rebalance with the account carried forward. ## Bar-by-bar stepping \[#bar-by-bar-stepping] The native Rust engine adds steppers: a simulator object that stays in memory and advances one bar at a time, with strategy and execution state kept between steps. A stepper can be cloned or serialized as a checkpoint and restored later, for example after a restart, and its outputs can be saved as NumPy files that Python loads back into a portfolio. !!! info "Tutorial" The members-only [From Python to Rust](https://members.vectorbt.pro/tutorials/from-python-to-rust/live/) tutorial continues a stateful strategy in Python, in Numba, and with a native Rust stepper, and checks that all three agree. ## Live pipelines \[#live-pipelines] A live loop has three stages, and each one keeps its own state: the data, the indicators, and the portfolio. `data.update()` fetches new bars and, with `return_meta=True`, reports which rows were appended and which were revised. Indicators either recompute over the window they need or, for streaming indicators, update from their last state. The portfolio continues with `pf.update`. `vbt.wait(timeframe, floor=True)` sleeps until the next bar boundary, so the loop runs right after each bar closes: ```python title="Structure of a polling loop" >>> while True: ... vbt.wait("1h", floor=True) ... update = data.update(return_meta=True) ... data = update["data"] ... for row in update["appended"]: ... ... # compute signals for the closed bar, then call pf.update ``` ## Connecting to a broker \[#connecting-to-a-broker] VBT does not send orders to a broker. It decides and simulates, and your execution layer routes the orders, handles fills, and reports them back. A few rules keep the two consistent: * **Decide on closed bars.** Use only completed bars for signals, so a decision cannot change after it was acted on. Many sources also return the bar that is still forming, so drop it before computing signals. * **Plan before the fill.** With next-open execution, the order to place comes from the signals of the last closed bar. The simulator records it only once the next bar arrives, and a stop or a conflicting signal can still change it. * **Reconcile.** Compare the broker's fills and positions with the simulated ones after each update, and avoid sending an order twice when a bar is revised. Real fills can be analyzed as a portfolio of their own, as shown on the [Orders and execution](/features/backtesting/orders-and-execution/#live-fills-versus-the-backtest) page. Order records hold only filled orders. Pending stops and limit orders live in the final state, so a broker-side stop can mirror the simulated one: ```python title="Read the trailing stop level to place at the broker" >>> data = vbt.YFData.pull("ETH-USD", start="2024-09-01", end="2024-11-13") >>> sma = data.close.rolling(20).mean() >>> pf = vbt.PF.from_signals( ... data, ... data.close.vbt.crossed_above(sma), ... data.close.vbt.crossed_below(sma), ... tsl_stop=0.08, ... ) >>> state = pf.last_state # (1) >>> position = float(state.last_position[0]) >>> tsl_info = state.last_tsl_info[0] >>> position, float(tsl_info["peak_price"]) (0.0333110557990236, 3444.154052734375) >>> vbt.pf_nb.get_tsl_info_target_price_nb(tsl_info, position) # (2) 3168.621728515625 ``` 1. Cash, position, open position info, and every pending stop and limit order after the last bar. 2. 8% below the highest price since entry. The helper returns `NaN` when no trailing stop is active. The position opened on November 6 and is still open after the November 12 close. If the next bar trades through 3168.62, the backtest sells at that level, or at the open if the bar opens below it. Your execution layer can use the same stop level at the broker and reconcile the actual fill with the simulated one. ## Portfolio continuation \[#portfolio-continuation] New in v2026.9.5 ✅ Pick up right where your simulation left off as new data arrives. VBT carries positions, order IDs, and stop state into each update, including entry timestamps and trailing highs. Your trailing stops remember their peaks, your time stops keep counting, and each update returns a new portfolio with the combined history. === "Trailing stop" ```python title="Preserve a trailing stop across two updates" >>> close = pd.Series( ... [100.0, 110.0, 108.0, 98.0, 103.0, 115.0], ... index=pd.date_range("2026-09-01", periods=6, freq="D") ... ) >>> entries = pd.Series([True, False, False, False, True, False], index=close.index) >>> pf_kwargs = dict(size=1, init_cash=1000, tsl_stop=0.05, freq="1D") >>> pf = vbt.PF.from_signals( ... close.iloc[:2], ... entries=entries.iloc[:2], ... attach_preparer=True, # (1) ... **pf_kwargs, ... ) >>> for start in [2, 4]: ... pf = pf.update( # (2) ... close.iloc[start:start + 2], ... entries=entries.iloc[start:start + 2], ... ) >>> print(pf.orders.readable[["Order Id", "Fill Index", "Side", "Price", "Stop Type"]]) Order Id Fill Index Side Price Stop Type 0 0 2026-09-01 Buy 100.0 None 1 1 2026-09-04 Sell 98.0 TSL 2 2 2026-09-05 Buy 103.0 None >>> full_pf = vbt.PF.from_signals(close, entries=entries, **pf_kwargs) # (3) >>> pf.orders.records.equals(full_pf.orders.records) and pf.value.equals(full_pf.value) True ``` 1. Keep the simulation arguments available for subsequent updates. 2. Preserve the $110 trailing high across updates. The 5% stop exits at $98, the next available close below the threshold. Updates join the history by default. Use `stack=False` to return only the new segment. 3. Compare the combined order records and portfolio value with a single run over the full dataset. === "Time stop" ```python title="Preserve a three-day time stop across an update" >>> close = pd.Series( ... [100.0, 110.0, 108.0, 98.0, 103.0, 115.0], ... index=pd.date_range("2026-09-01", periods=6, freq="D") ... ) >>> entries = pd.Series([True, False, False, False, True, False], index=close.index) >>> pf = vbt.PF.from_signals( ... close.iloc[:2], ... entries=entries.iloc[:2], ... td_stop="3 days", ... size=1, ... init_cash=1000, ... attach_preparer=True, ... freq="1D", ... ) >>> pf = pf.update(close.iloc[2:], entries=entries.iloc[2:]) # (1) >>> print(pf.orders.readable[["Fill Index", "Side", "Stop Type"]]) Fill Index Side Stop Type 0 2026-09-01 Buy None 1 2026-09-04 Sell TD 2 2026-09-05 Buy None ``` 1. The entry timestamp remains September 1, so the three-day stop exits on September 4. The next entry on September 5 starts a new holding period. !!! info "Tutorial" Learn more in the [Live simulation](https://members.vectorbt.pro/tutorials/from-python-to-rust/live/) tutorial. ## Chaining simulations \[#chaining-simulations] New in v2026.3.1 ✅ Every built-in simulation function now returns the final simulation state after processing all data, including the last cash, position, pending order(s), and other relevant information. This state can be passed to the next simulation run, allowing you to continue from where the previous run ended. This enables seamless chaining of simulations across different time periods or datasets. === "Example 1: Monthly" ```python title="Simulate a SMA crossover strategy on a monthly basis" >>> data = vbt.BinanceData.pull( # (1) ... "BTCUSDT", ... start="one year ago", ... timeframe="5 minutes", ... cache=True ... ) >>> fast_sma = data.run("talib_func:sma", timeperiod=20) # (2) >>> slow_sma = data.run("talib_func:sma", timeperiod=50) >>> long_entries = fast_sma.vbt.crossed_above(slow_sma) >>> short_entries = fast_sma.vbt.crossed_below(slow_sma) >>> single_pf = vbt.PF.from_signals( # (3) ... data, ... long_entries=long_entries, ... short_entries=short_entries, ... ) >>> data_splits = data.split(by="month") # (4) >>> long_entries_splits = long_entries.vbt.split(by="month", into=None) >>> short_entries_splits = short_entries.vbt.split(by="month", into=None) >>> pf_list = [] >>> last_state = None >>> for i in range(len(data_splits)): # (5) ... pf = vbt.PF.from_signals( ... data_splits.iloc[i], ... long_entries=long_entries_splits.iloc[i], ... short_entries=short_entries_splits.iloc[i], ... last_state=last_state, ... ) ... pf_list.append(pf) ... last_state = pf.last_state >>> stacked_pf = vbt.PF.row_stack(*pf_list, chained=True) # (6) >>> print(stacked_pf.returns.equals(single_pf.returns)) True ``` 1. Pull 5-minute BTC data for the past year from Binance and cache it for faster access. 2. Generate long and short entry signals for full dataset based on a simple SMA crossover strategy. 3. Run a single simulation on the full dataset as a reference. 4. Split the data and signals by month to run simulations on a monthly basis. 5. Iterate through each month, running a simulation with the corresponding data and signals, and passing the last state from the previous simulation to the next one. 6. Row-stack the resulting portfolio objects together. The result is identical to the single simulation on the full dataset. === "Example 2: Live data stream" ```python title="Simulate a SMA crossover strategy on a live data stream" >>> def generate_signals(data): ... fast_sma = data.run("talib_func:sma", timeperiod=20) ... slow_sma = data.run("talib_func:sma", timeperiod=50) ... long_entries = fast_sma.vbt.crossed_above(slow_sma) ... short_entries = fast_sma.vbt.crossed_below(slow_sma) ... return long_entries, short_entries >>> data = vbt.BinanceData.pull( # (1) ... "BTCUSDT", ... start="1 day ago", ... end="1 minute ago", ... timeframe="1 minute" ... ) >>> long_entries, short_entries = generate_signals(data) >>> pf = vbt.PF.from_signals( # (2) ... data, ... long_entries=long_entries, ... short_entries=short_entries, ... attach_preparer=True ... ) >>> with vbt.ProgressBar() as pbar: ... while True: ... try: ... vbt.wait("1 minute", floor=True) # (3) ... except KeyboardInterrupt: ... break ... ... n_bars = len(data.index) ... data = data.update() # (4) ... if len(data.index) == n_bars: ... pbar.set_postfix(str(data.index[-1])) ... pbar.update() ... continue ... ... long_entries, short_entries = generate_signals(data) ... new_pf = pf.update( # (5) ... data.iloc[n_bars:], ... long_entries=long_entries.iloc[n_bars:], ... short_entries=short_entries.iloc[n_bars:], ... stack=False ... ) ... new_orders = new_pf.orders.readable ... if len(new_orders) > 0: # (6) ... for i in range(len(new_orders)): ... print("NEW ORDER:") ... print(new_orders.iloc[i]) ... print() ... ... pf = vbt.PF.row_stack( # (7) ... (pf, new_pf), ... chained=True, ... preparer=new_pf.preparer ... ) ... pbar.set_postfix(str(data.index[-1])) ... pbar.update() ``` 1. Pull 1-minute BTC data for the past day from Binance. Don't include the most recent minute to avoid incomplete data. 2. Run an initial simulation on the full dataset and attach the preparer to access the original simulation arguments later. 3. Wait for the next minute to start, ensuring that we have new data to work with. Flooring the wait time ensures that we align with the start of the minute. 4. Update the data to get the latest bars. If no new bars are available, skip the rest of the loop. 5. Update the portfolio with the new data and signals, without stacking it with the previous portfolio to keep it separate. 6. Check for new orders generated by the update and print them out. 7. Row-stack the new portfolio with the previous one, enabling seamless continuation while keeping the history of the simulation intact. # Orders and execution (/features/backtesting/orders-and-execution) How exactly does a backtest fill your orders, and can it model orders that wait for a price? VBT simulates market, limit, and stop-entry orders with explicit rules for price, timing, expiry, and rejection, so you can backtest limit orders in Python and see why each order filled or did not. ```python title="Buy a breakout with a stop-entry order that expires after five bars" >>> data = vbt.YFData.pull("BTC-USD", start="2023-01-01", end="2024-01-01") >>> sma = data.close.rolling(50).mean() >>> setup = data.close.vbt.crossed_above(sma) >>> order_type = data.symbol_wrapper.fill("market") >>> order_type[setup] = "limit" # (1) >>> price = data.symbol_wrapper.fill(np.inf) >>> price[setup] = data.high.rolling(10).max()[setup] # (2) >>> breakout_pf = vbt.PF.from_signals( ... data, ... entries=setup, ... exits=data.close.vbt.crossed_below(sma), ... order_type=order_type, ... price=price, ... limit_reverse=True, # (3) ... limit_tif=5, ... time_delta_format="rows", ... size=0.3, ... init_cash=10_000, ... fees=0.0004, ... ) >>> print(setup.sum(), breakout_pf.orders.side_buy.count()) 6 3 >>> cols = ["Signal Index", "Fill Index", "Price", "Side", "Type"] >>> breakout_pf.orders.readable[cols].head(4) Signal Index Fill Index Price Side Type 0 2023-03-13 00:00:00+00:00 2023-03-14 00:00:00+00:00 24550.837891 Buy Limit 1 2023-05-01 00:00:00+00:00 2023-05-01 00:00:00+00:00 28091.568359 Sell Market 2 2023-06-20 00:00:00+00:00 2023-06-21 00:00:00+00:00 28388.968750 Buy Limit 3 2023-07-30 00:00:00+00:00 2023-07-30 00:00:00+00:00 29275.308594 Sell Market ``` 1. Entries become pending orders. Exits stay market orders that fill at the close. 2. The order waits for the 10-day high, the breakout level at the time of the setup. 3. A reversed limit buys when the price rises to the level, which makes it a stop-entry order. Six setups produced three trades. The other three breakouts never happened within five bars, so their orders expired unfilled, exactly as a resting stop order would at a broker. ## Pending limit and stop-entry orders \[#pending-limit-and-stop-entry-orders] With `order_type="limit"`, a signal creates an order that waits for its target price. The target comes from `price`, optionally moved by `limit_delta`, and the order is checked against the high and low of each following bar. `limit_reverse=True` flips the direction of the check, which turns a limit into a stop-entry order. Pending orders can expire after a number of bars or a duration with `limit_tif`, or at a date or period boundary with `limit_expiry`, which covers day orders, good-till-canceled, and good-till-date orders. A positive `limit_delta` places an ordinary buy limit below the price and a sell limit above it. Reversing the limit puts the trigger on the other side, for buying breakouts or selling breakdowns. Use `limit_delay=True` when a limit should start checking prices on the next bar even if it could fill on its creation bar. This is separate from expiry: you choose when the order can start filling as well as when to stop waiting. When the price gaps through the level, the fill price is a choice: ```python title="Fill a buy limit after a gap down" >>> index = pd.date_range("2026-01-01", periods=4) >>> pf = vbt.PF.from_signals( ... pd.Series([100.0, 100.0, 98.5, 99.0], index=index), ... pd.Series([True, False, False, False], index=index), ... open=pd.Series([100.0, 100.5, 97.0, 98.0], index=index), ... high=pd.Series([100.0, 101.0, 99.0, 99.5], index=index), ... low=pd.Series([100.0, 99.0, 96.5, 97.5], index=index), ... order_type="limit", ... limit_delta=0.02, # (1) ... limit_order_price=vbt.Param(["autolimit", "limit"]), ... ) >>> pf.orders.readable[["Column", "Signal Index", "Fill Index", "Price"]] Column Signal Index Fill Index Price 0 autolimit 2026-01-01 2026-01-03 98.0 1 limit 2026-01-01 2026-01-03 97.0 ``` 1. Buy 2% below the $100 close of the signal bar, so at $98. The default fills an ordinary limit at its limit price, the conservative assumption, and fills a stop-entry order at the open when the price gaps through it. `"limit"` lets an ordinary limit fill at the better open. Order sizes are resolved when the order fills, not when it is placed, so a percentage size uses the cash available at that moment. The signal simulator keeps one pending limit order per column. While it waits, a new signal in the same direction is ignored by default, so the order keeps its first price. `upon_adj_limit_conflict="cancelexecute"` replaces it instead, which re-quotes the order from each new signal: ```python title="Keep or re-quote a buy limit while the price rises" >>> index = pd.date_range("2026-01-01", periods=5) >>> close = pd.Series([100.0, 101.0, 102.0, 103.0, 99.0], index=index) >>> open_ = pd.Series([100.0, 100.5, 101.5, 102.5, 102.0], index=index) >>> pf = vbt.PF.from_signals( ... close, ... pd.Series([True, True, True, True, False], index=index), ... open=open_, ... high=np.maximum(open_, close) + 0.5, ... low=np.minimum(open_, close) - 0.5, ... order_type="limit", ... limit_delta=0.02, ... upon_adj_limit_conflict=vbt.Param(["keepignore", "cancelexecute"]), ... ) >>> pf.orders.readable[["Column", "Signal Index", "Fill Index", "Price"]] Column Signal Index Fill Index Price 0 cancelexecute 2026-01-04 2026-01-05 100.94 ``` The first order waits at $98, 2% below the first close, and the drop on the last day stops at $98.50, so it never fills. The re-quoted order follows the rising closes, sits at $100.94 after the fourth signal, and fills. `upon_opp_limit_conflict` does the same for an opposite signal, and cancels the pending order by default. Limit prices can also be changed while the order waits from an adjustment function, and strategies that need several resting orders at once, such as grids or order books, manage them in a callback or a custom simulator. The members-only [custom order logic](https://members.vectorbt.pro/cookbook/portfolio/#custom-order-logic) recipe tracks opposing breakout levels. [Event-driven backtesting](/features/backtesting/event-driven-backtesting/) shows how to keep custom state and place multiple orders within a bar. ## Adjusting pending orders \[#adjusting-pending-orders] Adjust a pending order as conditions change. Move its price or temporarily suspend fills while keeping the order active. For example, you might block entries during scheduled news or while the portfolio already has enough open positions. Here a buy limit waits 2% below $100. The price reaches $98 on the second day, but a rule blocks fills that day. The same order fills when $98 is reached again: ```python title="Temporarily suspend a pending buy limit" >>> index = pd.date_range("2026-01-01", periods=4) >>> close = pd.Series([100.0, 98.0, 99.0, 98.0], index=index) >>> can_fill = np.array([True, False, True, True]) >>> @njit ... def adjust_limit_nb(ctx, can_fill): ... if ctx.last_limit_info["creation_idx"][ctx.col] != -1: ... ctx.last_limit_info["delta"][ctx.col] = 0.02 if can_fill[ctx.i] else np.inf >>> pf = vbt.PF.from_signals( ... close, ... entries=[True, False, False, False], ... order_type="limit", ... limit_delta=0.02, ... adjust_func_nb=adjust_limit_nb, ... adjust_args=(can_fill,), ... ) >>> pf.orders.readable[["Signal Index", "Fill Index", "Price"]] Signal Index Fill Index Price 0 2026-01-01 2026-01-04 98.0 ``` Setting the stored delta to infinity puts this buy limit out of reach. Restoring the 2% delta makes it eligible again, without needing another entry signal. ## Price and time thresholds \[#price-and-time-thresholds] Stops and limits accept levels in several formats through `delta_format`: | Format | Meaning | Example for a $100 entry | | --------------------- | ------------------------------- | ------------------------ | | `"percent"` (default) | Fraction of the reference price | `0.05` is $5 away | | `"percent100"` | Percentage points | `5` is $5 away | | `"absolute"` | Price distance | `5` is $5 away | | `"target"` | The price itself | `95` is the level | Time limits work the same way with `time_delta_format`: `"index"` reads durations such as `"3D"`, and `"rows"` counts bars. When a new signal arrives while an order is pending, `upon_adj_limit_conflict` and `upon_opp_limit_conflict` decide whether the pending order is kept or canceled and whether the new signal executes. Stops have the matching `upon_adj_stop_conflict` and `upon_opp_stop_conflict`. ## Execution price and timing \[#execution-price-and-timing] By default, an order fills at the close of the bar it was generated on. `price` accepts `"open"`, `"close"`, `"nextopen"`, and `"nextclose"`, or an array of prices. To delay everything by a number of bars, `from_ago` reads the order information from that many bars back. The [Order delays](#order-delays) highlight below compares both timings on a chart. VBT splits each bar into three parts, the open, the time between open and close, and the close, and processes whatever is due first. That is how a pending limit triggered at the open beats an order you placed at the close. Prices outside the bar's low-to-high range are accepted by default. `price_area_vio_mode="cap"` clips them to the range and `"error"` raises. When prices come from your own calculations, `"error"` is a cheap way to catch fills that the bar could not have produced. Bid and ask prices are arrays like any other. Fill one price array with the ask at entries and the bid at exits: ```python title="Buy at the ask and sell at the bid" >>> index = pd.date_range("2026-01-01", periods=3) >>> bid = pd.Series([99.9, 101.9, 102.9], index=index) >>> ask = pd.Series([100.1, 102.1, 103.1], index=index) >>> entries = pd.Series([True, False, False], index=index) >>> exits = pd.Series([False, False, True], index=index) >>> price = (bid + ask) / 2 # (1) >>> price[entries] = ask[entries] >>> price[exits] = bid[exits] >>> pf = vbt.PF.from_signals(price, entries, exits, price=price, size=1) >>> pf.orders.readable[["Fill Index", "Side", "Price"]] Fill Index Side Price 0 2026-01-01 Buy 100.1 1 2026-01-03 Sell 102.9 ``` 1. The mid price values the position between trades. For resting limits, you can also add bid or ask checks in an adjustment function and cancel an order when your quote condition is not met. This lets you use the executable side of your own quote data when deciding which orders to allow. ## Processing order within a bar \[#processing-order-within-a-bar] When several assets share one cash balance, the order in which they trade on a bar matters. Selling first frees the cash that buying needs. `call_seq="auto"` sorts the orders of a bar by their value so that sells go first: ```python title="Rotate from one asset into two others on the same bar" >>> index = pd.date_range("2026-01-01", periods=2) >>> close = pd.DataFrame( ... {"A": [10.0, 10.0], "B": [20.0, 20.0], "C": [40.0, 40.0]}, ... index=index ... ) >>> weights = pd.DataFrame( ... {"A": [0.0, 0.5], "B": [0.0, 0.5], "C": [1.0, 0.0]}, ... index=index ... ) >>> kwargs = dict( ... size=weights, ... size_type="targetpercent", ... group_by=True, ... cash_sharing=True ... ) >>> vbt.PF.from_orders(close, **kwargs).allocations.iloc[-1] # (1) A 0.0 B 0.0 C 0.0 Name: 2026-01-02 00:00:00, dtype: float64 >>> vbt.PF.from_orders(close, call_seq="auto", **kwargs).allocations.iloc[-1] A 0.5 B 0.5 C 0.0 Name: 2026-01-02 00:00:00, dtype: float64 ``` 1. Columns trade from left to right. A and B try to buy before C has sold, find no cash, and the rotation ends in cash. With `call_seq` you can also pass your own order per bar, for example to rank assets. ## Fills, limits, and rejections \[#fills-limits-and-rejections] VBT checks order size and available cash before filling. `min_size` ignores orders that are too small, `max_size` caps each order, for example at a share of the bar's volume, and an order larger than the available cash fills partially unless `allow_partial=False`. Pass `log=True` to record the request, the result, and the reason for every order: ```python title="Cap, partially fill, and ignore orders" >>> index = pd.date_range("2026-01-01", periods=4) >>> close = pd.Series([10.0, 10.0, 10.0, 10.0], index=index) >>> pf = vbt.PF.from_orders( ... close, ... size=[50, 200, 0.5, -1000], ... min_size=1, ... max_size=100, ... init_cash=3000, ... log=True, ... ) >>> cols = ["Index", "[REQ] Size", "[RES] Size", "[RES] Status", "[RES] Status Info"] >>> pf.logs.readable[cols] Index [REQ] Size [RES] Size [RES] Status [RES] Status Info 0 2026-01-01 50.0 50.0 Filled None 1 2026-01-02 200.0 100.0 Filled PartialFill 2 2026-01-03 0.5 NaN Ignored MinSizeNotReached 3 2026-01-04 -1000.0 100.0 Filled PartialFill ``` The size limits follow `size_type`, so with `size_type="value"` they are amounts of money. `cash_limit` caps the cash a single order may use, `size_granularity` rounds sizes to whole shares or lots, and `reject_prob` rejects a random share of orders to test robustness. To stop at the first order that cannot be filled as requested, pass `raise_reject=True`. A `NaN` size places no order, which is how to keep a suspended asset's position untouched during a rebalance. ## Live fills versus the backtest \[#live-fills-versus-the-backtest] Executions from a broker or another backtester become a full portfolio by passing them as order records. That makes it easy to measure how far live trading drifted from the simulation. Here sample fills for the breakout strategy above are 0.15% worse on each side and pay higher fees: ```python title="Compare live fills with the simulated breakout" >>> import io >>> csv = io.StringIO("""date,side,size,price,fees ... 2023-03-14,Buy,0.3,24587.67,7.38 ... 2023-05-01,Sell,0.3,28049.43,8.41 ... 2023-06-21,Buy,0.3,28431.55,8.53 ... 2023-07-30,Sell,0.3,29231.40,8.77 ... 2023-10-01,Buy,0.3,27529.99,8.26 ... """) >>> fills = pd.read_csv(csv, parse_dates=["date"]) >>> fills["idx"] = data.index.get_indexer(fills.pop("date").dt.tz_localize("UTC")) # (1) >>> live_pf = vbt.PF(data.close, order_records=fills, init_cash=10_000) >>> pd.DataFrame({ ... "simulated": breakout_pf.trades.returns.values, ... "live": live_pf.trades.returns.values, ... }) simulated live 0 0.143363 0.138652 1 0.030409 0.026104 2 0.537144 0.534242 >>> pd.Series({"simulated": breakout_pf.total_return, "live": live_pf.total_return}) simulated 0.574451 live 0.565769 dtype: float64 ``` 1. Order records locate each fill by its bar position in the price data. Every trade, drawdown, and metric is now available for the live account, and the 0.9 point gap in total return is the cost of execution. The [Portfolio from fills](#portfolio-from-fills) highlight below shows the minimal form. Order records are taken as given, without checking cash. To run the same fills through the simulator instead, so that cash limits and fees apply, pass them as [records](/features/backtesting/backtesting-engine/#inputs-as-records). ## Portfolio from fills \[#portfolio-from-fills] New in v2026.9.5 ✅ Turn your execution records into a VBT portfolio and explore trades, drawdowns, and performance with the same tools you use for backtests. Missing record fields receive defaults, and readable side names are mapped automatically, keeping the setup light. ```python title="Calculate portfolio value and profit from two fills" >>> close = pd.Series( ... [100.0, 105.0, 110.0], ... index=pd.date_range("2026-09-01", periods=3, freq="D") ... ) >>> fills = [ ... dict(idx=0, size=2, price=100, fees=1, side="Buy"), ... dict(idx=2, size=2, price=110, fees=1, side="Sell"), ... ] >>> pf = vbt.PF(close, order_records=fills, init_cash=1000, freq="1D") >>> print(pf.total_profit) # (1) 18.0 >>> pf.value.tolist() # (2) [999.0, 1009.0, 1018.0] ``` 1. The $20 price gain is reduced to $18 by the two $1 fees. 2. Value includes unrealized profit between the fills. ## Target price \[#target-price] New in 1.10.0 ✅ Limit and stop orders can now be defined using a target price instead of a delta. ```python title="Set the SL to the previous low in a random portfolio" >>> data = vbt.YFData.pull("BTC-USD") >>> pf = vbt.PF.from_random_signals( ... data, ... n=100, ... seed=42, ... sl_stop=data.low.vbt.ago(1), ... delta_format="target" ... ) >>> sl_orders = pf.orders.stop_type_sl >>> signal_index = pf.wrapper.index[sl_orders.signal_idx.values] >>> hit_index = pf.wrapper.index[sl_orders.idx.values] >>> hit_after = hit_index - signal_index >>> hit_after TimedeltaIndex([ '7 days', '3 days', '1 days', '5 days', '4 days', '1 days', '28 days', '1 days', '1 days', '1 days', '1 days', '1 days', '13 days', '10 days', '5 days', '1 days', '3 days', '4 days', '1 days', '9 days', '5 days', '1 days', '1 days', '2 days', '1 days', '1 days', '1 days', '3 days', '1 days', '1 days', '1 days', '1 days', '1 days', '2 days', '2 days', '1 days', '12 days', '3 days', '1 days', '1 days', '1 days', '1 days', '1 days', '3 days', '1 days', '1 days', '1 days', '4 days', '1 days', '1 days', '2 days', '6 days', '11 days', '1 days', '2 days', '1 days', '1 days', '1 days', '1 days', '1 days', '4 days', '10 days', '1 days', '1 days', '1 days', '2 days', '3 days', '1 days'], dtype='timedelta64[ns]', name='Date', freq=None) ``` ## Order delays \[#order-delays] New in 1.4.1 ✅ By default, VBT executes every order at the end of the current bar. Previously, if you wanted to delay execution to the next bar, you had to manually shift all order-related arrays by one bar, which made the process error-prone. Now, you can simply specify how many bars in the past should be used to take order information from. In addition, the price argument now supports "nextopen" and "nextclose" as options, providing a one-line solution. ```python title="Compare orders without and with a delay in a random portfolio" >>> pf = vbt.PF.from_random_signals( ... vbt.YFData.pull("BTC-USD", start="2021-01", end="2021-02"), ... n=3, ... seed=42, ... price=vbt.Param(["close", "nextopen"]) ... ) >>> fig = pf.orders["close"].plot( ... buy_trace_kwargs=dict(name="Buy (close)", marker=dict(symbol="triangle-up-open")), ... sell_trace_kwargs=dict(name="Sell (close)", marker=dict(symbol="triangle-down-open")) ... ) >>> pf.orders["nextopen"].plot( ... plot_ohlc=False, ... plot_close=False, ... buy_trace_kwargs=dict(name="Buy (nextopen)"), ... sell_trace_kwargs=dict(name="Sell (nextopen)"), ... fig=fig ... ) >>> fig.show() ``` BTC-USD OHLC with random orders executed at the close or delayed until the next open. [Figure data (JSON)](/assets/figures/features/portfolio/order-delays.6a9760444aa9.json) ## Limit orders \[#limit-orders] New in 1.4.0 ✅ Long-awaited support for limit orders is now available for signal-based simulation! Includes time-in-force (TIF) orders such as DAY, GTC, GTD, LOO, and FOK ⏰ You can also reverse a limit order or create it using a delta for easier testing. ```python title="Explore how limit delta affects number of orders in a random portfolio" >>> pf = vbt.PF.from_random_signals( ... vbt.YFData.pull("BTC-USD"), ... n=100, ... seed=42, ... order_type="limit", ... limit_delta=vbt.Param(np.arange(0.001, 0.1, 0.001)), # (1) ... ) >>> pf.orders.count().vbt.plot( ... xaxis_title="Limit delta", ... yaxis_title="Order count" ... ).show() ``` 1. Limit delta is the distance between the close (or any specified price) and the target limit price, expressed as a percentage. The higher the delta, the lower the chance it will eventually be hit. Order count across limit-order delta values in a seeded random BTC-USD portfolio. [Figure data (JSON)](/assets/figures/features/portfolio/limit-delta.7987726a54d4.json) ## Delta formats \[#delta-formats] New in 1.4.0 ✅ Previously, stop orders could only be provided as percentages. While this worked for single values, it often required extra transformations for arrays. For example, setting SL to ATR meant you needed to know the entry price. More generally, to lock in a specific dollar amount of a trade, you might want to use a fixed price trailing stop. To address this, VBT now offers multiple stop value formats ("delta formats") to choose from. ```python title="Use ATR as SL" >>> data = vbt.YFData.pull("BTC-USD") >>> atr = vbt.talib("ATR").run(data.high, data.low, data.close).real >>> pf = vbt.PF.from_holding( ... data.loc["2022-01-01":"2022-01-07"], ... sl_stop=atr.loc["2022-01-01":"2022-01-07"], ... delta_format="absolute" ... ) >>> pf.orders.plot().show() ``` BTC-USD OHLC with a holding trade stopped using ATR as an absolute stop-loss. [Figure data (JSON)](/assets/figures/features/portfolio/delta-formats.fdbb55d4608e.json) ## Bar skipping \[#bar-skipping] New in 1.4.0 ✅ Simulation based on orders and signals can now (partially) skip bars that do not define any orders, often resulting in significant speedups for strategies with sparsely distributed orders. ```python title="Benchmark bar skipping in a buy-and-hold portfolio" >>> data = vbt.BinanceData.pull("BTCUSDT", start="one month ago UTC", timeframe="minute") >>> size = data.symbol_wrapper.fill(np.nan) >>> size[0] = np.inf ``` ```python >>> %%timeit >>> vbt.PF.from_orders(data, size, ffill_val_price=True) # (1) 5.92 ms ± 300 µs per loop (mean ± std. dev. of 7 runs, 1 loop each) ``` 1. When enabled (default), this argument forces the simulation to process every bar. ```python >>> %%timeit >>> vbt.PF.from_orders(data, size, ffill_val_price=False) 2.75 ms ± 16 µs per loop (mean ± std. dev. of 7 runs, 100 loops each) ``` # Portfolio accounting (/features/backtesting/portfolio-accounting) Where did the cash go, and what does the portfolio hold at every bar? VBT keeps a full account for every backtest: cash shared across assets, deposits and withdrawals, dividends and interest, fees, positions, and their value. Everything can be inspected as a time series or as records, so a multi-asset backtest with shared cash adds up to the cent. ```python title="Invest $500 a month in a 60/40 portfolio and collect dividends" >>> data = vbt.YFData.pull( ... ["SPY", "TLT"], ... start="2020-01-01", ... end="2025-01-01", ... auto_adjust=False, # (1) ... ) >>> month_start = ~data.index.tz_localize(None).to_period("M").duplicated() >>> deposits = pd.Series(0.0, index=data.index) >>> deposits[month_start] = 500 >>> weights = data.symbol_wrapper.fill(np.nan) >>> weights[month_start] = [0.6, 0.4] >>> pf = vbt.PF.from_orders( ... data, ... size=weights, ... size_type="targetpercent", ... group_by=True, ... cash_sharing=True, # (2) ... call_seq="auto", ... init_cash=0, ... cash_deposits=deposits, ... cash_dividends=data.get("Dividends"), # (3) ... fees=0.0005, ... ) >>> pd.Series({ ... "deposits": pf.cash_deposits.sum(), ... "dividends": pf.cash_earnings.sum(), ... "fees": pf.orders.fees.sum(), ... "cash": pf.cash.iloc[-1], ... "assets": pf.asset_value.iloc[-1], ... "value": pf.final_value, ... }).round(2) deposits 30000.00 dividends 1756.07 fees 16.96 cash 174.82 assets 34520.04 value 34694.86 dtype: float64 >>> pd.DataFrame({ ... "Deposited": pf.cash_deposits.cumsum(), ... "Portfolio value": pf.value, ... }).vbt.plot().show() ``` 1. Use raw prices. Adjusted prices already include dividends, which would count them twice. 2. Both ETFs draw from one cash balance. 3. Dividends per share. Each payment is multiplied by the shares held on that day. Cumulative deposits and portfolio value of a monthly 60/40 SPY and TLT savings plan from 2020 to 2024. [Figure data (JSON)](/assets/figures/features/backtesting/portfolio-accounting-deposits.0dc61451e905.json) Sixty deposits of $500 and $1,756 of dividends went in, $16.96 of fees went out, and the dividends were reinvested at the next monthly rebalance. The final value equals the remaining cash plus the value of the shares. ## Shared cash \[#shared-cash] By default, every column is its own account. Grouping columns with `group_by` and setting `cash_sharing=True` turns them into one account: positions stay per asset, while cash, value, and returns are tracked per group. `init_cash` is then the starting balance of each group, not of each asset. Within a bar, the assets of a group trade one after another, and `call_seq="auto"` puts sells first so their proceeds can fund the buys. Results can be read per group or per asset. For example, `pf.get_cash_earnings(group_by=False)` splits the dividends above into $719.56 from SPY and $1,036.51 from TLT. ## Starting state \[#starting-state] A simulation starts with `init_cash`, and optionally with positions from `init_position` and their entry prices from `init_price`, for example to continue from a live account. When the amount of capital should not limit the test, `init_cash="auto"` simulates with unlimited cash and then sets the starting balance to the most the strategy ever needed: ```python title="Find the cash a sequence of orders requires" >>> index = pd.date_range("2026-01-01", periods=4) >>> close = pd.Series([10.0, 12.0, 8.0, 11.0], index=index) >>> pf = vbt.PF.from_orders(close, size=[5, 5, -10, 20], init_cash="auto") >>> print(pf.init_cash) 250.0 >>> pf.cash.tolist() [200.0, 140.0, 220.0, 0.0] ``` With several columns, `"autoalign"` gives all of them the largest requirement, so their returns share one capital base. Sizes relative to cash or value, such as `"percent"`, `"valuepercent"`, and target weights, have nothing finite to refer to during such a run and raise an error. Simulate them with real cash and, without leverage, call `pf.replace(init_cash="auto")` afterwards to learn how much of it the strategy actually used. ### Existing holdings \[#existing-holdings] You can test what happens next to an account that already holds assets. Here the account starts with $1,000 in cash and ten shares, then sells the shares in two stages: ```python title="Start with shares already in the account" >>> held_close = pd.Series([100.0, 105.0, 110.0], index=pd.date_range("2026-01-01", periods=3)) >>> held_pf = vbt.PF.from_orders( ... held_close, ... size=[np.nan, -4, -6], ... init_cash=1000, ... init_position=10, ... init_price=100, ... ) >>> pd.DataFrame({"cash": held_pf.cash, "shares": held_pf.assets, "value": held_pf.value}) cash shares value 2026-01-01 1000.0 10.0 2000.0 2026-01-02 1420.0 6.0 2050.0 2026-01-03 2080.0 0.0 2080.0 ``` The initial shares count toward the portfolio's value from the start. Selling four at $105 and the remaining six at $110 leaves $2,080 in cash. To keep an existing simulation running as new bars arrive, see [Live simulation](/features/backtesting/live-simulation/). ## Cash flows \[#cash-flows] Money enters and leaves the account in four ways besides trading: | Flow | Argument | Notes | | ---------------------------------- | -------------------- | -------------------------------------------------- | | Deposits and withdrawals | `cash_deposits` | Negative values withdraw, limited to the free cash | | Dividends | `cash_dividends` | Per share, multiplied by the position | | Interest and other income or costs | `cash_earnings` | Cash amounts, credited at the end of the bar | | Trading costs | `fees`, `fixed_fees` | Charged per order | Deposits are counted as invested capital, so they raise the input value without raising the return. Flows that depend on the account itself, such as a management fee on the current value, a performance fee at year end, or taxes on realized gains, are written into `cash_earnings` by a callback while the simulation runs. ## Valuation \[#valuation] The reported portfolio value is its cash plus the value of its positions at closing prices. During simulation, `val_price` lets you choose the prices used to value positions for sizing decisions, such as how many shares make up a target allocation. Missing closing prices are filled by default, so a gap in the data does not zero out a position. The returns of a group come from its combined value, so they are not the sum or the average of the asset returns, which `pf.get_returns(group_by=False)` gives per asset. Profit splits into realized profit from closed trades and unrealized profit from open ones, and every series is available per bar: `pf.cash`, `pf.assets`, `pf.asset_value`, `pf.value`, and `pf.returns`. ## Records \[#records] The account keeps four kinds of records, each with a readable table: | Records | What one row is | | -------------- | -------------------------------------------------------------------------- | | `pf.orders` | A filled order, with signal, creation, and fill time for signal strategies | | `pf.logs` | A requested order with the state before and after it, filled or not | | `pf.trades` | An entry matched with an exit, including partial exits | | `pf.positions` | A position from opening to flat, combining its trades | Set `log=True` when simulating to keep order logs, including requests that did not fill. ```python title="Read positions, including the one still open" >>> pf = vbt.PF.from_orders(close, size=[5, 5, -10, 20], init_cash=1000) >>> cols = ["Entry Index", "Exit Index", "Size", "Avg Entry Price", "PnL", "Status"] >>> pf.positions.readable[cols] Entry Index Exit Index Size Avg Entry Price PnL Status 0 2026-01-01 2026-01-03 10.0 11.0 -30.0 Closed 1 2026-01-04 2026-01-04 20.0 11.0 0.0 Open ``` To attach your own information to orders, such as the reason for an exit, record it in a side array from a callback and join it to the order records by row and column. ## Allocations and exposure \[#allocations-and-exposure] `pf.allocations` gives the weight of each asset in its group on every bar. Exposure summarizes the book: long and short exposure are the long and short asset values relative to portfolio value, gross exposure is their sum, and net exposure their difference. Here a book starts 60% long SPY and 40% short TLT and is left to drift: ```python title="Track gross and net exposure of a long/short book" >>> weights = data.symbol_wrapper.fill(np.nan) >>> weights.iloc[0] = [0.6, -0.4] >>> book_pf = vbt.PF.from_orders( ... data, ... size=weights, ... size_type="targetpercent", ... group_by=True, ... cash_sharing=True, ... call_seq="auto", ... init_cash=10_000, ... ) >>> pd.DataFrame({ ... "long": book_pf.get_gross_exposure(direction="longonly"), ... "short": book_pf.get_gross_exposure(direction="shortonly"), ... "gross": book_pf.gross_exposure, ... "net": book_pf.net_exposure, ... }).iloc[[0, 500, 1000]].round(3) long short gross net Date 2020-01-02 00:00:00-05:00 0.600 0.400 1.000 0.200 2021-12-27 00:00:00-05:00 0.707 0.349 1.056 0.358 2023-12-21 00:00:00-05:00 0.631 0.209 0.839 0.422 ``` As SPY rose and TLT fell, the short shrank and the book became more net long. For time spent in the market, `pf.position_coverage` gives the share of bars with an open position. ## Asset weighting \[#asset-weighting] New in v2024.8.20 ✅ Asset weighting lets you fine-tune the influence of individual assets or strategies within your portfolio, giving you enhanced control over your portfolio's overall performance. The key benefit is that these weights are not limited to returns. They are consistently applied to all time series and metrics, including orders, cash flows, and more. This comprehensive approach ensures that every aspect of your portfolio stays precisely aligned. `pf.apply_weights` reweights completed results without rerunning the simulation. This is useful for comparing allocations across assets or strategies you have already tested. To test how assets compete for the same cash during trading, use [shared cash](#shared-cash). See [Multi-strategy portfolios](/features/strategies/multi-strategy-portfolios/) for combining several strategies. ```python title="Maximize Sharpe of a random portfolio" >>> data = vbt.YFData.pull(["AAPL", "MSFT", "GOOG"], start="2020") >>> pf = data.run("from_random_signals", n=vbt.Default(50), seed=42, group_by=True) >>> pf.get_sharpe_ratio(group_by=False) # (1) symbol AAPL 1.401012 MSFT 0.456162 GOOG 0.852490 Name: sharpe_ratio, dtype: float64 >>> pf.sharpe_ratio # (2) 1.2132857343006869 >>> prices = pf.get_value(group_by=False) >>> weights = vbt.pypfopt_optimize(prices=prices) # (3) >>> weights {'AAPL': 0.85232, 'MSFT': 0.0, 'GOOG': 0.14768} >>> weighted_pf = pf.apply_weights(weights, rescale=True) # (4) >>> weighted_pf.weights symbol AAPL 2.55696 MSFT 0.00000 GOOG 0.44304 dtype: float64 >>> weighted_pf.get_sharpe_ratio(group_by=True) # (5) 1.426112580298898 ``` 1. Sharpe ratio for each individual asset. 2. Sharpe ratio for the combined portfolio. The goal is to maximize this value. 3. Maximize Sharpe based on equity (that is, portfolio value) development. 4. Rescale the weights for multiplication and create a new portfolio with the weights applied. 5. Sharpe ratio for the optimized portfolio. ## Position views \[#position-views] New in v2024.8.20 ✅ Position views let you analyze your portfolio by focusing on either long or short positions, providing a clear and distinct perspective for each investment strategy. ```python title="Separate long and short positions of a basic SMA crossover portfolio" >>> data = vbt.YFData.pull("BTC-USD") >>> fast_sma = data.run("talib_func:sma", timeperiod=20) >>> slow_sma = data.run("talib_func:sma", timeperiod=50) >>> long_entries = fast_sma.vbt.crossed_above(slow_sma) >>> short_entries = fast_sma.vbt.crossed_below(slow_sma) >>> pf = vbt.PF.from_signals( ... data, ... long_entries=long_entries, ... short_entries=short_entries, ... fees=0.01, ... fixed_fees=1.0 ... ) >>> long_pf = pf.long_view >>> short_pf = pf.short_view >>> fig = vbt.make_subplots(rows=2, cols=1, shared_xaxes=True, vertical_spacing=0.01) >>> fig = long_pf.assets.vbt.plot_against( ... 0, ... trace_kwargs=dict(name="Long position", line_shape="hv", line_color="mediumseagreen"), ... other_trace_kwargs=dict(visible=False), ... add_trace_kwargs=dict(row=1, col=1), ... fig=fig ... ) >>> fig = short_pf.assets.vbt.plot_against( ... 0, ... trace_kwargs=dict(name="Short position", line_shape="hv", line_color="coral"), ... other_trace_kwargs=dict(visible=False), ... add_trace_kwargs=dict(row=2, col=1), ... fig=fig ... ) >>> fig.show() ``` BTC-USD SMA crossover portfolio with long and short position assets shown separately. [Figure data (JSON)](/assets/figures/features/portfolio/position-views.e9ab9910acba.json) ```python >>> long_pf.sharpe_ratio 0.9185961894435091 >>> short_pf.sharpe_ratio 0.2760864152147919 ``` ## Position info \[#position-info] New in 1.11.0 ✅ Dynamic signal functions now have access to the current position information, such as (open) P\&L. ```python title="Enter randomly, exit randomly but only if in profit" >>> @njit ... def signal_func_nb(ctx, entries, exits): ... is_entry = vbt.pf_nb.select_nb(ctx, entries) ... is_exit = vbt.pf_nb.select_nb(ctx, exits) ... if is_entry: ... return True, False, False, False ... if is_exit: ... pos_info = ctx.last_pos_info[ctx.col] ... if pos_info["status"] == vbt.pf_enums.TradeStatus.Open: ... if pos_info["pnl"] >= 0: ... return False, True, False, False ... return False, False, False, False >>> data = vbt.YFData.pull("BTC-USD") >>> entries, exits = data.run("RANDNX", n=10, seed=42, unpack=True) >>> pf = vbt.Portfolio.from_signals( ... data, ... signal_func_nb=signal_func_nb, ... signal_args=(vbt.Rep("entries"), vbt.Rep("exits")), ... broadcast_named_args=dict(entries=entries, exits=exits), ... jitted=False # (1) ... ) >>> pf.trades.readable[["Entry Index", "Exit Index", "PnL"]] Entry Index Exit Index PnL 0 2014-11-01 00:00:00+00:00 2016-01-08 00:00:00+00:00 39.134739 1 2016-03-27 00:00:00+00:00 2016-09-07 00:00:00+00:00 61.220063 2 2016-12-24 00:00:00+00:00 2016-12-31 00:00:00+00:00 14.471414 3 2017-03-16 00:00:00+00:00 2017-08-05 00:00:00+00:00 373.492028 4 2017-09-12 00:00:00+00:00 2018-05-05 00:00:00+00:00 815.699284 5 2019-02-15 00:00:00+00:00 2019-11-10 00:00:00+00:00 2107.383227 6 2019-12-04 00:00:00+00:00 2019-12-10 00:00:00+00:00 12.630214 7 2020-07-12 00:00:00+00:00 2021-11-14 00:00:00+00:00 21346.035444 8 2022-01-15 00:00:00+00:00 2023-03-06 00:00:00+00:00 -11925.133817 ``` 1. Disable Numba during testing to avoid compilation. ## Cash deposits \[#cash-deposits] New in 1.0.0 ✅ Cash can be deposited or withdrawn at any time. ```python title="DCA $10 into Bitcoin each month" >>> data = vbt.YFData.pull("BTC-USD") >>> cash_deposits = data.symbol_wrapper.fill(0.0) >>> month_start_mask = ~data.index.tz_convert(None).to_period("M").duplicated() >>> cash_deposits[month_start_mask] = 10 >>> pf = vbt.PF.from_orders( ... data.close, ... init_cash=0, ... cash_deposits=cash_deposits ... ) >>> pf.input_value # (1) 1020.0 >>> pf.final_value 20674.328828315127 ``` 1. Total invested. ## Cash earnings \[#cash-earnings] New in 1.0.0 ✅ Cash can be continuously earned or spent depending on the current position. ```python title="Backtest Apple without and with dividend reinvestment" >>> data = vbt.YFData.pull("AAPL", start="2010") >>> pf_kept = vbt.PF.from_holding( # (1) ... data.close, ... cash_dividends=data.get("Dividends") ... ) >>> pf_kept.cash.iloc[-1] # (2) 93.9182408043298 >>> pf_kept.assets.iloc[-1] # (3) 15.37212731743495 >>> pf_reinvested = vbt.PF.from_orders( # (4) ... data.close, ... cash_dividends=data.get("Dividends") ... ) >>> pf_reinvested.cash.iloc[-1] 0.0 >>> pf_reinvested.assets.iloc[-1] 18.203284859405468 >>> fig = pf_kept.value.rename("Value (kept)").vbt.plot() >>> pf_reinvested.value.rename("Value (reinvested)").vbt.plot(fig=fig) >>> fig.show() ``` 1. Keep dividends as cash. 2. Final cash balance. 3. Final number of shares in the portfolio. 4. Reinvest dividends at the next bar. AAPL portfolio value with dividends kept as cash versus reinvested from 2010 onward. [Figure data (JSON)](/assets/figures/features/portfolio/dividends.5b1cc406d059.json) # Position sizing (/features/backtesting/position-sizing) How much should each trade buy? The answer changes a backtest as much as the entry rule does. VBT lets you test position sizing in Python with fixed units, cash amounts, percent of equity, target weights, or risk-based sizes computed from the distance to your stop, and compare the rules side by side. ```python title="Risk 1% of equity per trade instead of buying 100 shares" >>> data = vbt.YFData.pull("SPY", start="2015-01-01", end="2025-01-01") >>> entries = data.close.vbt.crossed_above(data.close.rolling(50).mean()) >>> stop_dist = 2 * data.run("atr", window=14).atr >>> @njit ... def risk_size_nb(c, size, stop_dist, risk): # (1) ... if c.last_position[c.col] == 0: ... equity = c.last_value[c.col] ... size[c.i, c.col] = risk * equity / vbt.pf_nb.select_nb(c, stop_dist) >>> kwargs = dict( ... sl_stop=stop_dist, ... tp_stop=2 * stop_dist, ... delta_format="absolute", ... init_cash=100_000, ... ) >>> fixed_pf = vbt.PF.from_signals(data, entries, size=100, **kwargs) >>> risk_pf = vbt.PF.from_signals( ... data, ... entries, ... adjust_func_nb=risk_size_nb, ... adjust_args=(vbt.Rep("size"), vbt.Rep("stop_dist"), 0.01), ... broadcast_named_args=dict(stop_dist=stop_dist), ... size=np.nan, ... arg_config=dict(size=dict(full_shape=True)), # (2) ... **kwargs, ... ) >>> pd.DataFrame({ ... "100 shares": fixed_pf.trades.losing.pnl.to_pd(ignore_index=True).describe(), ... "1% risk": risk_pf.trades.losing.pnl.to_pd(ignore_index=True).describe(), ... }).loc[["count", "mean", "std", "min", "max"]].round(0) 100 shares 1% risk count 17.0 17.0 mean -882.0 -1100.0 std 437.0 196.0 min -1773.0 -1459.0 max -253.0 -513.0 >>> values = pd.DataFrame({"100 shares": fixed_pf.value, "1% risk": risk_pf.value}) >>> values.vbt.plot().show() ``` 1. Runs at the start of every bar. When flat, it sizes the next entry so that hitting the stop loses 1% of the current equity. 2. Give `size` the full shape of the data so the function can write one value per bar. SPY portfolio value from 2015 to 2024 for a fixed 100-share position size and for 1% equity risk per trade. [Figure data (JSON)](/assets/figures/features/backtesting/position-sizing-risk-vs-fixed.fb37233ca5fe.json) Both versions take the same 37 trades with a 2 ATR stop and a 4 ATR target. With 100 shares, a losing trade cost anywhere from $253 to $1,773, depending on how volatile the market was. With 1% risk, losses stay close to 1% of equity. They are not exactly equal because prices can gap through the stop. ## Size types \[#size-types] `size` is a number, and `size_type` says what it means: | Size type | `size` means | Example | | -------------------- | -------------------------------------------------------- | ------------------------------ | | `"amount"` (default) | Units of the asset | `10` buys 10 shares | | `"value"` | Cash to spend | `1000` buys $1,000 worth | | `"percent"` | Share of available cash, or of the position when selling | `0.5` uses half the cash | | `"valuepercent"` | Share of total portfolio value | `0.5` buys half the equity | | `"targetamount"` | The position to hold, in units | `10` buys or sells to reach 10 | | `"targetvalue"` | The position to hold, in cash | `1000` holds $1,000 worth | | `"targetpercent"` | The position to hold, as a weight | `0.25` holds 25% of equity | Each percentage type also has a `100` variant that reads `50` as 50%. The difference between ordinary and target types shows when the same order repeats: ```python title="Send the same order on two bars" >>> close = pd.Series([50.0, 50.0], index=pd.date_range("2026-01-01", periods=2)) >>> pf = vbt.PF.from_orders( ... close, ... size=vbt.Param([10, 1000, 0.5, 0.25], level=0), ... size_type=vbt.Param( ... ["amount", "value", "valuepercent", "targetpercent"], ... level=0 ... ), ... init_cash=10_000, ... ) >>> pf.assets.iloc[-1] size size_type 10.00 amount 20.0 1000.00 value 40.0 0.50 valuepercent 200.0 0.25 targetpercent 50.0 Name: 2026-01-02 00:00:00, dtype: float64 ``` Ordinary types buy again on every bar. A target type only trades the difference, so the second order does nothing. That makes target weights the natural way to rebalance. A `NaN` weight skips the bar and keeps the position, while a weight of zero closes it: ```python title="Rebalance to 60/40 on the first trading day of each month" >>> data = vbt.YFData.pull(["SPY", "TLT"], start="2020-01-01", end="2025-01-01") >>> rebalance = ~data.index.tz_localize(None).to_period("M").duplicated() >>> weights = data.symbol_wrapper.fill(np.nan) >>> weights[rebalance] = [0.6, 0.4] >>> pf = vbt.PF.from_orders( ... data, ... size=weights, ... size_type="targetpercent", ... group_by=True, ... cash_sharing=True, ... call_seq="auto", # (1) ... fees=0.0005, ... ) >>> pf.allocations.iloc[[0, 20, 21]].round(3) symbol SPY TLT Date 2020-01-02 00:00:00-05:00 0.600 0.400 2020-01-31 00:00:00-05:00 0.582 0.418 2020-02-03 00:00:00-05:00 0.600 0.400 ``` 1. Sell the overweight asset before buying the other, so the cash is available. The weights drift during the month and return to 60/40 on the next rebalance. Weights are fractions of the group's value, so without leverage they should add up to at most 1. The simulator processes the columns of a bar in order and stops buying when the cash runs out: weights of 0.5 on three assets fill the first two and leave nothing for the third. !!! warning "Target sizes and signals" With entry and exit signals, a target size can contradict the signal. An entry with a target below the current position would sell. Use target sizes with `from_orders`, or let `from_signals` derive the signals from the targets with `order_mode=True`, as shown on the [Signal backtesting](/features/backtesting/signal-backtesting/#targets-as-signals) page. ## Available cash or portfolio equity? \[#available-cash-or-portfolio-equity] Half the available cash and half the portfolio value can produce very different allocations. With shared cash, each buy leaves less cash for the next asset. In this example both assets cost $10, and A trades before B: ```python title="Compare half the available cash with half the equity" >>> close = pd.DataFrame( ... {"A": [10.0], "B": [10.0]}, ... index=pd.date_range("2026-01-01", periods=1), ... ) >>> positions = {} >>> for size_type in ["percent", "valuepercent"]: ... pf = vbt.PF.from_orders( ... close, ... size=0.5, ... size_type=size_type, ... group_by=True, ... cash_sharing=True, ... init_cash=1000, ... ) ... positions[size_type] = pf.assets.iloc[0] >>> pd.DataFrame(positions) percent valuepercent A 50.0 50.0 B 25.0 50.0 ``` `"percent"` spends $500 on A, then half the remaining $500 on B. `"valuepercent"` spends $500 on each because the equity is still $1,000. Choose the first when each new trade should use a share of remaining cash, and the second when its size should follow total account value. The [Portfolio accounting](/features/backtesting/portfolio-accounting/#shared-cash) page covers how assets share that account. ## Risk-based sizing \[#risk-based-sizing] Risk-based sizing divides a risk budget by the loss per unit if the stop is hit. When the budget is a fixed amount of cash, it is a plain array computation: `size = 1000 / stop_dist` with `size_type="amount"`. When the budget depends on equity, as in the example above, the size must be computed during the simulation, because equity depends on earlier fills and the value of open positions. An adjustment function is the simplest place for that. It runs before each bar's signals, reads the current equity, cash, and position, and writes the size the next order will use. Inside callbacks, `vbt.pf_nb.get_order_size_nb` converts a percentage or target size into units, which helps when you combine a sizing rule with signals. The conversion ignores fees, slippage, and lot sizes, so leave a margin when cash is tight. The same pattern covers volatility targeting, Kelly-style fractions estimated from past trades, and sizes produced by a separate model. Sizes and target weights can also come from arrays, so an external model can supply a different allocation for every asset and rebalance date. Use callbacks when the rule also needs the simulated account state, such as reducing the next order after losses. This lets you compare your own sizing rules with fixed sizes using the same entries and exits. For weights calculated from a portfolio objective, see [Portfolio optimization](/features/optimization/portfolio-optimization/). ## Lots and increments \[#lots-and-increments] Real markets trade in whole shares, contracts, or minimum lot steps. `size_granularity` rounds every order down to a multiple of the step: ```python title="Round a $1,000 order to whole shares" >>> close = pd.Series([33.0], index=pd.date_range("2026-01-01", periods=1)) >>> pf = vbt.PF.from_orders( ... close, ... size=1000, ... size_type="value", ... size_granularity=vbt.Param([np.nan, 1]), ... init_cash=10_000, ... ) >>> pf.orders.size.to_pd().iloc[0] size_granularity NaN 30.30303 1.0 30.00000 Name: 2026-01-01 00:00:00, dtype: float64 ``` Combine it with `min_size` and `size_type="value"` to skip orders below a minimum notional, as exchanges require. A granularity setting also applies when closing, so a fractional position left over from earlier orders may not close completely. ## Compounding \[#compounding] Whether profits are reinvested depends on the sizing rule. The default, `size=np.inf`, spends all available cash, so each trade grows with the account. Percent of equity and risk-based sizes tied to equity also scale with the account. A fixed amount keeps the unit count constant, while a fixed value keeps the requested cash amount constant. Both let you compare trades without automatically increasing the requested size after a profit. A fixed size still needs the cash to pay for it: when the account is short, the order fills partially, and `allow_partial=False` rejects it instead. ## Sizing for reversals \[#sizing-for-reversals] A reversal closes the current position and opens the opposite one in a single order, so the order is larger than the new position: ```python title="Reverse a one-unit long into a one-unit short" >>> close = pd.Series([10.0, 11.0, 12.0], index=pd.date_range("2026-01-01", periods=3)) >>> pf = vbt.PF.from_signals( ... close, ... entries=pd.Series([True, False, False], index=close.index), ... exits=pd.Series([False, True, False], index=close.index), ... direction="both", ... size=1, ... ) >>> pf.orders.readable[["Fill Index", "Size", "Side"]] Fill Index Size Side 0 2026-01-01 1.0 Buy 1 2026-01-02 2.0 Sell ``` Keep this in mind with `max_size`: a cap of one unit turns a one-unit reversal into a plain exit. To reduce a position instead of reversing it, enable accumulation. # Signal backtesting (/features/backtesting/signal-backtesting) You have entry and exit signals, and you want to know how they become trades and what happens when they disagree. VBT lets you backtest buy and sell signals in Python by passing boolean arrays to `vbt.PF.from_signals`, which turns them into orders, positions, and a full portfolio you can inspect. Use signals from technical indicators, your own pandas calculations, or model predictions converted to entry and exit conditions. You can trade long or short, scale into positions, and combine your signals with built-in stops and limit orders. ```python title="Backtest a moving average crossover on Bitcoin" >>> data = vbt.YFData.pull("BTC-USD", start="2021-01-01", end="2024-01-01") >>> fast = data.run("talib:sma", timeperiod=20).real >>> slow = data.run("talib:sma", timeperiod=50).real >>> entries = fast.vbt.crossed_above(slow) >>> exits = fast.vbt.crossed_below(slow) >>> pf = vbt.PF.from_signals(data, entries, exits, price="nextopen", fees=0.001) # (1) >>> pf.trades.readable[["Entry Index", "Exit Index", "Return"]].head(3) Entry Index Exit Index Return 0 2021-08-02 00:00:00+00:00 2021-09-24 00:00:00+00:00 0.122841 1 2021-10-12 00:00:00+00:00 2021-11-28 00:00:00+00:00 -0.049127 2 2022-02-20 00:00:00+00:00 2022-03-08 00:00:00+00:00 -0.053252 >>> pf.stats(["total_return", "total_trades", "win_rate", "max_dd"]) Total Return [%] -13.87894 Total Trades 12 Win Rate [%] 18.181818 Max Drawdown [%] 58.6206 dtype: object >>> pf.plot(settings=dict(bm_returns=False)).show() ``` 1. Signals are computed on each bar's close and filled at the next bar's open, with 0.1% fees per order. Bitcoin price with moving average crossover entries and exits, trade returns, and cumulative returns from 2021 to 2023. [Figure data (JSON)](/assets/figures/features/backtesting/signal-backtesting-sma-crossover.c0a5967bf35b.json) ## Multiple assets and parameter combinations \[#multiple-assets-and-parameter-combinations] The same method works with one signal Series or a DataFrame containing many assets and parameter combinations. Compare indicator settings, position sizes, and conflict rules in one simulation, then select each result by its column labels. Each column has its own cash by default. To test signals as a multi-asset portfolio, group the asset columns and enable cash sharing. The [Backtesting engine](/features/backtesting/backtesting-engine/#many-backtests-in-one-call) page shows both approaches, and [Parameter optimization](/features/optimization/strategy-optimization/) shows how to build larger searches. ## From signals to orders \[#from-signals-to-orders] Each signal is a request, not an order. At every bar the simulator reads the signals, checks the current position, and converts the winning signal into an order with a size, a price, and a direction. By default, an entry while flat opens a position. A second entry while already in that position is ignored. An exit closes the position in full. Every order argument broadcasts with the signals, so it can be a scalar, a row, a column, or a full array. To use a different value per signal, fill an array only where the signals are set: ```python title="Use a different size for each entry" >>> close = pd.Series( ... [10.0, 11.0, 12.0, 11.0, 10.0, 12.0], ... index=pd.date_range("2026-01-01", periods=6) ... ) >>> entries = pd.Series([True, False, False, False, True, False], index=close.index) >>> exits = pd.Series([False, False, True, False, False, True], index=close.index) >>> size = close.vbt.wrapper.fill(np.nan) >>> size[entries] = [5, 10] >>> pf = vbt.PF.from_signals(close, entries, exits, size=size, init_cash=1000) >>> pf.orders.readable[["Fill Index", "Size", "Side"]] Fill Index Size Side 0 2026-01-01 5.0 Buy 1 2026-01-03 5.0 Sell 2 2026-01-05 10.0 Buy 3 2026-01-06 10.0 Sell ``` Without a size, each entry uses all available cash. Size types that target a position, such as `"targetpercent"`, are rejected because a target can contradict the direction of a signal. To size each entry as a share of portfolio value, use `"valuepercent"`, or pass targets as described in [Targets as signals](#targets-as-signals). The per-signal pattern works for `price`, `order_type`, `fees`, and any other order argument. A price array, for example, lets exits fill at levels computed by your own logic: ```python title="Exit at computed prices and enter at the close" >>> price = close.copy() # (1) >>> price[exits] = [11.8, 11.7] >>> pf = vbt.PF.from_signals(close, entries, exits, price=price) >>> pf.orders.readable[["Fill Index", "Size", "Price", "Side"]] Fill Index Size Price Side 0 2026-01-01 10.0 10.0 Buy 1 2026-01-03 10.0 11.8 Sell 2 2026-01-05 11.8 10.0 Buy 3 2026-01-06 11.8 11.7 Sell ``` 1. Start from the close so that entries keep a valid price. A bar whose price is `NaN` places no order, so a price array filled only at exits would skip every entry without an error. In a price array, `-np.inf` stands for the bar's open and `np.inf` for its close. Setting `price[entries] = -np.inf` on an array filled with `np.inf` enters at the open and exits at the close. !!! warning "Execution timing" By default, an order fills at the close of the bar where its signal appears. If your signals are computed from that same close, use `price="nextopen"` or `price="nextclose"`, or shift the signals by one bar, so the backtest does not trade on a price it could not have known in time. ## Stops and limit orders \[#stops-and-limit-orders] Your entry signals can work with stop losses, trailing stops, take-profit targets, and time exits. The simulator tracks these alongside your signals, so you can test an exit rule without writing the position-tracking logic yourself. Stop levels can differ across assets and parameter combinations. See [Stop loss and take profit](/features/backtesting/stop-loss-and-take-profit/). Signals can also place limit orders that wait for a price instead of filling immediately. You can use different order types for entries and exits, and set how long an unfilled limit order stays active. See [Orders and execution](/features/backtesting/orders-and-execution/) for limit prices, expiry, and fill behavior. ## Long, short, and reversals \[#long-short-and-reversals] There are two ways to describe direction. With two masks, `entries` and `exits`, a `direction` argument decides what they mean. `"longonly"` is the default, `"shortonly"` flips it, and `"both"` makes each exit reverse into a short position. With four masks, `long_entries`, `long_exits`, `short_entries`, and `short_exits`, the signals set the direction themselves, so a position can also go flat between trades, and `direction` is ignored. The difference matters. Below, a Bollinger Bands strategy buys below the lower band, shorts above the upper band, and exits at the middle band. Collapsing it into two masks with `direction="both"` removes the exits, so the strategy is always in the market: ```python title="Compare four direction-aware masks with two reversing masks" >>> data = vbt.YFData.pull("BTC-USD", start="2023-01-01", end="2024-01-01") >>> bb = data.run("bbands", window=20, alpha=2) >>> long_entries = data.close.vbt.crossed_below(bb.lower) >>> long_exits = data.close.vbt.crossed_above(bb.middle) >>> short_entries = data.close.vbt.crossed_above(bb.upper) >>> short_exits = data.close.vbt.crossed_below(bb.middle) >>> pf_four = vbt.PF.from_signals( ... data, ... long_entries=long_entries, ... long_exits=long_exits, ... short_entries=short_entries, ... short_exits=short_exits, ... ) >>> pf_two = vbt.PF.from_signals( ... data, ... entries=long_entries, ... exits=short_entries, ... direction="both" ... ) >>> metrics = ["total_trades", "total_time_exposure", "total_return"] >>> pd.DataFrame({ ... "four masks": pf_four.stats(metrics), ... "two masks": pf_two.stats(metrics), ... }) four masks two masks Total Trades 15 6 Position Coverage [%] 44.931507 89.315068 Total Return [%] 14.886316 -40.748144 ``` With four masks, the 15 trades split into 6 longs and 9 shorts, and the strategy waits in cash for more than half the year. Use two masks when one direction rules a whole column, and four masks when positions must close without reversing. ## Conflicting signals \[#conflicting-signals] Signals generated by different rules often fire on the same bar. The simulator resolves them in a fixed order, and each step has its own argument: | Conflict | Argument | Default | | ------------------------------------ | ------------------------------------------- | ----------------- | | Entry and exit in the same direction | `upon_long_conflict`, `upon_short_conflict` | `"ignore"` | | Long entry and short entry together | `upon_dir_conflict` | `"ignore"` | | Entry opposite to the open position | `upon_opposite_entry` | `"reversereduce"` | Same-direction conflicts pick `"entry"`, `"exit"`, or the signal `"adjacent"` or `"opposite"` to the current position. Direction conflicts pick `"long"`, `"short"`, `"adjacent"`, or `"opposite"`. Opposite entries can be ignored, close the position, or reverse it. Like any other argument, each mode can vary by bar and column, and `vbt.Param` tests several at once: === "Entry and exit together" ```python title="Resolve an entry and an exit on the same bar" >>> close = pd.Series( ... [10.0, 11.0, 12.0, 11.0], ... index=pd.date_range("2026-01-01", periods=4) ... ) >>> entries = pd.Series([True, False, True, False], index=close.index) >>> exits = pd.Series([False, False, True, False], index=close.index) >>> pf = vbt.PF.from_signals( ... close, ... entries, ... exits, ... upon_long_conflict=vbt.Param(["ignore", "exit"]), ... size=1, ... ) >>> pf.assets upon_long_conflict ignore exit 2026-01-01 1.0 1.0 2026-01-02 1.0 1.0 2026-01-03 1.0 0.0 2026-01-04 1.0 0.0 ``` === "Opposite entry" ```python title="Close or reverse a long position on a short entry" >>> long_entries = pd.Series([True, False, False, False], index=close.index) >>> short_entries = pd.Series([False, False, True, False], index=close.index) >>> pf = vbt.PF.from_signals( ... close, ... long_entries=long_entries, ... short_entries=short_entries, ... upon_opposite_entry=vbt.Param(["ignore", "close", "reverse"]), ... size=1, ... ) >>> pf.assets upon_opposite_entry ignore close reverse 2026-01-01 1.0 1.0 1.0 2026-01-02 1.0 1.0 1.0 2026-01-03 1.0 0.0 -1.0 2026-01-04 1.0 0.0 -1.0 ``` !!! info "Reversals are one order" A reversal closes the old position and opens the new one in a single order, so both legs share one price and order type. To close with a market order and reopen with a limit order, issue the exit on one bar and the opposite entry on the next, and set `order_type` per signal. Trade records still show two trades, one closing and one opening, and a `max_size` smaller than both legs together can block the reversal. ## Accumulation and entry ladders \[#accumulation-and-entry-ladders] Without accumulation, the simulator keeps at most one position per column and ignores repeated entries. Set `accumulate=True` to treat every signal as an order, so entries add to the position and exits with a size reduce it: ```python title="Add one unit on each entry signal" >>> close = pd.Series( ... [10.0, 11.0, 12.0, 13.0, 12.0, 14.0], ... index=pd.date_range("2026-01-01", periods=6) ... ) >>> entries = pd.Series([True, True, True, True, False, False], index=close.index) >>> exits = pd.Series([False, False, False, False, False, True], index=close.index) >>> pf = vbt.PF.from_signals( ... close, ... entries, ... exits, ... size=1, ... accumulate=vbt.Param([False, True]) ... ) >>> pf.assets accumulate False True 2026-01-01 1.0 1.0 2026-01-02 1.0 2.0 2026-01-03 1.0 3.0 2026-01-04 1.0 4.0 2026-01-05 1.0 4.0 2026-01-06 0.0 3.0 ``` `accumulate` also takes `"addonly"` to scale in while each exit closes the whole position, and `"removeonly"` to scale out of a single entry. With `size_type="percent"`, an exit size is a share of the current position, so taking half off and then closing the rest is two exits: ```python title="Buy with all cash, sell half, then sell the rest" >>> close = pd.Series( ... [10.0, 11.0, 12.0, 11.5, 13.0, 12.0], ... index=pd.date_range("2026-01-01", periods=6) ... ) >>> entries = pd.Series([True, False, False, False, False, False], index=close.index) >>> exits = pd.Series([False, False, True, False, True, False], index=close.index) >>> size = close.vbt.wrapper.fill(np.nan) >>> size[entries] = 1.0 # (1) >>> size[exits] = [0.5, 1.0] >>> pf = vbt.PF.from_signals( ... close, ... entries, ... exits, ... size=size, ... size_type="percent", ... accumulate="removeonly", ... init_cash=1000, ... ) >>> pf.orders.readable[["Fill Index", "Size", "Price", "Side"]] Fill Index Size Price Side 0 2026-01-01 100.0 10.0 Buy 1 2026-01-03 50.0 12.0 Sell 2 2026-01-05 50.0 13.0 Sell ``` 1. For entries, the percentage applies to available cash, so 1.0 invests all of it. For pyramiding with a cap, the decision depends on the position you already hold, so it cannot be precomputed as a mask. A signal function written with Numba sees the simulation state at every bar. Here it adds one unit on each new 20-day high, up to three units, and exits below the 20-day average: ```python title="Pyramid into new highs with a three-unit cap" >>> @njit ... def pyramid_signal_nb(c, new_high, exits, max_units): ... position = c.last_position[c.col] # (1) ... if position > 0 and vbt.pf_nb.select_nb(c, exits): ... return False, True, False, False # (2) ... if position < max_units and vbt.pf_nb.select_nb(c, new_high): ... return True, False, False, False ... return False, False, False, False >>> new_high = data.close >= data.close.rolling(20).max() >>> exits = data.close.vbt.crossed_below(data.close.rolling(20).mean()) >>> pf = vbt.PF.from_signals( ... data, ... signal_func_nb=pyramid_signal_nb, ... signal_args=(vbt.Rep("new_high"), vbt.Rep("exits"), 3), ... broadcast_named_args=dict(new_high=new_high, exits=exits), # (3) ... size=1, ... init_cash=100_000, ... accumulate="addonly", ... ) >>> pf.orders.readable[["Fill Index", "Size", "Price", "Side"]].head(4) Fill Index Size Price Side 0 2023-01-20 00:00:00+00:00 1.0 22676.552734 Buy 1 2023-01-21 00:00:00+00:00 1.0 22777.625000 Buy 2 2023-01-23 00:00:00+00:00 1.0 22934.431641 Buy 3 2023-02-06 00:00:00+00:00 3.0 22760.109375 Sell ``` 1. The position in the current column before this bar's order. 2. The function returns four flags: long entry, long exit, short entry, and short exit. 3. Arrays passed here are broadcast to the data's shape and substituted for `vbt.Rep` placeholders. The same technique builds entry ladders and DCA plans. The signal function records the initial entry, then releases staged entries after a set number of bars or at set price levels, each with its own size. You can also add to a winning position after it reaches a profit threshold. Signal callbacks can read the open position's return and issue another entry with accumulation enabled. See [Position info](/features/backtesting/portfolio-accounting/#position-info) for the running position metrics available to your logic. !!! info "Documentation" The members-only [Portfolio from signals](https://members.vectorbt.pro/documentation/portfolio/from-signals/) guide builds a parameterized entry ladder step by step. ## Targets as signals \[#targets-as-signals] Sometimes you know the position you want, not the signals. With `order_mode=True`, the size array is read as a list of orders, and the simulator derives the matching signals so stop and limit orders still apply. `pf.get_signals()` returns the four signal masks that were actually executed: ```python title="Derive signals from target positions" >>> close = pd.Series( ... [10.0, 11.0, 12.0, 11.0, 13.0], ... index=pd.date_range("2026-01-01", periods=5) ... ) >>> target = pd.Series([5, np.nan, 10, 0, -5], index=close.index) # (1) >>> pf = vbt.PF.from_signals( ... close, ... size=target, ... size_type="targetamount", ... order_mode=True, ... accumulate=True, ... direction="both", ... init_cash=1000, ... ) >>> long_entries, long_exits, short_entries, short_exits = pf.get_signals() >>> pd.DataFrame({ ... "long entry": long_entries, ... "long exit": long_exits, ... "short entry": short_entries, ... }) long entry long exit short entry 2026-01-01 True False False 2026-01-02 False False False 2026-01-03 True False False 2026-01-04 False True False 2026-01-05 False False True ``` 1. Hold 5 units, keep the position, raise it to 10, go flat, then hold a 5-unit short. `NaN` means no order. ## Calling the kernel directly \[#calling-the-kernel-directly] `vbt.PF.from_signals` prepares arguments, broadcasts them, and wraps the results. The engine underneath is a compiled function that takes plain NumPy arrays. You can call it directly, for example inside your own Numba code or a large optimization loop: ```python title="Run the compiled signal simulator on NumPy arrays" >>> close_arr = np.array([[10.0], [11.0], [12.0], [11.0], [13.0]]) >>> long_entries = np.array([[True], [False], [False], [True], [False]]) >>> long_exits = np.array([[False], [False], [True], [False], [True]]) >>> sim_out = vbt.pf_nb.from_signals_nb( ... target_shape=close_arr.shape, ... group_lens=np.array([1]), # (1) ... close=close_arr, ... init_cash=100.0, ... long_entries=long_entries, ... long_exits=long_exits, ... ) >>> pd.DataFrame(sim_out.order_records)[["idx", "size", "price"]] idx size price 0 0 10.000000 10.0 1 2 10.000000 12.0 2 3 10.909091 11.0 3 4 10.909091 13.0 ``` 1. One group with one column. Columns in the same group share cash. At this level, argument preparation is up to you: string options become their enum integers, and arrays must already have the target shape or broadcast to it. The callback version, `from_signal_func_nb`, accepts the same signal functions as `from_signals`, and trade records and metrics can be rebuilt from the order records with compiled functions as well. !!! info "Tutorial" The members-only [From Python to Rust](https://members.vectorbt.pro/tutorials/from-python-to-rust/static/) tutorial takes one strategy from `vbt.PF.from_signals` down to the Numba kernel and then to Rust. ## Target size to signals \[#target-size-to-signals] New in 1.10.0 ✅ Target size can be converted to signals using a special signal function, giving access to stop and limit order functionality. This is especially useful, for example, in portfolio optimization. ```python title="Perform the Mean-Variance Optimization with SL and TP" >>> data = vbt.YFData.pull( ... ["SPY", "TLT", "XLF", "XLE", "XLU", "XLK", "XLB", "XLP", "XLY", "XLI", "XLV"], ... start="2022", ... end="2023", ... missing_index="drop" ... ) >>> pfo = vbt.PFO.from_riskfolio(data.returns, every="M") >>> pf = pfo.simulate( ... data, ... pf_method="from_signals", ... sl_stop=0.05, ... tp_stop=0.1, ... stop_exit_price="close" # (1) ... ) >>> pf.plot_allocations().show() ``` 1. Otherwise, user and stop signals will occur at different times within the same bar, making it impossible to establish the correct order of execution. Monthly Mean-Variance portfolio allocations with stop-loss and take-profit protection during 2022. [Figure data (JSON)](/assets/figures/features/portfolio/target-size-to-signals.8f527b79be15.json) # Stop loss and take profit (/features/backtesting/stop-loss-and-take-profit) Exits decide most of a strategy's risk. VBT lets you backtest stop losses, trailing stops, take profits, and time stops in Python as arguments of `vbt.PF.from_signals`, and test whole grids of them in one call. Stops are checked against each bar's open, high, low, and close, with explicit rules for what fills first. ```python title="Test 64 stop loss and take profit combinations at once" >>> data = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2024-01-01") >>> fast = data.close.rolling(20).mean() >>> slow = data.close.rolling(50).mean() >>> entries = fast.vbt.crossed_above(slow) >>> pf = vbt.PF.from_signals( ... data, ... entries, # (1) ... sl_stop=vbt.Param(np.arange(2, 17, 2) / 100), ... tp_stop=vbt.Param(np.arange(5, 45, 5) / 100), ... fees=0.001, ... ) >>> pf.sharpe_ratio.sort_values(ascending=False).head(3) sl_stop tp_stop 0.08 0.4 0.941107 0.12 0.4 0.917926 0.08 0.1 0.910485 Name: sharpe_ratio, dtype: float64 >>> pf.sharpe_ratio.vbt.heatmap(x_level="sl_stop", y_level="tp_stop").show() ``` 1. There are no exit signals. Every position is closed by its stop loss or its take profit. Heatmap of Sharpe ratios for stop loss values from 2% to 16% and take profit values from 5% to 40% on a Bitcoin moving average strategy. [Figure data (JSON)](/assets/figures/features/backtesting/stop-loss-take-profit-grid.45ce7fc98a45.json) The best cell sits on the edge of the grid, and its neighbors differ a lot. A heatmap makes that visible before a single best value becomes a decision. ## Stops and targets \[#stops-and-targets] Four stop types are built in. `sl_stop` is a stop loss, `tsl_stop` a trailing stop that follows the best price since entry, `tp_stop` a take profit, and `tsl_th` turns the trailing stop into a trailing take profit that only starts trailing after the price has moved by that threshold. Each is measured from the entry price as a fraction by default: ```python title="Exit by take profit or by trailing stop" >>> index = pd.date_range("2026-01-01", periods=5) >>> ohlc = pd.DataFrame({ ... "open": [100.0, 101.0, 104.0, 108.0, 103.0], ... "high": [101.0, 105.0, 111.0, 109.0, 104.0], ... "low": [99.0, 100.0, 103.0, 102.0, 94.0], ... "close": [100.0, 104.0, 108.0, 103.0, 95.0], ... }, index=index) >>> entries = pd.Series([True, False, False, False, False], index=index) >>> pf = vbt.PF.from_signals( ... ohlc["close"], ... entries, ... open=ohlc["open"], ... high=ohlc["high"], ... low=ohlc["low"], ... sl_stop=0.05, ... tsl_stop=vbt.Param([np.nan, 0.04], level=0), # (1) ... tp_stop=vbt.Param([0.1, np.nan], level=0), ... ) >>> pf.orders.readable[["Column", "Fill Index", "Side", "Price", "Stop Type"]] Column Fill Index Side Price Stop Type 0 (nan, 0.1) 2026-01-01 Buy 100.00 None 1 (nan, 0.1) 2026-01-03 Sell 110.00 TP 2 (0.04, nan) 2026-01-01 Buy 100.00 None 3 (0.04, nan) 2026-01-04 Sell 106.56 TSL ``` 1. Sharing `level=0` pairs the values instead of building a product: a 10% take profit alone, then a 4% trailing stop alone. The take profit fills at $110 on the third bar. The trailing stop follows the $111 high down to $106.56 and fills on the fourth bar. With `delta_format="absolute"`, stop values are price distances instead of fractions, and with `"target"` they are price levels. Stop values broadcast like any other argument, so they can differ per asset, per bar, and per direction. To use different stops for longs and shorts, fill one array with the long value at long entries and the short value at short entries. Stops are read when a position opens and stay fixed afterwards unless a callback changes them. A stop is checked from the bar after the entry, even when the entry fills at the open, because the bar's high and low cannot be placed before or after the fill. When it fires, it closes the position. With `stop_exit_type="reverse"`, the same order also opens the opposite position. Combine a stop loss and a take profit to test a bracket around each position. When one closes the position, VBT clears the other stops, so an old target cannot act on a later position. A risk-to-reward setup is two arrays. Here the risk is the distance to the lowest low of the last five bars, and the target is twice that distance: ```python title="Set the stop below recent lows and the target at 2R" >>> data = vbt.YFData.pull("BTC-USD", start="2023-01-01", end="2024-01-01") >>> entries = data.close.vbt.crossed_above(data.close.rolling(20).max().shift(1)) >>> risk = data.close - data.low.rolling(5).min() >>> pf = vbt.PF.from_signals( ... data, ... entries, ... sl_stop=risk, ... tp_stop=2 * risk, ... delta_format="absolute", ... ) >>> cols = ["Entry Index", "Avg Entry Price", "Avg Exit Price", "Return"] >>> pf.trades.readable[cols].head(4) Entry Index Avg Entry Price Avg Exit Price Return 0 2023-01-23 00:00:00+00:00 22934.431641 20685.380859 -0.098064 1 2023-03-14 00:00:00+00:00 24746.074219 34981.714844 0.413627 2 2023-10-29 00:00:00+00:00 34538.480469 36781.667969 0.064947 3 2023-11-15 00:00:00+00:00 37880.582031 43744.746094 0.154807 ``` ## Trailing take profit \[#trailing-take-profit] A fixed target exits as soon as it is reached. A trailing take profit lets the move continue, then exits on a pullback. Set `tsl_th` to the gain that activates it and `tsl_stop` to the distance it trails by. You can keep a separate `sl_stop` in place before that threshold is reached. Here the same price path first pulls back, then rises past 10%. One portfolio trails from the start, while the other waits for that gain before enabling its 5% trailing exit: ```python title="Start trailing only after a 10% gain" >>> index = pd.date_range("2026-01-01", periods=6) >>> close = pd.Series([100.0, 104.0, 98.0, 112.0, 120.0, 113.0], index=index) >>> pf = vbt.PF.from_signals( ... close, ... entries=[True, False, False, False, False, False], ... sl_stop=0.1, ... tsl_stop=0.05, ... tsl_th=vbt.Param([np.nan, 0.1], keys=["trail immediately", "trail after 10%"]), ... ) >>> pf.orders.side_sell.readable[["Column", "Fill Index", "Price", "Stop Type"]] Column Fill Index Price Stop Type 0 trail immediately 2026-01-03 98.0 TSL 1 trail after 10% 2026-01-06 113.0 TTP ``` Both portfolios have a 10% stop loss. The threshold changes when the trailing exit takes over. This example checks only the supplied closing prices, so the exits fill at those closes. ## Time-based exits \[#time-based-exits] A time stop exits after a holding period or at a point in time, whatever the price does. `td_stop` takes a duration such as `"7D"`, or a number of bars with `time_delta_format="rows"`. `dt_stop` takes a date, a period such as `"M"` for the end of the month, or a time of day such as `"18:00"`. The holding period counts from the open of the entry bar, so a time stop fills at the open of the bar where it expires. The [Time stops](#time-stops) highlight below exits every position before the month ends. ```python title="Exit five bars after each entry" >>> pf = vbt.PF.from_signals(data, entries, td_stop=5, time_delta_format="rows") >>> pf.orders.readable[["Fill Index", "Side", "Stop Type"]].head(4) Fill Index Side Stop Type 0 2023-01-23 00:00:00+00:00 Buy None 1 2023-01-28 00:00:00+00:00 Sell TD 2 2023-01-29 00:00:00+00:00 Buy None 3 2023-02-03 00:00:00+00:00 Sell TD ``` ## Adaptive stops \[#adaptive-stops] Volatility-scaled stops are arrays, too. Pass a multiple of ATR with `delta_format="absolute"` and each trade gets a distance that matches the market at its entry. The distance is read once, so a stop series does not make a trailing stop follow the current ATR. To move a stop while a trade is open, write an adjustment function. It runs at the start of every bar and can rewrite the active stop in `c.last_sl_info`. This one moves the stop to the entry price once the previous close is one risk unit in profit: ```python title="Move an ATR stop to breakeven after 1R" >>> @njit ... def breakeven_nb(c): ... sl_info = c.last_sl_info[c.col] ... if c.last_position[c.col] > 0 and vbt.pf_nb.is_stop_info_active_nb(sl_info): ... prev_close = vbt.pf_nb.select_nb(c, c.close, i=c.i - 1) # (1) ... target = sl_info["init_price"] + sl_info["stop"] ... if sl_info["stop"] > 0 and prev_close >= target: ... sl_info["stop"] = 0.0 # (2) >>> atr = data.run("atr", window=14).atr >>> kwargs = dict(sl_stop=2 * atr, tp_stop=6 * atr, delta_format="absolute") >>> fixed = vbt.PF.from_signals(data, entries, **kwargs) >>> breakeven = vbt.PF.from_signals(data, entries, adjust_func_nb=breakeven_nb, **kwargs) >>> pd.DataFrame({ ... "entry": fixed.trades.readable["Entry Index"], ... "fixed": fixed.trades.readable["Return"], ... "breakeven": breakeven.trades.readable["Return"], ... }).iloc[3:6] entry fixed breakeven 3 2023-05-28 00:00:00+00:00 -0.056052 -0.056052 4 2023-06-20 00:00:00+00:00 -0.060298 0.000000 5 2023-10-01 00:00:00+00:00 -0.041770 -0.041770 ``` 1. The function runs before the current bar is known, so it decides on the previous close. 2. A distance of zero puts the stop at the entry price. The June trade rose by more than its initial risk, then fell back. With the fixed stop it lost 6%. With the breakeven rule it closed flat. The same pattern can tighten a stop on a higher timeframe, trail by a chandelier distance, or rebase the stop on the average entry price after adding to a position. !!! info "Adding to a position" Each stop type keeps one active level per column. When an entry increases the position, `upon_stop_update` decides whether the existing stop is kept or replaced by the new one. ## Stop ladders and partial exits \[#stop-ladders-and-partial-exits] A stop normally closes the whole position. Pass a list of stop values with `stop_ladder` to scale out at successive levels instead. `"uniform"` exits an equal share at each level, `"weighted"` sizes each exit by the distance to the previous level, and the adaptive variants recompute the size from the remaining position. The [Stop laddering](#stop-laddering) highlight below tests two take profit ladders side by side. A ladder keeps the remaining stops alive after a partial stop exit, combining staged profit-taking with a protective stop for the remaining position. For control over each step, set `exit_size` and `exit_type` on the stop records in a callback, for example to reverse instead of close. ## Stop-market and stop-limit exits \[#stop-market-and-stop-limit-exits] By default, a triggered stop creates a market order. With `stop_order_type="limit"`, it can create a limit order instead, with `stop_limit_delta` setting the offset from the stop's exit price. This lets you compare exiting when the stop fires with waiting for a chosen price. The limit can remain unfilled if that price is never reached. See [Orders and execution](/features/backtesting/orders-and-execution/#pending-limit-and-stop-entry-orders) for pending orders and fill-price choices. ## Realistic stop fills \[#realistic-stop-fills] Daily bars hide the order of events inside the day. VBT splits each bar into its open, the part between open and close, and its close, and fills whatever is reached first. When a stop loss and a take profit are both reached inside the same part of the bar, the stop loss wins: ```python title="Resolve a bar that hits both the stop and the target" >>> index = pd.date_range("2026-01-01", periods=2) >>> pf = vbt.PF.from_signals( ... pd.Series([100.0, 100.0], index=index), ... pd.Series([True, False], index=index), ... open=pd.Series([100.0, 100.0], index=index), ... high=pd.Series([100.0, 112.0], index=index), ... low=pd.Series([100.0, 94.0], index=index), ... sl_stop=0.05, ... tp_stop=0.1, ... ) >>> pf.orders.readable[["Fill Index", "Side", "Price", "Stop Type"]] Fill Index Side Price Stop Type 0 2026-01-01 Buy 100.0 None 1 2026-01-02 Sell 95.0 SL ``` The same pessimism applies to trailing stops: on each bar the stop is checked before the new high can raise it. When the stops are hit in different parts of the bar, the earlier one fills. Gaps are the other trap. If the price opens beyond the stop, a real order fills at the open, not at the stop. `stop_exit_price` controls this: ```python title="Fill a stop after a gap down" >>> pf = vbt.PF.from_signals( ... pd.Series([100.0, 92.0], index=index), ... pd.Series([True, False], index=index), ... open=pd.Series([100.0, 90.0], index=index), ... high=pd.Series([100.0, 93.0], index=index), ... low=pd.Series([100.0, 89.0], index=index), ... sl_stop=0.05, ... stop_exit_price=vbt.Param(["stop", "hardstop", "close"]), ... ) >>> pf.orders.readable[["Column", "Side", "Price"]] Column Side Price 0 stop Buy 100.0 1 stop Sell 90.0 2 hardstop Buy 100.0 3 hardstop Sell 95.0 4 close Buy 100.0 5 close Sell 92.0 ``` The default, `"stop"`, fills at the open after a gap. `"hardstop"` always fills at the stop level, which is optimistic, and `"close"` fills at the bar's close. On the entry side, `stop_entry_price` sets the reference the stop is measured from. It defaults to the order price, such as the open with `price="nextopen"`. Set it to `"fillprice"` to include slippage, or to `"close"` to measure stops from the close of the entry bar. !!! warning "Use finer data for tight stops" When stops are small relative to a bar's range, many bars hit both levels and the pessimistic rule decides the outcome. Test such stops on [intraday data](/features/backtesting/intraday-and-tick-backtesting/), where far fewer bars contain both levels. ## Stop signals before simulation \[#stop-signals-before-simulation] Stops can also be computed as exit signals, without a portfolio. This is useful for signal research, labeling, and for checking how often a stop would fire before you size any trades: ```python title="Generate stop exits as signals" >>> exits = entries.vbt.signals.generate_ohlc_stop_exits( ... entry_price=data.close, ... open=data.open, ... high=data.high, ... low=data.low, ... close=data.close, ... sl_stop=0.05, ... tp_stop=0.1, ... out_dict=(out := {}), # (1) ... ) >>> stop_names = dict(enumerate(vbt.sig_enums.StopType._fields)) >>> pd.DataFrame({ ... "stop price": out["stop_price"][exits], ... "stop type": out["stop_type"][exits].map(stop_names), ... }).head(4) stop price stop type Date 2023-02-09 00:00:00+00:00 22585.838086 SL 2023-02-24 00:00:00+00:00 23587.691016 SL 2023-03-17 00:00:00+00:00 27558.067969 TP 2023-03-22 00:00:00+00:00 26767.025586 SL ``` 1. Collect the price and the type of each stop that fired. By default, an exit is placed only between two entries, so entries that arrive while a stop is still pending do not start a new stop. ## Stop laddering \[#stop-laddering] New in 1.12.0 ✅ Stop laddering is a technique for incrementally moving out of a position. Instead of providing a single stop value to close a position, you can provide an array of stop values, with each one removing a certain amount of the position when triggered. You can control this amount by choosing a different ladder mode. Thanks to a new broadcasting feature that allows arrays to broadcast along just one axis, the stop values do not need to have the same shape as the data. You can even provide stop arrays of different shapes as parameters! ```python title="Test two TP ladders" >>> data = vbt.YFData.pull("BTC-USD", end="2017-01") >>> pf = vbt.PF.from_holding( ... data, ... stop_ladder="uniform", ... tp_stop=vbt.Param([ ... [0.1, 0.2, 0.3, 0.4, 0.5], ... [0.4, 0.5, 0.6], ... ], keys=["tp_ladder_1", "tp_ladder_2"]) ... ) >>> pf.trades.plot(column="tp_ladder_1").show() ``` BTC-USD holding trade with five uniform take-profit ladder exits. [Figure data (JSON)](/assets/figures/features/portfolio/stop-laddering.e265b961a2c9.json) ## Time stops \[#time-stops] New in 1.11.0 ✅ Joining other stop orders, time stop orders can close a position either after a certain period of time or on a specific date. ```python title="Enter randomly, exit before the end of the month" >>> data = vbt.YFData.pull("BTC-USD", start="2022-01", end="2022-04") >>> entries = vbt.pd_acc.signals.generate_random(data.symbol_wrapper, n=10, seed=42) >>> pf = vbt.PF.from_signals(data, entries, dt_stop="M") # (1) >>> pf.orders.readable[["Fill Index", "Side", "Stop Type"]] Fill Index Side Stop Type 0 2022-01-19 00:00:00+00:00 Buy None 1 2022-01-31 00:00:00+00:00 Sell DT 2 2022-02-25 00:00:00+00:00 Buy None 3 2022-02-28 00:00:00+00:00 Sell DT 4 2022-03-11 00:00:00+00:00 Buy None 5 2022-03-31 00:00:00+00:00 Sell DT ``` 1. Use `dt_stop` for datetime-based stops and `td_stop` for timedelta-based stops. Datetime-based stops can be periods ("D"), timestamps ("2023-01-01"), and even specific times ("18:00"). # Drawdown analysis (/features/analytics/drawdown-analysis) How deep did the strategy fall, how long did it stay down, and how fast did it recover? VBT turns every drawdown into a record with its peak, valley, and recovery, so drawdown analysis in Python becomes a table you can sort, filter, and plot, next to the familiar max drawdown and underwater curve. ```python title="Find the five worst drawdowns of a 60/40 portfolio" >>> data = vbt.YFData.pull(["SPY", "TLT"], start="2005-01-01", end="2025-01-01") >>> rebalance = ~data.index.tz_localize(None).to_period("M").duplicated() >>> weights = data.symbol_wrapper.fill(np.nan) >>> weights[rebalance] = [0.6, 0.4] >>> pf = vbt.PF.from_orders( ... data, ... size=weights, ... size_type="targetpercent", ... group_by=True, ... cash_sharing=True, ... call_seq="auto", ... ) >>> dd = pf.drawdowns # (1) >>> pd.DataFrame({ ... "peak": dd.readable["Start Index"].dt.date, ... "valley": dd.readable["Valley Index"].dt.date, ... "depth": dd.drawdown.values, ... "decline": dd.decline_duration.values, # (2) ... "recovery": dd.recovery_duration.values, ... "status": dd.readable["Status"], ... }).sort_values("depth").head(5).round(3) peak valley depth decline recovery status 48 2007-12-06 2009-03-09 -0.311 314.0 388.0 Recovered 298 2021-12-27 2022-10-20 -0.275 206.0 475.0 Recovered 254 2020-02-20 2020-03-18 -0.184 19.0 48.0 Recovered 226 2018-08-29 2018-12-24 -0.107 80.0 55.0 Recovered 176 2015-03-20 2015-08-25 -0.078 109.0 142.0 Recovered >>> dd.plot(top_n=5).show() ``` 1. One record per drawdown, from its peak through its valley to the bar where value regained the peak. 2. Durations are counted in bars, here trading days. Value of a monthly rebalanced 60/40 SPY and TLT portfolio from 2005 to 2024 with its five largest drawdowns highlighted. [Figure data (JSON)](/assets/figures/features/analytics/drawdown-analysis-top5.eed6f01cff26.json) The 2022 drawdown was shallower than 2008 but took longer to recover, 475 trading days against 388, because stocks and bonds fell together. ## Drawdown records \[#drawdown-records] `pf.drawdowns` holds one record for each drawdown in the value series. Each record has the peak, the valley, the end, the values at those points, and a status: recovered, or still active at the end of the data. Because they are records, they can be filtered, for example `dd.status_recovered`, mapped to any field, and turned into statistics with `dd.stats()`. Note the naming: `pf.drawdown` without the "s" is the time series of the current percentage below the running peak. Depths are percentages of the peak value. When a strategy trades a fixed amount out of a large account, most of that value is idle cash, and the percentages look small. The drawdown in money is a field away: `(dd.start_val - dd.valley_val).max()` gives the largest fall from a peak in account currency. The same records work on any series, not only on a portfolio. `price.vbt.drawdowns` finds the drawdowns of a price, an indicator, or an equity curve from somewhere else. ## Duration and recovery \[#duration-and-recovery] Depth is only half of the risk. The decline duration counts the bars from peak to valley, and the recovery duration the bars from valley back to the peak. The underwater curve shows both at once: ```python title="Plot the underwater curve" >>> pf.plot_underwater().show() ``` Underwater curve of a monthly rebalanced 60/40 SPY and TLT portfolio from 2005 to 2024. [Figure data (JSON)](/assets/figures/features/analytics/drawdown-analysis-underwater.62efb61aaa32.json) The share of time spent below a previous peak is `(pf.drawdown < 0).mean()`, 87.3% of the bars for this portfolio. It makes a useful optimization objective for strategies that should spend little time underwater. ## Active and average drawdowns \[#active-and-average-drawdowns] A drawdown that has not recovered by the end of the data is active. It has a depth and a duration so far, but no recovery yet. `pf.stats()` includes active drawdowns in the maximum drawdown, while `dd.stats()` leaves them out of its summaries unless `incl_active` is enabled in `vbt.settings.drawdowns`. You can also include them for a single report with `dd.stats(settings=dict(incl_active=True))`. An active drawdown can already be recovering. Its worst depth tells you how far the account fell, while its current depth tells you how far it still has to recover: ```python title="Separate the worst loss from the loss still to recover" >>> equity = pd.Series([100.0, 90.0, 100.0, 120.0, 90.0, 108.0], index=pd.date_range("2026-01-01", periods=6)) >>> equity_dd = equity.vbt.drawdowns >>> pd.Series({ ... "Worst recovered [%]": equity_dd.status_recovered.max_drawdown * 100, ... "Worst overall [%]": equity_dd.max_drawdown * 100, ... "Current drawdown [%]": equity_dd.active_drawdown * 100, ... }).round(1) Worst recovered [%] -10.0 Worst overall [%] -25.0 Current drawdown [%] -10.0 dtype: float64 ``` The first fall from 100 to 90 recovered fully. The second fell from 120 to 90, a 25% loss, and only recovered to 108. The account is now 10% below its peak, but excluding the unfinished drawdown would hide the worst loss. This works on an external equity curve as well as a VBT portfolio, so you can compare their drawdown histories with the same tools. Average drawdown has two meanings. The average depth of the records, `dd.avg_drawdown`, was 1.2% here, because hundreds of shallow drawdowns count as much as the deep ones. The average of the drawdown series over time, `pf.drawdown.mean()`, was 4.5%, because the deep drawdowns lasted longer. State which one you report. ## Drawdowns across a grid \[#drawdowns-across-a-grid] Maximum drawdown is a metric like any other, so it can be compared across parameters. Here the 100 moving average pairs from the [Performance and risk metrics](/features/analytics/performance-metrics/) page are shown by Sharpe ratio and by maximum drawdown: ```python title="Map Sharpe ratio and maximum drawdown across 100 parameter pairs" >>> btc = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2025-01-01") >>> fast_w, slow_w = np.meshgrid(np.arange(5, 55, 5), np.arange(60, 260, 20)) >>> fast = vbt.MA.run(btc.close, window=fast_w.ravel(), short_name="fast") >>> slow = vbt.MA.run(btc.close, window=slow_w.ravel(), short_name="slow") >>> grid_pf = vbt.PF.from_signals( ... btc, ... fast.ma_crossed_above(slow), ... fast.ma_crossed_below(slow), ... fees=0.001, ... ) >>> fig = vbt.make_subplots( ... rows=1, ... cols=2, ... subplot_titles=["Sharpe ratio", "Max drawdown"], ... horizontal_spacing=0.15, ... ) >>> grid_pf.sharpe_ratio.vbt.heatmap( ... x_level="fast_window", ... y_level="slow_window", ... fig=fig, ... add_trace_kwargs=dict(row=1, col=1), ... trace_kwargs=dict(colorbar=dict(x=0.43, len=0.9)), ... ) >>> grid_pf.max_drawdown.vbt.heatmap( ... x_level="fast_window", ... y_level="slow_window", ... fig=fig, ... add_trace_kwargs=dict(row=1, col=2), ... trace_kwargs=dict(colorbar=dict(x=1.0, len=0.9)), ... ) >>> fig.show() ``` Heatmaps of Sharpe ratio and maximum drawdown for 100 Bitcoin moving average window pairs. [Figure data (JSON)](/assets/figures/features/analytics/drawdown-analysis-grid.f3c3a6b19188.json) The pair with the best Sharpe ratio, 5 and 120 days, fell 38.6% at its worst, while 5 and 160 days had the shallowest drawdown in the grid at 30.1%. Across the grid, a higher Sharpe ratio came with deeper drawdowns more often than not. Use the two maps together to find parameter regions with a return and drawdown balance worth investigating. [Robustness and overfitting](/features/optimization/robustness-and-overfitting/) covers checking whether those results hold up beyond the best backtest. ## Equity at or below zero \[#equity-at-or-below-zero] Drawdowns are measured relative to the peak value, so they are capped at 100% only while the value stays positive. With leverage or short positions the value can fall below zero, and the drawdown then exceeds 100%. The simulator does not liquidate the account at that point. To end the analysis there, set the simulation end to the first bar where the value reaches zero. # Analysis (/features/analytics) Measure returns and risk, study drawdowns, dissect trades, chart results, explore recurring market events, and query the event records behind all of them. This section is for anyone who has a backtest, or any return series, and wants to know how good it was and why it behaved the way it did. Each page below answers one of those questions, for one portfolio or for thousands at once. ## Start here \[#start-here] Begin with [Performance and risk metrics](/features/analytics/performance-metrics/) for the full report on a backtest and how to compare it with a benchmark. Then follow the question you want to answer: | Your question | Where to look | | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | How deep were the losses, and how long did recovery take? | [Drawdown analysis](/features/analytics/drawdown-analysis/) for individual drawdowns, time underwater, and unfinished recoveries | | Which trades made money, and did the exits leave profit behind? | [Trade analytics](/features/analytics/trade-analytics/) for entry and exit records, MAE, MFE, and long/short comparisons | | How can I inspect a trade or compare a parameter grid visually? | [Interactive charts](/features/analytics/interactive-charts/) for price overlays, dashboards, heatmaps, and sharing charts | | What happened after similar patterns or dated events? | [Patterns and event studies](/features/analytics/patterns-and-event-studies/) for historical matches and forward price paths | | How can I analyze just the events or groups I care about? | [Records and mapped arrays](/features/analytics/records-and-mapped-arrays/) for filtering and regrouping orders, trades, and intervals | ## Explore analysis features \[#explore-analysis-features] * [Performance and risk metrics](/features/analytics/performance-metrics): Compute returns, Sharpe, Sortino, benchmark, and rolling metrics on any backtest * [Drawdown analysis](/features/analytics/drawdown-analysis): Measure the depth, duration, and recovery of every drawdown as records * [Trade analytics](/features/analytics/trade-analytics): Analyze trades and positions with MAE, MFE, edge ratio, profit factor, and plots * [Interactive charts](/features/analytics/interactive-charts): Plot backtests, candlesticks, indicators, signals, and parameter heatmaps with Plotly * [Patterns and event studies](/features/analytics/patterns-and-event-studies): Search price history for similar patterns and study what happened after events * [Records and mapped arrays](/features/analytics/records-and-mapped-arrays): Store sparse events and intervals as records, then filter, reduce, and regroup them ## Work with results you already have \[#work-with-results-you-already-have] The analysis tools also work with your own data. Use a Pandas return series or an external equity curve with [Performance and risk metrics](/features/analytics/performance-metrics/#analyze-an-external-equity-curve), or inspect its losses with [Drawdown analysis](/features/analytics/drawdown-analysis/). If you have a list of earnings, news, or signal dates, the [event calendar example](/features/analytics/patterns-and-event-studies/#bring-your-own-event-calendar) shows how to compare the price paths that followed them. ## Turn findings into the next test \[#turn-findings-into-the-next-test] A trade breakdown might suggest a different exit, while a parameter heatmap might reveal a region worth exploring. Take those ideas back to [Backtesting](/features/backtesting/) and [Parameter optimization](/features/optimization/strategy-optimization/), then use [Walk-forward and cross-validation](/features/optimization/time-series-cross-validation/) to test them on periods that were not used to choose them. For a worked example of pattern detection and projections, follow the [Patterns and projections tutorial](/tutorials/patterns-and-projections/). # Interactive charts (/features/analytics/interactive-charts) How do you see what a strategy actually did? VBT plots backtests, prices, indicators, signals, and parameter results as interactive Plotly charts in Python: zoom into a single trade, hover for exact values, and combine any of them in one figure. ```python title="Plot a backtest with orders, trade P&L, a custom RSI panel, and drawdowns" >>> data = vbt.YFData.pull("BTC-USD", start="2023-01-01", end="2024-01-01") >>> rsi = data.run("rsi", window=14).rsi >>> pf = vbt.PF.from_signals(data, rsi.vbt.crossed_below(30), rsi.vbt.crossed_above(70)) >>> def plot_rsi(pf, rsi, add_trace_kwargs=None, fig=None): # (1) ... rsi.rename("RSI").vbt.plot(add_trace_kwargs=add_trace_kwargs, fig=fig) >>> pf.plot( ... subplots=[ ... "orders", ... "trade_pnl", ... ("rsi", dict(title="RSI", plot_func=plot_rsi, rsi=rsi)), ... "drawdowns", ... ], ... settings=dict(bm_returns=False), ... ).show() ``` 1. A custom panel is a function that draws into the subplot it is given. Bitcoin RSI strategy chart for 2023 with buy and sell orders, trade profit and loss, the RSI indicator, and drawdowns. [Figure data (JSON)](/assets/figures/features/analytics/interactive-charts-portfolio.82d6e04cdee9.json) ## Portfolio and trade charts \[#portfolio-and-trade-charts] `pf.plot()` draws a dashboard from named subplots. Built-in subplots include `orders`, `trades`, `trade_pnl`, `trade_signals`, `cumulative_returns`, `drawdowns`, `underwater`, `gross_exposure`, `allocations`, `cash`, `assets`, and `value`, and each can be configured through `subplot_settings`. Every subplot also exists as its own method, such as `pf.plot_cumulative_returns()`, `pf.plot_underwater()`, or `pf.plot_allocations()` for multi-asset weights over time. Records plot themselves too: `pf.trades.plot()` shows each trade from entry to exit with its profit, and `pf.drawdowns.plot(top_n=5)` shades the largest drawdowns. For returns, a calendar heatmap of monthly returns is one line: `pf.returns_acc.resample("M").ts_heatmap()`. ## Price, indicator, and signal charts \[#price-indicator-and-signal-charts] Data objects plot as candlesticks or OHLC bars with volume. Indicators and signals are added to the same figure by passing `fig`: ```python title="Overlay moving averages and crossover signals on candlesticks" >>> sub = data.loc["2023-04-01":"2023-08-31"] >>> fast = sub.close.rolling(10).mean() >>> slow = sub.close.rolling(30).mean() >>> entries = fast.vbt.crossed_above(slow) >>> exits = fast.vbt.crossed_below(slow) >>> fig = sub.plot(plot_volume=False) >>> fast.rename("SMA 10").vbt.plot(fig=fig) >>> slow.rename("SMA 30").vbt.plot(fig=fig) >>> entries.vbt.signals.plot_as_entries(fast, fig=fig) # (1) >>> exits.vbt.signals.plot_as_exits(fast, fig=fig) >>> fig.show() ``` 1. Draw each entry as a marker on the fast moving average. Bitcoin candlestick chart from April to August 2023 with 10 and 30 day moving averages and crossover entry and exit markers. [Figure data (JSON)](/assets/figures/features/analytics/interactive-charts-candlestick.5b9b028ce41e.json) Indicators built with VBT have a `plot` method with sensible defaults, and TA-Lib indicators plot according to their output types, for example as lines or histograms. ## Heatmaps and other generic plots \[#heatmaps-and-other-generic-plots] Any Series or DataFrame gets plotting methods through its accessor: line, scatter, bar, histogram, box, heatmap, and 3D volume plots. A parameter grid with three parameters becomes a heatmap with a slider for the third: ```python title="Explore three RSI strategy parameters with a heatmap and a slider" >>> btc = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2025-01-01") >>> rsi = btc.run("rsi", window=14).rsi >>> @vbt.parameterized(merge_func="concat") # (1) ... def sharpe(lower, upper, sl_stop): ... pf = vbt.PF.from_signals( ... btc, ... rsi.vbt.crossed_below(lower), ... rsi.vbt.crossed_above(upper), ... sl_stop=sl_stop, ... ) ... return pf.sharpe_ratio >>> sharpes = sharpe( ... vbt.Param([20, 25, 30, 35, 40]), ... vbt.Param([60, 65, 70, 75, 80]), ... vbt.Param([0.05, 0.1, 0.2]), ... ) >>> sharpes.vbt.heatmap(x_level="lower", y_level="upper", slider_level="sl_stop").show() ``` 1. Run the function for every combination of the parameters and concatenate the 75 results. Heatmap of Sharpe ratios for RSI entry and exit thresholds with a slider for the stop loss level. [Figure data (JSON)](/assets/figures/features/analytics/interactive-charts-heatmap-slider.53955f7134c5.json) When Plotly Express has a chart you need, call it from the accessor, for example `df.vbt.px.parallel_coordinates()`. Cross-validation splits have their own plots that show the training and test periods of every split. ## Customization \[#customization] Every plotting method takes `trace_kwargs` for the trace, `add_trace_kwargs` to place it in a subplot, and layout keywords for the figure. For example, `slow.vbt.plot(trace_kwargs=dict(line=dict(color="orange", dash="dash")), fig=fig)` draws one dashed orange line. `vbt.make_subplots` creates figures with several panels, and since the result is a regular Plotly figure, everything Plotly offers still works afterwards. Themes and defaults live in `vbt.settings.plotting`, for example `vbt.settings.set_theme("dark")` for dark charts. For markets that close overnight or on weekends, `fig.auto_rangebreaks(freq="1D")` adds Plotly range breaks for the missing time, so candles sit next to each other instead of leaving gaps. ## Charts that update with new data \[#charts-that-update-with-new-data] You can update the data in existing Plotly traces while keeping the figure's layout and styling. Connect those updates to a `DataUpdater` to refresh a candlestick chart as new bars arrive, or update lines for prices and indicators in a notebook widget. This is useful for watching the latest part of a series without creating a new chart each time. The [Data pipelines](/features/data/financial-data-pipelines/) page covers scheduled data updates, and [Live simulation](/features/backtesting/live-simulation/) covers continuing a portfolio on new bars. You can also save successive chart images as frames in a GIF with `imageio` to replay how a chart developed. ## Large data and output \[#large-data-and-output] A minute chart over several years has millions of points, which a browser draws slowly. With `plotly-resampler` installed, set `vbt.settings.plotting["use_resampler"] = True` and charts load a downsampled view that refines as you zoom. Alternatively, select a shorter range before plotting, or resample the portfolio first: `pf.resample("1D")` returns a daily portfolio with the same total return, and its charts draw a point per day. ## Share interactive charts and export images \[#share-interactive-charts-and-export-images] Figures show interactively in notebooks and browsers with `fig.show()`, as static images with `fig.show_png()` or `fig.show_svg()`, and save to files with `fig.write_image()` or `fig.write_html()`. Static images are rendered by Plotly's `kaleido` package, so install it first, and update it if an export hangs. The renderer can be set per figure or globally. An HTML export keeps zoom, hover labels, and legend controls, so someone else can explore the results in a browser without installing Python or VBT. Plotly includes the chart data and its JavaScript library in the file by default. See [Plotly's HTML export guide](https://plotly.com/python/interactive-html-export/) for saving a figure or combining several charts in one page. Use PNG or SVG when you need a fixed image for a report or presentation. # Patterns and event studies (/features/analytics/patterns-and-event-studies) When a price shape or a market event appeared before, what happened next? VBT searches price history for windows similar to a pattern, and turns any set of events into forward price paths you can summarize. Pattern recognition and event studies in Python take a few lines and run at compiled speed. ```python title="Find the 10 closest matches to the last 30 days and project the next 30" >>> close = vbt.YFData.pull("BTC-USD", start="2015-01-01", end="2025-01-01").close >>> pattern = close.iloc[-30:] >>> ranges = close.vbt.find_pattern( ... pattern=pattern.values, ... rescale_mode="rebase", # (1) ... min_similarity=0.75, ... ) >>> past = ranges.end_idx.values < len(close) - 60 # (2) >>> similarity = np.where(past, ranges.similarity.values, -np.inf) >>> top10 = ranges.apply_mask(similarity >= np.sort(similarity)[-10]) >>> top10.readable[["Start Index", "End Index", "Similarity"]].round(3) Start Index End Index Similarity 0 2015-07-20 00:00:00+00:00 2015-08-19 00:00:00+00:00 0.831 1 2016-07-07 00:00:00+00:00 2016-08-06 00:00:00+00:00 0.810 2 2017-08-18 00:00:00+00:00 2017-09-17 00:00:00+00:00 0.829 3 2017-11-08 00:00:00+00:00 2017-12-08 00:00:00+00:00 0.808 4 2019-03-04 00:00:00+00:00 2019-04-03 00:00:00+00:00 0.809 5 2022-05-18 00:00:00+00:00 2022-06-17 00:00:00+00:00 0.816 6 2022-08-28 00:00:00+00:00 2022-09-27 00:00:00+00:00 0.807 7 2022-11-29 00:00:00+00:00 2022-12-29 00:00:00+00:00 0.801 8 2023-04-21 00:00:00+00:00 2023-05-21 00:00:00+00:00 0.830 9 2024-08-11 00:00:00+00:00 2024-09-10 00:00:00+00:00 0.807 >>> after = top10.with_delta(30) # (3) >>> after.get_projections().iloc[-1].quantile([0.1, 0.5, 0.9]).round(3) 0.1 0.989 0.5 1.071 0.9 1.413 Name: 2025-01-30 00:00:00+00:00, dtype: float64 >>> after.plot_projections(plot_past_period=90).show() # (4) ``` 1. Compare shapes, not price levels: each window is scaled to start where the pattern starts. 2. Keep only matches whose next 30 days are fully known, which also drops the pattern itself. 3. Take the 30 days after each match. 4. Plot the last 90 days of price with the projected paths, their median, and quantile bands. Bitcoin price for the last 90 days of 2024 with the paths that followed the 10 most similar historical windows projected 30 days forward. [Figure data (JSON)](/assets/figures/features/analytics/patterns-projection.fb92fff9e081.json) Thirty days after the ten most similar windows, the median path was up 7.1%, and the 10th and 90th percentiles ranged from a 1.1% loss to a 41.3% gain. Ten past cases are a description of history, not a forecast, and the spread says as much as the median. ## Pattern search \[#pattern-search] `find_pattern` slides a window over the series, fits the pattern to each window, and scores the fit from 0 to 1. A pattern can be a list of points, such as `[5, 1, 3, 1, 2, 1]` for a descending triangle, or a piece of real price history. Each window is stretched to the pattern's length and scaled by `rescale_mode`: `"minmax"` compares shapes regardless of price range, and `"rebase"` compares percentage moves. With `max_window`, the search tries every window length up to that size, which finds the same shape at different speeds. Every extra length is another full search, so `row_select_prob` and `window_select_prob` can sample a share of the rows and lengths instead. The distance can be mean absolute or squared error, and `max_error` limits how far any single point may deviate. Matches come back as range records with a similarity score, which can be filtered, plotted, and turned into signals. A record's end index is the bar after the match, and `last_pd_mask` marks the bar where each match completes. The same score is also available as a rolling indicator, one value per bar: ```python title="Compute pattern similarity as an indicator" >>> patsim = vbt.PATSIM.run( ... close, ... pattern=pattern.values, ... window=30, ... rescale_mode="rebase", ... ) >>> patsim.similarity.iloc[-5:].round(3) Date 2024-12-27 00:00:00+00:00 0.682 2024-12-28 00:00:00+00:00 0.682 2024-12-29 00:00:00+00:00 0.730 2024-12-30 00:00:00+00:00 0.796 2024-12-31 00:00:00+00:00 1.000 Freq: D, Name: (array, 30, rebase), dtype: float64 ``` The last value is 1 because the pattern was taken from those 30 bars. !!! warning "Using matches as trading signals" By default, overlapping matches are resolved by keeping the most similar one, and a better match found later can remove an earlier one. That looks ahead. For signals, search with `overlap_mode="allowall"`, or use the rolling similarity indicator. A match is complete at the close of its last bar, so trade it on the next bar. ## Forward paths after events \[#forward-paths-after-events] Projections work for any event, not only patterns. Turn a signal mask into ranges that start at each event, and VBT collects the price path after every one of them, rebased to start at 1. Here are all opening gaps of 1% or more in SPY since 2010: ```python title="Study what SPY did in the five days after a gap down" >>> data = vbt.YFData.pull("SPY", start="2010-01-01", end="2025-01-01", auto_adjust=False) >>> gap_down = data.open / data.close.shift(1) - 1 <= -0.01 >>> events = gap_down.vbt.signals.delta_ranges(5, close=data.close) >>> paths = events.get_projections() >>> paths.shape # (1) (6, 176) >>> paths.iloc[-1].quantile([0.1, 0.5, 0.9]).round(3) 0.1 0.960 0.5 1.010 0.9 1.041 Name: 2025-01-05 00:00:00-05:00, dtype: float64 >>> print((paths.iloc[-1] > 1).mean().round(3)) 0.631 ``` 1. Six rows, the event bar and the five after it, and one column for each of the 176 gaps. Five days after a gap down, SPY was higher 63% of the time, with a median gain of 1.0%. The projections can be summarized as quantile bands or plotted as a fan of paths, and the same approach covers earnings dates, macro releases, or any other dated event. ### Bring your own event calendar \[#bring-your-own-event-calendar] If you already have a list of event dates, mark the corresponding bars and extract a path after each one. Here two sample dates pick out two-bar moves from a small price series: ```python title="Compare price moves after your own event dates" >>> event_close = pd.Series([100.0, 102.0, 103.0, 104.0, 200.0, 198.0, 196.0, 198.0], index=pd.date_range("2026-01-01", periods=8)) >>> event_dates = pd.to_datetime(["2026-01-01", "2026-01-05"]) >>> event_mask = pd.Series(event_close.index.isin(event_dates), index=event_close.index) >>> event_ranges = event_mask.vbt.signals.delta_ranges(2, close=event_close) >>> event_paths = event_ranges.get_projections(id_level="start_idx") >>> ((event_paths.iloc[-1] - 1) * 100).rename("Return [%]").round(1) start_idx 2026-01-01 3.0 2026-01-05 -2.0 Name: Return [%], dtype: float64 ``` The first path goes from 100 to 103, and the second from 200 to 196. Each starts at its own event close, so the different price levels become comparable percentage moves. Replace the sample dates with your calendar, aligned to the price bars, to compare earnings announcements, scheduled releases, or your own signal dates. The full `event_paths` DataFrame also lets you compare the route to each result, not just the final return. When an event suggests a trading rule, [Signal backtesting](/features/backtesting/signal-backtesting/) adds position sizing, exits, and trading costs. Use [Walk-forward and cross-validation](/features/optimization/time-series-cross-validation/) to test the rule on periods that were not used to choose it. ## Market structure events \[#market-structure-events] Many events are simple masks. A price gap is a comparison between the open and the previous close. Directional changes, which mark reversals of a minimum size, are confirmed only after the price has moved far enough, so a provisional turning point can change as new bars arrive. `vbt.PIVOTINFO` finds them from highs and lows with separate up and down thresholds, and reports both the last confirmed pivot and the latest provisional one with the bar where each occurred. Account for the confirmation delay before using pivots in a backtest. ## Plotting matches and projections \[#plotting-matches-and-projections] `ranges.plot()` shows each match on the price with its similarity, and `plot_projections()` draws the forward paths with optional quantile bands next to the current price. The [Patterns](#patterns) and [Projections](#projections) highlights below show both. !!! info "Tutorial" The members-only [Patterns and projections](https://members.vectorbt.pro/tutorials/patterns-and-projections/patterns/) tutorial covers fitting, distance measures, and pattern-based signals in depth. ## Patterns \[#patterns] New in 1.5.0 ✅ Patterns are distinctive formations created by price movements on a chart and are central to technical analysis. There are now new dedicated functions and classes for detecting patterns of any complexity in any type of time series data. The idea is simple: fit a pattern to align with the scale and period of your selected data window, then compute the element-wise distance between them to get a single similarity score. You can adjust the threshold for this score to decide above which value a data window should be marked as "matched." Thanks to Numba, this operation can be performed hundreds of thousands of times per second! 🔎 ```python title="Find and plot a descending triangle pattern" >>> data = vbt.YFData.pull("BTC-USD") >>> data.hlc3.vbt.find_pattern( ... pattern=[5, 1, 3, 1, 2, 1], ... window=100, ... max_window=700, ... ).loc["2017":"2019"].plot().show() ``` Descending triangle pattern matches in BTC-USD from 2017 through 2019. [Figure data (JSON)](/assets/figures/features/analysis/patterns.0fd1d09b4584.json) !!! info "Tutorial" Learn more in the [Patterns and projections](/tutorials/patterns-and-projections) tutorial. ## Projections \[#projections] New in 1.5.0 ✅ There are cleaner ways to analyze events and their impact on price than conventional backtesting. Meet projections! 👋 Not only can they help you assess event performance visually and quantitatively, but they can also project events into the future to support trading. This is done by extracting the price range after each event, collecting all these price ranges into a multidimensional array, and then deriving confidence intervals and other useful statistics from that array. When combined with patterns, these tools are a quantitative analyst's dream! 🌟 ```python title="Find occurrences of the price moving similarly to the last week and project them" >>> data = vbt.YFData.pull("ETH-USD") >>> pattern_ranges = data.hlc3.vbt.find_pattern( ... pattern=data.close.iloc[-7:], ... rescale_mode="rebase" ... ) >>> delta_ranges = pattern_ranges.with_delta(7) >>> fig = data.iloc[-7:].plot(plot_volume=False) >>> delta_ranges.plot_projections(fig=fig) >>> fig.show() ``` ETH-USD last-week pattern matches with projected confidence bands. [Figure data (JSON)](/assets/figures/features/analysis/projections.0b45eca04db2.json) !!! info "Tutorial" Learn more in the [Patterns and projections](/tutorials/patterns-and-projections) tutorial. # Performance and risk metrics (/features/analytics/performance-metrics) How good is a backtest result, and compared with what? VBT computes backtest performance metrics such as total return, Sharpe, Sortino, Calmar, drawdowns, and benchmark statistics in Python for one portfolio or for thousands of them at once, and works on any return series, not only on its own backtests. ```python title="Get a full report for one backtest" >>> data = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2025-01-01") >>> fast = data.close.rolling(20).mean() >>> slow = data.close.rolling(50).mean() >>> pf = vbt.PF.from_signals( ... data, ... fast.vbt.crossed_above(slow), ... fast.vbt.crossed_below(slow), ... fees=0.001, ... ) >>> pf.stats() Start Index 2020-01-01 00:00:00+00:00 End Index 2024-12-31 00:00:00+00:00 Total Duration 1827 days 00:00:00 Start Value 100.0 Min Value 95.605003 Max Value 787.725311 End Value 693.387328 Total Return [%] 593.387328 Benchmark Return [%] 1197.596406 Position Coverage [%] 53.858785 Max Gross Exposure [%] 100.0 Max Drawdown [%] 58.610935 Max Drawdown Duration 1126 days 00:00:00 Total Orders 37 Total Fees Paid 15.776306 Total Trades 19 Win Rate [%] 33.333333 Best Trade [%] 381.070734 Worst Trade [%] -19.099978 Avg Winning Trade [%] 83.748564 Avg Losing Trade [%] -8.434649 Avg Winning Trade Duration 93 days 08:00:00 Avg Losing Trade Duration 27 days 04:00:00 Profit Factor 1.754588 Expectancy 20.504842 Sharpe Ratio 1.083913 Calmar Ratio 0.805908 Omega Ratio 1.249536 Sortino Ratio 1.700246 dtype: object ``` The same call works on a whole grid. Here are 100 moving average pairs, one row each: ```python title="Compare selected metrics across 100 backtests" >>> fast_w, slow_w = np.meshgrid(np.arange(5, 55, 5), np.arange(60, 260, 20)) >>> fast = vbt.MA.run(data.close, window=fast_w.ravel(), short_name="fast") >>> slow = vbt.MA.run(data.close, window=slow_w.ravel(), short_name="slow") >>> grid_pf = vbt.PF.from_signals( ... data, ... fast.ma_crossed_above(slow), ... fast.ma_crossed_below(slow), ... fees=0.001, ... ) >>> metrics = ["total_return", "sharpe_ratio", "max_dd", "total_trades"] >>> grid_stats = grid_pf.stats(metrics) # (1) >>> grid_stats.sort_values("Sharpe Ratio", ascending=False).head() Total Return [%] Sharpe Ratio Max Drawdown [%] Total Trades fast_window slow_window 5 120 1744.634182 1.510302 38.569486 9 100 1577.778405 1.467615 41.260714 12 25 100 1315.741883 1.405711 40.937689 8 15 100 1241.937564 1.372806 38.948698 9 10 100 1244.107822 1.365325 41.252897 10 ``` 1. With several columns, `stats` returns one row per column. Pass `agg_func=np.mean` to average each metric across columns instead. The table makes it easy to compare return, drawdown, and trade count alongside Sharpe. To take the best rows into further testing, see [Robustness and overfitting](/features/optimization/robustness-and-overfitting/). ## Returns \[#returns] Every metric starts from a return series. For a portfolio, `pf.returns` is the bar-by-bar change in value, with deposits and withdrawals taken out so they do not count as performance. `pf.asset_returns` ignores cash and measures only the invested part. Convert a price or value series with `series.vbt.to_returns()`, then use the returns series' `vbt.returns` accessor for cumulative, total, and annualized returns, volatility, and the ratios on this page. Annualization needs two numbers: how long a bar is and how long a year is. The year defaults to 365 days, which fits markets that trade every day. For stocks that trade about 252 days a year, set `year_freq`, or let VBT count the bars per year with `"auto"`: ```python title="Annualize stock returns with the right year length" >>> spy = vbt.YFData.pull("SPY", start="2020-01-01", end="2025-01-01") >>> rets = spy.close.vbt.to_returns() >>> print(round(rets.vbt.returns(freq="1D").sharpe_ratio(), 3)) 0.892 >>> print(round(rets.vbt.returns(freq="1D", year_freq="252 days").sharpe_ratio(), 3)) 0.741 >>> print(round(rets.vbt.returns(freq="1D", year_freq="auto").sharpe_ratio(), 3)) 0.741 ``` Set it once for a session with `vbt.settings.returns.year_freq`. ### Analyze an external equity curve \[#analyze-an-external-equity-curve] You can use the same metrics on an equity curve exported from another backtester, or on returns you have already calculated in Pandas. Here is a small account-value series with no deposits or withdrawals: ```python title="Measure returns from an equity curve without creating a portfolio" >>> equity = pd.Series([102.0, 101.0, 104.0, 103.0, 106.0], index=pd.date_range("2026-01-05", periods=5)) >>> external_returns = equity.vbt.to_returns(init_value=100) >>> external_acc = external_returns.vbt.returns(freq="1D", year_freq="252 days") >>> pd.Series({ ... "Total return [%]": external_acc.total() * 100, ... "Max drawdown [%]": external_acc.max_drawdown() * 100, ... }).round(2) Total return [%] 6.00 Max drawdown [%] -0.98 dtype: float64 ``` The starting value of 100 includes the first day's gain to 102. The final value of 106 gives a 6% total return. The same accessor works on a DataFrame of return series, so results from several strategies can be compared without rebuilding their trades. ## Risk-adjusted ratios \[#risk-adjusted-ratios] The Sharpe, Sortino, Calmar, Omega, and information ratios, value at risk, conditional value at risk, tail ratio, skew, and kurtosis are all available as properties with defaults and as methods that take arguments, such as `pf.get_sharpe_ratio(risk_free=...)`. | Question | Metrics to inspect | | ------------------------------------------------------------------ | ------------------------------------------- | | How much return did the strategy earn relative to its variability? | Sharpe ratio | | How much return did it earn relative to downside variation? | Sortino ratio and downside risk | | How does annualized return compare with the worst drawdown? | Calmar ratio | | What do the worst bar returns look like? | Value at risk and conditional value at risk | For the depth, duration, and recovery of individual losses, see [Drawdown analysis](/features/analytics/drawdown-analysis/). The Sharpe ratio is the mean excess bar return divided by its standard deviation, times the square root of the bars per year. It is not the annualized return divided by the annualized volatility, which compounds first and gives a different number. !!! info "Set an annual risk-free rate" Pass an annual rate, for example `pf.get_sharpe_ratio(risk_free=0.04)` for 4%. VBT converts it to a per-bar return using the configured frequency and year length. For a changing rate, subtract an aligned series of per-bar risk-free returns from your strategy returns, then calculate Sharpe with `risk_free=0`. Bars without a position have a return of zero, and those zeros stay in the calculation, because waiting in cash is part of the strategy. To measure only the time in the market, set those returns to `NaN` before computing the ratio. Returns of individual trades cannot replace bar returns in the Sharpe ratio, because trades have different lengths and cannot be annualized. ## Benchmark comparison \[#benchmark-comparison] Every portfolio has a benchmark. By default it is buy-and-hold of the traded assets, and `bm_close` sets any other price series, as in the [Benchmark](#benchmark) highlight below. The returns accessor then compares the two: ```python title="Compare the crossover strategy with holding Bitcoin" >>> ret_acc = pf.returns_acc >>> pd.Series({ ... "alpha": ret_acc.alpha(), ... "beta": ret_acc.beta(), ... "information ratio": ret_acc.information_ratio(), ... "up capture": ret_acc.up_capture_ratio(), ... "down capture": ret_acc.down_capture_ratio(), ... }).round(3) alpha 0.142 beta 0.491 information ratio -0.027 up capture 0.127 down capture 0.883 dtype: float64 ``` The strategy carries about half of Bitcoin's market exposure. It captured little of the upside and most of the downside relative to holding, which is why it returned half as much. ## Rolling metrics \[#rolling-metrics] A single number hides how performance changes over time. Every ratio has a rolling version over a window of bars: ```python title="Plot a rolling one-year Sharpe ratio against the benchmark" >>> rolling = pd.DataFrame({ ... "Strategy": pf.returns_acc.rolling_sharpe_ratio(365), ... "Benchmark": pf.bm_returns.vbt.returns(freq="1D").rolling_sharpe_ratio(365), ... }) >>> rolling.vbt.plot().show() ``` Rolling one-year Sharpe ratio of a Bitcoin moving average strategy and of holding Bitcoin from 2020 to 2024. [Figure data (JSON)](/assets/figures/features/analytics/performance-metrics-rolling-sharpe.856e51fa45cc.json) ## Attribution and regimes \[#attribution-and-regimes] The return of a group is the return of its combined value, not the sum of its members' returns. To split it by asset, weight each column's return by its share of the group value on the bar before, cash included. To compare market regimes, label each bar with its regime, group the returns by label, and compute the metrics on each group through the returns accessor: ```python title="Compare Sharpe ratios in uptrends and downtrends" >>> sma200 = data.close.rolling(200).mean() >>> regime = pd.Series( ... np.where(data.close > sma200, "uptrend", "downtrend"), ... index=data.index, ... name="regime", ... )[sma200.notna()] # (1) >>> def sharpe(returns): ... return returns.vbt.returns(freq="1D").sharpe_ratio() >>> pd.DataFrame({ ... "bars": regime.value_counts(), ... "strategy": pf.returns.groupby(regime).apply(sharpe), ... "buy and hold": pf.bm_returns.groupby(regime).apply(sharpe), ... }).round(2) bars strategy buy and hold regime downtrend 617 -1.3 -1.14 uptrend 1011 2.0 2.67 ``` 1. Skip the first 199 bars, where the 200-day average does not exist yet. The strategy earned its returns in uptrends and lost in downtrends, and holding had the better Sharpe ratio in both. A split like this shows whether a rule adds anything beyond the trend of the market itself. ## Statistics reports \[#statistics-reports] `stats` builds the report from a list of metrics. Choose the ones you need, which also makes it faster on large grids, or add your own next to the built-in ones: ```python title="Add a custom metric to the report" >>> pf.stats([ ... "total_return", ... "sharpe_ratio", ... ("trades_per_year", dict( ... title="Trades per Year", ... calc_func=lambda self: self.trades.count() / (len(self.wrapper.index) / 365), ... )), ... ]) Total Return [%] 593.387328 Sharpe Ratio 1.083913 Trades per Year 3.79584 dtype: object ``` Durations in a report count bars times the frequency, not calendar time. Four daily bars spread over nine calendar days report a total duration of 4 days, so weekends and holidays that are not in the data are not counted. Settings pass through to every metric, for example `pf.stats(settings=dict(use_asset_returns=True))` to compute the return metrics on asset returns. The same reports exist for returns (`returns_stats`), trades, drawdowns, and orders, and `stats` on a grouped portfolio reports per group. For very large grids, compute `stats` on chunks of columns in parallel with `vbt.chunked`. ## QuantStats \[#quantstats] With QuantStats installed, `pf.qs` exposes its functions, plots, and reports with the portfolio's returns, benchmark, and frequency already filled in. For example, `pf.qs.sharpe()` returns the QuantStats version of the ratio, and `pf.qs.html_report()` builds its full tearsheet. The adapter also translates the risk-free rate and annualization settings for QuantStats. ## Benchmark \[#benchmark] New in 1.0.4 ✅ The benchmark can now be easily set for your entire portfolio. ```python title="Compare Microsoft to S&P 500" >>> data = vbt.YFData.pull(["SPY", "MSFT"], start="2010", missing_columns="drop") >>> pf = vbt.PF.from_holding( ... close=data.data["MSFT"]["Close"], ... bm_close=data.data["SPY"]["Close"] ... ) >>> pf.plot_cumulative_returns().show() ``` Cumulative returns of Microsoft compared with the S\&P 500 benchmark. [Figure data (JSON)](/assets/figures/features/analysis/benchmark.c1d30a1b0d0b.json) # Records and mapped arrays (/features/analytics/records-and-mapped-arrays) Orders, trades, drawdowns, and pattern matches are events, not time series: most bars have none, and some have several. VBT stores such sparse events and intervals as records with a column map, so you can filter, reduce, regroup, and plot them across thousands of columns without building a dense array for every field. ```python title="Find the order with the worst fill among 20,000 orders in 1,000 columns" >>> close = vbt.GBMOHLCData.pull("S", start="2024-01-01", end="2025-01-01", seed=42).close >>> np.random.seed(42) >>> slippage = pd.DataFrame( ... np.random.uniform(0, 0.005, size=(len(close), 1000)), ... index=close.index, ... ) >>> pf = vbt.PF.from_random_signals(close, n=10, seed=42, slippage=slippage) # (1) >>> orders = pf.orders >>> print(orders.count().sum()) 20000 >>> fill_vs_close = orders.price.values / close.values[orders.idx.values] - 1 >>> cost = orders.map_array( # (2) ... np.where(orders.side.values == 0, fill_vs_close, -fill_vs_close) ... ) >>> cost.max().describe().round(4) # (3) count 1000.0000 mean 0.0048 std 0.0002 min 0.0035 25% 0.0047 50% 0.0048 75% 0.0049 max 0.0050 Name: max, dtype: float64 >>> readable = cost.to_readable() >>> readable.loc[readable["Value"].idxmax()] Id 1 Column 165 Index 2024-03-12 00:00:00+00:00 Value 0.004999 Name: 3301, dtype: object ``` 1. One synthetic price, 1,000 columns with random slippage, and 10 random entries and exits per column. 2. One value per order: how much worse than the close it filled. 3. Reduce the 20,000 values to the worst fill of each column, then summarize the 1,000 results. Twenty thousand orders take twenty thousand rows, not 366 bars times 1,000 columns times every field. The worst fill was the second order in column 165, on March 12, 2024. ## Records \[#records] A record array is a structured NumPy array, one row per event, with fields such as the column, the bar, the price, and the size. Records classes wrap it with the time index and column labels of the data, so the same object knows both the raw positions and their dates. Orders, logs, trades, positions, drawdowns, and pattern matches are all records. Ranges are records with a start and an end. Any boolean mask becomes ranges, which turns periods into objects you can measure: ```python title="Turn overbought periods into ranges" >>> btc = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2025-01-01") >>> rsi = btc.run("rsi", window=14).rsi.rename("RSI") >>> overbought = vbt.Ranges.from_array(rsi > 70) >>> print(overbought.count(), overbought.coverage.round(3)) # (1) 42 0.128 >>> longest = overbought.apply_mask(overbought.duration.top_n_mask(3)) >>> longest.readable[["Start Index", "End Index", "Status"]] Start Index End Index Status 0 2023-01-11 00:00:00+00:00 2023-01-30 00:00:00+00:00 Closed 1 2023-10-20 00:00:00+00:00 2023-11-14 00:00:00+00:00 Closed 2 2024-11-06 00:00:00+00:00 2024-11-25 00:00:00+00:00 Closed >>> longest.duration.values array([19, 25, 19]) ``` 1. 42 separate overbought periods covering 12.8% of the bars. Records can also be built from your own data. A DataFrame or a list of dictionaries with dates and symbols becomes typed records, which is how [index records](/features/backtesting/backtesting-engine/#index-records) pass sparse orders into a simulation. ## Mapped arrays \[#mapped-arrays] A mapped array holds one value per record together with the record's column and bar. Every field of a records object is available as one, for example `pf.trades.pnl` or `pf.drawdowns.duration`, and `map_array` attaches any values you compute. Mapped arrays reduce per column or group with `mean`, `max`, `idxmax`, `count`, or any compiled function, filter with masks such as `top_n_mask`, and convert to pandas with `to_pd` or `to_readable` when you need a table. `to_pd` places each value at its record's bar. When several records of one column share a bar, it keeps the latest and warns. Pass `reduce_func_nb`, such as `"sum"`, to combine them, `repeat_index=True` to keep all of them, or `ignore_index=True` to stack the values without dates. This lets you ask more specific questions of a backtest: how long did losing trades last when they barely moved into profit, or which orders had the largest costs? Filter the records or their mapped values, then run the same reductions on the selected events. The results keep their asset and parameter labels. [Trade analytics](/features/analytics/trade-analytics/) shows this workflow for long and short trades and their price excursions. ## Indexing and regrouping \[#indexing-and-regrouping] Records stay sorted by column, and a column map remembers where each column's records start. Selecting a column or a group, as in `pf.trades["BTC-USD"]`, therefore does not scan all records. Grouping can change after the fact: the same trade records report per asset with `group_by=False` or per strategy with a different grouping. For a chronological view across columns, sort the readable table by its index column. For example, report three assets separately, then combine A and B into one research group: ```python title="Regroup trade profits without rerunning the backtest" >>> group_close = pd.DataFrame({"A": [10.0, 11.0, 12.0], "B": [20.0, 18.0, 19.0], "C": [30.0, 33.0, 36.0]}, index=pd.date_range("2026-01-01", periods=3)) >>> group_pf = vbt.PF.from_orders(group_close, size=np.array([1, 0, -1])[:, None]) >>> trade_pnl = group_pf.trades.status_closed.pnl >>> trade_pnl.sum() A 2.0 B -1.0 C 6.0 Name: sum, dtype: float64 >>> trade_pnl.sum(group_by=["Group 1", "Group 1", "Group 2"]) group Group 1 1.0 Group 2 6.0 Name: sum, dtype: float64 ``` The same records now answer a different reporting question. You can group by sectors, strategy families, or another label for each column. To have assets share capital while the simulation runs, use [shared cash](/features/backtesting/portfolio-accounting/#shared-cash). ## Custom record classes \[#custom-record-classes] Your own events can have their own class. Define a NumPy dtype with the fields you need, attach titles and value mappings so readable tables show names instead of codes, and subclass `vbt.Records` or `vbt.Ranges` to get filters, mapped fields, statistics, and plots for free. Records save to disk and load back like any other VBT object. Inside Numba code, read record fields with brackets, such as `record["price"]`, which works whether compilation is on or off. ## OHLC-native classes \[#ohlc-native-classes] New in 1.3.0 ✅ Previously, OHLC data was used for simulation, but only the close price was analyzed. Now, most classes let you track all OHLC data for more accurate quantitative and qualitative analysis. ```python title="Plot trades of a random portfolio" >>> data = vbt.YFData.pull("BTC-USD", start="2020-01", end="2020-03") >>> pf = vbt.PF.from_random_signals( ... open=data.open, ... high=data.high, ... low=data.low, ... close=data.close, ... n=10, ... seed=42 ... ) >>> pf.trades.plot().show() ``` BTC-USD OHLC with random portfolio trade entries and exits. [Figure data (JSON)](/assets/figures/features/analysis/ohlc-native-classes.4ffa9efd631b.json) # Trade analytics (/features/analytics/trade-analytics) Which trades made the money, and were the exits any good? VBT keeps every trade as a record with its entry, exit, profit, and excursions, so trade analysis in Python covers win rate, profit factor, expectancy, MAE and MFE, and the edge ratio for one backtest or thousands. ```python title="Check whether a 5% stop would have cut the winners" >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"], start="2018-01-01", end="2025-01-01") >>> fast = data.close.rolling(20).mean() >>> slow = data.close.rolling(50).mean() >>> pf = vbt.PF.from_signals( ... data, ... fast.vbt.crossed_above(slow), ... fast.vbt.crossed_below(slow), ... fees=0.001, ... ) >>> trades = pf.trades.status_closed # (1) >>> metrics = ["total_records", "win_rate", "profit_factor", "expectancy", "sqn"] >>> trades.stats(metrics, agg_func=None) Total Records Win Rate [%] Profit Factor Expectancy SQN symbol BTC-USD 26 30.769231 1.632437 13.422132 0.669763 ETH-USD 23 52.173913 1.867036 33.244891 0.803366 >>> mae = trades.mae_returns.values # (2) >>> returns = trades.returns.values >>> pnl = trades.pnl.values >>> cut = (returns > 0) & (mae < -0.05) >>> pd.Series({ ... "winners": (returns > 0).sum(), ... "winners that first fell over 5%": cut.sum(), ... "their profit": pnl[cut].sum().round(2), ... "profit of all winners": pnl[returns > 0].sum().round(2), ... }) winners 20.00 winners that first fell over 5% 9.00 their profit 1306.13 profit of all winners 2547.29 dtype: float64 >>> trades.plot_mae_returns(column="BTC-USD").show() ``` 1. Only trades that have been closed. The last trade of each asset may still be open. 2. The worst return each trade reached before it closed. Scatter plot of maximum adverse excursion against final return for Bitcoin moving average crossover trades. [Figure data (JSON)](/assets/figures/features/analytics/trade-analytics-mae.23f245cf1a10.json) Nine of the 20 winning trades first fell more than 5% below their entry, and they brought in half of the winning profit. A 5% stop would have closed them at a loss. The scatter shows the same thing for every Bitcoin trade: how far it went against the position compared with how it ended. ## Trades and positions \[#trades-and-positions] The same orders can be grouped into trades in three ways, and each answers a different question: | Records | One record per | Use it for | | ------------------------------ | --------------------------------------- | ----------------------- | | `pf.entry_trades` | Order that opens or adds to a position | Judging entries | | `pf.exit_trades` (`pf.trades`) | Order that reduces or closes a position | Judging exits | | `pf.positions` | Position from open to flat | Judging whole positions | With a single entry and exit they are identical. With scaling in or out they differ: ```python title="Split two buys and two sells into trades and positions" >>> index = pd.date_range("2026-01-01", periods=4) >>> close = pd.Series([10.0, 11.0, 12.0, 13.0], index=index) >>> pf = vbt.PF.from_orders(close, size=[1, 1, -1, -1]) >>> cols = ["Entry Index", "Exit Index", "Size", "PnL"] >>> pf.entry_trades.readable[cols] Entry Index Exit Index Size PnL 0 2026-01-01 2026-01-04 1.0 2.5 1 2026-01-02 2026-01-04 1.0 1.5 >>> pf.exit_trades.readable[cols] Entry Index Exit Index Size PnL 0 2026-01-01 2026-01-03 1.0 1.5 1 2026-01-01 2026-01-04 1.0 2.5 >>> pf.positions.readable[cols] Entry Index Exit Index Size PnL 0 2026-01-01 2026-01-04 2.0 4.0 ``` Entry trades measure each entry against the average exit price, and exit trades measure each exit against the average entry price. Records carry the column labels of your inputs, so trades of a parameter grid can be grouped by parameter, and `direction_long` or `direction_short` selects one side. `pf.trade_history` joins orders with all three views, as the [Trade history](#trade-history) highlight below shows. It has one row per order, and each row carries the profit of that order's entry trade or exit trade, so in the example above its `PnL` column adds up to 8, twice the real profit. Compute statistics from one of the three record types instead. ## Trade metrics \[#trade-metrics] `trades.stats()` reports win rate, best and worst trade, average win and loss, winning and losing streaks, profit factor, expectancy, and the system quality number (SQN). Every metric is also a property, such as `trades.profit_factor`. A trade's return is its profit relative to the money committed at entry, not to the account. A $5 profit on a $100 position is 5%, whatever the account size. Profit factor, expectancy, and SQN are computed from profit by default, and `use_returns=True` computes them from returns instead, which removes the effect of position size. Profit factor divides the total profit of winning trades by the total loss of losing trades. A value of 2 means the winners made twice what the losers lost. Expectancy is the average profit per trade in the account's currency, so an expectancy of 10 means an average gain of 10 per trade in the selected records. Read these alongside win rate to see whether the size of the winners makes up for the losers. Measures that need information the records do not store, such as R-multiples, are a few lines on top of them. With a stop two ATRs away, a trade's profit divided by its initial risk gives its R-multiple: ```python title="Express trade results as multiples of the initial risk" >>> stop_dist = 2 * data.run("atr", window=14).atr >>> pf = vbt.PF.from_signals( ... data, ... fast.vbt.crossed_above(slow), ... fast.vbt.crossed_below(slow), ... sl_stop=stop_dist, ... delta_format="absolute", ... fees=0.001, ... ) >>> trades = pf.trades.status_closed >>> entry_risk = stop_dist.values[trades.entry_idx.values, trades.col.values] >>> risk = entry_risk * trades.size.values >>> pd.Series(trades.pnl.values / risk).describe().round(2) count 50.00 mean 3.19 std 14.88 min -1.05 25% -1.02 50% -1.01 75% 1.05 max 77.89 dtype: float64 ``` Most losers stop out close to one unit of risk, while a few winners return many times it, the typical profile of a trend-following system. ## Compare long and short trades \[#compare-long-and-short-trades] You can run the same analysis on a subset of trades without rerunning the backtest. Here four trades give the long and short sides the same win rate, but very different results: ```python title="Compare both sides of a strategy from one simulation" >>> side_close = pd.Series([100.0, 120.0, 100.0, 105.0, 100.0, 95.0, 100.0, 98.0], index=pd.date_range("2026-01-01", periods=8)) >>> side_pf = vbt.PF.from_orders(side_close, size=[1, -1, -1, 1, 1, -1, -1, 1], init_cash=1000) >>> side_trades = side_pf.trades.status_closed >>> side_metrics = ["total_records", "win_rate", "profit_factor", "expectancy"] >>> pd.DataFrame({ ... "Long": side_trades.direction_long.stats(side_metrics), ... "Short": side_trades.direction_short.stats(side_metrics), ... }).round(2) Long Short Total Records 2 2 Win Rate [%] 50.0 50.0 Profit Factor 4.0 0.4 Expectancy 7.5 -1.5 ``` The long trades made 20 and lost 5, while the short trades lost 5 and made 2. Separating the sides shows where the profit came from. The filtered records still support the same trade plots and excursion analysis. For other ways to filter and group records, see [Records and mapped arrays](/features/analytics/records-and-mapped-arrays/). ## Excursions \[#excursions] Maximum adverse excursion (MAE) is the worst point a trade reached, and maximum favorable excursion (MFE) the best. Both are available in price units and as returns, with the bar where they occurred. Comparing them with the final result shows whether stops are too tight and whether exits leave profit behind. Expanding versions track both bar by bar from the entry, as the [Expanding trade metrics](#expanding-trade-metrics) highlight below shows, and the [MAE and MFE](#mae-and-mfe) highlight compares a portfolio with and without a stop. Use these results to choose stop or target levels to test, then simulate those exits with [Stop loss and take profit](/features/backtesting/stop-loss-and-take-profit/). Compare the new trade distribution and portfolio results to see what the change did to both winners and losers. ## Entry quality \[#entry-quality] The edge ratio divides the average volatility-adjusted MFE by the average volatility-adjusted MAE. Above one, entries tend to move in the trade's favor more than against it. The running edge ratio computes it for every holding period, so you can see how many bars an entry needs to show its edge, and compare it with random entries, as in the [Edge ratio](#edge-ratio) highlight. ## Trade plots \[#trade-plots] `trades.plot()` draws each trade from entry to exit, shaded by profit or loss. `pf.plot_trade_signals()` marks long and short entries and exits separately, and `plot_pnl`, `plot_returns`, `plot_mae`, and `plot_mfe` show trade-level results as scatter plots. The figures are regular Plotly figures, so hover labels can carry any extra information, such as indicator values at entry. ## Expanding trade metrics \[#expanding-trade-metrics] New in 1.11.0 ✅ Regular metrics like MAE and MFE only represent the final point of each trade. But what if you want to see how these metrics develop during the trade? You can now analyze expanding trade metrics as DataFrames! ```python title="Visualize the expanding MFE using projections" >>> data = vbt.YFData.pull("BTC-USD") >>> pf = vbt.PF.from_random_signals(data, n=50, tp_stop=0.5, seed=42) >>> pf.trades.plot_expanding_mfe_returns().show() ``` Expanding maximum favorable excursion return projections for BTC-USD trades. [Figure data (JSON)](/assets/figures/features/analysis/expanding-mfe-returns.a7f673138861.json) ## Trade signals \[#trade-signals] New in 1.8.2 ✅ New trade plotting method that separates entry and exit trades into long entries, long exits, short entries, and short exits. It supports different styles for positions. ```python title="Plot trade signals of a Bollinger Bands strategy" >>> data = vbt.YFData.pull("BTC-USD") >>> bb = data.run("bbands") >>> long_entries = data.hlc3.vbt.crossed_above(bb.upper) & (bb.bandwidth < 0.1) >>> long_exits = data.hlc3.vbt.crossed_below(bb.upper) & (bb.bandwidth > 0.5) >>> short_entries = data.hlc3.vbt.crossed_below(bb.lower) & (bb.bandwidth < 0.1) >>> short_exits = data.hlc3.vbt.crossed_above(bb.lower) & (bb.bandwidth > 0.5) >>> pf = vbt.PF.from_signals( ... data, ... long_entries=long_entries, ... long_exits=long_exits, ... short_entries=short_entries, ... short_exits=short_exits ... ) >>> pf.plot_trade_signals().show() ``` BTC-USD OHLC with long and short Bollinger Bands strategy trade signals. [Figure data (JSON)](/assets/figures/features/analysis/trade-signals.c1d8660ae356.json) ## Edge ratio \[#edge-ratio] New in 1.8.1 ✅ [Edge ratio](https://www.buildalpha.com/eratio/) is a unique metric for quantifying entry profitability. Unlike most performance metrics, the edge ratio accounts for both open profits and losses. This can help you find better trade exits. ```python title="Compare the edge ratio of an EMA crossover to a random strategy" >>> data = vbt.YFData.pull("BTC-USD") >>> fast_ema = data.run("ema", 10, hide_params=True) >>> slow_ema = data.run("ema", 20, hide_params=True) >>> entries = fast_ema.real_crossed_above(slow_ema) >>> exits = fast_ema.real_crossed_below(slow_ema) >>> pf = vbt.PF.from_signals(data, entries, exits, direction="both") >>> rand_pf = vbt.PF.from_random_signals(data, n=pf.orders.count() // 2, seed=42) # (1) >>> fig = pf.trades.plot_running_edge_ratio( ... trace_kwargs=dict(line_color="limegreen", name="Edge Ratio (S)") ... ) >>> fig = rand_pf.trades.plot_running_edge_ratio( ... trace_kwargs=dict(line_color="mediumslateblue", name="Edge Ratio (R)"), ... fig=fig ... ) >>> fig.show() ``` 1. The random strategy should have a similar number of orders to allow comparison. Running edge ratios for EMA crossover and random BTC-USD strategies. [Figure data (JSON)](/assets/figures/features/analysis/running-edge-ratio.b9bb905dcad9.json) ## Trade history \[#trade-history] New in 1.8.1 ✅ Trade history is a human-readable DataFrame listing orders, extended with useful details about entry trades, exit trades, and positions. ```python title="Get the trade history of a random portfolio with one signal" >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"], missing_index="drop") >>> pf = vbt.PF.from_random_signals( ... data, ... n=1, ... seed=42, ... run_kwargs=dict(hide_params=True), ... tp_stop=0.5, ... sl_stop=0.1 ... ) >>> pf.trade_history Order Id Column Signal Index Creation Index \ 0 0 BTC-USD 2016-02-20 00:00:00+00:00 2016-02-20 00:00:00+00:00 1 1 BTC-USD 2016-02-20 00:00:00+00:00 2016-06-12 00:00:00+00:00 2 0 ETH-USD 2019-05-25 00:00:00+00:00 2019-05-25 00:00:00+00:00 3 1 ETH-USD 2019-05-25 00:00:00+00:00 2019-07-15 00:00:00+00:00 Fill Index Side Type Stop Type Size Price \ 0 2016-02-20 00:00:00+00:00 Buy Market None 0.228747 437.164001 1 2016-06-12 00:00:00+00:00 Sell Market TP 0.228747 655.746002 2 2019-05-25 00:00:00+00:00 Buy Market None 0.397204 251.759872 3 2019-07-15 00:00:00+00:00 Sell Market SL 0.397204 226.583885 Fees PnL Return Direction Status Entry Trade Id Exit Trade Id \ 0 0.0 50.0 0.5 Long Closed 0 -1 1 0.0 50.0 0.5 Long Closed -1 0 2 0.0 -10.0 -0.1 Long Closed 0 -1 3 0.0 -10.0 -0.1 Long Closed -1 0 Position Id 0 0 1 0 2 0 3 0 ``` ## MAE and MFE \[#mae-and-mfe] New in 1.3.0 ✅ [Maximum Adverse Excursion (MAE)](https://analyzingalpha.com/maximum-adverse-excursion) helps you see the maximum loss taken during a trade, also known as the maximum drawdown of the position. [Maximum Favorable Excursion (MFE)](https://analyzingalpha.com/maximum-favorable-excursion) shows the highest profit reached during a trade. Analyzing MAE and MFE statistics can help you improve your exit strategies. ```python title="Analyze the MAE of a random portfolio without SL" >>> data = vbt.YFData.pull("BTC-USD") >>> pf = vbt.PF.from_random_signals(data, n=50, seed=42) >>> pf.trades.plot_mae_returns().show() ``` Maximum adverse excursion versus return for BTC-USD trades without stop loss. [Figure data (JSON)](/assets/figures/features/analysis/mae-without-stop-loss.45e6b1c85f4d.json) ```python title="Analyze the MAE of a random portfolio with SL" >>> pf = vbt.PF.from_random_signals(data, n=50, sl_stop=0.1, seed=42) >>> pf.trades.plot_mae_returns().show() ``` Maximum adverse excursion versus return for BTC-USD trades with stop loss. [Figure data (JSON)](/assets/figures/features/analysis/mae-with-stop-loss.904e9d91750d.json) # AI research assistant (/features/ai/ai-research-assistant) Can an assistant that knows VBT help you write and fix research code? ChatVBT is an AI assistant for quant research in Python that brings VBT's documentation, code examples, and community discussions into the conversation. Ask how a feature works, get help adapting a backtest, or work through an error without leaving your notebook or terminal. ```python title="Ask the Portfolio class how to add a trailing stop" >>> vbt.PF.chat("How do I add a 10% trailing stop to a signal backtest?") # (1) ``` 1. Needs an API key for a model provider, such as `OPENAI_API_KEY`. With an OpenAI key, the default model is `gpt-5.4`. ````markdown title="Answer" You want to add a 10% trailing stop to a signal-based portfolio backtest. Use the `tsl_stop` argument in `vbt.PF.from_signals` and set it to `0.1`. ```python import vectorbtpro as vbt data = vbt.YFData.pull("BTC-USD") fast_ma = data.run("vbt:ma", window=20, hide_params=True) slow_ma = data.run("vbt:ma", window=50, hide_params=True) entries = fast_ma.ma_crossed_above(slow_ma) exits = fast_ma.ma_crossed_below(slow_ma) pf = vbt.PF.from_signals( data, entries=entries, exits=exits, tsl_stop=0.1 ) print(pf.sharpe_ratio) ``` If you want to combine it with other stops, you can also pass `sl_stop` and/or `tp_stop` in the same call. ... ```` The question went to the `Portfolio` class, so the model received code examples that use it as context. The returned code ran unchanged and printed a Sharpe ratio of 1.28 for the full Bitcoin history on October 2, 2026. Answers vary between runs and models, so treat them like code from a colleague: read them, run them, and check the result. ## Help with the next step in your research \[#help-with-the-next-step-in-your-research] Start with a specific change or question. For example: * "How do I add a trailing stop to this signal backtest?" * "How can I test several moving-average windows across multiple assets?" * "What does this error mean when I pass an array to my signal callback?" * "How do I get trade statistics for each portfolio group?" Include the relevant function, code, or error message so the answer can address your setup. You can then ask a follow-up using the same `chat_history`, such as adding fees or changing how assets share cash. Ask for Python code that you can run and inspect in your own research. ## Choose how to work with it \[#choose-how-to-work-with-it] | What you need | Use | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | An answer that draws on VBT documentation and examples | `vbt.chat`, or `vbt.quick_chat` for keyword-based retrieval. | | Help with a particular class or method | Class-level chat, such as `vbt.PF.chat`, with relevant material about that class. | | An assistant that can look things up or run a calculation while answering | `vbt.interact` with a model that supports tool calls. | | Changes across files in an existing project | A coding agent with VBT skills, documentation, and access to your installation. | ## Grounded chat \[#grounded-chat] `vbt.chat` searches the whole knowledge base for the question, ranks the most relevant pages, examples, and discussions, and sends them to the model with the question. `vbt.quick_chat` ranks with keyword search instead of embeddings, which is faster and works offline apart from the model itself once the knowledge assets are available locally. Both take a `chat_history` to continue a conversation, stream the answer, and print it as plain text, render it in a notebook, or open it as an HTML page in the browser. The same commands run in a terminal as `vbt chat` and `vbt quick-chat`, as the [ChatVBT](#chatvbt) highlight below shows. Models come from OpenAI, Anthropic, Google Gemini, Hugging Face Inference, a local Ollama server, or any provider LiteLLM supports. VBT picks the first one with a key set, and every call can name a provider, a model, and the provider's own arguments. `vbt.chat` also needs embeddings to rank the knowledge base, which the [Knowledge search](/features/ai/knowledge-search/) page sets up. Give the assistant your code, data, or an error message to work through a specific task. Each answer uses your question, conversation history, and relevant VBT material. Enable tools through `vbt.interact` to let it inspect your environment and run code. You can also use local Ollama models and local embeddings after downloading the knowledge assets. Choose the model provider separately from the search provider, so a local search setup can also be used with a hosted chat model. For changes across your own files, see [Coding agents](#coding-agents) below. ## Tools and reasoning \[#tools-and-reasoning] `vbt.interact` lets the model call tools while it answers. It can search the documentation, look up an object's API, read source code, and run Python code through the same tools as the MCP server, and you can add your own functions as tools. Supported models can show the reasoning summaries or thought segments their provider supplies. See the [Function calling](#function-calling) and [Reasoning steps](#reasoning-steps) highlights below. ## Ask any object \[#ask-any-object] VBT classes with the knowledge interface can find material about themselves. `find_api`, `find_docs`, `find_examples`, and `find_messages` return its API pages, documentation, code examples, and community discussions. `chat` answers with the code examples as context by default, and `asset_names` adds the other kinds, as the [Self-aware classes](#self-aware-classes) highlight below shows. ## Coding agents \[#coding-agents] ChatVBT helps with questions and code snippets. For work across your project, coding agents such as Claude Code or Codex can work with VBT directly: * **Agent skills:** `vbt agents install` adds step-by-step procedures for common tasks, such as generating signals, backtesting, and optimizing parameters, matched to your installed version. * **Documentation:** members get `llms.txt` indexes, Markdown versions of every page, and downloadable knowledge assets that an agent can search. * **Tools:** the MCP server, or the same functions called from Python, let an agent search the documentation and run code in your installation. See the [MCP server](/features/ai/mcp-server/) for the available tools. * **Refactoring:** `vbt.refactor_source` improves code with a model and VBT knowledge, as the [Source refactorer](#source-refactorer) highlight below shows. !!! info "Guide" The members-only [Using AI](https://members.vectorbt.pro/using-ai/) guide sets up agent skills, documentation access, and the MCP server step by step. ## Function calling \[#function-calling] New in v2025.10.15 ✅ VBT now supports function calling with compatible models, allowing you to use the MCP server and define custom functions that the model can invoke, and all of this without any additional setup! This feature is particularly useful for complex queries, research tasks, and interactive applications where you want the model to perform specific tasks or calculations on your behalf. ```python title="Ask VBT a question using ChatGPT and let it use the MCP server" >>> env["OPENAI_API_KEY"] = "" >>> vbt.interact( # (1) ... "How to backtest a weekly rebalancing strategy with vbt.PF.from_orders?", ... tool_display_format="compact", # (2) ... formatter="html", ... ) ``` 1. Use `interact()` instead of `chat()` to enable function calling. 2. Optional. Use a compact display format for tools. By default, tools are displayed in a collapsed format. ![](/assets/images/features/intelligence/function_calling.light.gif#only-light) ![](/assets/images/features/intelligence/function_calling.dark.gif#only-dark) ## Reasoning steps \[#reasoning-steps] New in v2025.10.15 ✅ VBT now displays reasoning summaries and thought segments from supported models, helping you follow the explanation alongside the answer. This is particularly useful for complex queries that require multiple steps to answer. ```python title="Ask VBT a question using ChatGPT and see its reasoning steps" >>> env["GITHUB_TOKEN"] = "" >>> env["OPENAI_API_KEY"] = "" >>> vbt.chat( ... "How to backtest a weekly rebalancing strategy with vbt.PF.from_orders?", ... reasoning=dict(effort="low", summary="auto"), # (1) ... formatter="html" ... ) ``` 1. Enable reasoning with low effort and automatic summary for OpenAI models. ![](/assets/images/features/intelligence/reasoning_steps.light.gif#only-light) ![](/assets/images/features/intelligence/reasoning_steps.dark.gif#only-dark) ## ChatVBT \[#chatvbt] New in v2025.3.1 ✅ Similar to SearchVBT, ChatVBT takes search results and forwards them to your chosen model. This lets you ask questions about the VBT knowledge base and receive answers informed by the retrieved material. ```python title="Ask VBT a question using ChatGPT" >>> env["GITHUB_TOKEN"] = "" >>> env["OPENAI_API_KEY"] = "" >>> vbt.chat("How to rebalance weekly?", formatter="html") ``` ![](/assets/images/features/intelligence/chatvbt.light.gif#only-light) ![](/assets/images/features/intelligence/chatvbt.dark.gif#only-dark) ## Self-aware classes \[#self-aware-classes] New in v2024.12.15 ✅ Each VBT class offers methods to explore its features, including its API, associated documentation, Discord messages, and code examples. You can even ask it questions directly through a model! ```python title="Ask portfolio optimizer a question" >>> env["GITHUB_TOKEN"] = "" >>> env["OPENAI_API_KEY"] = "" >>> vbt.PortfolioOptimizer.find_assets().get("link") ['https://members.vectorbt.pro/api/portfolio/pfopt/base/#vectorbtpro.portfolio.pfopt.base', 'https://members.vectorbt.pro/api/generic/analyzable/#vectorbtpro.generic.analyzable.Analyzable', 'https://members.vectorbt.pro/api/base/wrapping/#vectorbtpro.base.wrapping.Wrapping', ... 'https://members.vectorbt.pro/features/optimization/portfolio-optimization/#riskfolio-lib', 'https://members.vectorbt.pro/features/optimization/portfolio-optimization/#portfolio-optimization', 'https://members.vectorbt.pro/features/optimization/portfolio-optimization/#pyportfolioopt', ... 'https://discord.com/channels/x/918629995415502888/1064943203071045753', 'https://discord.com/channels/x/918629995415502888/1067718833646874634', 'https://discord.com/channels/x/918629995415502888/1067718855734075403', ...] >>> vbt.PortfolioOptimizer.chat("How to rebalance weekly?", formatter="html") ``` ![](/assets/images/features/intelligence/knowledge_assets.light.gif#only-light) ![](/assets/images/features/intelligence/knowledge_assets.dark.gif#only-dark) ## Source refactorer \[#source-refactorer] New in v2025.5.11 ✅ Use the source refactorer to automatically enhance any Python code, whether it is a full package, Python object, or raw string. For larger sources, it uses the Python syntax tree to split the code into chunks, refactors each with a model, and merges the results. You can choose to return the result, update the source in place, or copy it to your clipboard. For full transparency, you can also preview the diff directly in your browser ✏️ ```python title="Complete a signal function" >>> env["GITHUB_TOKEN"] = "" >>> env["OPENAI_API_KEY"] = "" >>> source = """ ... @njit ... def signal_func_nb(ctx, entries, exits): ... is_entry = vbt.pf_nb.select_nb(ctx, entries) ... is_exit = vbt.pf_nb.select_nb(ctx, exits) ... ... # TODO: Enter only if no other asset is active ... ... return is_entry, is_exit, False, False ... """ # (1) >>> new_source = vbt.refactor_source( ... source, ... attach_knowledge=True, # (2) ... model="gpt-5-mini", ... reasoning=dict(effort="high"), ... show_diff=True, # (3) ... ) >>> print(new_source) @njit def signal_func_nb(ctx, entries, exits): is_entry = vbt.pf_nb.select_nb(ctx, entries) is_exit = vbt.pf_nb.select_nb(ctx, exits) for col in range(ctx.from_col, ctx.to_col): if col != ctx.col and ctx.last_position[col] != 0: is_entry = False break return is_entry, is_exit, False, False ``` 1. Use **TODO** or **FIXME** comments to provide custom instructions. 2. Attach relevant knowledge from the website and Discord. 3. Show the produced changes in a browser. ![](/assets/images/features/intelligence/source_refiner.light.png#only-light) ![](/assets/images/features/intelligence/source_refiner.dark.png#only-dark) # AI (/features/ai) Get help writing and fixing Python backtests with VBT documentation, code examples, and community answers close at hand. Ask a question in your notebook, search for a working example, or connect a coding assistant such as Claude Code, Codex, or Cursor to your VBT installation. Find the right API, test an idea, and inspect the results in the same conversation. * [AI research assistant](/features/ai/ai-research-assistant): Chat with an assistant grounded in VBT documentation and examples, with tools and reasoning * [Knowledge search](/features/ai/knowledge-search): Search documentation, API, examples, and community answers with keyword and embedding ranking * [MCP server](/features/ai/mcp-server): Let your coding assistant search VBT documentation, look up the API, and run code over MCP ## Choose where to start \[#choose-where-to-start] | What do you want to do? | Explore | | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Ask how to use VBT, fix a code snippet, or get help in a notebook | [AI research assistant](/features/ai/ai-research-assistant/), with chat based on VBT documentation and examples, class-specific help, and callable tools. | | Find an API, code example, or community answer and read the source yourself | [Knowledge search](/features/ai/knowledge-search/), with keyword and natural-language search, source links, and support for your own research notes. | | Work on a project with your existing coding assistant | [MCP server](/features/ai/mcp-server/), with documentation lookup, source inspection, agent skills, and Python execution in your installation. | ## From a focused question to a backtest \[#from-a-focused-question-to-a-backtest] Start with the part you are working on, such as adding a trailing stop or selecting parameters on training data. ChatVBT retrieves relevant VBT material to help answer the question. You can include your code or an error message and continue with follow-up questions. Models that support tool calls can use `vbt.interact` to look up more information or run Python while answering. Supported models can also display reasoning summaries supplied by their provider. For changes across project files, give your coding assistant VBT's documentation and agent skills. The MCP server lets it check the API, read examples, and run code. After a backtest, ask it to inspect the trades or compare settings while holding the rest of the strategy fixed. The [MCP demonstration](/features/ai/mcp-server/) shows the search, API lookup, and execution behind one such task. ## Use your choice of model \[#use-your-choice-of-model] ChatVBT supports hosted providers and local models through Ollama. Search and chat providers can be chosen separately, and knowledge search can supply context for your own model. If you just need to find a warning or function name, keyword search works without a model provider once the knowledge assets have been downloaded. ## Start here \[#start-here] Browse the [Cookbook](/cookbook/) for practical recipes on loading, searching, and chatting with knowledge assets. The members-only [Using AI](https://members.vectorbt.pro/using-ai/) guide covers agent skills, documentation access, and connecting your coding assistant. # Knowledge search (/features/ai/knowledge-search) How do you find the right answer among thousands of pages and messages? VBT's knowledge search searches its documentation, API reference, code examples, and community answers from Python. Look up an exact warning or ask a question in your own words, then open the original sources. You can also collect the best matches as context for your own LLM. ```python title="Search the knowledge base and see where the best matches come from" >>> def source(link): ... if "discord.com" in link: ... return "community" ... if "/api/" in link: ... return "API" ... if "/tutorials/" in link or "/cookbook/" in link: ... return "tutorials and cookbook" ... return "documentation" >>> results = vbt.search("trailing stop after partial exit", display=False) # (1) >>> len(results) 42434 >>> top = results[:20] >>> pd.Series([source(d["link"]) for d in top]).value_counts() community 17 documentation 2 API 1 Name: count, dtype: int64 >>> docs = [d["link"].split(".pro")[1] for d in top if source(d["link"]) != "community"] >>> print("\n".join(dict.fromkeys(docs))) /documentation/portfolio/from-signals/#types /documentation/portfolio/from-signals/#creation-1 /api/signals/generators/stcx/#vectorbtpro.signals.generators.stcx.STCX.exit_place_func_nb ``` 1. Ranks all 42,434 documents for the query and returns them best first. Without `display=False`, the results open as an HTML page in the browser. Searching the whole knowledge base took 2.7 seconds on an Apple M3 once its data was cached. The first search downloads the knowledge assets and their precomputed embeddings, which took about 15 minutes here. For a question about a specific situation, community answers dominated the top 20, alongside the documentation sections that explain how stop orders are created. ## The knowledge base \[#the-knowledge-base] The knowledge base is a set of assets: website pages, community messages, code examples, and concepts, each a list of records with a link, title, and content. `vbt.find_docs`, `vbt.find_api`, `vbt.find_examples`, and `vbt.find_messages` return the records about an object or a query, and the assets themselves can be filtered, queried, sorted, grouped, and merged like data, with methods such as `select`, `query`, `find`, and `apply`. Message threads and page sections can be combined into single documents before searching, and your own text can be wrapped in an asset and searched or chatted with the same way. See the [Knowledge assets](#knowledge-assets) highlight below. ## Search and ranking \[#search-and-ranking] Ranking runs in three steps: * **Splitting:** long documents are split into chunks, with code blocks and headings kept intact. * **Retrieval:** embeddings find documents with a similar meaning, BM25 finds documents with the same words, and the default hybrid mode merges both rankings with reciprocal rank fusion. * **Reranking:** an optional reranker from Cohere, Jina, Voyage, a local Hugging Face cross-encoder, or any LLM scores the top results again, as the [Reranking](#reranking) highlight below shows. Embeddings come from OpenAI, Gemini, Voyage, Cohere, Jina, Hugging Face, a local Sentence Transformers model, or Ollama, and are stored in memory, in files, or in LMDB. For the default models, precomputed embeddings of the knowledge base download with each release, so only your queries need to be embedded. Embeddings from different models cannot be mixed, so after switching the embeddings provider, clear the cached embeddings and let VBT build them again. The website pages and community messages are not part of the package. They download from the release on GitHub with the same `GITHUB_TOKEN` used to install VBT, and an updated VBT fetches the matching assets on its first search. Machines without access can point the asset settings at a local copy of the files. ## Search tools \[#search-tools] | Tool | Use it for | Needs | | ---------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------ | | `vbt.search` | Questions in your own words, using meaning and keywords together | An embeddings provider | | `vbt.quick_search` | Exact warnings, function names, and other keywords | Nothing beyond the downloaded assets | | `vbt.chat`, `vbt.quick_chat` | An answer based on the retrieved sources | A completions provider, plus embeddings for `vbt.chat` | Results open as an HTML page or return as an asset for your own code, as the [SearchVBT](#searchvbt) and [Quick search and chat](#quick-search-and-chat) highlights below show. The same ranking feeds the [AI research assistant](/features/ai/ai-research-assistant/), and the member website has its own search bar for pages and API. ## Find code or community answers \[#find-code-or-community-answers] Looking for a working example? Limit a search to `asset_names="examples"`. Debugging a warning or an unusual backtest setup? Use `asset_names="messages"` to search community discussions. This lets you choose the kind of answer you need without searching every source at once. If you already know the VBT object, `vbt.find_api` and `vbt.find_examples` can find its API reference and examples directly. For custom signal logic, the [Knowledge assets](#knowledge-assets) example below goes further and finds code containing a particular function definition. ## Search your own research notes \[#search-your-own-research-notes] Your knowledge base can include your own material too. Wrap notes or text extracted from your documents in a `KnowledgeAsset`, then filter, search, or chat with it. For example, keep execution assumptions and validation plans together and find the note you need: ```python title="Find an execution assumption in personal research notes" >>> notes = vbt.KnowledgeAsset([ ... dict(title="Execution assumptions", content="Compare slippage of 0.05% and 0.1%."), ... dict(title="Validation plan", content="Reserve the final year for out-of-sample testing."), ... ]) >>> print(notes.find("slippage").get("title")) ['Execution assumptions'] ``` This text lookup runs locally without an embeddings or chat provider. The same asset can supply context for a model when you want to ask questions about the notes instead. ## Context for your own LLM \[#context-for-your-own-llm] `to_context` turns ranked results into one block of text within a token budget, with optional metadata such as links, ready to paste into any model or pass to your own pipeline. Choose how much source material to include with `max_tokens`. Local caching keeps downloaded assets and search results ready for reuse, and answers can stream into your notebook or be saved as text, Markdown, or HTML. ## Reranking \[#reranking] New in v2026.4.7 ✅ After the initial document retrieval, VBT can now rerank results using a dedicated reranking model to surface the most relevant documents. Five providers are supported out of the box: Cohere, Jina, Voyage, Hugging Face cross-encoders (local), and any LLM via completions-based scoring. === "Example 1: Search with reranking" ```python title="Rerank search results using Cohere" >>> env["COHERE_API_KEY"] = "" >>> vbt.search( # (1) ... "How to rebalance weekly?", ... rerank=True, # (2) ... reranker="cohere", # (3) ... rerank_limit=20, # (4) ... ) ``` 1. Works the same way with `vbt.chat()`, `vbt.quick_chat()`, and `vbt.interact()`. 2. Enable reranking after the initial retrieval pass. 3. Choose a reranker. Available options: `"cohere"`, `"jina"`, `"voyage"`, `"hf_cross_encoder"`, `"completions"`. 4. Only the top 20 documents from the initial ranking are sent to the reranker. === "Example 2: Chat with local reranking" ```python title="Rerank using a local cross-encoder model" >>> env["OPENAI_API_KEY"] = "" >>> vbt.chat( # (1) ... "How to use stop losses with from_signals?", ... rank_kwargs=dict( ... rerank=True, ... reranker="hf_cross_encoder", # (2) ... ), ... formatter="html", ... ) ``` 1. Pass reranking parameters through `rank_kwargs` when calling `vbt.chat()`. 2. Use a Hugging Face cross-encoder model for fully local, offline reranking. !!! info "Cookbook" Don't use OpenAI? Explore more configurations in the knowledge section of the [Cookbook](/cookbook/). ## Quick search and chat \[#quick-search-and-chat] New in v2025.5.11 ✅ In addition to embeddings, which require prior generation, VBT now supports [BM25](https://en.wikipedia.org/wiki/Okapi_BM25) for fast, fully offline lexical search. This is perfect for quickly finding something specific. ```python title="Search VBT knowledge for a warning" >>> env["GITHUB_TOKEN"] = "" >>> vbt.quick_search("UserWarning: Symbols have mismatching index") ``` === "Page 1" ![](/assets/images/features/intelligence/quick_search1.light.png#only-light) ![](/assets/images/features/intelligence/quick_search1.dark.png#only-dark) === "Page 2" ![](/assets/images/features/intelligence/quick_search2.light.png#only-light) ![](/assets/images/features/intelligence/quick_search2.dark.png#only-dark) === "Page 3" ![](/assets/images/features/intelligence/quick_search3.light.png#only-light) ![](/assets/images/features/intelligence/quick_search3.dark.png#only-dark) ## SearchVBT \[#searchvbt] New in v2025.3.1 ✅ Want to find specific information using natural language on the website or Discord? SearchVBT accepts your question and generates an HTML page with ranked results and links to their sources. It searches by meaning as well as keywords, so you can describe what you want to do even when you do not know the VBT function name yet. ```python title="Search VBT knowledge for a warning" >>> env["GITHUB_TOKEN"] = "" >>> env["OPENAI_API_KEY"] = "" >>> vbt.search("How to run indicator expressions?") ``` === "Page 1" ![](/assets/images/features/intelligence/searchvbt1.light.png#only-light) ![](/assets/images/features/intelligence/searchvbt1.dark.png#only-dark) === "Page 2" ![](/assets/images/features/intelligence/searchvbt2.light.png#only-light) ![](/assets/images/features/intelligence/searchvbt2.dark.png#only-dark) === "Page 3" ![](/assets/images/features/intelligence/searchvbt3.light.png#only-light) ![](/assets/images/features/intelligence/searchvbt3.dark.png#only-dark) ## Knowledge assets \[#knowledge-assets] New in v2024.11.12 ✅ Each [release](https://github.com/polakowo/vectorbt.pro/releases) now includes valuable knowledge assets, JSON files containing private website content and the complete "vectorbt.pro" Discord history. These assets can be used with LLMs and services like Cursor. In addition, VBT offers a palette of classes for working with these assets, providing functions such as converting to Markdown and HTML files, browsing the website offline, performing targeted searches, interacting with LLMs, and much more! ```python title="Gather all pages and messages that define signal_func_nb" >>> env["GITHUB_TOKEN"] = "" >>> pages_asset = vbt.PagesAsset.pull() # (1) >>> messages_asset = vbt.MessagesAsset.pull() >>> vbt_asset = pages_asset + messages_asset >>> code = vbt_asset.find_code("def signal_func_nb", return_type="item") >>> code.print_sample(seed=42) # (2) ``` 1. The first pull will download the assets, while subsequent pulls will use the cached versions. 2. Print a random code snippet. ````yaml link: https://discord.com/channels/x/918630948248125512/1251081573147742298 block: https://discord.com/channels/x/918630948248125512/1251081573147742298 thread: https://discord.com/channels/x/918630948248125512/1250844139952541837 reference: https://discord.com/channels/x/918630948248125512/1250844139952541837 replies: - https://discord.com/channels/x/918630948248125512/1251083513336299610 channel: support timestamp: '2024-06-14 07:51:31' author: '@polakowo' content: Something like this mentions: - '@fei' attachments: - file_name: Screenshot_2024-06-13_at_20.29.45-B4517.png content: |- Here's the text extracted from the image: ```python @njit def signal_func_nb(ctx, entries, exits, wait): is_entry = vbt.pf_nb.select_nb(ctx, entries) if is_entry: return True, False, False, False is_exit = vbt.pf_nb.select_nb(ctx, exits) if is_exit: if vbt.pf_nb.in_position_nb(ctx): last_order = vbt.pf_nb.get_last_order_nb(ctx) if ctx.index[ctx.i] - ctx.index[last_order["idx"]] >= wait: return False, True, False, False return False, False, False, False pf = vbt.PF.from_random_signals( "BTC-USD", n=100, seed=42, signal_func_nb=signal_func_nb, signal_args=( vbt.Rep("entries"), vbt.Rep("exits"), vbt.dt.to_ns(vbt.timedelta("1000 days")) ) ) ``` reactions: 0 ```` # MCP server (/features/ai/mcp-server) Can your own AI coding assistant use VBT directly? The VBT MCP server connects any client that supports the Model Context Protocol, such as Claude Code, Codex, or Cursor, to your installation, so the assistant can search the documentation, look up the API, read source code, and run Python backtests. Keep working in your editor while the assistant checks VBT examples and tests changes against your installed package. ```bash title="Register the server with Claude Code" vbt mcp config claude-code # (1) claude mcp add --transport stdio vectorbtpro -- /path/to/python -m vectorbtpro.mcp_server ``` 1. Prints the command for your client with the path to the Python interpreter that runs VBT filled in. `vbt mcp config` also supports `codex`, `cursor`, `vscode`, `gemini-cli`, `opencode`, and `claude-desktop`. Asked to add a 5% stop loss and a 10% take profit to a moving average crossover, an assistant connected to the server makes calls like these. The tools are Python functions in `vbt.mcp`, so the same calls run without a server: ```python title="Search, resolve, and run, as an assistant does through the server" >>> import json >>> from vectorbtpro import mcp >>> found = mcp.search( # (1) ... "stop loss and take profit in from_signals", ... asset_names=["docs"], ... n=3, ... ) >>> for result in json.loads(found): ... print(result["name"]) Stop signals Discretionary Signal Backtesting High-level VBT >>> print(mcp.resolve_refnames(["vbt.PF.from_signals"])) # (2) OK vbt.PF.from_signals vectorbtpro.portfolio.base.Portfolio.from_signals >>> print(mcp.run_code(""" ... data = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2025-01-01") ... fast = data.close.vbt.rolling_mean(20) ... slow = data.close.vbt.rolling_mean(50) ... pf = vbt.PF.from_signals( ... data, ... fast.vbt.crossed_above(slow), ... fast.vbt.crossed_below(slow), ... sl_stop=0.05, ... tp_stop=0.10, ... fees=0.001, ... ) ... print(pf.stats(["total_return", "max_dd", "total_trades", "win_rate"])) ... """)) # (3) Total Return [%] -18.880116 Max Drawdown [%] 38.686652 Total Trades 19 Win Rate [%] 26.315789 dtype: object ``` 1. Searches only the documentation and returns the three best matches as JSON, which is what the assistant reads. 2. Confirms the exact object before the assistant reads its API or source. 3. Runs the code in a Jupyter kernel with VBT imported, and keeps the kernel's variables for later calls. The assistant found the tutorial on stop signals, confirmed the method, and ran a real backtest in your environment. You get the code and calculated statistics together, ready to inspect the trades, adjust the settings, and run the next comparison. ## From a question to a tested backtest \[#from-a-question-to-a-tested-backtest] The connection is useful throughout a research project. You can ask your assistant to: * Find the VBT method and examples for a strategy idea before writing the code. * Read the relevant API and source to investigate an error in your backtest. * Compare fees, slippage, or stop settings and show the resulting statistics. * Use [walk-forward validation](/features/optimization/time-series-cross-validation/) to test chosen parameters on later data. For example, after the backtest above, ask it to compare the same strategy with and without stops while keeping fees and signals fixed. The persistent kernel keeps `data`, `fast`, `slow`, and `pf` available for follow-up calls, so the assistant can reuse the loaded data and inspect the trades. You can also give it a member page URL and ask it to read the page. The server retrieves the text from the release's [knowledge assets](/features/ai/knowledge-search/#knowledge-assets), using your configured GitHub access. It does not need to control your browser or use its sign-in session. Long pages can be read section by section, and community answers can be opened as whole threads. ## Agent skills for research tasks \[#agent-skills-for-research-tasks] VBT ships with step-by-step instructions for common tasks, including backtesting, indicators, parameter optimization, and cross-validation. The assistant can discover them through `list_skills` and read the relevant instructions with `get_skill`. This gives it a procedure to follow alongside the API reference and code examples. For a parameter search, for example, the cross-validation skill covers train and test periods, indicator warmup, and what happens to open positions when parameters change. The [members-only skills pages](https://members.vectorbt.pro/using-ai/skills/) show the procedures available to your assistant. ## Server \[#server] The server runs on your machine with your VBT installation, so API and source lookups use the version you have installed. Clients usually start it themselves over stdio. To run it in another environment, such as a container or WSL, start it over HTTP with `vbt mcp serve --transport streamable-http --port 8000` and register its `/mcp` address in the client. Over HTTP, the server binds to the local machine by default. `run_code`, which executes code, is available only over stdio. Over stdio, `run_code` uses a persistent Jupyter kernel in your VBT environment. Your client's approval controls let you decide which code the assistant runs. The setup guide below covers installation and client configuration. `get_environment` reports the Python interpreter and the Python and VBT versions, so an assistant can check its setup first. The first search after starting the server loads the knowledge assets, which takes the most time, and later searches reuse them. When embeddings for some documents are missing, search ranks them by keywords instead of generating the embeddings first. Tools support token budgets and pagination, so the assistant can request a focused result and read more when needed. ## Tools \[#tools] | Tool | What it does | | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `search` | Ranks documentation, API, examples, and community answers for a query | | `find` | Returns the material about specific objects, such as `vbt.PF.from_signals` | | `resolve_refnames` | Turns names like `vbt.Data` into fully qualified names | | `get_page`, `get_message`, `get_message_block`, `get_message_thread` | Read a page, a message, consecutive messages from one author, or a whole discussion by its link | | `find_concepts`, `get_concept` | Search the concept map and see how concepts relate | | `get_attrs`, `get_source` | List an object's attributes, read its source code | | `list_skills`, `get_skill` | Read the agent skills that ship with VBT | | `run_code` | Runs Python with VBT in a persistent Jupyter kernel | | `get_environment` | Reports the Python interpreter and the Python and VBT versions | Every tool also runs from the terminal, as in `vbt mcp search "rolling Sharpe ratio"`, and from Python through `vbt.mcp`. The server exposes these functions as MCP tools, including the tools that read documentation. You can also use them from the [AI research assistant](/features/ai/ai-research-assistant/) inside Python. !!! info "Guide" The members-only [Using AI](https://members.vectorbt.pro/using-ai/) guide sets up the server for each client, serves it over HTTP, and lists prompts to try. # Binance data (/features/data/binance-data) How do you get Binance historical data into Python? `vbt.BinanceData` downloads klines for spot and futures markets from Binance's public API, including trade counts and taker volume, and returns them as one data object ready for indicators and backtests. ```python title="Pull a year of hourly spot and perpetual futures bars for BTCUSDT" >>> kwargs = dict(start="2024-01-01", end="2025-01-01", timeframe="1h") >>> spot = vbt.BinanceData.pull("BTCUSDT", **kwargs) >>> perp = vbt.BinanceData.pull("BTCUSDT", klines_type="futures", **kwargs) # (1) >>> spot.features[5:] # (2) ['Quote volume', 'Trade count', 'Taker base volume', 'Taker quote volume'] >>> def summarize(d): ... return { ... "volume (M BTC)": d.volume.sum() / 1e6, ... "trades (M)": d.get("Trade count").sum() / 1e6, ... "taker buys": d.get("Taker base volume").sum() / d.volume.sum(), ... } >>> pd.DataFrame({"spot": summarize(spot), "perpetual": summarize(perp)}).T.round(3) volume (M BTC) trades (M) taker buys spot 12.931 1015.161 0.497 perpetual 100.355 1365.867 0.497 >>> basis_bps = (perp.close / spot.close - 1) * 10_000 # (3) >>> basis_bps.describe().round(2) count 8784.00 mean -0.29 std 5.25 min -20.76 25% -4.44 50% -2.76 75% 4.70 max 28.88 Name: Close, dtype: float64 ``` 1. USD-margined futures. The same pull without `klines_type` returns spot bars. 2. Features that Binance adds to the usual open, high, low, close, and volume. 3. The perpetual contract's premium over spot, in basis points. All 8,784 hours of 2024 came back for both markets. The perpetual contract traded 7.8 times the spot volume, and its hourly closing price stayed within 29 basis points of spot. In both markets, takers bought almost exactly half the volume over the year. Each hour's share can be calculated from its taker buy volume and total volume. ## From Binance candles to strategy research \[#from-binance-candles-to-strategy-research] The extra fields let you ask questions that prices alone cannot answer. Does a breakout behave differently when it comes with more trades? Does a larger share of taker buying help filter an entry signal? How does a strategy perform on spot compared with the perpetual contract? You can calculate these features alongside your indicators and test them with [Signal backtesting](/features/backtesting/signal-backtesting/). The example above compares the two markets on matching hourly bars. Use the same approach to study when the perpetual trades above or below spot, or compare activity across several coins. The prices and extra fields stay together in the data object, so you can select a symbol or a period without rebuilding the dataset. See [Data pipelines](/features/data/financial-data-pipelines/) for working with the downloaded data. ## Spot and futures \[#spot-and-futures] `klines_type` selects the market and price series: | Data | `klines_type` | Useful for | | --------------------- | ------------------------------------------------------- | ----------------------------------------------------- | | Spot | `"spot"` (default) | Coin prices, traded volume, and activity | | USD-margined futures | `"futures"` | Contract prices and spot versus futures comparisons | | Coin-margined futures | `"futures_coin"` | Research on contracts margined in the underlying coin | | Futures mark price | `"futures_mark_price"` or `"futures_coin_mark_price"` | Comparing traded prices with the mark price | | Futures index price | `"futures_index_price"` or `"futures_coin_index_price"` | Comparing contracts with their reference index | Spot and USD-margined trade candles include open, high, low, close, and volume, plus quote volume, the number of trades, and the base and quote volume bought by takers. These taker fields measure buying initiated by traders taking liquidity, which OHLC bars alone cannot show. Choose trade candles for volume research. Mark and index candles provide reference prices, with placeholders in the activity fields, as shown in [Binance's market data reference](https://developers.binance.com/en/docs/catalog/core-trading-derivatives-trading-usd-s-m-futures/api/rest-api/market-data). ## Downloading and updating historical data \[#downloading-and-updating-historical-data] Timeframes run from one minute to one month, as in `"1m"`, `"1h"`, or `"1d"`, and dates accept strings such as `"2024-01-01"` or `"1 year ago"`. A pull starting before a symbol's first trade begins at its first available candle, so a long range is safe to request. The end date is exclusive: the example stops before January 1, 2025, covering the full calendar year of 2024. Requests are split into batches of 1,000 klines with a 0.5-second pause between them by default. Each batch starts where the previous one ended, so one symbol downloads sequentially: a year of one-minute bars is about 530 requests and several minutes. Many symbols can be pulled in parallel threads with `execute_kwargs=dict(engine="threadpool")`, as long as the total stays within Binance's rate limits. Assign the result of `data.update()` to keep the latest data. Updates fetch from the last stored candle, refreshing that candle and adding newer bars. For a pull with a fixed end date, supply a later end date when updating. To keep a large history on disk and update it on a schedule, see [Data storage and databases](/features/data/data-storage-and-databases/). ## Finding symbols \[#finding-symbols] `vbt.BinanceData.list_symbols` lists spot symbols, filtered with a glob or a regular expression: ```python title="List Binance symbols that match a pattern" >>> vbt.BinanceData.list_symbols("BTC*USDT") ['BTCDOWNUSDT', 'BTCSTUSDT', 'BTCUPUSDT', 'BTCUSDT'] ``` Pulling many symbols at once returns one data object with a column per symbol, aligned on one index. ## Accounts and regions \[#accounts-and-regions] The class uses the `python-binance` client, installed with `pip install python-binance`, not the unrelated `binance` package. Historical klines are public, so no API key is needed. Keys and other client options go into `client_config`, and `client_config=dict(tld="us")` connects to Binance.US. If you already use `python-binance`, pass your existing client through `client` to reuse its configuration across pulls. For data from many other exchanges, `vbt.CCXTData` offers the same interface through CCXT, as the [Market data sources](/features/data/market-data-sources/) page shows. # Data storage and databases (/features/data/data-storage-and-databases) Where should market data live once it is downloaded, and how do you read back just the part you need? VBT saves any data object to CSV, HDF5, Feather, Parquet, DuckDB, SQL databases, or ArcticDB, and reads it back into a data object ready for research. Store market data in Python and select the dates and symbols you need for your next backtest. ```python title="Store four weeks of minute bars in DuckDB and query one week" >>> data = vbt.GBMOHLCData.pull( # (1) ... ["AAA", "BBB", "CCC"], ... start="2024-01-01", ... end="2024-01-29", ... timeframe="1min", ... std=0.0005, ... seed=42, ... ) >>> data.loc[:"2024-01-21 23:59"].to_duckdb(connection="market.duckdb") >>> data.loc["2024-01-22":].to_duckdb( # (2) ... connection="market.duckdb", ... if_exists="append", ... ) >>> vbt.DuckDBData.list_tables(connection="market.duckdb") ['AAA', 'BBB', 'CCC'] >>> week = vbt.DuckDBData.pull( ... ["AAA", "BBB", "CCC"], ... start="2024-01-15", ... end="2024-01-22", ... tz="UTC", # (3) ... connection="market.duckdb", ... ) >>> week.close.shape (10080, 3) >>> week.close.head(3).round(2) symbol AAA BBB CCC 2024-01-15 00:00:00+00:00 67.01 176.99 60.39 2024-01-15 00:01:00+00:00 66.99 176.51 60.20 2024-01-15 00:02:00+00:00 67.18 175.62 60.15 ``` 1. Four weeks of seeded synthetic minute bars for three symbols, so the example runs offline. 2. Append the later bars to the same tables, as a scheduled job would after each download. 3. Read the dates as UTC rather than the machine's local timezone. Each symbol becomes a table, appends extend it, and a query returns only the requested week as a regular data object, ready for indicators and backtests. ## Choosing a storage format \[#choosing-a-storage-format] Choose around how you collect and reuse the data: | What you need | Where to start | | ------------------------------------------------------------ | ----------------------------------------- | | Files you can inspect and exchange with other tools | CSV | | Several symbol datasets in one file, with later appends | HDF5 | | Saved DataFrames to reload with Python and Arrow tools | Feather | | Compressed archives that you write once and query repeatedly | Parquet, with date partitions when useful | | SQL analysis of local tables or existing Parquet files | DuckDB | | Data already held in PostgreSQL, MySQL, or SQLite | SQLAlchemy through `vbt.SQLData` | | Versioned DataFrames in local or object storage | ArcticDB | You can use more than one. Keep a Parquet archive, query a subset with DuckDB, and pass the result into a backtest. The examples below show both storage and retrieval. ## Files \[#files] Every data object has `to_csv`, `to_hdf`, `to_feather`, and `to_parquet`, and the matching classes `vbt.CSVData`, `vbt.HDFData`, `vbt.FeatherData`, and `vbt.ParquetData` read the files back. The same four weeks of minute bars take very different space depending on the format: ```python title="Compare file sizes for 40,320 bars of three symbols" >>> import os >>> data.to_csv("csv") >>> data.to_hdf("data.h5") >>> data.to_parquet("parquet") >>> data.to_feather("feather") >>> def size_mb(path): ... if os.path.isfile(path): ... return os.path.getsize(path) / 1e6 ... return sum( ... os.path.getsize(os.path.join(d, f)) ... for d, _, files in os.walk(path) ... for f in files ... ) / 1e6 >>> paths = ["csv", "data.h5", "parquet", "feather", "market.duckdb"] >>> pd.Series({path: round(size_mb(path), 1) for path in paths}) csv 12.0 data.h5 5.2 parquet 5.9 feather 4.8 market.duckdb 5.8 dtype: float64 ``` CSV is readable everywhere but is the largest and slowest to parse. HDF5 keeps many symbols in one file. Parquet is compressed, columnar, and read by most data tools, and it can be partitioned by symbol or date. Reading a folder finds the files in it, matching symbols by file name. CSV and HDF readers can process chunks and keep only the rows you need. Parquet filters select dates or other values, as the [partitioned dataset example](#pyarrow-and-fastparquet) below shows. With separate files, each file is treated as one symbol. A partitioned Parquet directory can instead hold many date partitions for the same symbol. For an existing collection of daily files, combine them with Pandas and use `vbt.Data.from_data`, or query them with DuckDB. ## Databases \[#databases] `vbt.DuckDBData` stores and queries data in DuckDB, an embedded analytical database that runs in your process and can also query Parquet and CSV files directly. `vbt.SQLData` works with any database that SQLAlchemy supports, such as PostgreSQL, MySQL, or SQLite, and `vbt.ArcticDBData` uses ArcticDB for large versioned time-series stores. DuckDB and SQLData accept custom SQL queries and can list schemas, tables, and views. ArcticDBData lists libraries and symbols, and reads through ArcticDB's own API. `vbt.DuckDBData.pull` opens the database read-only by default, so several research processes can read the same file at once. Connections can be passed in as objects or created from a URL. For repeated SQL reads and updates, you can reuse your SQLAlchemy engine and its connection pool. ArcticDBData can select a stored `version`, date range, and columns. This lets you revisit a saved dataset version when comparing research runs, even after newer data has been written. ## Use your existing data store \[#use-your-existing-data-store] You do not need a separate table for every symbol. A custom query can select rows from a shared table, join other inputs, and rename columns for VBT. The result becomes the same kind of data object as a provider download. This small example creates a Parquet file with made-up prices for two symbols, then reads only the last two days. In your own archive, the file already exists: ```python title="Query an existing multi-symbol Parquet file" >>> archive_rows = pd.DataFrame( ... { ... "timestamp": pd.to_datetime(["2024-01-01", "2024-01-02", "2024-01-03"] * 2, utc=True), ... "ticker": ["AAA"] * 3 + ["BBB"] * 3, ... "price": [100.0, 102.0, 104.0, 50.0, 49.0, 51.0], ... } ... ) >>> archive_rows.to_parquet("archive.parquet", index=False) >>> archive_data = vbt.DuckDBData.pull( ... ["AAA", "BBB"], ... query=vbt.key_dict( ... { ... symbol: f""" ... SELECT timestamp, price AS Close ... FROM read_parquet('archive.parquet') ... WHERE ticker = '{symbol}' AND timestamp >= '2024-01-02' ... ORDER BY timestamp ... """ ... for symbol in ["AAA", "BBB"] ... } ... ), ... index_col="timestamp", ... ) >>> archive_data.close symbol AAA BBB timestamp 2024-01-02 00:00:00+00:00 102.0 49.0 2024-01-03 00:00:00+00:00 104.0 51.0 ``` The SQL query selects the rows and columns before they become a Pandas object. DuckDB can [filter Parquet data while reading](https://duckdb.org/docs/current/data/parquet/overview), so a research run can work with the relevant slice of a larger archive. SQLData offers the same custom-query entry point for your SQL database. If you already have a loader that returns DataFrames, the [market data page](/features/data/market-data-sources/#custom-providers) shows how to bring those into VBT too. ## Keeping stores current \[#keeping-stores-current] Keep your research data current automatically. Data savers combine `update` with saving: they pull whatever is new and append it to the store on a schedule, and they can be stopped and resumed without losing their place, as the [Data saver](#data-saver) highlight below shows. During research, data caching stores each download locally so that rerunning a notebook reads the cache instead of the provider, as in the [Data caching](#data-caching) highlight. Savers are available for CSV, HDF5, SQL, DuckDB, and ArcticDB, and work with multiple symbols. Use the saver matching your store, such as `vbt.DuckDBDataSaver` or `vbt.SQLDataSaver`, with a provider data object that knows how to fetch updates. The [data pipelines page](/features/data/financial-data-pipelines/) covers incremental updates and scheduling. ## Save a research session \[#save-a-research-session] To keep the data together with its VBT settings and fetch arguments, save the whole object with `data.save` and restore it with the data class's `load` method. This is useful when you want to continue working with the same provider object in another session. Tabular exports such as Parquet are useful for sharing the underlying data with other tools. [Configuration and persistence](/features/tooling/configuration-and-persistence/) covers saving and restoring VBT objects. ## Data caching \[#data-caching] New in v2026.3.1 ✅ Data caching is now available for all data classes, allowing you to cache data on disk when pulling from a (remote) data source. Caching is performed using LMDB, which provides efficient key-value storage. The cache key is generated based on the hash of the class, symbol, and other fetch parameters, ensuring that different data pulls are cached separately. ```python title="Pull AAPL minute data from TradingView or cache if available" >>> data = vbt.TVData.pull( ... "AAPL", ... exchange="NASDAQ", ... timeframe="1 minute", ... tz="America/New_York", ... cache=True # (1) ... ) ``` 1. Next time you pull the same data with the same parameters, it will be loaded from the cache. Use `refresh_cache=True` to refresh the cache. ## ArcticDB \[#arcticdb] New in v2026.3.1 ✅ [ArcticDB](https://arcticdb.io/) is a serverless DataFrame database engine designed for the Python Data Science ecosystem. It can store, retrieve and process Series and DataFrames at scale, backed by commodity object storage (S3-compatible storages and Azure Blob Storage). ArcticDB requires zero additional infrastructure beyond a running Python environment and access to object storage and can be installed in seconds. ```python title="Save minute data to a ArcticDB database, and read one day" >>> data = vbt.TVData.pull( ... "AAPL", ... exchange="NASDAQ", ... timeframe="1 minute", ... tz="America/New_York" ... ) >>> data.to_arcticdb() >>> day_data = vbt.ArcticDBData.pull( ... "AAPL", ... start="2026-02-27 09:30:00", ... end="2026-02-27 16:00:00", ... tz="America/New_York", ... ) >>> day_data.get() Open High Low Close Volume datetime 2026-02-27 09:30:00-05:00 272.90 272.90 269.80 269.960 49256.0 2026-02-27 09:31:00-05:00 269.97 270.12 269.19 269.230 43715.0 2026-02-27 09:32:00-05:00 269.18 270.05 269.18 269.890 33913.0 2026-02-27 09:33:00-05:00 269.85 270.01 269.60 269.770 27569.0 2026-02-27 09:34:00-05:00 269.74 269.98 269.40 269.500 22963.0 ... ... ... ... ... ... 2026-02-27 15:55:00-05:00 264.41 264.51 263.15 263.490 162153.0 2026-02-27 15:56:00-05:00 263.51 263.78 263.23 263.670 114741.0 2026-02-27 15:57:00-05:00 263.67 263.78 262.89 263.655 113641.0 2026-02-27 15:58:00-05:00 263.61 263.92 263.25 263.620 158462.0 2026-02-27 15:59:00-05:00 263.68 264.28 263.65 264.200 107619.0 [390 rows x 5 columns] ``` ## SQL queries \[#sql-queries] New in v2023.10.22 ✅ Thanks to [DuckDB](https://duckdb.org/), you can now run SQL queries directly on data instances. ```python title="Run a rolling average of 14 days on minute data using SQL" >>> data = vbt.TVData.pull( ... "AAPL", ... exchange="NASDAQ", ... timeframe="1 minute", ... tz="America/New_York" ... ) >>> data.sql(""" ... SELECT datetime, AVG(Close) OVER( ... ORDER BY "datetime" ASC ... RANGE BETWEEN INTERVAL 14 DAYS PRECEDING AND CURRENT ROW ... ) AS "Moving Average" ... FROM "AAPL"; ... """) datetime 2023-09-11 09:30:00-04:00 180.080000 2023-09-11 09:31:00-04:00 179.965000 2023-09-11 09:32:00-04:00 180.000000 2023-09-11 09:33:00-04:00 180.022500 2023-09-11 09:34:00-04:00 179.984000 ... 2023-10-20 15:55:00-04:00 177.786669 2023-10-20 15:56:00-04:00 177.785492 2023-10-20 15:57:00-04:00 177.784322 2023-10-20 15:58:00-04:00 177.783166 2023-10-20 15:59:00-04:00 177.781986 Name: Moving Average, Length: 11700, dtype: float64 ``` ## DuckDB \[#duckdb] New in v2023.10.22 ✅ [DuckDB](https://duckdb.org/) is a high-performance analytical database system that offers a robust SQL dialect for interacting with various data stores. Not only can it run analytical queries on local data, even if the data does not fit into memory and without needing a distributed framework, but it can also query CSV, Parquet, and JSON files directly. ```python title="Save minute data to a DuckDB database, and read one day" >>> data = vbt.TVData.pull( ... "AAPL", ... exchange="NASDAQ", ... timeframe="1 minute", ... tz="America/New_York" ... ) >>> URL = "database.duckdb" >>> data.to_duckdb(connection=URL) >>> day_data = vbt.DuckDBData.pull( ... "AAPL", ... start="2023-10-02 09:30:00", ... end="2023-10-02 16:00:00", ... tz="America/New_York", ... connection=URL ... ) >>> day_data.get() Open High Low Close Volume datetime 2023-10-02 09:30:00-04:00 171.260 171.34 170.93 171.10 61654.0 2023-10-02 09:31:00-04:00 171.130 172.37 171.13 172.30 53481.0 2023-10-02 09:32:00-04:00 172.310 172.64 172.16 172.64 44750.0 2023-10-02 09:33:00-04:00 172.640 172.97 172.54 172.78 53195.0 2023-10-02 09:34:00-04:00 172.780 173.07 172.75 173.00 47416.0 ... ... ... ... ... ... 2023-10-02 15:55:00-04:00 173.300 173.51 173.26 173.51 61619.0 2023-10-02 15:56:00-04:00 173.525 173.59 173.42 173.43 45066.0 2023-10-02 15:57:00-04:00 173.430 173.55 173.42 173.50 45220.0 2023-10-02 15:58:00-04:00 173.510 173.60 173.46 173.56 47371.0 2023-10-02 15:59:00-04:00 173.560 173.78 173.56 173.75 161253.0 [390 rows x 5 columns] ``` ## SQLAlchemy \[#sqlalchemy] New in v2023.10.22 ✅ [SQLAlchemy](https://www.sqlalchemy.org/) provides a standard interface that allows developers to create database-agnostic code for communicating with a wide range of SQL database engines. With its help, you can now easily store data in SQL databases and read from them as well. ```python title="Save minute data to a PostgreSQL database, and read one day" >>> data = vbt.TVData.pull( ... "AAPL", ... exchange="NASDAQ", ... timeframe="1 minute", ... tz="America/New_York" ... ) >>> URL = "postgresql://postgres:postgres@localhost:5432" >>> data.to_sql(engine=URL) >>> day_data = vbt.SQLData.pull( ... "AAPL", ... start="2023-10-02 09:30:00", ... end="2023-10-02 16:00:00", ... tz="America/New_York", ... engine=URL ... ) >>> day_data.get() Open High Low Close Volume datetime 2023-10-02 09:30:00-04:00 171.260 171.34 170.93 171.10 61654.0 2023-10-02 09:31:00-04:00 171.130 172.37 171.13 172.30 53481.0 2023-10-02 09:32:00-04:00 172.310 172.64 172.16 172.64 44750.0 2023-10-02 09:33:00-04:00 172.640 172.97 172.54 172.78 53195.0 2023-10-02 09:34:00-04:00 172.780 173.07 172.75 173.00 47416.0 ... ... ... ... ... ... 2023-10-02 15:55:00-04:00 173.300 173.51 173.26 173.51 61619.0 2023-10-02 15:56:00-04:00 173.525 173.59 173.42 173.43 45066.0 2023-10-02 15:57:00-04:00 173.430 173.55 173.42 173.50 45220.0 2023-10-02 15:58:00-04:00 173.510 173.60 173.46 173.56 47371.0 2023-10-02 15:59:00-04:00 173.560 173.78 173.56 173.75 161253.0 [390 rows x 5 columns] ``` ## PyArrow and FastParquet \[#pyarrow-and-fastparquet] New in v2023.10.22 ✅ Data can be written to Feather with PyArrow and to Parquet using PyArrow or FastParquet. Parquet performs especially well in write-once, read-many scenarios, providing highly efficient data compression and decompression, making it a great choice for storing time series data. ```python title="Save minute data to a Parquet dataset partitioned by day, and read one day" >>> data = vbt.TVData.pull( ... "AAPL", ... exchange="NASDAQ", ... timeframe="1 minute", ... tz="America/New_York" ... ) >>> data.to_parquet(partition_by="day") # (1) >>> day_data = vbt.ParquetData.pull("AAPL", filters=[("group", "==", "2023-10-02")]) >>> day_data.get() Open High Low Close Volume datetime 2023-10-02 09:30:00-04:00 171.260 171.34 170.93 171.10 61654.0 2023-10-02 09:31:00-04:00 171.130 172.37 171.13 172.30 53481.0 2023-10-02 09:32:00-04:00 172.310 172.64 172.16 172.64 44750.0 2023-10-02 09:33:00-04:00 172.640 172.97 172.54 172.78 53195.0 2023-10-02 09:34:00-04:00 172.780 173.07 172.75 173.00 47416.0 ... ... ... ... ... ... 2023-10-02 15:55:00-04:00 173.300 173.51 173.26 173.51 61619.0 2023-10-02 15:56:00-04:00 173.525 173.59 173.42 173.43 45066.0 2023-10-02 15:57:00-04:00 173.430 173.55 173.42 173.50 45220.0 2023-10-02 15:58:00-04:00 173.510 173.60 173.46 173.56 47371.0 2023-10-02 15:59:00-04:00 173.560 173.78 173.56 173.75 161253.0 [390 rows x 5 columns] ``` 1. Without `partition_by`, the data will be saved to a single Parquet file. You will still be able to filter rows by any column in newer versions of PyArrow and Pandas. ## Data saver \[#data-saver] New in 1.1.1 ✅ Imagine a script that can periodically pull the latest data from an exchange and save it to disk, all without your intervention. VBT implements two classes that can do exactly this: one that saves to CSV and another that saves to HDF. ```python title="BTCUSDT_1m_saver.py" from vectorbtpro import * import logging logging.basicConfig(level=logging.INFO) if __name__ == "__main__": if vbt.CSVDataSaver.file_exists(): csv_saver = vbt.CSVDataSaver.load() csv_saver.update() init_save = False else: data = vbt.BinanceData.pull( "BTCUSDT", start="10 minutes ago UTC", timeframe="1 minute" ) csv_saver = vbt.CSVDataSaver(data) init_save = True csv_saver.update_every(1, "minute", init_save=init_save) csv_saver.save() # (1) ``` 1. The CSV data saver only stores the latest data update, which serves as the starting point for the next update. Be sure to save it and re-use it in the next runtime. ```console title="Run in console and then interrupt" $ python BTCUSDT_1m_saver.py 2023-02-01 12:26:36.744000+00:00 - 2023-02-01 12:36:00+00:00: : 1it [00:01, 1.22s/it] INFO:vectorbtpro.data.saver:Saved initial 10 rows from 2023-02-01 12:27:00+00:00 to 2023-02-01 12:36:00+00:00 INFO:vectorbtpro.utils.schedule_:Starting schedule manager with jobs [Every 1 minute do update(save_kwargs=None) (last run: [never], next run: 2023-02-01 13:37:38)] INFO:vectorbtpro.data.saver:Saved 2 rows from 2023-02-01 12:36:00+00:00 to 2023-02-01 12:37:00+00:00 INFO:vectorbtpro.data.saver:Saved 2 rows from 2023-02-01 12:37:00+00:00 to 2023-02-01 12:38:00+00:00 INFO:vectorbtpro.utils.schedule_:Stopping schedule manager ``` ```console title="Run in console again to continue" $ python BTCUSDT_1m_saver.py INFO:vectorbtpro.utils.schedule_:Starting schedule manager with jobs [Every 1 minute do update(save_kwargs=None) (last run: [never], next run: 2023-02-01 13:42:08)] INFO:vectorbtpro.data.saver:Saved 5 rows from 2023-02-01 12:38:00+00:00 to 2023-02-01 12:42:00+00:00 INFO:vectorbtpro.utils.schedule_:Stopping schedule manager ``` ## Local data \[#local-data] New in 1.0.0 ✅ Once you have fetched remote data, you will most likely want to save it to disk. There are two new options for this: you can either serialize the entire data class, or save the actual data to CSV or HDF5. Each dataset can be stored in a single flat file, which makes handling the data easier than using a database. After saving, you can easily load the data back either by deserializing or by using data classes that specialize in loading from CSV and HDF5 files. These classes support a range of features, including filtering by row and datetime ranges, updating, chunking, and even a smart dataset search that can recursively walk through sub-directories and return datasets that match a specific glob pattern or regular expression 🧲 ```python title="Fetch and save symbols separately, then load them back jointly" >>> btc_data = vbt.BinanceData.pull("BTCUSDT") >>> eth_data = vbt.BinanceData.pull("ETHUSDT") >>> btc_data.to_hdf() >>> eth_data.to_hdf() >>> data = vbt.BinanceData.from_hdf(start="2020", end="2021") ``` Key 2/2: 100% ```python >>> data.close symbol BTCUSDT ETHUSDT Open time 2020-01-01 00:00:00+00:00 7200.85 130.77 2020-01-02 00:00:00+00:00 6965.71 127.19 2020-01-03 00:00:00+00:00 7344.96 134.35 2020-01-04 00:00:00+00:00 7354.11 134.20 2020-01-05 00:00:00+00:00 7358.75 135.37 ... ... ... 2020-12-27 00:00:00+00:00 26281.66 685.11 2020-12-28 00:00:00+00:00 27079.41 730.41 2020-12-29 00:00:00+00:00 27385.00 732.00 2020-12-30 00:00:00+00:00 28875.54 752.17 2020-12-31 00:00:00+00:00 28923.63 736.42 [366 rows x 2 columns] ``` # Data pipelines (/features/data/financial-data-pipelines) How do you turn raw downloads into data that is ready for analysis and stays current? VBT keeps every symbol and feature in one `Data` object that aligns symbols with different histories, normalizes timezones, updates incrementally, and runs indicators directly, so a market data pipeline in Python is a few method calls. ```python title="Download 50 stocks, update them a month later, and compute RSI on all of them" >>> symbols = [ ... "AAPL", "MSFT", "AMZN", "GOOGL", "META", "NVDA", "JPM", "V", "MA", "UNH", ... "HD", "PG", "JNJ", "XOM", "CVX", "KO", "PEP", "MRK", "ABBV", "LLY", ... "COST", "WMT", "BAC", "WFC", "CSCO", "ORCL", "INTC", "AMD", "QCOM", "TXN", ... "ADBE", "CRM", "NFLX", "DIS", "NKE", "MCD", "SBUX", "BA", "CAT", "DE", ... "GE", "HON", "IBM", "MMM", "UPS", "LOW", "T", "VZ", "PFE", "TMO", ... ] >>> data = vbt.YFData.pull(symbols, start="2024-01-01", end="2024-06-01") >>> data.close.shape, data.index[-1].date() ((105, 50), datetime.date(2024, 5, 31)) >>> data = data.update(end="2024-07-01") # (1) >>> data.close.shape, data.index[-1].date() ((124, 50), datetime.date(2024, 6, 28)) >>> rsi = data.run("rsi", window=14).rsi # (2) >>> rsi.iloc[-1].sort_values(ascending=False).head(5).round(1) rsi_window symbol 14 LLY 75.8 T 75.4 ADBE 74.5 ORCL 66.5 HON 63.6 Name: 2024-06-28 00:00:00-04:00, dtype: float64 ``` 1. Refresh the last stored bar and append the bars after it, for every symbol. 2. Run an indicator on every symbol at once, with the right input features picked automatically. ## Data containers \[#data-containers] A `Data` object maps each symbol to its features, such as open, high, low, close, and volume. Features are available by name, as in `data.close` or `data.get("Volume")`, and derived prices such as `data.hlc3` are computed on demand. Each feature comes back as a DataFrame with one column per symbol, ready for indicators and backtests. The same container can also be organized by feature, which suits data that arrives as one table per field, as the [Feature-oriented data](#feature-oriented-data) highlight below shows. Symbols and features can be selected, renamed, added, and removed without leaving the object. Your own data becomes a data object with `vbt.Data.from_data`. It takes one DataFrame per symbol, so a long table with a symbol column, as many exports and databases produce, is split first: ```python title="Turn a long table of daily bars into a data object" >>> long = pd.DataFrame({ ... "date": pd.to_datetime(["2024-01-02", "2024-01-03", "2024-01-02", "2024-01-03"], utc=True), ... "symbol": ["AAPL", "AAPL", "MSFT", "MSFT"], ... "close": [185.64, 184.25, 370.87, 370.60], ... "volume": [82488700, 58414500, 25258600, 23083500], ... }) >>> data = vbt.Data.from_data({ ... symbol: df.set_index("date").drop(columns="symbol") ... for symbol, df in long.groupby("symbol") ... }) >>> data.symbols, data.features (['AAPL', 'MSFT'], ['close', 'volume']) >>> data.close symbol AAPL MSFT date 2024-01-02 00:00:00+00:00 185.64 370.87 2024-01-03 00:00:00+00:00 184.25 370.60 ``` A dictionary of wide DataFrames, one per feature with symbols as columns, works too with `columns_are_symbols=True`. This is useful for prices, fundamentals, model scores, or portfolio time series that already arrive as separate tables. A custom provider can also fetch and update one feature across many symbols by implementing `fetch_feature` and `update_feature`. ## Alignment \[#alignment] Symbols rarely share the same history. When they are pulled together, their indexes are combined and the missing bars are filled with `NaN`, or dropped with `missing_index="drop"`. Either way, a warning reports that the indexes did not match: ```python title="Align a symbol that started trading later" >>> data = vbt.YFData.pull(["BTC-USD", "SOL-USD"], start="2020-01-01", end="2021-01-01") >>> data.close.shape (366, 2) >>> data.close.apply(lambda x: x.first_valid_index().date()).tolist() [datetime.date(2020, 1, 1), datetime.date(2020, 4, 10)] >>> dropped = vbt.YFData.pull( ... ["BTC-USD", "SOL-USD"], ... start="2020-01-01", ... end="2021-01-01", ... missing_index="drop", ... ) >>> dropped.close.shape, dropped.index[0].date() ((266, 2), datetime.date(2020, 4, 10)) ``` Timezones are handled the same way: data can be converted to one timezone on load, and symbols that come back in different timezones are reported instead of silently misaligned. Indexes are sorted on load, and for duplicate timestamps the last value is kept. Keep missing observations when you want to study the full history of each asset, or use the shared period when comparing assets over the same dates. Alignment does not invent prices for the missing bars. For daily and intraday inputs that become available at different times, use [multi-timeframe analysis](/features/data/multi-timeframe-analysis/) to align them by availability. ## Updates \[#updates] `update` fetches only what is new. Pass `return_meta=True` to see which bars were appended and which overlapping bars the provider revised, which matters when the last bar was still forming at the previous update. For a fixed schedule, `vbt.DataUpdater` runs updates at an interval and calls your code after each one, which is the basis of a live pipeline, as described on the [Live simulation](/features/backtesting/live-simulation/#live-pipelines) page. Assign the returned object, as in `data = data.update()`. Keeping the original history and extending it gives repeated indicator calculations the same starting point. This matters for calculations such as exponential averages, whose values can change if each run starts from a different recent window. If you only need the updated range, use `concat=False`. That suits a collector that writes each batch to disk through a [data saver](/features/data/data-storage-and-databases/#keeping-stores-current). For calculations that retain indicator state between observations, see [streaming indicators](/features/indicators/streaming-indicators/). Already receive bars from an external feed? Your integration can wrap each batch as a data object and merge it with the previous data, or provide its own update method. Later data replaces overlapping observations when merging, so a revised bar can replace the earlier version. The feed connection and recovery of missed bars stay with your integration. ## Transform and merge \[#transform-and-merge] `transform` applies any function to the data as one DataFrame and returns a new data object, which covers cleaning, filtering, and adding features. `merge` combines data objects, for example from two providers, and concatenation joins consecutive periods. Raw files and DataFrames become data objects through parsing, with timeframes such as `"15 minutes"` and `"1h"` understood everywhere. The [Data parsing](#data-parsing), [Data transformation](#data-transformation), and [Data merging](#data-merging) highlights below show each step. ## Running functions on data \[#running-functions-on-data] `data.run()` takes an indicator name, a function, or an expression and fills in the features it needs by name, so `data.run("rsi")` reads the close and `data.run("atr")` reads high, low, and close. Arguments can differ per function, and many functions can run in one call, in parallel if needed, as the [Runnable data](#runnable-data) and [Parallel data](#parallel-data) highlights show. ## Keep research features beside prices \[#keep-research-features-beside-prices] You can attach calculated features to the same data object. This makes it easier to keep prices, indicator outputs, and model scores together for the next stage of research. The calculation can be a regular Python function whose argument names match the data fields: ```python title="Keep a custom feature beside prices" >>> research_close = pd.DataFrame( ... {"AAA": [100.0, 102.0, 104.0], "BBB": [50.0, 49.0, 51.0]}, ... index=pd.date_range("2024-01-01", periods=3, freq="D", tz="UTC"), ... ) >>> research_data = vbt.Data.from_data( ... vbt.feature_dict( ... { ... "Close": research_close, ... "High": research_close + 2, ... "Low": research_close - 2, ... } ... ) ... ) >>> def range_pct(high, low, close): ... return 100 * (high - low) / close >>> range_values = research_data.run(range_pct) >>> research_data = research_data.add_feature("RangePct", range_values) >>> research_data.features ['Close', 'High', 'Low', 'RangePct'] >>> research_data.get("RangePct").round(2) AAA BBB 2024-01-01 00:00:00+00:00 4.00 8.00 2024-01-02 00:00:00+00:00 3.92 8.16 2024-01-03 00:00:00+00:00 3.85 7.84 ``` One calculation adds the high-to-low range as a percentage of the close for both sample symbols at once. You can select it later by name or save it with the other features using the [storage methods](/features/data/data-storage-and-databases/). ## Universes and futures \[#universes-and-futures] Symbols can carry classes such as sector or exchange, which become column levels for grouping. For research on index members, build a membership table with the dates each symbol was in the index and use it as a mask, so the universe does not include stocks that only joined later. Continuous futures series should be rolled and back-adjusted before they are loaded, so that roll gaps do not appear as price moves. ## Errors \[#errors] Keep a large download moving with `skip_on_error=True`: VBT collects the available symbols and reports those that failed. Retry those symbols later and merge them into the dataset. ## Feature-oriented data \[#feature-oriented-data] New in 1.14.0 ✅ Keep your data organized the way you use it. VBT supports both symbol-oriented and feature-oriented storage: one table per instrument, or one table per field such as open, high, low, and close. Feature-oriented data makes those price tables directly available across symbols, ready for indicators and backtests. ```python title="Create a feature-oriented data instance from various portfolio time series" >>> data = vbt.YFData.pull(["AAPL", "MSFT", "GOOG"], tz_convert="UTC") >>> pf = data.run("from_random_signals", n=[10, 20, 30], seed=42) >>> pf_data = vbt.Data.from_data( ... vbt.feature_dict({ ... "cash": pf.cash, ... "assets": pf.assets, ... "asset_value": pf.asset_value, ... "value": pf.value ... }) ... ) >>> pf_data.get(feature="cash", symbol=(10, "AAPL")) Date 1980-12-12 05:00:00+00:00 100.000000 1980-12-15 05:00:00+00:00 100.000000 1980-12-16 05:00:00+00:00 100.000000 1980-12-17 05:00:00+00:00 100.000000 1980-12-18 05:00:00+00:00 100.000000 ... 2023-08-25 04:00:00+00:00 1837.648268 2023-08-28 04:00:00+00:00 1837.648268 2023-08-29 04:00:00+00:00 1837.648268 2023-08-30 04:00:00+00:00 1837.648268 2023-08-31 04:00:00+00:00 1837.648268 Name: (10, AAPL), Length: 10770, dtype: float64 ``` ## Parallel data \[#parallel-data] New in 1.10.0 ✅ Data fetching and updating can be easily parallelized. ```python title="Benchmark fetching multiple symbols serially and concurrently" >>> symbols = ["SPY", "TLT", "XLF", "XLE", "XLU", "XLK", "XLB", "XLP", "XLY", "XLI", "XLV"] >>> with vbt.Timer() as timer: ... data = vbt.YFData.pull(symbols) >>> print(timer.elapsed()) 4.52 seconds >>> with vbt.Timer() as timer: ... data = vbt.YFData.pull(symbols, execute_kwargs=dict(engine="threadpool")) >>> print(timer.elapsed()) 918.54 milliseconds ``` ## Runnable data \[#runnable-data] New in 1.5.0 ✅ Tired of figuring out which arguments are required by an indicator? Data instances can now recognize the arguments of any indicator or function, map them to column names, and run the function by passing in the required columns. You can also change the mapping, override indicator parameters, and query indicators by name. The data instance will search all integrated indicator packages and return the first (and best) match it finds. ```python title="Run Stochastic RSI by data" >>> data = vbt.YFData.pull("BTC-USD") >>> stochrsi = data.run("stochrsi") >>> stochrsi.fastd Date 2014-09-17 00:00:00+00:00 NaN 2014-09-18 00:00:00+00:00 NaN 2014-09-19 00:00:00+00:00 NaN 2014-09-20 00:00:00+00:00 NaN 2014-09-21 00:00:00+00:00 NaN ... 2023-01-15 00:00:00+00:00 96.168788 2023-01-16 00:00:00+00:00 91.733393 2023-01-17 00:00:00+00:00 78.295255 2023-01-18 00:00:00+00:00 48.793133 2023-01-20 00:00:00+00:00 26.242474 Name: Close, Length: 3047, dtype: float64 ``` ## Data parsing \[#data-parsing] New in 1.3.0 ✅ Tired of passing open, high, low, and close as separate time series? Portfolio class methods now accept a data instance instead of just close and automatically extract the contained OHLC data. This small but handy feature saves you time! ```python title="Backtest random signals from a data instance" >>> data = vbt.YFData.pull("BTC-USD", start="2020-01", end="2020-03") >>> pf = vbt.PF.from_random_signals(data, n=10, seed=42) ``` ## Data transformation \[#data-transformation] New in 1.2.3 ✅ After fetching data, how do you change it? There is a new method that puts all symbols into a single DataFrame and passes it to a UDF for transformation. ```python title="Remove weekends" >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"], start="2020-01-01", end="2020-01-14") >>> new_data = data.transform(lambda df: df[~df.index.weekday.isin([5, 6])]) >>> new_data.close symbol BTC-USD ETH-USD Date 2020-01-01 00:00:00+00:00 7200.174316 130.802002 2020-01-02 00:00:00+00:00 6985.470215 127.410179 2020-01-03 00:00:00+00:00 7344.884277 134.171707 2020-01-06 00:00:00+00:00 7769.219238 144.304153 2020-01-07 00:00:00+00:00 8163.692383 143.543991 2020-01-08 00:00:00+00:00 8079.862793 141.258133 2020-01-09 00:00:00+00:00 7879.071289 138.979202 2020-01-10 00:00:00+00:00 8166.554199 143.963776 2020-01-13 00:00:00+00:00 8144.194336 144.226593 ``` ## Data merging \[#data-merging] New in 1.1.0 ✅ Often, there is a need to backtest symbols from different exchanges by placing them in the same basket. For this purpose, VBT offers a class method that can merge multiple data instances into a single one. You can not only combine multiple symbols, but also merge datasets for a single symbol, all done automatically! ```python title="Pull BTC datasets from various exchanges and plot the last full year relative to their mean" >>> binance_data = vbt.CCXTData.pull("BTCUSDT", exchange="binance") >>> bybit_data = vbt.CCXTData.pull("BTCUSDT", exchange="bybit") >>> bitfinex_data = vbt.CCXTData.pull("BTC/USDT", exchange="bitfinex") >>> kucoin_data = vbt.CCXTData.pull("BTC-USDT", exchange="kucoin") >>> data = vbt.Data.merge([ ... binance_data.rename({"BTCUSDT": "Binance"}), ... bybit_data.rename({"BTCUSDT": "Bybit"}), ... bitfinex_data.rename({"BTC/USDT": "Bitfinex"}), ... kucoin_data.rename({"BTC-USDT": "KuCoin"}), ... ], missing_index="drop", silence_warnings=True) >>> @njit ... def rescale_nb(x): ... return (x - x.mean()) / x.mean() >>> rescaled_close = data.close.vbt.row_apply(rescale_nb) >>> rescaled_close = rescaled_close.vbt.rolling_mean(30) >>> last_full_year = rescaled_close.index[-1].year - 1 >>> rescaled_close.loc[str(last_full_year)].vbt.plot().show() ``` Rescaled BTC prices from Binance, Bybit, Bitfinex, and KuCoin during the last full calendar year. [Figure data (JSON)](/assets/figures/features/data/data-merging.ecc16eb2ecbd.json) # Data (/features/data) Bring market data into a research workflow, whether it comes from a provider such as Yahoo Finance, Binance, or TradingView, from a local file, or from a database. This section is for anyone who needs clean, aligned, and current data before testing a strategy. It covers data sources, storage and querying, pipelines that keep data up to date, combining timeframes by when their values become available, and synthetic prices for testing a strategy on paths that never happened. ## Start here \[#start-here] Begin with [Market data sources](/features/data/market-data-sources/) to pull your first dataset. Already have your data? Start with [Data storage and databases](/features/data/data-storage-and-databases/) for files and database queries, or [Data pipelines](/features/data/financial-data-pipelines/) for working with your own Pandas objects. | What do you want to do? | Where to start | | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Find a provider for stocks, crypto, futures, or FX | [Market data sources](/features/data/market-data-sources/) | | Bring chart data into Python or compare Binance spot and futures | [TradingView data](/features/data/tradingview-data/) and [Binance data](/features/data/binance-data/) | | Keep a local history and load only the data you need | [Data storage and databases](/features/data/data-storage-and-databases/) | | Align symbols with different histories, add research features, and update the dataset | [Data pipelines](/features/data/financial-data-pipelines/) | | Use a daily indicator with hourly entries | [Multi-timeframe analysis](/features/data/multi-timeframe-analysis/) | | Test a strategy on generated prices and different market conditions | [Synthetic data](/features/data/synthetic-data/) | * [Market data sources](/features/data/market-data-sources): Pull stock, crypto, futures, and FX data from many providers with one interface * [TradingView data](/features/data/tradingview-data): Pull TradingView bars for stocks, futures, crypto, and FX, and search its symbols * [Binance data](/features/data/binance-data): Download Binance spot and futures klines with trade counts and taker volume * [Data storage and databases](/features/data/data-storage-and-databases): Save and query market data in files, DuckDB, SQL databases, and ArcticDB * [Data pipelines](/features/data/financial-data-pipelines): Align, update, transform, and analyze multi-symbol market data in one object * [Multi-timeframe analysis](/features/data/multi-timeframe-analysis): Resample and realign data across timeframes by when each value became available * [Synthetic data](/features/data/synthetic-data): Generate reproducible random walks, GBM paths, and synthetic OHLC bars ## From data to a backtest \[#from-data-to-a-backtest] You can start with downloaded candles, saved files, or DataFrames from your own research. VBT's data object keeps symbols and features together, aligns their indexes, and lets you choose whether to retain each symbol's full history or work with their shared timestamps. Prices and custom features can then feed indicators and trading signals. For example, pull hourly prices for several coins, save the history locally, and compare a strategy across the same period for each coin. Add a daily trend filter with the multi-timeframe tools, then try the strategy on synthetic paths to explore how it behaves outside that history. Each part has its own feature page above, so you can use the pieces your research needs. Continue with [Technical indicators](/features/indicators/technical-indicators/) to calculate signals, or [Signal backtesting](/features/backtesting/signal-backtesting/) if your entry and exit conditions are ready. Use the [Data documentation](/documentation/data/) to learn how VBT represents, retrieves, updates, and manages market data. # Market data sources (/features/data/market-data-sources) Where can you get market data, and does every provider need its own code? VBT lets you download stock, crypto, futures, and FX data in Python from Yahoo Finance, Binance, CCXT exchanges, Alpaca, Polygon, Databento, TradingView, and more, with the same `pull` and `update` calls and the same data object at the end. ```python title="Download one year of Bitcoin from Binance and from Yahoo Finance" >>> kwargs = dict(start="2024-01-01", end="2025-01-01", timeframe="1d") >>> binance = vbt.BinanceData.pull("BTCUSDT", **kwargs) >>> yahoo = vbt.YFData.pull("BTC-USD", **kwargs) >>> close = pd.concat({"Binance": binance.close, "Yahoo": yahoo.close}, axis=1) >>> close.head(3).round(2) Binance Yahoo 2024-01-01 00:00:00+00:00 44179.55 44167.33 2024-01-02 00:00:00+00:00 44946.91 44957.97 2024-01-03 00:00:00+00:00 42845.23 42848.18 >>> (close["Yahoo"] / close["Binance"] - 1).abs().describe().round(5) # (1) count 366.00000 mean 0.00061 std 0.00056 min 0.00000 25% 0.00020 50% 0.00042 75% 0.00086 max 0.00363 dtype: float64 ``` 1. How far the two daily closes are apart, as a fraction of the price. Two providers, two symbols, one call shape. Their closes differ by 0.04% on a typical day and by up to 0.36%, because each source aggregates its own trades. Backtest on the data you will trade. ## One interface for every provider \[#one-interface-for-every-provider] Every provider class has the same methods. `pull` downloads one or many symbols for a date range and timeframe, splitting long ranges into as many requests as the provider needs. `update` fetches only what is new and appends it. The result is a `Data` object that holds every symbol and feature, saves to disk, and feeds indicators and backtests directly: ```python title="Download several symbols and update them later" >>> data = vbt.YFData.pull(["SPY", "QQQ", "TLT"], start="2024-01-01", end="2024-06-01") >>> data.symbols, data.close.shape (['SPY', 'QQQ', 'TLT'], (105, 3)) >>> data = data.update(end="2024-07-01") # (1) >>> data.close.shape (124, 3) ``` 1. Fetch from the last stored bar onward and append the new rows. Data objects never change in place, so assign the result of `update`. With most providers, it starts from the last stored bar, not the bar after it, because that bar may have been incomplete when it was downloaded, and replaces it with the provider's current version. Dates can be timestamps, strings, or phrases such as `"30 days ago"`, and the end date is exclusive. A symbol that fails stops the pull unless `skip_on_error=True`, which skips it with a warning, and a delay between requests keeps a large download within a provider's rate limit. ## Supported providers \[#supported-providers] | Provider | Class | Markets | | ----------------------------- | ----------------- | ---------------------------------------------- | | Yahoo Finance | `vbt.YFData` | Stocks, ETFs, indexes, FX, crypto | | Binance | `vbt.BinanceData` | Crypto spot and futures | | CCXT | `vbt.CCXTData` | Crypto on more than 100 exchanges | | Alpaca | `vbt.AlpacaData` | US stocks, crypto, options | | Massive (formerly Polygon.io) | `vbt.PolygonData` | Stocks, FX, crypto | | Databento | `vbt.BentoData` | Futures, equities, options | | Alpha Vantage | `vbt.AVData` | Stocks, FX, crypto, and other endpoints | | Nasdaq Data Link | `vbt.NDLData` | Datasets and data tables | | TradingView | `vbt.TVData` | Most markets that TradingView charts | | findatapy | `vbt.FinPyData` | Several sources, including Dukascopy tick data | VBT connects to these services using your provider account where one is required. Data subscriptions are separate from VBT PRO. Classes that use a Python client can configure it for you or reuse an existing client, so you can keep your current credentials and connection setup. Paid providers apply their own limits and charges, and `vbt.BentoData` can estimate the cost of a Databento request before you run it. It uses Databento's historical API, not its live feed. [Polygon.io is now Massive](https://www.massive.com/blog/polygon-is-now-massive). The VBT class is still named `vbt.PolygonData`, as in the example below. ## Choosing a market data source \[#choosing-a-market-data-source] Start with the instruments, history, and resolution your strategy needs. Daily bars are enough for many portfolio studies. An intraday strategy may need minute bars, individual trades, or bid and ask prices. The [Databento](#databento) and [FinDataPy](#findatapy) examples below show data beyond OHLCV, including BBO and FX ticks. Then choose the feed and subscription that cover your market and date range. The same symbol can have different prices, sessions, or adjustments across providers. Even the opening Bitcoin comparison uses a USDT pair on Binance and USD prices on Yahoo. A common interface makes it easier to compare sources, while the provider determines which observations you receive. Already have a data subscription or a collection of DataFrames? You can bring those into VBT too, as the [custom providers](#custom-providers) section shows. ## Crypto \[#crypto] `vbt.BinanceData` downloads spot klines and, with `klines_type`, USD-margined and coin-margined futures, as the [Binance data](/features/data/binance-data/) page shows. `vbt.CCXTData` reaches any exchange that CCXT supports with the same arguments, and can search for the earliest date an exchange still serves, since many exchanges return nothing for a range that starts before their history does. ## Stocks, futures, and FX \[#stocks-futures-and-fx] Yahoo Finance is the quickest start for daily stock data. Its prices are adjusted for splits and dividends by default, which is right for returns, while `auto_adjust=False` disables that automatic adjustment and keeps the adjusted close as a separate feature. VBT does not adjust prices itself, so use adjusted data, or adjust it before backtesting across a split. For intraday history, depth, or futures, the commercial providers in the table offer more choices, and their sections below show each one. You can also pull inputs beyond market prices. Alpha Vantage can return indicators such as the [Stochastic RSI example](#alpha-vantage) below. Nasdaq Data Link supports both time-series datasets and datatables, selected with `data_format="datatable"`, with table filters passed through to the provider. This opens up research with economic and fundamental datasets alongside prices. [Data pipelines](/features/data/financial-data-pipelines/) covers preparing and aligning the data for your strategy. ## TradingView \[#tradingview] `vbt.TVData` downloads bars for symbols in TradingView's notation, such as `NASDAQ:AAPL` or `BINANCE:BTCUSDT`, across stocks, futures, crypto, FX, and indexes, without an account. The [TradingView data](/features/data/tradingview-data/) page covers timeframes, sessions, symbol search, and history limits. ## Finding symbols \[#finding-symbols] Most providers can list their symbols with `list_symbols`, filtered with a glob or a regular expression, and TradingView can also list the members of an index: ```python title="List Binance symbols that match a pattern" >>> vbt.BinanceData.list_symbols("BTC*USDT") ['BTCDOWNUSDT', 'BTCSTUSDT', 'BTCUPUSDT', 'BTCUSDT'] ``` Symbols can be tagged with classes such as sector or asset type, which become column levels for grouping, as the [Symbol classes](#symbol-classes) highlight below shows. ## Custom providers \[#custom-providers] Your data does not have to come from a built-in provider. Use Pandas prices directly in indicators and backtests, or turn them into a `Data` object with `vbt.Data.from_data`. Here is a small example with made-up closing prices, one column per asset: ```python title="Use prices already in Pandas" >>> existing_close = pd.DataFrame( ... {"Asset A": [100.0, 102.0, 105.0], "Asset B": [50.0, 49.0, 51.0]}, ... index=pd.date_range("2024-01-01", periods=3, freq="D", tz="UTC"), ... ) >>> existing_data = vbt.Data.from_data(existing_close, columns_are_symbols=True) >>> existing_data.symbols ['Asset A', 'Asset B'] >>> existing_pf = vbt.PF.from_holding(existing_data.get()) >>> existing_pf.total_return.round(4) Asset A 0.05 Asset B 0.02 Name: total_return, dtype: float64 ``` The same approach works with DataFrames returned by another Python data library or your own loader. Keep your existing data source and use VBT for the research that follows. Any API can become a provider. Subclass `vbt.RemoteData`, implement how one symbol is fetched, and the class inherits pulling many symbols, updating, saving, and everything else on this page. Files behind a URL or in a cloud bucket can be read with the file classes on the [Data storage and databases](/features/data/data-storage-and-databases/) page. ## FinDataPy \[#findatapy] New in v2024.8.20 ✅ Introducing a new class for [findatapy](https://github.com/cuemacro/findatapy), designed to pull data from Bloomberg, Eikon, Quandl, Dukascopy, and other data sources. ```python title="Discover tickers on Dukascopy and pull one day of tick data" >>> vbt.FinPyData.list_symbols(data_source="dukascopy") ['fx.dukascopy.tick.NYC.AUDCAD', 'fx.dukascopy.tick.NYC.AUDCHF', 'fx.dukascopy.tick.NYC.AUDJPY', ... 'fx.dukascopy.tick.NYC.USDTRY', 'fx.dukascopy.tick.NYC.USDZAR', 'fx.dukascopy.tick.NYC.ZARJPY'] >>> data = vbt.FinPyData.pull( # (1) ... "fx.dukascopy.tick.NYC.EURUSD", ... start="14 Jun 2016", ... end="15 Jun 2016" ... ) >>> data.get() close Date 2016-06-14 00:00:00.844000+00:00 1.128795 2016-06-14 00:00:01.591000+00:00 1.128790 2016-06-14 00:00:01.743000+00:00 1.128775 2016-06-14 00:00:02.464000+00:00 1.128770 2016-06-14 00:00:02.971000+00:00 1.128760 ... ... 2016-06-14 23:59:57.733000+00:00 1.121020 2016-06-14 23:59:58.239000+00:00 1.121030 2016-06-14 23:59:58.953000+00:00 1.121035 2016-06-14 23:59:59.004000+00:00 1.121050 2016-06-14 23:59:59.934000+00:00 1.121055 [82484 rows x 1 columns] >>> data = vbt.FinPyData.pull( # (2) ... "EURUSD", ... start="14 Jun 2016", ... end="15 Jun 2016", ... timeframe="tick", ... category="fx", ... data_source="dukascopy", ... fields=["bid", "ask", "bidv", "askv"] ... ) >>> data.get() bid ask bidv askv Date 2016-06-14 00:00:00.844000+00:00 1.12877 1.12882 1.00 10.12 2016-06-14 00:00:01.591000+00:00 1.12877 1.12881 1.00 1.00 2016-06-14 00:00:01.743000+00:00 1.12875 1.12880 3.11 3.00 2016-06-14 00:00:02.464000+00:00 1.12875 1.12879 2.21 1.00 2016-06-14 00:00:02.971000+00:00 1.12875 1.12877 2.21 1.00 ... ... ... ... ... 2016-06-14 23:59:57.733000+00:00 1.12100 1.12104 1.24 1.50 2016-06-14 23:59:58.239000+00:00 1.12101 1.12105 9.82 1.12 2016-06-14 23:59:58.953000+00:00 1.12102 1.12105 1.50 1.12 2016-06-14 23:59:59.004000+00:00 1.12103 1.12107 1.50 1.12 2016-06-14 23:59:59.934000+00:00 1.12103 1.12108 1.87 2.25 [82484 rows x 4 columns] ``` 1. String format. 2. Keyword format. ## Databento \[#databento] New in v2023.12.23 ✅ Introducing a new class specialized in pulling data from [Databento](https://databento.com/). ```python title="Get best bid and offer (BBO) data from Databento" >>> vbt.BentoData.set_custom_settings( ... client_config=dict( ... key="YOUR_KEY" ... ) ... ) >>> params = dict( ... symbols="ESH3", ... dataset="GLBX.MDP3", ... start=vbt.timestamp("2022-10-28 20:30:00"), ... end=vbt.timestamp("2022-10-28 21:00:00"), ... schema="tbbo" ... ) >>> vbt.BentoData.get_cost(**params) 1.2002885341644287e-05 >>> data = vbt.BentoData.pull(**params) >>> data.get() ts_event \ ts_recv 2022-10-28 20:30:59.047138053+00:00 2022-10-28 20:30:59.046914657+00:00 2022-10-28 20:37:53.112494436+00:00 2022-10-28 20:37:53.112246421+00:00 ... 2022-10-28 20:59:15.075191111+00:00 2022-10-28 20:59:15.074953895+00:00 2022-10-28 20:59:34.607239899+00:00 2022-10-28 20:59:34.606984277+00:00 rtype publisher_id instrument_id \ ts_recv 2022-10-28 20:30:59.047138053+00:00 1 1 206299 2022-10-28 20:37:53.112494436+00:00 1 1 206299 ... 2022-10-28 20:59:15.075191111+00:00 1 1 206299 2022-10-28 20:59:34.607239899+00:00 1 1 206299 action side depth price size flags \ ts_recv 2022-10-28 20:30:59.047138053+00:00 T B 0 3955.25 1 0 2022-10-28 20:37:53.112494436+00:00 T A 0 3955.00 1 0 ... 2022-10-28 20:59:15.075191111+00:00 T A 0 3953.75 1 0 2022-10-28 20:59:34.607239899+00:00 T A 0 3954.50 2 0 ts_in_delta sequence bid_px_00 \ ts_recv 2022-10-28 20:30:59.047138053+00:00 18553 73918214 3954.75 2022-10-28 20:37:53.112494436+00:00 18334 73926240 3955.00 ... 2022-10-28 20:59:15.075191111+00:00 19294 73945515 3953.75 2022-10-28 20:59:34.607239899+00:00 18701 73945932 3954.50 ask_px_00 bid_sz_00 ask_sz_00 \ ts_recv 2022-10-28 20:30:59.047138053+00:00 3955.25 1 1 2022-10-28 20:37:53.112494436+00:00 3955.75 1 1 ... 2022-10-28 20:59:15.075191111+00:00 3956.00 1 1 2022-10-28 20:59:34.607239899+00:00 3956.00 4 1 bid_ct_00 ask_ct_00 symbol ts_recv 2022-10-28 20:30:59.047138053+00:00 1 1 ESH3 2022-10-28 20:37:53.112494436+00:00 1 1 ESH3 ... 2022-10-28 20:59:15.075191111+00:00 1 1 ESH3 2022-10-28 20:59:34.607239899+00:00 3 1 ESH3 ``` ## Symbol search \[#symbol-search] New in 1.7.0 ✅ Most data classes can retrieve the complete list of symbols available for an exchange, and optionally filter the list using a [globbing](https://en.wikipedia.org/wiki/Glob_\(programming\)) or [regular expression](https://en.wikipedia.org/wiki/Regular_expression) pattern. This also works for local data classes. ```python title="Get all XRP pairs listed on Binance" >>> vbt.BinanceData.list_symbols("XRP*") ['XRPAUD', 'XRPBEARBUSD', 'XRPBEARUSDT', 'XRPBIDR', 'XRPBKRW', 'XRPBNB', 'XRPBRL', 'XRPBTC', 'XRPBULLBUSD', 'XRPBULLUSDT', 'XRPBUSD', 'XRPDOWNUSDT', 'XRPETH', 'XRPEUR', 'XRPGBP', 'XRPNGN', 'XRPPAX', 'XRPRUB', 'XRPTRY', 'XRPTUSD', 'XRPUPUSDT', 'XRPUSDC', 'XRPUSDT'] ``` ## Symbol classes \[#symbol-classes] New in 1.7.0 ✅ Since VBT uses multi-indexes in Pandas, you can associate each symbol with one or more classes, such as sectors. This allows you to analyze the performance of a trading strategy relative to each class. ```python title="Compare equal-weighted portfolios for three sectors" >>> classes = vbt.symbol_dict({ ... "MSFT": dict(sector="Technology"), ... "GOOGL": dict(sector="Technology"), ... "META": dict(sector="Technology"), ... "JPM": dict(sector="Finance"), ... "BAC": dict(sector="Finance"), ... "WFC": dict(sector="Finance"), ... "AMZN": dict(sector="Retail"), ... "WMT": dict(sector="Retail"), ... "BABA": dict(sector="Retail"), ... }) >>> data = vbt.YFData.pull( ... list(classes.keys()), ... classes=classes, ... missing_index="drop" ... ) >>> pf = vbt.PF.from_orders( ... data, ... size=vbt.index_dict({0: 1 / 3}), # (1) ... size_type="targetpercent", ... group_by="sector", ... cash_sharing=True ... ) >>> pf.value.vbt.plot().show() ``` 1. There are three assets in each group. Allocate 33.3% to each asset at the first bar. Equal-weighted Technology, Finance, and Retail portfolio values over time. [Figure data (JSON)](/assets/figures/features/data/classes.dc2278f36b04.json) ## Polygon.io \[#polygonio] New in 1.1.1 ✅ Welcome a new class specialized in pulling data from [Polygon.io](https://polygon.io/)! ```python title="Get one month of 30-minute AAPL data from Polygon.io" >>> vbt.PolygonData.set_custom_settings( ... client_config=dict( ... api_key="YOUR_API_KEY" ... ) ... ) >>> data = vbt.PolygonData.pull( ... "AAPL", ... start="2022-12-01", # (1) ... end="2023-01-01", ... timeframe="30 minutes", ... tz="US/Eastern" ... ) >>> data.get() Open High Low Close Volume \ Open time 2022-12-01 04:00:00-05:00 148.08 148.08 147.04 147.3700 50886.0 2022-12-01 04:30:00-05:00 147.37 147.37 147.12 147.2600 16575.0 2022-12-01 05:00:00-05:00 147.31 147.51 147.20 147.3800 20753.0 2022-12-01 05:30:00-05:00 147.43 147.56 147.38 147.3800 7388.0 2022-12-01 06:00:00-05:00 147.30 147.38 147.24 147.2400 7416.0 ... ... ... ... ... ... 2022-12-30 17:30:00-05:00 129.94 130.05 129.91 129.9487 35694.0 2022-12-30 18:00:00-05:00 129.95 130.00 129.94 129.9500 15595.0 2022-12-30 18:30:00-05:00 129.94 130.05 129.94 130.0100 20287.0 2022-12-30 19:00:00-05:00 129.99 130.04 129.99 130.0000 12490.0 2022-12-30 19:30:00-05:00 130.00 130.04 129.97 129.9700 28271.0 Trade count VWAP Open time 2022-12-01 04:00:00-05:00 1024 147.2632 2022-12-01 04:30:00-05:00 412 147.2304 2022-12-01 05:00:00-05:00 306 147.3466 2022-12-01 05:30:00-05:00 201 147.4818 2022-12-01 06:00:00-05:00 221 147.2938 ... ... ... 2022-12-30 17:30:00-05:00 350 129.9672 2022-12-30 18:00:00-05:00 277 129.9572 2022-12-30 18:30:00-05:00 312 130.0034 2022-12-30 19:00:00-05:00 176 130.0140 2022-12-30 19:30:00-05:00 366 129.9941 [672 rows x 7 columns] ``` 1. In the timezone provided via `tz`. ## Alpha Vantage \[#alpha-vantage] New in 1.1.1 ✅ Welcome a new class specialized in pulling data from [Alpha Vantage](https://www.alphavantage.co/)! ```python title="Get Stochastic RSI of IBM from Alpha Vantage" >>> data = vbt.AVData.pull( ... "IBM", ... category="technical-indicators", ... function="STOCHRSI", ... params=dict(fastkperiod=14) ... ) >>> data.get() FastD FastK 1999-12-07 00:00:00+00:00 100.0000 100.0000 1999-12-08 00:00:00+00:00 100.0000 100.0000 1999-12-09 00:00:00+00:00 77.0255 31.0765 1999-12-10 00:00:00+00:00 43.6922 0.0000 1999-12-13 00:00:00+00:00 12.0197 4.9826 ... ... ... 2023-01-26 00:00:00+00:00 11.7960 0.0000 2023-01-27 00:00:00+00:00 3.7773 0.0000 2023-01-30 00:00:00+00:00 4.4824 13.4471 2023-01-31 00:00:00+00:00 7.8258 10.0302 2023-02-01 16:00:01+00:00 13.0966 15.8126 [5826 rows x 2 columns] ``` ## Nasdaq Data Link \[#nasdaq-data-link] New in 1.1.1 ✅ Welcome a new class specialized in pulling data from [Nasdaq Data Link](https://data.nasdaq.com/)! ```python title="Get Index of Consumer Sentiment from Nasdaq Data Link" >>> data = vbt.NDLData.pull("UMICH/SOC1") >>> data.get() Index Date 1952-11-30 00:00:00+00:00 86.2 1953-02-28 00:00:00+00:00 90.7 1953-08-31 00:00:00+00:00 80.8 1953-11-30 00:00:00+00:00 80.7 1954-02-28 00:00:00+00:00 82.0 ... ... 2022-08-31 00:00:00+00:00 58.2 2022-09-30 00:00:00+00:00 58.6 2022-10-31 00:00:00+00:00 59.9 2022-11-30 00:00:00+00:00 56.8 2022-12-31 00:00:00+00:00 59.7 [632 rows x 1 columns] ``` ## Alpaca \[#alpaca] New in 1.0.2 ✅ Welcome a new class specialized in pulling data from [Alpaca](https://alpaca.markets/)! ```python title="Get one week of adjusted 1-minute AAPL data from Alpaca" >>> vbt.AlpacaData.set_custom_settings( ... client_config=dict( ... api_key="YOUR_API_KEY", ... secret_key="YOUR_API_SECRET" ... ) ... ) >>> data = vbt.AlpacaData.pull( ... "AAPL", ... start="one week ago 00:00", # (1) ... end="15 minutes ago", # (2) ... timeframe="1 minute", ... adjustment="all", ... tz="US/Eastern" ... ) >>> data.get() Open High Low Close Volume \ Open time 2023-01-30 04:00:00-05:00 145.5400 145.5400 144.0100 144.0200 5452.0 2023-01-30 04:01:00-05:00 144.0800 144.0800 144.0000 144.0500 3616.0 2023-01-30 04:02:00-05:00 144.0300 144.0400 144.0100 144.0100 1671.0 2023-01-30 04:03:00-05:00 144.0100 144.0300 144.0000 144.0300 4721.0 2023-01-30 04:04:00-05:00 144.0200 144.0200 144.0200 144.0200 1343.0 ... ... ... ... ... ... 2023-02-03 19:54:00-05:00 154.3301 154.3301 154.3301 154.3301 347.0 2023-02-03 19:55:00-05:00 154.3300 154.3400 154.3200 154.3400 1438.0 2023-02-03 19:56:00-05:00 154.3400 154.3400 154.3300 154.3300 588.0 2023-02-03 19:58:00-05:00 154.3500 154.3500 154.3500 154.3500 555.0 2023-02-03 19:59:00-05:00 154.3400 154.3900 154.3300 154.3900 3835.0 Trade count VWAP Open time 2023-01-30 04:00:00-05:00 165 144.376126 2023-01-30 04:01:00-05:00 81 144.036336 2023-01-30 04:02:00-05:00 52 144.035314 2023-01-30 04:03:00-05:00 56 144.012680 2023-01-30 04:04:00-05:00 40 144.021854 ... ... ... 2023-02-03 19:54:00-05:00 21 154.331340 2023-02-03 19:55:00-05:00 38 154.331756 2023-02-03 19:56:00-05:00 17 154.338971 2023-02-03 19:58:00-05:00 27 154.343090 2023-02-03 19:59:00-05:00 58 154.357219 [4224 rows x 7 columns] ``` 1. In the timezone provided via `tz`. 2. Remove if you have a paid plan. # Multi-timeframe analysis (/features/data/multi-timeframe-analysis) How do you use a daily indicator on hourly bars without peeking into the future? When a daily bar is labeled with the time it opens, its close is still only known when it ends. VBT resamples and realigns data by when each value became available, helping you avoid look-ahead bias in multi-timeframe backtests in Python. ```python title="Filter hourly entries with a daily trend, aligned naively and safely" >>> h1_data = vbt.GBMOHLCData.pull( # (1) ... "SYN", ... start="2024-01-01", ... end="2025-01-01", ... timeframe="1h", ... std=0.002, ... seed=7, ... ) >>> d1_data = h1_data.resample("1d") # (2) >>> d1_uptrend = d1_data.close > d1_data.close.rolling(10).mean() >>> naive_filter = d1_uptrend.reindex(h1_data.index, method="ffill") # (3) >>> safe_filter = ( ... d1_uptrend.vbt.realign_closing(h1_data.index) # (4) ... .fillna(False) ... .astype(bool) ... ) >>> h1_sma = h1_data.close.rolling(24).mean() >>> entries = h1_data.close.vbt.crossed_above(h1_sma) >>> exits = h1_data.close.vbt.crossed_below(h1_sma) >>> pf = vbt.PF.from_signals( ... h1_data, ... entries=pd.concat({ ... "naive": entries & naive_filter, ... "safe": entries & safe_filter, ... }, axis=1), ... exits=exits, ... fees=0.0005, ... ) >>> pf.stats(["total_return", "sharpe_ratio", "win_rate", "total_trades"], agg_func=None) Total Return [%] Sharpe Ratio Win Rate [%] Total Trades naive 42.179045 0.863159 26.050420 239 safe -56.766534 -1.172668 18.552036 222 >>> pf.value.vbt.plot().show() ``` 1. A year of seeded synthetic hourly bars, so the result does not depend on a data provider. 2. Aggregate hourly bars into daily bars: first open, highest high, lowest low, last close. 3. The pandas way: each daily value is copied to every hour from the label of its day onward. 4. The safe way: each daily value becomes available on the hourly bar where that day closes. Portfolio value of an hourly strategy with a daily trend filter aligned naively and safely in 2024. [Figure data (JSON)](/assets/figures/features/data/mtf-naive-vs-safe.ead37995507f.json) The naive version looks profitable, and it is wrong. On a day when the daily close crosses above its average, the naive filter turns on at midnight, 23 hours before that close exists: ```python title="Compare when each filter turns on" >>> filters = pd.DataFrame({"naive": naive_filter, "safe": safe_filter}) >>> filters.loc["2024-01-28 23:00":"2024-01-30 00:00"].iloc[[0, 1, 2, 22, 23, 24, 25]] naive safe 2024-01-28 23:00:00+00:00 False False 2024-01-29 00:00:00+00:00 True False 2024-01-29 01:00:00+00:00 True False 2024-01-29 21:00:00+00:00 True False 2024-01-29 22:00:00+00:00 True False 2024-01-29 23:00:00+00:00 True True 2024-01-30 00:00:00+00:00 True True ``` With the filter aligned to when the information existed, the same strategy loses money. The gap between the two curves is entirely look-ahead bias. The hourly row labeled `23:00` represents the bar from 23:00 to midnight. Its close and the daily close become known together at the end of that bar. The safe filter on that row is for a decision at the bar's close. For execution on the next bar, the [signal backtesting page](/features/backtesting/signal-backtesting/) covers delaying signals. ## Combine timeframes in one strategy \[#combine-timeframes-in-one-strategy] Give each timeframe a job, then align the results to the bars on which you make decisions: | Research idea | How to build it | | ------------------------------------------------------- | ----------------------------------------------------------------------- | | Trade hourly entries only when the daily trend agrees | Calculate the daily filter and align it to hourly closes, as above | | Use a four-hour momentum signal with 15-minute entries | Compute on four-hour bars and realign the output to the 15-minute index | | Compare the same indicator on several timeframes | Pass a list to the TA-Lib `timeframe` parameter | | Review a minute-by-minute simulation as monthly returns | Resample the completed portfolio for reporting | Start with data at the finest resolution your strategy needs. One minute-bar dataset can supply five-minute, hourly, and daily views. You can also combine data that was downloaded at different resolutions by realigning each result to a common target index. ## Opening and closing alignment \[#opening-and-closing-alignment] Two rules cover most cases. Values derived from the open of a bar are known at its start and are realigned with `realign_opening`. Values derived from its close, high, low, or volume are known at its end and are realigned with `realign_closing`. Indicators computed from closes follow the closing rule. Both work in either direction: downsampling hourly data to daily bars, or bringing daily values back onto hourly bars. Realigned masks come back as floats, with `NaN` on the bars before the first value is known. Fill them with `False` before casting, as `safe_filter` does above, because `NaN` cast to a boolean is `True` and would switch the filter on from the first bar. `data.resample()` aggregates whole OHLCV datasets with the right function for each column, and `vbt.Resampler` maps between any two indexes, including irregular ones and custom bounds such as trading sessions. The [Safe resampling](#safe-resampling) highlight below runs one indicator on daily, weekly, and monthly closes and shows all three on daily bars. Build daily bars from intraday data, or carry a completed daily level into an hourly strategy. VBT handles both aggregation and alignment, so each timeframe can play its own role in the same backtest. For datasets with extra fields, custom aggregation rules can say how those fields behave when resampled. VBT's provider classes already include rules for fields such as Binance quote volume. ## Resampling whole objects \[#resampling-whole-objects] Data is not the only thing that can change timeframe. Indicators, records, and whole portfolios resample too, each with rules for its parts: prices take the last value, cash flows are summed, and orders keep their timestamps. A common pattern is to simulate on fine bars for accurate fills and analyze on coarse bars for speed and readability, as in the [Resamplable objects](#resamplable-objects) highlight below. Resampling the finished portfolio changes the reporting frequency. To test trading decisions on a different timeframe, resample the inputs and run the simulation at that timeframe. ## Frequencies \[#frequencies] Annualized metrics and resampling need the bar frequency. VBT infers it from a sample of consecutive timestamps, which works even with occasional gaps. When the data starts irregularly or has no regular spacing, pass `freq` explicitly or set it once in `vbt.settings.wrapping["freq"]`. Indexes with different datetime resolutions, such as milliseconds and nanoseconds, should be converted to the same resolution before realigning. ## Indicators on other timeframes \[#indicators-on-other-timeframes] Every TA-Lib indicator takes a `timeframe` argument. The input is resampled to that timeframe, the indicator is computed there, and the output is realigned safely to the original bars, so a list of timeframes becomes a parameter like any other. Other indicators take the same three steps by hand: resample the input, compute the indicator, and realign the output with `realign_closing`. The [TA-Lib timeframes](#ta-lib-timeframes) highlight below runs one indicator on three timeframes. The indicator's window is measured in bars of the calculation timeframe. A 14-period daily SMA uses 14 daily closes, while a 14-period hourly SMA uses 14 hourly closes. The daily result is then carried back onto the hourly index, where it changes as each new daily value becomes available. You can compare timeframe choices alongside other parameters using [parameter optimization](/features/optimization/strategy-optimization/). A completed higher-timeframe bar is only known at its end. Some platforms instead update the indicator on every lower bar using the bar that is still forming. That gives earlier values that change until the bar closes. If you need that behavior, compute it explicitly from the partial bar at each step, and backtest with the values exactly as they were at the time. !!! info "Tutorial" The members-only [MTF analysis](https://members.vectorbt.pro/tutorials/mtf-analysis/resampling/) tutorial covers resampling, alignment, and aggregation in depth. ## Safe resampling \[#safe-resampling] New in 1.1.2 ✅ [Look-ahead bias](https://www.investopedia.com/terms/l/lookaheadbias.asp) is an ongoing risk when working with array data, especially on multiple timeframes. Using Pandas alone is strongly discouraged because it does not recognize that financial data mainly involves bars where timestamps are the opening times, and events may occur at any time between bars. Pandas thus incorrectly assumes that timestamps indicate the exact time of an event. In VBT, there is a complete collection of functions and classes for safely resampling and analyzing data! ```python title="Calculate SMA on multiple timeframes and display on the same chart" >>> def mtf_sma(close, close_freq, target_freq, timeperiod=5): ... target_close = close.vbt.realign_closing(target_freq) # (1) ... target_sma = vbt.talib("SMA").run(target_close, timeperiod=timeperiod).real # (2) ... target_sma = target_sma.rename(f"SMA ({target_freq})") ... return target_sma.vbt.realign_closing(close.index, freq=close_freq) # (3) >>> data = vbt.YFData.pull("BTC-USD", start="2020", end="2023") >>> fig = mtf_sma(data.close, "D", "daily").vbt.plot() >>> mtf_sma(data.close, "D", "weekly").vbt.plot(fig=fig) >>> mtf_sma(data.close, "D", "monthly").vbt.plot(fig=fig) >>> fig.show() ``` 1. Resample the source frequency to the target frequency. Since Close occurs at the end of the bar, resample it as a "closing event". 2. Calculate the SMA on the target frequency. 3. Resample the target frequency back to the source frequency to show multiple timeframes on the same chart. Because `close` contains gaps, you cannot simply resample to `close_freq` as this might produce unaligned series. Instead, resample directly to the index of `close`. Bitcoin simple moving averages calculated on daily, weekly, and monthly timeframes. [Figure data (JSON)](/assets/figures/features/productivity/safe-resampling.5bdd558681a0.json) !!! info "Tutorial" Learn more in the [MTF analysis](/tutorials/mtf-analysis) tutorial. ## Resamplable objects \[#resamplable-objects] New in 1.1.2 ✅ You can resample not only time series, but also complex VBT objects! Under the hood, each object is made up of a collection of array-like attributes, so resampling means aggregating all the related information together. This is especially helpful if you want to simulate at a higher frequency for maximum accuracy and then analyze at a lower frequency for better speed. ```python title="Plot the monthly return heatmap of a random portfolio" >>> import calendar >>> data = vbt.YFData.pull("BTC-USD", start="2018", end="2023") >>> pf = vbt.PF.from_random_signals(data, n=100, direction="both", seed=42) >>> mo_returns = pf.resample("M").returns # (1) >>> mo_return_matrix = pd.Series( ... mo_returns.values, ... index=pd.MultiIndex.from_arrays([ ... mo_returns.index.year, ... mo_returns.index.month ... ], names=["year", "month"]) ... ).unstack("month") >>> mo_return_matrix.columns = mo_return_matrix.columns.map(lambda x: calendar.month_abbr[x]) >>> mo_return_matrix.vbt.heatmap( ... is_x_category=True, ... trace_kwargs=dict(zmid=0, colorscale="Spectral") ... ).show() ``` 1. Resample the entire portfolio to monthly frequency and calculate the returns. Monthly return heatmap for a seeded random Bitcoin portfolio from 2018 through 2022. [Figure data (JSON)](/assets/figures/features/productivity/monthly-return-heatmap.36c65fb0009f.json) !!! info "Tutorial" Learn more in the [MTF analysis](/tutorials/mtf-analysis) tutorial. ## TA-Lib timeframes \[#ta-lib-timeframes] New in 1.2.0 ✅ Comparing indicators on different timeframes involves many nuances. Now, all TA-Lib indicators support a parameter that resamples the input arrays to a target timeframe, calculates the indicator, and then resamples the output arrays back to the original timeframe. This makes parameterized MTF analysis easier than ever! ```python title="Run SMA on multiple timeframes and display the whole thing as a heatmap" >>> h1_data = vbt.BinanceData.pull( ... "BTCUSDT", ... start="3 months ago UTC", ... timeframe="1h" ... ) >>> mtf_sma = vbt.talib("SMA").run( ... h1_data.close, ... timeperiod=14, ... timeframe=["1d", "4h", "1h"], ... skipna=True ... ) >>> mtf_sma.real.vbt.ts_heatmap().show() ``` BTCUSDT simple moving averages across hourly, four-hour, and daily timeframes. [Figure data (JSON)](/assets/figures/features/indicators/ta-lib-time-frames.a70363fe5509.json) !!! info "Tutorial" Learn more in the [MTF analysis](/tutorials/mtf-analysis) tutorial. # Synthetic data (/features/data/synthetic-data) How does a strategy behave on prices that never happened? VBT generates synthetic price data in Python: random walks, geometric Brownian motion, and full OHLC bars, reproducible with a seed and returned as the same data object as real market data. Running a strategy on hundreds of synthetic paths shows the range of results a strategy can produce under a chosen model. ```python title="Run one strategy on 500 random price paths" >>> paths = vbt.GBMData.pull( # (1) ... [f"path_{i}" for i in range(500)], ... start="2020-01-01", ... end="2024-01-01", ... timeframe="1d", ... seed=42, ... ) >>> close = paths.get() >>> close.shape (1461, 500) >>> fast = close.rolling(20).mean() >>> slow = close.rolling(50).mean() >>> pf = vbt.PF.from_signals( ... close, ... fast.vbt.crossed_above(slow), ... fast.vbt.crossed_below(slow), ... fees=0.001, ... ) >>> pf.sharpe_ratio.describe().round(3) count 500.000 mean -0.096 std 0.494 min -1.598 25% -0.437 50% -0.129 75% 0.224 max 1.754 Name: sharpe_ratio, dtype: float64 >>> print(round((pf.sharpe_ratio > 0).mean(), 3)) 0.406 >>> pf.sharpe_ratio.vbt.histplot(trace_kwargs=dict(nbinsx=40)).show() ``` 1. Geometric Brownian motion with zero drift and 1% daily volatility, one independent path per symbol. No predictable trend is built into the model. Histogram of Sharpe ratios of a moving average crossover strategy on 500 synthetic random price paths. [Figure data (JSON)](/assets/figures/features/data/synthetic-sharpe-distribution.de0439809b7d.json) Even with no predictable trend built into the model, the crossover had a positive Sharpe ratio on 41% of the paths, and the best path reached 1.75. This gives you a comparison for the same strategy on historical data. Look at the distribution across paths, rather than treating the best simulated result as a universal pass mark. ## What can you test with synthetic data? \[#what-can-you-test-with-synthetic-data] Use generated paths when you want control over the conditions: * Compare strategy changes on the same seeded prices. * Try calmer or more volatile markets without changing the strategy. * Exercise stop, limit, and signal logic on generated OHLC bars. * Check whether an unexpectedly strong result also appears on random data. The generated data works with the same indicators, backtests, and plots as downloaded data, and needs no data-provider account. For broader validation on historical data, see [robustness and overfitting](/features/optimization/robustness-and-overfitting/). ## Generators \[#generators] `vbt.RandomData` compounds normally distributed returns, and `vbt.GBMData` simulates geometric Brownian motion. Both take a start value, a mean, a standard deviation, and a seed, which can differ per symbol, and both produce any number of symbols on any index or timeframe. With a seed, every run gives the same paths, so experiments on synthetic data are as reproducible as those on stored data. For random returns, `symmetric=True` transforms losses so that a gain and a loss of the same size cancel out multiplicatively, which removes the downward drift of plain returns. You can use an asset's returns to estimate the generator parameters. `RandomData` takes the mean and standard deviation of sampled returns. For GBM, choose drift, volatility, and `dt` consistently with the time step you are modeling. These describe a simple model: volatility stays constant, and there is no clustering, no autocorrelation, and no fat tails. These generators test whether a rule finds structure in noise, not how it would trade a real market. For more realistic dynamics, write your own model as shown below. ## Compare market scenarios \[#compare-market-scenarios] Parameters can differ by symbol, so each symbol can represent a scenario. Here both paths use the same random draws, with different volatility settings: ```python title="Compare volatility scenarios with the same random draws" >>> scenarios = vbt.GBMData.pull( ... ["calm", "volatile"], ... start="2024-01-01", ... periods=252, ... timeframe="1d", ... mean=0.0, ... std=vbt.symbol_dict({"calm": 0.005, "volatile": 0.02}), ... seed=42, ... split_seed=False, ... ) >>> scenarios.get().shape (252, 2) >>> (scenarios.get().pct_change().std() * 100).round(2) symbol calm 0.48 volatile 1.94 dtype: float64 ``` The output is the sample standard deviation of daily returns, in percent. `split_seed=False` keeps the random draws the same across these scenarios so you can isolate the volatility change. By default, VBT derives a separate seed for each symbol, as in the 500-path example. Pass `scenarios.get()` to your strategy to compare how it behaves in the two settings. ## Synthetic OHLC bars \[#synthetic-ohlc-bars] `vbt.RandomOHLCData` and `vbt.GBMOHLCData` simulate ticks within each bar and aggregate them into open, high, low, and close, so stops, limits, and intrabar logic can be tested as well. The number of simulated ticks is controlled by `n_ticks`, which can also vary by bar. The [Synthetic OHLC](#synthetic-ohlc) highlight below plots the resulting candles. Real data can be turned into synthetic data too. `data.mirror_ohlc()` reverses log returns and transforms the other OHLC prices around the mirrored path. Compare a strategy on the original and its mirror to explore how much its behavior changes when price moves reverse direction. ## Custom generators \[#custom-generators] Any model becomes a data class. Subclass `vbt.SyntheticData` and return a series for each symbol, and the class handles symbols, seeds, and indexes like any other data source. You can also provide an update method that continues your model from its previous state. Here returns follow a Student's t distribution, which produces the fat tails that normal returns lack: ```python title="Generate fat-tailed price paths with a custom class" >>> class StudentTData(vbt.SyntheticData): ... @classmethod ... def generate_key( ... cls, key, index, df=3, scale=0.01, start_value=100.0, seed=None, **kwargs ... ): ... if seed is not None: ... np.random.seed(seed) ... returns = np.random.standard_t(df, size=len(index)) * scale ... return pd.Series(start_value * np.cumprod(1 + returns), index=index) >>> fat = StudentTData.pull( ... ["A", "B"], ... start="2024-01-01", ... end="2025-01-01", ... timeframe="1d", ... seed=42, ... ) >>> fat.get().pct_change().kurt().round(2) # (1) symbol A 5.60 B 10.26 dtype: float64 ``` 1. Excess kurtosis well above zero, the value for normally distributed returns. ## Synthetic OHLC \[#synthetic-ohlc] New in 1.2.1 ✅ New basic models are available for generating synthetic OHLC data. These are especially useful for leakage detection. ```python title="Generate 3 months of synthetic data using Geometric Brownian Motion" >>> data = vbt.GBMOHLCData.pull("R", start="2022-01", end="2022-04", seed=42) >>> data.plot().show() ``` Three months of synthetic OHLC data generated with geometric Brownian motion. [Figure data (JSON)](/assets/figures/features/data/synthetic-ohlc.2cf9918db1d2.json) # TradingView data (/features/data/tradingview-data) How do you get TradingView data into Python? `vbt.TVData` pulls bars for stocks, futures, crypto, FX, and indexes in TradingView's own symbol notation, without an account, and returns them as one data object ready for indicators and backtests. ```python title="Pull daily bars for six markets in one call and compare 2024" >>> symbols = [ ... "NASDAQ:AAPL", "CME_MINI:ES1!", "BINANCE:BTCUSDT", ... "TVC:DXY", "FX:EURUSD", "TVC:GOLD", ... ] >>> data = vbt.TVData.pull(symbols, timeframe="1D") # (1) >>> year = data.loc["2024"] >>> first = year.close.apply(lambda s: s.dropna().iloc[0]) >>> last = year.close.apply(lambda s: s.dropna().iloc[-1]) >>> returns = (last / first - 1).round(4) >>> pd.DataFrame({"bars": year.close.notna().sum(), "return": returns}) bars return symbol NASDAQ:AAPL 252 0.3490 CME_MINI:ES1! 252 0.2399 BINANCE:BTCUSDT 366 1.1181 TVC:DXY 259 0.0614 FX:EURUSD 260 -0.0534 TVC:GOLD 252 0.2747 ``` 1. Downloads each symbol's available history, from the most recent bar back. The bars arrive in UTC on one shared index, with NaN where a market was closed. A stock, a continuous futures contract, a crypto pair, the dollar index, a currency pair, and gold came back in one call. Each market keeps its own calendar: Bitcoin traded on all 366 days of 2024, stocks on 252, and FX on 260, which is why each column above counts its own bars. ## From chart data to Python research \[#from-chart-data-to-python-research] Use the symbols you already follow on TradingView as inputs to a Python strategy. Once pulled, `data.close` gives you prices across symbols, and `data.run` can compute indicators from the available OHLCV fields. Pass the data and your entry and exit signals into a [signal backtest](/features/backtesting/signal-backtesting/), then compare instruments and [parameter choices](/features/optimization/strategy-optimization/) in the same workflow. This is useful for testing a chart idea across several markets, building an index-member universe, or combining a daily trend with intraday entries through [multi-timeframe analysis](/features/data/multi-timeframe-analysis/). ## Pulling bars \[#pulling-bars] Symbols use TradingView's notation, `EXCHANGE:SYMBOL`. Use minute, hourly, daily, weekly, or monthly bars, as in `"1 minute"`, `"1 hour"`, or `"1D"`. The adapter also accepts second-based timeframes where TradingView makes them available. `tz` converts the index to a market's local time. Prices are adjusted for splits by default, `adjustment` also accounts for dividends, and `extended_session=True` adds pre-market and after-hours bars. For futures, `fut_contract=1` returns the continuous front contract and `fut_contract=2` the next one. Assign `data = data.update()` to refresh the available bars and combine them with your stored history. There is no start date. TradingView serves the most recent bars, up to `limit`, so pull them and then select the period you need with `data.loc`, as the example above does for 2024. The class downloads bars only, not the values of TradingView indicators or strategies. An error about data that could not be parsed usually means the symbol or timeframe does not exist on that exchange, and `skip_on_error=True` skips such symbols in a larger pull. ## Match the chart you are researching \[#match-the-chart-you-are-researching] Before comparing an indicator or backtest with a TradingView chart, match the data choices: | Chart setting | VBT input | | ---------------------------- | ------------------------------------- | | Instrument and exchange | The full `EXCHANGE:SYMBOL` identifier | | Bar interval | `timeframe` | | Regular or extended session | `extended_session` | | Split or dividend adjustment | `adjustment` | | Display timezone | `tz` | Different sessions and adjustments can change the indicator even when its formula is identical. VBT's [technical indicators](/features/indicators/technical-indicators/) and [custom indicators](/features/indicators/indicator-development/) let you calculate the studies in Python from those bars. If you need values already calculated on a chart, TradingView can [export chart data and indicators to CSV](https://www.tradingview.com/support/solutions/43000537255-how-to-export-chart-data/). Load that export with `vbt.CSVData` or Pandas, keeping its timestamp and indicator columns. The [storage page](/features/data/data-storage-and-databases/#files) covers file inputs. This provides another route for comparing chart outputs with your Python calculations. ## Finding symbols \[#finding-symbols] `vbt.TVData.list_symbols` searches TradingView's symbols by pattern, exchange, or text, and its market scanner lists symbols by market, by field values such as sector, or by index membership: ```python title="List the members of the Nasdaq-100" >>> ndx = vbt.TVData.list_symbols(groups=dict(index="NASDAQ:NDX")) >>> len(ndx), ndx[:5] (101, ['NASDAQ:AAPL', 'NASDAQ:ABNB', 'NASDAQ:ADBE', 'NASDAQ:ADI', 'NASDAQ:ADP']) ``` The list holds today's members, so a backtest over past years built from it carries survivorship bias, as the [Realistic backtests](/features/backtesting/backtest-realism/#point-in-time-universes) page explains. You can also request scanner fields such as sector, currency, or market capitalization and filter the results before downloading bars. With `return_field_data=True`, symbol discovery returns those fields alongside the symbol names, so you can keep the information used to select your research universe. ## History and accounts \[#history-and-accounts] TradingView serves a limited number of bars per symbol, so the depth of history depends on the timeframe: daily bars reach back years, while one-minute bars covered about the last six weeks for AAPL on October 2, 2026. VBT requests up to 20,000 bars by default. Signing in with your own TradingView username and password, or a session token, through `client_config` uses the access of your account. You can reuse an authenticated `TVClient` across pulls instead of creating a new client for each one. TradingView's [exchange data subscriptions](https://www.tradingview.com/support/solutions/43000471705-how-to-purchase-additional-market-data/) are separate from VBT PRO, and TradingView says its paid plans do not include exchange data fees. Standard `TVData` pulls retrieve recent bars. They do not automate TradingView's Bar Replay or page backward through the full chart history. Updating requests the recent window again and merges it into the existing object. For long intraday history, the commercial providers on the [Market data sources](/features/data/market-data-sources/) page fit better, and [Data storage and databases](/features/data/data-storage-and-databases/) keeps what you download growing over time. !!! info "Terms of use" TradingView data is subject to TradingView's terms. Use your own account where they require it, and check them before using the data beyond personal research. ## Trading View \[#trading-view] New in 1.9.0 ✅ A new class specialized for pulling data from [TradingView](https://www.tradingview.com/) is now available. ```python title="Pull 1-minute AAPL data" >>> data = vbt.TVData.pull( ... "NASDAQ:AAPL", ... timeframe="1 minute", ... tz="US/Eastern" ... ) >>> data.get() Open High Low Close Volume datetime 2022-12-05 09:30:00-05:00 147.75 148.31 147.50 148.28 37769.0 2022-12-05 09:31:00-05:00 148.28 148.67 148.28 148.49 10525.0 2022-12-05 09:32:00-05:00 148.50 148.73 148.30 148.30 4860.0 2022-12-05 09:33:00-05:00 148.25 148.73 148.25 148.64 5306.0 2022-12-05 09:34:00-05:00 148.62 148.97 148.52 148.97 5808.0 ... ... ... ... ... ... 2023-01-17 15:55:00-05:00 135.80 135.91 135.80 135.86 37573.0 2023-01-17 15:56:00-05:00 135.85 135.88 135.80 135.88 18796.0 2023-01-17 15:57:00-05:00 135.88 135.93 135.85 135.91 21019.0 2023-01-17 15:58:00-05:00 135.90 135.97 135.89 135.95 20934.0 2023-01-17 15:59:00-05:00 135.94 136.00 135.84 135.94 86696.0 [11310 rows x 5 columns] ``` # Indicators and signals (/features/indicators) Compute indicators, build your own, update them bar by bar, and turn them into signals or learning targets. This section is for anyone who builds the inputs of a strategy, from standard indicators to their own formulas or a model's predictions. The pages below go from built-in and custom indicators to streaming updates, trading signals, and labels for machine learning. ## Start here \[#start-here] | What do you want to build? | Where to start | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | RSI, moving averages, bands, or another existing study across symbols and settings | [Technical indicators](/features/indicators/technical-indicators/) | | Your own formula or a reusable version of a pandas calculation | [Custom indicators](/features/indicators/indicator-development/) | | Calculations that continue as new bars arrive | [Streaming indicators](/features/indicators/streaming-indicators/) | | Entry and exit conditions from crossings, levels, or calendar rules | [Trading signals](/features/indicators/trading-signals/) | | Return, breakout, or trend targets for a prediction model | [Machine learning labels](/features/indicators/machine-learning-labels/) | * [Technical indicators](/features/indicators/technical-indicators): Run TA-Lib, pandas-ta, ta, SMC, WorldQuant Alphas, and native indicators at scale * [Custom indicators](/features/indicators/indicator-development): Turn Python, pandas, or Numba calculations into reusable indicators with parameter grids * [Streaming indicators](/features/indicators/streaming-indicators): Update indicators bar by bar with stateful accumulators that match batch results * [Trading signals](/features/indicators/trading-signals): Generate, combine, clean, and analyze entry and exit signals before backtesting * [Machine learning labels](/features/indicators/machine-learning-labels): Create triple-barrier, trend, and pivot labels, and backtest model predictions ## From a calculation to a strategy \[#from-a-calculation-to-a-strategy] An indicator gives you values, such as RSI or distance from a moving average. A trading rule turns those values into signals, such as buying when RSI crosses back above a threshold. You can compare windows and thresholds across several symbols, inspect how often the signals fire, and then pass them to [Signal backtesting](/features/backtesting/signal-backtesting/) to measure the trades. Start with an integrated library or bring your own Python, pandas, or Numba calculation. Custom indicators use the same labeled outputs and comparison helpers, so you can combine a familiar indicator with your own research feature. For larger searches across settings, continue to [Parameter optimization](/features/optimization/strategy-optimization/). If you use machine learning, indicators can supply model features and labels define the future outcome the model should learn to predict. The model's predictions then become trading inputs. The labels page shows that full workflow, including a comparison with a simple baseline. See the [Indicators documentation](/documentation/indicators/) for the development pipeline, or follow the [Signal development tutorial](/tutorials/signal-development/) for a worked strategy. # Custom indicators (/features/indicators/indicator-development) How do you turn your own formula into an indicator you can sweep over parameters and reuse? VBT's indicator factory wraps any Python or Numba function into an indicator class with parameter grids, labeled outputs, signal helpers, and plotting, so a custom indicator in Python behaves exactly like the built-in ones. ```python title="Build a volatility-adjusted momentum indicator and test six parameter pairs" >>> @njit ... def vam_nb(close, fast, slow): # (1) ... momentum = close / vbt.nb.fshift_nb(close, fast) - 1 ... returns = close / vbt.nb.fshift_nb(close, 1) - 1 ... volatility = vbt.nb.rolling_std_nb(returns, slow) ... return momentum / (volatility * np.sqrt(fast)) >>> VAM = vbt.IF( ... class_name="VAM", ... short_name="vam", ... input_names=["close"], ... param_names=["fast", "slow"], ... output_names=["vam"], ... ).with_apply_func(vam_nb, takes_1d=False, fast=10, slow=50) # (2) >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"], start="2023-01-01", end="2025-01-01") >>> vam = VAM.run( ... data.close, ... fast=vbt.Param([5, 10, 20, 40], condition="fast < slow"), # (3) ... slow=vbt.Param([10, 20, 40]), ... param_product=True, ... ) >>> vam.vam.shape (731, 12) >>> vam.vam.columns.droplevel("symbol").unique().tolist() [(5, 10), (5, 20), (5, 40), (10, 20), (10, 40), (20, 40)] >>> entries = vam.vam_crossed_above(1) # (4) >>> exits = vam.vam_crossed_below(0) >>> pf = vbt.PF.from_signals(data, entries, exits) >>> pf.total_return.unstack("symbol").round(3) symbol BTC-USD ETH-USD vam_fast vam_slow 5 10 0.717 -0.187 20 0.388 0.454 40 0.771 0.228 10 20 0.576 0.131 40 1.119 0.000 20 40 1.322 -0.004 ``` 1. Momentum over `fast` bars divided by volatility over `slow` bars, written with compiled helpers so it runs on whole arrays. 2. The function receives a 2D array with one column per asset for each parameter combination. The factory also sets default parameter values. 3. Of the 12 combinations, keep only those where the fast window is shorter than the slow one. 4. Every output gets comparison methods such as `vam_crossed_above` for building signals. The function is ten lines. The factory adds the parameter grid, column labels, signal methods, and everything else an indicator needs, and the result goes straight into a backtest. ## From a function to an indicator \[#from-a-function-to-an-indicator] `vbt.IF` takes the names of inputs, parameters, and outputs, and a function that computes them. The function can work on one column at a time or on whole arrays, return one output or several, and keep extra results as in-place outputs. The resulting class has a `run` method with defaults, readable output properties, comparison helpers such as `crossed_above` and `above` for each output, and plotting. Outputs behave like pandas objects and support arithmetic, so `vam.vam * 2` or `fast.ma - slow.ma` work directly. The function receives NumPy arrays by default, which keeps it compilable. Pass `keep_pd=True` to receive pandas objects instead, for example to call pandas rolling or group methods. The function then has to be plain Python, because Numba cannot compile code that takes pandas objects. Regular indicator outputs match the shape of the inputs for each parameter combination. A function that returns something else, such as one number per run or arrays of other lengths, fits the parameterized decorator better, as described under [Parameterize any function](/features/optimization/strategy-optimization/#parameterize-any-function). ## Reuse your pandas calculations \[#reuse-your-pandas-calculations] You can start with a calculation that already works in a notebook. Here, a plain Python function returns a rolling mean and the price's percentage distance from it. `keep_pd=True` lets it use pandas directly, while the factory handles the windows, symbols, and output labels. ```python title="Turn a pandas calculation into a reusable indicator" >>> def distance_from_mean(close, window): ... mean = close.rolling(window).mean() ... return mean, 100 * (close / mean - 1) >>> Distance = vbt.IF( ... class_name="Distance", ... short_name="dist", ... input_names=["close"], ... param_names=["window"], ... output_names=["mean", "distance"], ... ).with_apply_func(distance_from_mean, keep_pd=True) >>> close = pd.DataFrame({ ... "A": [10, 11, 12, 11, 13, 15], ... "B": [20, 19, 18, 19, 17, 15], ... }, index=pd.date_range("2025-01-01", periods=6)) >>> close.columns.name = "symbol" >>> result = Distance.run(close, window=[2, 3]) >>> result.output_names ('mean', 'distance') >>> result.distance.iloc[-1].unstack("symbol").round(2) symbol A B dist_window 2 7.14 -6.25 3 15.38 -11.76 ``` On these fictional prices, A finishes above its rolling mean and B below it. Both the mean and distance remain available for plotting, comparisons, or another calculation. You could use the distance as a model feature or a threshold for a mean-reversion strategy, then test that rule with [Signal backtesting](/features/backtesting/signal-backtesting/). ## Parameters and grids \[#parameters-and-grids] Parameters accept single values, lists, or `vbt.Param` objects. Lists are paired element by element by default, and `param_product=True` builds every combination. Conditions filter combinations by name, as above, and each parameter becomes a column level named after the indicator's short name, so results can be selected and grouped by parameter. ## Inputs \[#inputs] Inputs of different shapes broadcast against each other. A single price series combines with parameters to produce one column per combination, and several assets multiply the grid, as the two assets and six pairs above did. With `takes_1d=True`, the function receives one column at a time, and the factory loops over the columns for you. If each asset needs its own setting instead of the same grid, `per_column=True` pairs each input column with its parameter combination. ## Formulas as indicators \[#formulas-as-indicators] An indicator can also be written as an expression, such as `(close - low) / (high - low)`, with inputs, parameters, and helper functions resolved by name, as the [Indicator expressions](#indicator-expressions) highlight below shows. Expressions suit quick ideas, and the factory turns them into the same kind of class as a compiled function. ## Performance \[#performance] Compiled functions run at Numba speed on the full grid. When the same intermediate result is needed for many combinations, such as one moving average shared by several pairs, the factory can compute it once in a cache function and reuse it. Indicators that work column by column can run in parallel threads, and indicators written for one dimension can be parallelized across columns automatically, as the [1D-native indicators](#1d-native-indicators) and [Parallelizable indicators](#parallelizable-indicators) highlights show. Rolling indicators need a warm-up period, so the first values are `NaN` until enough bars are available. ## Composition and reuse \[#composition-and-reuse] Indicators combine: the output of one can be the input of another, several can be stacked into one object, and the result can be indexed like a DataFrame. Once registered, a custom indicator is found by name with `vbt.indicator()` and runs from a data object with `data.run()`, just like built-in ones. The [Indicator search](#indicator-search) highlight below shows how to find indicators across all integrated libraries, and [Indicators for ML](#indicators-for-ml) turns many of them into a feature matrix. Registration can also organize indicators into named groups, such as your trend filters or volatility features. Run a whole group from a data object to rebuild the same feature set on a new dataset. This is useful when comparing models that should receive the same inputs. You can add derived properties through `lazy_outputs`, calculating them only when requested. For example, an indicator that returns several lines can expose their spread as another property. This keeps related calculations together while letting you choose which results to inspect. For calculations that update as each new bar arrives, see [Streaming indicators](/features/indicators/streaming-indicators/). ## Indicator search \[#indicator-search] New in 1.11.1 ✅ VBT implements or integrates more than 500 indicators, making it hard to keep track of them all. To make indicators easier to find, several new methods are available for globally searching for indicators. ```python title="List all moving average indicators" >>> vbt.IF.list_indicators("*ma") [ 'vbt:MA', 'talib:DEMA', 'talib:EMA', 'talib:KAMA', 'talib:MA', ... 'technical:ZEMA', 'technical:ZLEMA', 'technical:ZLHMA', 'technical:ZLMA' ] >>> vbt.indicator("technical:ZLMA") # (1) vectorbtpro.indicators.factory.technical.ZLMA ``` 1. Same as `vbt.IF.get_indicator`. ## Indicators for ML \[#indicators-for-ml] New in 1.8.2 ✅ Want to feed indicators as features to a machine-learning model? There is no need to run them individually: you can tell VBT to run all indicators from an indicator package on the given data instance. The data instance will recognize the input names of each indicator and supply the required data. You can also easily change the defaults for each indicator. ```python title="Run all talib indicators on entire BTC-USD history" >>> data = vbt.YFData.pull("BTC-USD") >>> features = data.run("talib", mavp=vbt.run_arg_dict(periods=14)) >>> features.shape (3046, 175) ``` ## 1D-native indicators \[#1d-native-indicators] New in 1.0.10 ✅ Previously, custom indicators could only be created by accepting two-dimensional input arrays, which forced users to adapt all functions accordingly. Now, the indicator factory can split each input array along columns and pass one column at a time, making it much easier to design indicators that are meant to be run natively on one-dimensional data (such as TA-Lib!). ```python title="Create a TA-Lib powered STOCHRSI indicator" >>> import talib >>> params = dict( ... rsi_period=14, ... fastk_period=5, ... slowk_period=3, ... slowk_matype=0, ... slowd_period=3, ... slowd_matype=0 ... ) >>> def stochrsi_1d(close, *args): ... rsi = talib.RSI(close, args[0]) ... k, d = talib.STOCH(rsi, rsi, rsi, *args[1:]) ... return rsi, k, d >>> STOCHRSI = vbt.IF( ... input_names=["close"], ... param_names=list(params.keys()), ... output_names=["rsi", "k", "d"] ... ).with_apply_func(stochrsi_1d, takes_1d=True, **params) >>> data = vbt.YFData.pull("BTC-USD", start="2022-01", end="2022-06") >>> stochrsi = STOCHRSI.run(data.close) >>> fig = stochrsi.k.rename("%K").vbt.plot() >>> stochrsi.d.rename("%D").vbt.plot(fig=fig) >>> fig.show() ``` TA-Lib-powered stochastic RSI percent K and percent D for BTC-USD. [Figure data (JSON)](/assets/figures/features/indicators/stochastic-rsi.73211844ad8e.json) ## Parallelizable indicators \[#parallelizable-indicators] New in 1.0.10 ✅ Processing parameter combinations with the indicator factory can be distributed across multiple threads, processes, or even in the cloud. This is a huge help when working with slow indicators 🐌 ```python title="Benchmark a serial and multithreaded rolling min-max indicator" >>> @njit ... def minmax_nb(close, window): ... return ( ... vbt.nb.rolling_min_nb(close, window), ... vbt.nb.rolling_max_nb(close, window) ... ) >>> MINMAX = vbt.IF( ... class_name="MINMAX", ... input_names=["close"], ... param_names=["window"], ... output_names=["min", "max"] ... ).with_apply_func(minmax_nb, window=14) >>> data = vbt.YFData.pull("BTC-USD") ``` ```python >>> %%timeit >>> minmax = MINMAX.run( ... data.close, ... np.arange(2, 200), ... jitted_loop=True ... ) 420 ms ± 2.05 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) ``` ```python >>> %%timeit >>> minmax = MINMAX.run( ... data.close, ... np.arange(2, 200), ... jitted_loop=True, ... jitted_warmup=True, # (1) ... execute_kwargs=dict(engine="threadpool", n_chunks="auto") # (2) ... ) 120 ms ± 355 µs per loop (mean ± std. dev. of 7 runs, 10 loops each) ``` 1. Run one parameter combination to compile the indicator before running others in a multithreaded fashion. 2. One Numba loop per thread, with the same number of threads as there are cores. ## Indicator expressions \[#indicator-expressions] New in 1.0.8 ✅ Indicators can now be created from expressions. An indicator expression is a regular string representing Python code enhanced with various extensions. The indicator factory automatically derives all required information, such as inputs, parameters, outputs, NumPy, VBT, and TA-Lib functions, and even complex indicators, thanks to a unique format and built-in matching mechanism. Designing indicators has never been easier! ```python title="Build a MACD indicator from an expression" >>> data = vbt.YFData.pull("BTC-USD", start="2020", end="2021") >>> expr = """ ... MACD: ... fast_ema = @talib_ema(close, @p_fast_w) ... slow_ema = @talib_ema(close, @p_slow_w) ... macd = fast_ema - slow_ema ... signal = @talib_ema(macd, @p_signal_w) ... macd, signal ... """ >>> MACD = vbt.IF.from_expr(expr, fast_w=12, slow_w=26, signal_w=9) # (1) >>> macd = MACD.run(data.close) >>> fig = macd.macd.rename("MACD").vbt.plot() >>> macd.signal.rename("Signal").vbt.plot(fig=fig) >>> fig.show() ``` 1. No need to manually set `input_names`, `param_names`, or other information. Expression-built MACD and signal lines for BTC-USD during 2020. [Figure data (JSON)](/assets/figures/features/indicators/indicator-expressions.6bbc8e453580.json) # Machine learning labels (/features/indicators/machine-learning-labels) How do you create targets for a trading model, and how do you backtest what it predicts? VBT generates machine learning labels in Python, including fixed-horizon returns, triple-barrier outcomes, trends, and pivots, and runs model predictions through the same backtester as any other signal, with the look-ahead in the labels kept explicit. ```python title="Label barrier outcomes, train a classifier walk-forward, and backtest its predictions" >>> from sklearn.ensemble import RandomForestClassifier >>> data = vbt.YFData.pull("BTC-USD", start="2018-01-01", end="2025-01-01") >>> labels = vbt.BOLB.run( # (1) ... data.high, data.low, window=10, up_th=0.05, down_th=0.05 ... ).labels.rename("label") >>> labels.value_counts(dropna=False).sort_index() label -1.0 1089 0.0 151 1.0 1317 Name: count, dtype: int64 >>> returns = data.close.pct_change() >>> features = pd.DataFrame({ # (2) ... "rsi": vbt.RSI.run(data.close, window=14).rsi, ... "ret_5": data.close.pct_change(5), ... "ret_20": data.close.pct_change(20), ... "vol_20": returns.rolling(20).std(), ... "dist_sma_50": data.close / data.close.rolling(50).mean() - 1, ... }) >>> proba = pd.Series(np.nan, index=data.index) >>> for year in [2021, 2022, 2023, 2024]: # (3) ... test = data.index.year == year ... train_end = data.index[test][0] - pd.Timedelta(days=10) ... train = ( ... (data.index < train_end) ... & features.notna().all(axis=1) ... & labels.notna() ... & (labels != 0) ... ) ... model = RandomForestClassifier(n_estimators=200, max_depth=4, random_state=42) ... model.fit(features[train], labels[train] == 1) ... proba[test] = model.predict_proba(features[test].fillna(0))[:, 1] >>> kwargs = dict( ... price="nextopen", # (4) ... tp_stop=0.05, ... sl_stop=0.05, ... td_stop=10, ... time_delta_format="rows", ... fees=0.001, ... ) >>> test_data = data.loc["2021":] >>> model_pf = vbt.PF.from_signals(test_data, (proba > 0.55).loc["2021":], **kwargs) >>> always_pf = vbt.PF.from_signals(test_data, True, **kwargs) # (5) >>> metrics = ["total_trades", "win_rate", "total_return", "sharpe_ratio"] >>> pd.DataFrame({ ... "model": model_pf.stats(metrics), ... "every bar": always_pf.stats(metrics), ... }).round(2) model every bar Total Trades 145 302 Win Rate [%] 51.03 47.84 Total Return [%] 9.14 -42.96 Sharpe Ratio 0.24 0.02 ``` 1. Scan the next 10 bars for a 5% rise from the current low (1) or a 5% fall from the current high (-1). Zero means no unambiguous breakout was found. These price and time barriers form the labeling target. 2. Features use only data up to each bar's close. 3. Train on all earlier years, leaving out the last 10 days before each test year so no training label looks into it. 4. A prediction made at a bar's close is traded at the next open. Stops use the same 5% distances and 10-bar limit, measured from the simulated trade rather than the label's high and low. 5. The baseline takes every trade the barriers allow, without the model. The model's entries won 51% of the time against 48% for entering on every bar, and turned a loss into a small gain over four out-of-sample years. A modest edge, measured honestly: labels from the future, features from the past, and predictions only on years the model never saw. The classifier is trained on the upward and downward outcomes, leaving out zero labels. Its probability threshold selects entries, and the portfolio simulation measures what those entries actually earn after fees. You can change the target, model, or threshold and keep this same research workflow. ## Choose what the model should predict \[#choose-what-the-model-should-predict] A label defines the question you want the model to answer. Use a future return when the size of the move matters, a barrier outcome when the order of price moves matters, or a trend label when you want to study broader market moves. These targets can serve regression or classification models in your preferred Python framework. ## Label generators \[#label-generators] Every label generator is an indicator that looks forward instead of back: | Indicator | Label | Useful for | | ------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------- | | `vbt.FIXLB` | Return from each bar to the bar a fixed number of bars ahead | Comparing prediction horizons | | `vbt.MEANLB` | Return to the average of a future window | Predicting an average future price level | | `vbt.BOLB` | Which threshold, up or down, is reached first within a future window | Classifying future breakout direction | | `vbt.PIVOTLB` | Whether each bar is a high or a low pivot, judged with hindsight | Learning turning-point targets | | `vbt.TRENDLB` | Trend between pivots, as a direction, a position within the move, or a return | Classifying trends or predicting progress within a move | Like other indicators, they take parameter lists, so a grid of horizons or thresholds produces a grid of labels, and they plot over price for a quick check. `vbt.PIVOTLB` and `vbt.TRENDLB` read highs and lows and take two positive thresholds: `up_th`, the rise from a trough that confirms it, and `down_th`, the fall from a peak. Equal percentages are not symmetric, since undoing a 50% fall takes a 100% rise. For breakout targets, `BOLB` offers two reference choices. The default `"swing"` mode measures upward moves from the current low and downward moves from the current high. `"range"` mode puts the thresholds beyond the current high and low, which suits questions about breaking out of the bar's range. Thresholds can also vary across observations, for example using a volatility-based series you calculate from past data. ## Compare prediction horizons \[#compare-prediction-horizons] The horizon is part of the research question. This fictional series produces different return targets one and three bars ahead, with percentages shown below: ```python title="Build one-bar and three-bar return targets together" >>> close = pd.Series([100.0, 110.0, 105.0, 120.0, 108.0], ... index=pd.date_range("2025-01-01", periods=5)) >>> labels = vbt.FIXLB.run(close, n=[1, 3]).labels >>> (labels * 100).round(2) fixlb_n 1 3 2025-01-01 10.00 20.00 2025-01-02 -4.55 -1.82 2025-01-03 14.29 NaN 2025-01-04 -10.00 NaN 2025-01-05 NaN NaN ``` `FIXLB` leaves a target missing when the required future price is unavailable. Select the horizon you want to model and train on rows where both its target and your features are available. !!! warning "Labels use the future" Labels use future observations. Use them as training targets or for retrospective analysis, not as information available to a trading decision. Exclude training labels whose future observations overlap the test period. A gap covers the fixed horizon in the example above, while pivot and trend labels need the time at which their outcomes became known. See [Walk-forward and cross-validation](/features/optimization/time-series-cross-validation/). ## Forward statistics \[#forward-statistics] `vbt.FMEAN`, `vbt.FMAX`, `vbt.FMIN`, and `vbt.FSTD` compute the mean, maximum, minimum, and standard deviation of a future window, with a `wait` before the window starts. They answer questions such as "how far did the price rise in the next 20 days" and serve as continuous targets. ## Meta-labeling \[#meta-labeling] A model does not have to find trades on its own. In meta-labeling, a rule-based strategy proposes trades, each trade is labeled by its outcome, for example profitable after fees or not, and a second model learns which proposals to take or how much to put into them. The labels come from the strategy's own trade records, such as `pf.trades.returns`, and the model's decision becomes a filter on the entries or a size for each one. Keep the features aligned to the original entry opportunity, then compare the filtered strategy with the original under the same fees and sizing rules. [Trade analytics](/features/analytics/trade-analytics/) helps inspect which trades the filter accepts and rejects. ## Backtesting predictions \[#backtesting-predictions] Predictions are arrays like any other input. Thresholded probabilities become entry and exit signals, predicted returns or scores become sizes, and predicted weights for several assets become target allocations for `from_orders`. Models trained on a GPU or in another framework only need their output converted to NumPy or pandas before it reaches the simulator, which runs on the CPU. !!! info "Tutorial" The members-only [Cross-validation](https://members.vectorbt.pro/tutorials/cross-validation/applications/) tutorial applies splitters to models and parameter searches without leaking the future into training. # Streaming indicators (/features/indicators/streaming-indicators) Can an indicator update with each new bar without recomputing its whole history? VBT computes streaming indicators in Python with accumulators: small functions that take the previous state and one new value and return the next state. They use the same formulas as the batch versions, so you can match batch results with the same inputs, settings, and initialization, without recomputing the full history on each update. ```python title="Update an EMA one bar at a time and compare it with the batch result" >>> close = vbt.YFData.pull("BTC-USD", start="2024-01-01", end="2025-01-01").close >>> span = 20 >>> alpha = 2 / (span + 1) >>> old_wt, weighted_avg, nobs = 1.0, np.nan, 0 # (1) >>> streamed = [] >>> for i, price in enumerate(close.values): ... if i == 0: ... weighted_avg = price ... state = vbt.nb.ewm_mean_acc_nb( # (2) ... vbt.nb.EWMMeanAIS(i, price, old_wt, weighted_avg, nobs, alpha, 1, True) ... ) ... old_wt, weighted_avg, nobs = state.old_wt, state.weighted_avg, state.nobs ... streamed.append(state.value) >>> batch = close.vbt.ewm_mean(span, minp=1) >>> print(np.allclose(streamed, batch), round(streamed[-1], 2), round(batch.iloc[-1], 2)) True 96421.8 96421.8 ``` 1. The whole state of an EMA is three numbers, carried from one update to the next. 2. One update: the input state holds the bar index, the new price, the previous state, and the settings. The streamed values match the batch EMA on every bar. Keeping the state instead of the history is what makes the update cost constant: ```python title="Time one streaming update against recomputing the history" >>> import timeit >>> in_state = vbt.nb.EWMMeanAIS(1, 100.0, 1.0, 100.0, 1, alpha, 1, True) # (1) >>> rows = {} >>> for n in [1_000, 100_000]: ... arr = np.random.default_rng(42).normal(size=n).cumsum() + 1000 ... batch_us = min(timeit.repeat( ... lambda: vbt.nb.ewm_mean_1d_nb(arr, span, 1, True), number=100, repeat=5 ... )) / 100 * 1e6 ... stream_us = min(timeit.repeat( ... lambda: vbt.nb.ewm_mean_acc_nb(in_state), number=10000, repeat=5 ... )) / 10000 * 1e6 ... rows[n] = { ... "recompute history (µs)": round(batch_us, 1), ... "one streaming update (µs)": round(stream_us, 1), ... } >>> pd.DataFrame(rows).T recompute history (µs) one streaming update (µs) 1000 4.9 0.8 100000 450.8 0.9 ``` 1. A representative state for timing a single update. Both functions were called once beforehand so compilation is not timed. Measured on an Apple M3. Recomputing grows with the history, while a streaming update stays under a microsecond, most of it Python's call overhead. ## Where streaming indicators help \[#where-streaming-indicators-help] | Research task | How accumulators help | | ------------------------------------------------- | ------------------------------------------------------------------------------------ | | Update a signal as each completed bar arrives | Calculate the next value from the retained state | | Follow many symbols or parameter settings | Keep a separate state for each calculation instead of rerunning every history | | Calculate indicators inside a simulation callback | Update the indicator alongside the strategy's bar-by-bar decisions | | Process history in successive batches | Carry the state across batches so calculations continue from the same starting point | You supply observations from your data workflow or simulation. For example, feed each completed bar into an EMA and RSI, combine their outputs into an entry condition, and pass that condition to your strategy. [Data pipelines](/features/data/financial-data-pipelines/) covers collecting and updating the data, while [Live simulation](/features/backtesting/live-simulation/) covers advancing a portfolio as observations arrive. ## Streaming state \[#streaming-state] Every streaming indicator is defined by its state. For an EMA it is the running average and its weight, for a rolling mean the running sum and the values about to leave the window, and for RSI the average gains and losses. Save the state, and the indicator can continue later, in another process, or after new data arrives, without replaying the full history it was computed from. Keep the settings and current position with that state. For rolling calculations in Numba, also retain the recent values needed as observations leave the window. Rust accumulators hold those buffers internally. Each symbol and parameter setting has its own state. This lets you track, for example, a fast and slow average on several assets without mixing their histories. A streaming indicator still needs a warm-up. Rolling windows return `NaN` until they have enough observations, and exponential averages depend on where they start: an EMA started a year ago and one started yesterday give different values today. Start streaming from the same point as the batch calculation with the same settings when the two must agree. Feeding earlier bars first also lets you warm up the indicator before the period you want to trade or evaluate, as described in [Walk-forward and cross-validation](/features/optimization/time-series-cross-validation/). ## Accumulator building blocks \[#accumulator-building-blocks] Accumulators exist for rolling sums, means, standard deviations, z-scores, minimums and maximums, exponential means and standard deviations, crossovers, and indicators such as RSI, ADX, on-balance volume, and SuperTrend. Because each one works with the current inputs and its retained state or window values, several can be combined in a single pass over the data, which is how complex indicators are built from simple ones. The [Accumulators](#accumulators) highlight below combines two of them into a one-pass rolling z-score. Streaming keeps each update focused on the new observation, making accumulators especially useful for long histories, many symbols, and calculations inside a simulation loop. Combine them with batch calculations for the rest of your indicators. The EMA benchmark above shows both approaches on the same data. ## Python, Numba, and Rust \[#python-numba-and-rust] The same accumulators run in a Python loop, inside a Numba-compiled loop or simulation callback, and in Rust. The Rust versions keep their own rolling buffers, so a Rust program only feeds in new values, as the [Streaming indicators](#streaming-indicators) highlight below shows. That makes it possible to prototype in Python and move the same logic into a compiled live system without changing the math. Rust accumulators can also be cloned to branch from the same warmed-up state. Feed different future observations into each copy to compare scenarios without replaying the shared history. Use `reset()` to start a fresh calculation with the same configuration. These are useful building blocks for [custom indicators](/features/indicators/indicator-development/) and native research programs, as well as live calculations. !!! info "Tutorial" The members-only [Superfast SuperTrend](https://members.vectorbt.pro/tutorials/superfast-supertrend/streaming/) tutorial builds a streaming SuperTrend from accumulators and compares it with the batch version. ## Streaming indicators \[#streaming-indicators] New in v2026.9.5 ✅ Keep your indicators moving with the market. VBT's Numba and Rust accumulators update one observation at a time, using the same formulas as batch execution. Rust accumulators even manage their own rolling buffers, so you can feed in new data and get straight to the next value. === "Python / Numba" ```python title="Update on-balance volume for each bar" >>> prev_close = np.nan >>> obv = 0.0 >>> for close, volume in [(100.0, 10.0), (102.0, 20.0), (101.0, 5.0)]: ... out = vbt.ind_nb.obv_acc_nb( # (1) ... vbt.ind_enums.OBVAIS(close, prev_close, volume, obv) ... ) ... prev_close, obv = close, out.cumsum # (2) ... print(out.value) 10.0 30.0 25.0 ``` 1. The accumulator can also run inside a Numba-compiled loop or callback. 2. Carry the previous close and cumulative on-balance volume into the next update. === "Rust" ```rust title="Update Bollinger Bands and RSI for each price" use vectorbtpro_rust::error::VbtResult; use vectorbtpro_rust::indicators::streaming::{Bbands, Rsi}; fn main() -> VbtResult<()> { let mut bands = Bbands::builder().window(3).build()?; let mut rsi = Rsi::builder().window(3).build()?; for price in [100.0, 101.0, 102.0, 99.0, 98.0, 103.0] { let band = bands.update(price); // (1) let strength = rsi.update(price).rsi; if strength.is_finite() { // (2) println!("${price:.0}: middle={:.2}, RSI={strength:.2}", band.middle); } } Ok(()) } ``` 1. The result also includes the upper and lower Bollinger bands. 2. Skip output until RSI has enough observations for its three-bar window. ```text title="Output" $99: middle=100.67, RSI=40.00 $98: middle=99.67, RSI=30.77 $103: middle=100.00, RSI=74.65 ``` !!! info "Tutorial" Learn more in the [Live simulation](https://members.vectorbt.pro/tutorials/from-python-to-rust/live/) tutorial. ## Accumulators \[#accumulators] New in 1.0.10 ✅ Most rolling indicators implemented with Pandas and NumPy require multiple passes over the data. For example, calculating the sum of three arrays requires at least two passes. If you want to calculate such an indicator iteratively (bar by bar), you either need to pre-calculate everything and store it in memory or re-calculate each window, which can significantly impact performance. [Accumulators](https://theboostcpplibraries.com/boost.accumulators), however, maintain an internal state that allows you to compute an indicator value as soon as a new data point arrives, resulting in the best possible performance. ```python title="Design a one-pass rolling z-score" >>> @njit ... def fastest_rolling_zscore_1d_nb(arr, window, minp=None, ddof=1): ... if minp is None: ... minp = window ... out = np.full(arr.shape, np.nan) ... cumsum = 0.0 ... cumsum_sq = 0.0 ... nancnt = 0 ... ... for i in range(len(arr)): ... pre_window_value = arr[i - window] if i - window >= 0 else np.nan ... mean_in_state = vbt.nb.RollMeanAIS( ... i, arr[i], pre_window_value, cumsum, nancnt, window, minp ... ) ... mean_out_state = vbt.nb.rolling_mean_acc_nb(mean_in_state) ... _, _, _, mean = mean_out_state ... std_in_state = vbt.nb.RollStdAIS( ... i, arr[i], pre_window_value, cumsum, cumsum_sq, nancnt, window, minp, ddof ... ) ... std_out_state = vbt.nb.rolling_std_acc_nb(std_in_state) ... cumsum, cumsum_sq, nancnt, _, std = std_out_state ... out[i] = (arr[i] - mean) / std ... return out >>> data = vbt.YFData.pull("BTC-USD") >>> rolling_zscore = fastest_rolling_zscore_1d_nb(data.returns.values, 14) >>> data.symbol_wrapper.wrap(rolling_zscore) Date 2014-09-17 00:00:00+00:00 NaN 2014-09-18 00:00:00+00:00 NaN 2014-09-19 00:00:00+00:00 NaN ... 2023-02-01 00:00:00+00:00 0.582381 2023-02-02 00:00:00+00:00 -0.705441 2023-02-03 00:00:00+00:00 -0.217880 Freq: D, Name: BTC-USD, Length: 3062, dtype: float64 >>> (data.returns - data.returns.rolling(14).mean()) / data.returns.rolling(14).std() Date 2014-09-17 00:00:00+00:00 NaN 2014-09-18 00:00:00+00:00 NaN 2014-09-19 00:00:00+00:00 NaN ... 2023-02-01 00:00:00+00:00 0.582381 2023-02-02 00:00:00+00:00 -0.705441 2023-02-03 00:00:00+00:00 -0.217880 Freq: D, Name: Close, Length: 3062, dtype: float64 ``` # Technical indicators (/features/indicators/technical-indicators) Which technical indicators can you use, and can you run them over many symbols and parameters at once? VBT runs indicators from TA-Lib, pandas-ta, ta, Technical, Smart Money Concepts, and the WorldQuant 101 Alphas, plus its own compiled indicators, through one interface in Python. Every indicator accepts lists of parameters and returns labeled columns. ```python title="Compute RSI with 10 window lengths on 5 ETFs in one call" >>> symbols = ["SPY", "QQQ", "IWM", "TLT", "GLD"] >>> data = vbt.YFData.pull(symbols, start="2024-01-01", end="2025-01-01") >>> rsi = vbt.talib("RSI").run(data.close, timeperiod=np.arange(5, 55, 5)) # (1) >>> rsi.real.shape (252, 50) >>> rsi.real.columns[:3] MultiIndex([(5, 'SPY'), (5, 'QQQ'), (5, 'IWM')], names=['rsi_timeperiod', 'symbol']) >>> rsi.real.iloc[-1].unstack("symbol").round(1).head(4) # (2) symbol GLD IWM QQQ SPY TLT rsi_timeperiod 5 51.2 32.5 29.0 29.5 32.7 10 47.6 33.9 40.7 37.8 33.1 15 47.4 37.7 45.7 42.4 35.7 20 47.9 40.9 48.4 45.5 37.5 ``` 1. Ten windows times five symbols give 50 columns, computed in one call. 2. The last value of each column, arranged as windows by symbols. ## Indicator libraries \[#indicator-libraries] Indicators from each library are available by name with a prefix: `vbt.talib("RSI")`, `vbt.pandas_ta("SUPERTREND")`, `vbt.ta("RSIIndicator")`, and `vbt.indicator("smc:...")` for Smart Money Concepts or `"wqa101:..."` for the WorldQuant 101 Alphas. Each one is wrapped in the same indicator class as VBT's own, so it accepts parameter lists, labels its outputs, offers signal helpers such as `crossed_above`, and plots. The libraries themselves are optional dependencies, and VBT only uses the ones you install. `vbt.IF.list_indicators("*vwap*")` searches all of them by name and returns, for example, `['vbt:VWAP', 'pandas_ta:VWAP']` when pandas-ta is installed. TA-Lib also brings candlestick patterns and studies such as Parabolic SAR, listed in its [function catalogue](https://ta-lib.org/functions/). Many WorldQuant alphas rank values across assets, so they need several symbols in one call: with a single asset, every cross-sectional rank is the same. Some formulas also use sector or industry groups, making them useful for research across a classified universe. Running an indicator returns an indicator object, not a DataFrame. Its outputs are attributes named after them, such as `.rsi` for `vbt.RSI` and `.real` for most TA-Lib indicators, and `output_names` lists them. The highlights below show [Smart Money Concepts](#smart-money-concepts), the [WorldQuant Alphas](#worldquant-alphas), and the [Technical](#technical-indicators) library from Freqtrade. ## Built-in indicators \[#built-in-indicators] VBT ships compiled indicators of its own: moving averages (`vbt.MA`), standard deviation (`vbt.MSD`), Bollinger Bands (`vbt.BBANDS`), RSI (`vbt.RSI`), stochastic (`vbt.STOCH`), MACD (`vbt.MACD`), ATR (`vbt.ATR`), ADX (`vbt.ADX`), on-balance volume (`vbt.OBV`), VWAP (`vbt.VWAP`), SuperTrend (`vbt.SUPERTREND`), and pivot detection with a ZigZag line (`vbt.PIVOTINFO`). VWAP resets every day by default, and its `anchor` parameter sets another period. They run in Numba without any extra dependency. When speed matters more than the indicator class, `vbt.talib_func` calls a TA-Lib function directly with broadcasting, missing-value handling, and timeframes, as the [Lightweight TA-Lib](#lightweight-ta-lib) highlight shows. Moving averages offer simple, weighted, exponential, Wilder, and VIDYA smoothing through `wtype`. Bollinger Bands also expose bandwidth and percent B, so you can study volatility contractions or where a price sits within its bands. SuperTrend returns trend direction alongside its lines, which you can use as a filter for another indicator's entries. ## Compare parameters and generate signals \[#compare-parameters-and-generate-signals] Parameter lists let you compare settings without writing a loop for each one. With several parameters, lists are paired by default. Set `param_product=True` to test every combination. The outputs keep the parameter and symbol labels, and crossing helpers produce Boolean signals with the same columns. Here are two fictional price series, two lookback windows, and two band widths. The result is eight columns of Bollinger Bands and a count of upper-band breakouts for each setting: ```python title="Compare Bollinger Band breakout settings" >>> close = pd.DataFrame({ ... "A": [10, 11, 10, 10, 14, 11, 10, 15, 12, 11, 16, 12], ... "B": [20, 19, 20, 20, 16, 19, 20, 15, 18, 19, 14, 18], ... }, index=pd.date_range("2025-01-01", periods=12)) >>> close.columns.name = "symbol" >>> bands = vbt.BBANDS.run(close, window=[3, 5], alpha=[1.0, 1.5], param_product=True) >>> entries = bands.close_crossed_above(bands.upper) >>> bands.upper.shape (12, 8) >>> entries.sum().unstack("symbol") symbol A B bb_window bb_alpha 3 1.0 3 0 1.5 0 0 5 1.0 2 0 1.5 0 0 ``` The wider bands produce fewer breakouts on these prices. Use the signals as entry conditions, combine them with a trend or volume filter, and add exit rules in [Signal backtesting](/features/backtesting/signal-backtesting/). For larger searches and comparing strategy results across settings, see [Parameter optimization](/features/optimization/strategy-optimization/). ## Statistical indicators \[#statistical-indicators] `vbt.HURST` estimates the Hurst exponent to tell trending from mean-reverting behavior, and `vbt.OLS` fits a rolling regression of one series on another, which is the base of many pairs trading strategies. `vbt.PATSIM` measures similarity to a pattern, as described on the [Patterns and event studies](/features/analytics/patterns-and-event-studies/) page. The [Hurst exponent](#hurst-exponent) and [Rolling OLS](#rolling-ols) highlights below show the first two. If your research calls for another statistic, the [indicator factory](/features/indicators/indicator-development/) lets you wrap your own Python or Numba calculation with the same parameter and output interface. ## Alternative charts \[#alternative-charts] Renko bricks turn a price series into fixed-size moves and ignore time, which filters noise. The [Renko chart](#renko-chart) highlight below builds them from closes and resamples them to OHLC bars. For a custom candle transform such as Heikin-Ashi, you can also wrap the calculation with the [indicator factory](/features/indicators/indicator-development/) and retain separate open, high, low, and close outputs. ## Running indicators \[#running-indicators] Indicators run on one or many columns, and `data.run("rsi")` picks the right inputs from a data object. TA-Lib indicators take `skipna=True` to skip missing values, so an asset that started trading later does not leave the rest of its column empty. Different libraries can disagree on the first values of the same indicator, because they start their smoothing in different ways. In this RSI comparison, the values converge after a warm-up period: ```python title="Compare TA-Lib's RSI with VBT's RSI" >>> btc = vbt.YFData.pull("BTC-USD", start="2024-01-01", end="2025-01-01") >>> talib_rsi = vbt.talib("RSI").run(btc.close, timeperiod=14).real >>> vbt_rsi = vbt.RSI.run(btc.close, window=14).rsi >>> pd.DataFrame({"talib": talib_rsi, "vbt": vbt_rsi}).iloc[[14, 15, 100, -1]].round(2) talib vbt Date 2024-01-15 00:00:00+00:00 44.24 58.19 2024-01-16 00:00:00+00:00 46.80 60.27 2024-04-10 00:00:00+00:00 56.07 56.08 2024-12-31 00:00:00+00:00 43.51 43.51 ``` When matching another platform's values matters, load more history than you analyze so the warm-up is over before your period starts. Match the input prices, timeframe, and smoothing settings too. If you only need arrays for further calculations, `return_raw="outputs"` returns NumPy outputs without constructing the final indicator object and labeled output columns. For indicators on a different calculation timeframe, see [Multi-timeframe analysis](/features/data/multi-timeframe-analysis/). For updating calculations as new bars arrive, see [Streaming indicators](/features/indicators/streaming-indicators/). ## Hurst exponent \[#hurst-exponent] New in v2024.6.19 ✅ Estimating the Hurst exponent provides insight into persistence and mean-reverting behavior in your data. VBT offers five (!) different implementations. ```python title="Plot rolling Hurst exponent by method" >>> data = vbt.YFData.pull("BTC-USD", start="12 months ago") >>> hurst = vbt.HURST.run(data.close, method=["standard", "logrs", "rs", "dma", "dsod"]) >>> fig = vbt.make_subplots(specs=[[dict(secondary_y=True)]]) >>> data.plot(plot_volume=False, ohlc_trace_kwargs=dict(opacity=0.3), fig=fig) >>> fig = hurst.hurst.vbt.plot(fig=fig, add_trace_kwargs=dict(secondary_y=True)) >>> fig = fig.select_range(start=hurst.param_defaults["window"]) >>> fig.show() ``` Rolling Hurst exponent by method over BTC-USD market data. [Figure data (JSON)](/assets/figures/features/indicators/hurst.78d7278fc132.json) ## Smart Money Concepts \[#smart-money-concepts] New in v2024.6.19 ✅ VBT integrates most of the indicators from the [Smart Money Concepts (SMC)](https://github.com/joshyattridge/smart-money-concepts) library. ```python title="Plot previous high and low" >>> data = vbt.YFData.pull("BTC-USD", start="6 months ago") >>> phl = vbt.smc("previous_high_low").run( # (1) ... data.open, ... data.high, ... data.low, ... data.close, ... data.volume, ... time_frame=vbt.Default("7D") ... ) >>> fig = data.plot() >>> phl.previous_high.rename("previous_high").vbt.plot(fig=fig) >>> phl.previous_low.rename("previous_low").vbt.plot(fig=fig) >>> (phl.broken_high == 1).rename("broken_high").vbt.signals.plot_as_markers( ... y=phl.previous_high, ... trace_kwargs=dict(marker=dict(color="limegreen")), ... fig=fig ... ) >>> (phl.broken_low == 1).rename("broken_low").vbt.signals.plot_as_markers( ... y=phl.previous_low, ... trace_kwargs=dict(marker=dict(color="orangered")), ... fig=fig ... ) >>> fig.show() ``` 1. Each SMC indicator requires OHLCV. BTC-USD OHLCV with previous weekly highs and lows and broken-level markers. [Figure data (JSON)](/assets/figures/features/indicators/smart-money-concepts.2c91e487d04e.json) ## Lightweight TA-Lib \[#lightweight-ta-lib] New in 1.14.0 ✅ TA-Lib functions wrapped with the indicator factory are very powerful because, unlike the official TA-Lib implementation, they can broadcast, handle DataFrames, skip missing values, and even resample to a different timeframe. Although TA-Lib functions are very fast, wrapping them with the indicator factory adds some overhead. To keep both the speed of TA-Lib and the power of VBT, the added features have been separated into a lightweight function that you can call just like a regular TA-Lib function. ```python title="Run and plot an RSI resampled to the monthly timeframe" >>> data = vbt.YFData.pull("BTC-USD") >>> run_rsi = vbt.talib_func("rsi") >>> rsi = run_rsi(data.close, timeperiod=12, timeframe="M") # (1) >>> rsi Date 2014-09-17 00:00:00+00:00 NaN 2014-09-18 00:00:00+00:00 NaN 2014-09-19 00:00:00+00:00 NaN 2014-09-20 00:00:00+00:00 NaN 2014-09-21 00:00:00+00:00 NaN ... 2024-01-18 00:00:00+00:00 64.210811 2024-01-19 00:00:00+00:00 64.210811 2024-01-20 00:00:00+00:00 64.210811 2024-01-21 00:00:00+00:00 64.210811 2024-01-22 00:00:00+00:00 64.210811 Freq: D, Name: Close, Length: 3415, dtype: float64 >>> plot_rsi = vbt.talib_plot_func("rsi") >>> plot_rsi(rsi).show() ``` 1. Parameters are applied to the target timeframe. BTC-USD RSI resampled to the monthly timeframe. [Figure data (JSON)](/assets/figures/features/indicators/native-ta-lib.d96222a6f261.json) ## Technical indicators \[#technical-indicators] New in 1.7.0 ✅ VBT integrates most of the indicators and consensus classes from freqtrade's [technical](https://github.com/freqtrade/technical) library. ```python title="Compute and plot the summary consensus with a one-liner" >>> vbt.YFData.pull("BTC-USD").run("sumcon", smooth=100).plot().show() ``` Smoothed technical indicator buy and sell summary consensus for BTC-USD. [Figure data (JSON)](/assets/figures/features/indicators/summary-consensus.0a262862e34f.json) ## Renko chart \[#renko-chart] New in 1.7.0 ✅ Unlike regular charts, a [Renko chart](https://www.investopedia.com/terms/r/renkochart.asp) is built using price movements. Each "brick" appears when the price changes by a specified amount. Because the output has irregular time intervals, only one column can be processed at once. As with everything, VBT's implementation can translate a huge number of data points very fast thanks to Numba. ```python title="Resample closing price into a Renko format" >>> data = vbt.YFData.pull("BTC-USD", start="2021", end="2022") >>> renko_ohlc = data.close.vbt.to_renko_ohlc(1000, reset_index=True) # (1) >>> renko_ohlc.vbt.ohlcv.plot().show() ``` 1. Bitcoin is very volatile, so the brick size is set to 1000. BTC-USD closing price resampled into a Renko OHLC chart. [Figure data (JSON)](/assets/figures/features/indicators/renko-chart.4982a9891b2d.json) ## Rolling OLS \[#rolling-ols] New in 1.3.0 ✅ Rolling regressions are models for analyzing changing relationships among variables over time. In VBT, this is implemented as an indicator that takes two time series and returns the slope, intercept, prediction, error, R-squared, and the z-score of the error at each time step. Use the regression and residuals in pairs research, for example to build a spread and test entry or rebalancing rules. It is also hundreds of times faster than the statsmodels equivalent [RollingOLS](https://www.statsmodels.org/dev/generated/statsmodels.regression.rolling.RollingOLS.html) 🔥 ```python title="Determine the spread between BTC and ETH" >>> data = vbt.YFData.pull( ... ["BTC-USD", "ETH-USD"], ... start="2022", ... end="2023", ... missing_index="drop" ... ) >>> ols = vbt.OLS.run( ... data.get("Close", "BTC-USD"), ... data.get("Close", "ETH-USD") ... ) >>> ols.plot_zscore().show() ``` Rolling OLS spread z-score between BTC and ETH during 2022. [Figure data (JSON)](/assets/figures/features/indicators/rolling-ols.4b021c8f0823.json) ## TA-Lib plotting \[#ta-lib-plotting] New in 1.0.9 ✅ Every TA-Lib indicator is fully capable of plotting itself, based entirely on output flags! ```python >>> data = vbt.YFData.pull("BTC-USD", start="2020", end="2021") >>> vbt.talib("MACD").run(data.close).plot().show() ``` TA-Lib MACD, signal, and histogram for BTC-USD during 2020. [Figure data (JSON)](/assets/figures/features/indicators/ta-lib.ce381192f226.json) ## WorldQuant Alphas \[#worldquant-alphas] New in 1.0.8 ✅ Each of [WorldQuant's 101 Formulaic Alphas](https://arxiv.org/pdf/1601.00991.pdf) is now available as an indicator 👀 ```python title="Run the first alpha" >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD", "XRP-USD"], missing_index="drop") >>> vbt.wqa101(1).run(data.close).out symbol BTC-USD ETH-USD XRP-USD Date 2017-11-09 00:00:00+00:00 0.166667 0.166667 0.166667 2017-11-10 00:00:00+00:00 0.166667 0.166667 0.166667 2017-11-11 00:00:00+00:00 0.166667 0.166667 0.166667 2017-11-12 00:00:00+00:00 0.166667 0.166667 0.166667 2017-11-13 00:00:00+00:00 0.166667 0.166667 0.166667 ... ... ... ... 2023-01-31 00:00:00+00:00 0.166667 0.166667 0.166667 2023-02-01 00:00:00+00:00 0.000000 0.000000 0.500000 2023-02-02 00:00:00+00:00 0.000000 0.000000 0.500000 2023-02-03 00:00:00+00:00 0.000000 0.500000 0.000000 2023-02-04 00:00:00+00:00 -0.166667 0.333333 0.333333 [1914 rows x 3 columns] ``` # Trading signals (/features/indicators/trading-signals) How do you turn indicators into clean entry and exit signals, and how do you know what those signals actually capture? VBT generates trading signals in Python from crossovers, thresholds, pivots, and calendars, and treats signals as boolean arrays it can clean, rank, partition, and measure before any backtest runs. ```python title="Find out how many separate episodes 111 oversold days really are" >>> btc = vbt.YFData.pull("BTC-USD", start="2018-01-01", end="2025-01-01") >>> rsi = vbt.RSI.run(btc.close, window=14).rsi >>> oversold = rsi < 30 >>> print(oversold.sum()) 111 >>> episodes = oversold.vbt.signals.partition_ranges() # (1) >>> print(episodes.count()) 33 >>> longest = episodes.apply_mask(episodes.duration.top_n_mask(3)) >>> longest.readable[["Start Index", "End Index"]].assign(Days=longest.duration.values) Start Index End Index Days 0 2018-11-14 00:00:00+00:00 2018-11-28 00:00:00+00:00 14 1 2022-06-13 00:00:00+00:00 2022-06-23 00:00:00+00:00 10 2 2023-08-17 00:00:00+00:00 2023-08-29 00:00:00+00:00 12 >>> print(round(longest.duration.values.sum() / oversold.sum(), 3)) 0.324 >>> print(oversold.vbt.signals.first().sum()) # (2) 33 ``` 1. A partition is a run of consecutive `True` values. Each one becomes a range record. 2. Keep only the first day of each episode. Seven years of daily data show 111 oversold days, but only 33 separate episodes, and the three longest ones hold a third of all those days. A strategy that buys oversold readings is mostly a bet on a handful of crashes, which is worth knowing before reading its backtest. ## Crossovers and thresholds \[#crossovers-and-thresholds] `crossed_above` and `crossed_below` mark the bar where one series crosses another or a level, and `above` and `below` mark every bar on one side. A crossover can require the new side to hold for a number of bars with `wait`, and missing values can be skipped instead of breaking the comparison, as the [Robust crossovers](#robust-crossovers) highlight below shows. Every indicator output has these methods too, such as `rsi.rsi_crossed_below(30)`. ## Combining conditions \[#combining-conditions] Conditions combine with `&`, `|`, and `~` across assets and parameter combinations, because signals are aligned arrays like any other. Outputs of indicators run with different parameters carry different column labels, such as `fast_window` 5 and 10 against `slow_window` 20 and 25, and pandas refuses to compare them. Put `.vbt` in front, as in `fast.vbt > slow`, or use `fast.vbt.crossed_above(slow)`: both align the columns and label the result with both parameters. A condition that should stay valid for a while, such as "RSI went below 30 in the last five days", is a rolling maximum of its mask: ```python title="Enter when price turns up within five days of an oversold cross" >>> crossed_down = rsi.vbt.crossed_below(30) >>> recently_oversold = crossed_down.rolling(5, min_periods=1).max().astype(bool) >>> trigger = btc.close.vbt.crossed_above(btc.close.rolling(10).mean()) >>> entries = recently_oversold & trigger >>> print(crossed_down.sum(), trigger.sum(), entries.sum()) 33 215 12 ``` The same approach covers streaks of consecutive bars, divergences between price and momentum, and signals from one asset used to trade another. ## Pivots and calendars \[#pivots-and-calendars] `vbt.PIVOTINFO` detects swing highs and lows that reversed by at least a given fraction, and tells confirmed pivots from the latest candidate, which can still change. The [Pivot detection](#pivot-detection) highlight below plots both. Calendar signals are masks over the index, for example the first trading day of each week or a fixed time of day, and `first` keeps the first signal of each consecutive run so a rule fires once per episode. ## One signal per day \[#one-signal-per-day] A strategy may allow one opportunity per day even if its condition becomes true several times. Group the mask by day and keep its first event. This differs from keeping the first event of each consecutive run, because later events may be separated by `False` values. ```python title="Keep the first signal of each day, including days with no signals" >>> @njit ... def first_signal_nb(values): ... out = np.full(values.shape, False) ... for i in range(len(values)): ... if values[i]: ... out[i] = True ... break ... return out >>> mask = pd.Series( ... [True, False, True, False, False, False, False, True, True], ... index=pd.date_range("2025-01-01", periods=9, freq="8h"), ... ) >>> first_per_day = mask.vbt.groupby_transform("D", first_signal_nb) >>> pd.DataFrame({ ... "Raw signals": mask.resample("D").sum(), ... "First per day": first_per_day.resample("D").sum(), ... }) Raw signals First per day 2025-01-01 2 1 2025-01-02 0 0 2025-01-03 2 1 ``` The empty day stays empty. The same grouping approach can express one opportunity per week or another calendar period, while signal ranking lets you select later events in a sequence. ## Custom generators \[#custom-generators] When a signal depends on earlier signals, such as an exit that must come a minimum number of bars after its entry, a vectorized mask is not enough. The signal factory builds generators from compiled placement functions that search forward from each entry for its exit, and `generate_random` and `generate_random_both` create reproducible random signals for baselines. Placement functions receive a context with the search window and the column, as described in the [Signal contexts](#signal-contexts) highlight. ## Cleaning and analysis \[#cleaning-and-analysis] Raw entry and exit masks often repeat themselves. `clean` keeps the first entry after each exit and the first exit after each entry, which turns them into alternating pairs: ```python title="Clean entries and exits into alternating pairs" >>> exits = rsi.vbt.crossed_above(70) >>> print(entries.sum(), exits.sum()) 12 60 >>> clean_entries, clean_exits = entries.vbt.signals.clean(exits) >>> print(clean_entries.sum(), clean_exits.sum()) 8 8 ``` Cleaning is for analysis. `vbt.PF.from_signals` resolves repeated signals itself, and cleaning before an accumulating backtest would remove the extra entries that accumulation relies on. Signals can also be ranked, counted per period, measured by the distance between them, unraveled into one column per signal, and summarized with `stats()`. Shift a signal forward with `fshift` when it is computed from the close and executed on the next bar. The [Signal unraveling](#signal-unraveling) and [Signal detection](#signal-detection) highlights below show two of these tools. ## From a signal to a trade \[#from-a-signal-to-a-trade] Use signal analysis to check what your rule captures: how often it fires, how long conditions persist, and whether events cluster in a few periods. Random signals provide a baseline for comparing your entry rule, while unraveling lets you inspect each opportunity separately. [Patterns and event studies](/features/analytics/patterns-and-event-studies/) takes this further by examining the price paths after events. A signal is a request to trade. Pass it to [Signal backtesting](/features/backtesting/signal-backtesting/) to account for position size, fees, stops, and whether orders can fill. If the next signal depends on an actual fill, available cash, or the current position, generate it inside a simulation callback as described in [Event-driven backtesting](/features/backtesting/event-driven-backtesting/). This also lets signals from one asset influence decisions in another. ## Signal unraveling \[#signal-unraveling] New in v2024.2.22 ✅ To backtest each signal individually, you can now "unravel" each signal, or each pair of entry and exit signals, into its own column. This creates a wide, two-dimensional mask that, when backtested, returns performance metrics for each signal rather than for the entire column. ```python title="For each signal, create a separate position with own stop orders" >>> data = vbt.YFData.pull("BTC-USD") >>> fast_sma = data.run("talib_func:sma", timeperiod=20) # (1) >>> slow_sma = data.run("talib_func:sma", timeperiod=50) >>> entries = fast_sma.vbt.crossed_above(slow_sma) >>> exits = fast_sma.vbt.crossed_below(slow_sma) >>> entries, exits = entries.vbt.signals.unravel_between(exits, relation="anychain") # (2) >>> pf = vbt.PF.from_signals( ... data, ... long_entries=entries, ... short_entries=exits, ... size=100, # (3) ... size_type="value", ... init_cash="auto", # (4) ... tp_stop=0.2, ... sl_stop=0.1, ... group_by=vbt.ExceptLevel("signal"), # (5) ... cash_sharing=True ... ) >>> pf.positions.returns.to_pd(ignore_index=True).vbt.barplot( ... trace_kwargs=dict(marker=dict(colorscale="Spectral")) ... ).show() # (6) ``` 1. Run a TA-Lib function faster without building an indicator: `"talib_func:sma"` vs `"talib:sma"`. 2. Place each pair of entry->exit and exit->entry signals in a separate column. 3. Order $100 worth of the asset. 4. Simulate with infinite cash. 5. Combine all columns (positions) under the same asset into a single portfolio. 6. Show position returns by signal index. Position returns for individually unraveled BTC-USD signals. [Figure data (JSON)](/assets/figures/features/indicators/signal-unraveling.5e7c83dd018b.json) ## Signal detection \[#signal-detection] New in 1.8.0 ✅ VBT includes an indicator that uses a robust peak detection algorithm based on z-scores. This indicator can be used to identify outbreaks and outliers in any time series data. ```python title="Detect sudden changes in the bandwidth of a Bollinger Bands indicator" >>> data = vbt.YFData.pull("BTC-USD") >>> fig = vbt.make_subplots(rows=2, cols=1, shared_xaxes=True) >>> bbands = data.run("bbands") >>> bbands.loc["2022"].plot(add_trace_kwargs=dict(row=1, col=1), fig=fig) >>> sigdet = vbt.SIGDET.run(bbands.bandwidth, factor=5) >>> sigdet.loc["2022"].plot(add_trace_kwargs=dict(row=2, col=1), fig=fig) >>> fig.show() ``` BTC-USD Bollinger Bands and detected bandwidth changes during 2022. [Figure data (JSON)](/assets/figures/features/indicators/signal-detection.af030867491c.json) ## Pivot detection \[#pivot-detection] New in 1.7.1 ✅ The pivot detection indicator is a tool for finding when the price trend is reversing. By identifying support and resistance areas, it helps spot significant price changes while filtering out short-term fluctuations and reducing noise. A valley is confirmed after the price rises by the chosen threshold, and a peak after it falls by the chosen threshold. The indicator exposes both the last confirmed pivot and the current candidate. Use the confirmed information from the bar where the reversal becomes known when building a trading rule. A [regular Zig Zag indicator](https://www.investopedia.com/ask/answers/030415/what-zig-zag-indicator-formula-and-how-it-calculated.asp) plots the turning points back at their original locations, which serves a different purpose from deciding when a strategy could act. ```python title="Plot the last pivot value" >>> data = vbt.YFData.pull("BTC-USD", start="2020", end="2023") >>> fig = data.plot(plot_volume=False) >>> pivot_info = data.run("pivotinfo", up_th=1.0, down_th=0.5) >>> pivot_info.plot(fig=fig, conf_value_trace_kwargs=dict(visible=False)) >>> fig.show() ``` BTC-USD OHLC with confirmed pivot values from 2020 through 2022. [Figure data (JSON)](/assets/figures/features/indicators/pivot-detection.0678a96251d4.json) ## Robust crossovers \[#robust-crossovers] New in 1.0.0 ✅ Crossovers are now robust to NaNs. ```python title="Remove a bunch of data points and plot the crossovers" >>> data = vbt.YFData.pull("BTC-USD", start="2022-01", end="2022-03") >>> fast_sma = vbt.talib("SMA").run(data.close, vbt.Default(5)).real >>> slow_sma = vbt.talib("SMA").run(data.close, vbt.Default(10)).real >>> np.random.seed(42) >>> fast_sma.iloc[np.random.choice(np.arange(len(fast_sma)), 5)] = np.nan >>> slow_sma.iloc[np.random.choice(np.arange(len(slow_sma)), 5)] = np.nan >>> crossed_above = fast_sma.vbt.crossed_above(slow_sma, skipna=True) >>> crossed_below = fast_sma.vbt.crossed_below(slow_sma, skipna=True) >>> fig = fast_sma.rename("Fast SMA").vbt.lineplot() >>> slow_sma.rename("Slow SMA").vbt.lineplot(fig=fig) >>> crossed_above.vbt.signals.plot_as_entries(fast_sma, fig=fig) >>> crossed_below.vbt.signals.plot_as_exits(fast_sma, fig=fig) >>> fig.show() ``` Robust fast and slow BTC-USD moving-average crossovers with missing data. [Figure data (JSON)](/assets/figures/features/indicators/resilient-crossovers.64a086686925.json) ## Signal contexts \[#signal-contexts] New in 1.2.3 ✅ Signal generation functions have been redesigned to operate on contexts. This allows you to design more complex signal strategies with less namespace pollution. ```python title="Entry at the first bar of the week, exit at the last bar of the week" >>> @njit ... def entry_place_func_nb(ctx, index): ... for i in range(ctx.from_i, ctx.to_i): # (1) ... if i == 0: ... return i - ctx.from_i # (2) ... else: ... index_before = index[i - 1] ... index_now = index[i] ... index_next_week = vbt.dt_nb.future_weekday_nb(index_before, 0) ... if index_now >= index_next_week: # (3) ... return i - ctx.from_i ... return -1 >>> @njit ... def exit_place_func_nb(ctx, index): ... for i in range(ctx.from_i, ctx.to_i): ... if i == len(index) - 1: ... return i - ctx.from_i ... else: ... index_now = index[i] ... index_after = index[i + 1] ... index_next_week = vbt.dt_nb.future_weekday_nb(index_now, 0) ... if index_after >= index_next_week: # (4) ... return i - ctx.from_i ... return -1 >>> data = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2020-01-14") >>> entries, exits = vbt.pd_acc.signals.generate_both( ... data.symbol_wrapper.shape, ... entry_place_func_nb=entry_place_func_nb, ... entry_place_args=(data.index.vbt.to_ns(),), ... exit_place_func_nb=exit_place_func_nb, ... exit_place_args=(data.index.vbt.to_ns(),), ... wrapper=data.symbol_wrapper ... ) >>> pd.concat(( ... entries.rename("Entries"), ... exits.rename("Exits") ... ), axis=1).to_period("W") Entries Exits Date 2020-01-06/2020-01-12 True False 2020-01-06/2020-01-12 False False 2020-01-06/2020-01-12 False False 2020-01-06/2020-01-12 False False 2020-01-06/2020-01-12 False False 2020-01-06/2020-01-12 False False 2020-01-06/2020-01-12 False True 2020-01-13/2020-01-19 True False ``` 1. Iterate over the bars in the current period segment. 2. If a signal should be placed, return an index relative to the segment. 3. Place a signal if the current bar crosses Monday. 4. Place a signal if the next bar crosses Monday. !!! info "Tutorial" Learn more in the [Signal development](/tutorials/signal-development) tutorial. # Optimization and validation (/features/optimization) Search parameters, validate them out of sample, test whether results survive, and allocate across assets. Turn a strategy into a repeatable research workflow, from large parameter sweeps to walk-forward testing, robustness checks, and portfolio optimization. ## Start here \[#start-here] | What do you want to test? | Where to start | | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Which windows, thresholds, stops, or rules work together | [Parameter optimization](/features/optimization/strategy-optimization/) | | How selected settings perform on data they were not chosen on | [Walk-forward and cross-validation](/features/optimization/time-series-cross-validation/) | | Whether results depend on a lucky setting, filter, or price history | [Robustness and overfitting](/features/optimization/robustness-and-overfitting/) | | How to weight assets and what rebalancing costs | [Portfolio optimization](/features/optimization/portfolio-optimization/) | * [Parameter optimization](/features/optimization/strategy-optimization): Sweep millions of parameter combinations with grids, conditions, and random search * [Walk-forward and cross-validation](/features/optimization/time-series-cross-validation): Test optimized parameters out of sample with rolling, expanding, and purged splits * [Robustness and overfitting](/features/optimization/robustness-and-overfitting): Check whether a backtest is luck with baselines, permutation tests, and deflated Sharpe * [Portfolio optimization](/features/optimization/portfolio-optimization): Allocate with your own functions or optimizer libraries and backtest rebalancing ## From a parameter search to a tested strategy \[#from-a-parameter-search-to-a-tested-strategy] Start with a Python function that calculates signals, runs a backtest, and returns the metrics you want to compare. VBT can run it over a grid or random sample of parameter combinations, then repeat the search across training windows and evaluate the selected settings on the following test periods. You can keep your existing pandas calculations and choose your own scoring rule. The robustness checks help you investigate what drives the result. Compare nearby settings, remove a filter, delay the signals, or repeat the search on shuffled histories. Results stay labeled by the combinations you tested, so you can inspect [drawdowns](/features/analytics/drawdown-analysis/) and [trade behavior](/features/analytics/trade-analytics/) alongside a headline Sharpe ratio. ## From asset weights to a backtest \[#from-asset-weights-to-a-backtest] Portfolio optimization starts with weights. Supply your own weight table, calculate allocations with a function, or use PyPortfolioOpt, Riskfolio-Lib, or Universal Portfolios. VBT turns the targets into a simulation where you can compare rebalancing schedules, weight drift, fees, and performance. An equal-weight basket gives you a simple baseline for the more elaborate methods. The worked pages show both sides of the process: searching strategy settings and evaluating them out of sample, then comparing asset allocations after trading costs. ## Worked tutorials \[#worked-tutorials] Follow the [Cross-validation tutorial](/tutorials/cross-validation/) to test strategy robustness, or the [Portfolio optimization tutorial](/tutorials/portfolio-optimization/) to compare allocation methods. # Portfolio optimization (/features/optimization/portfolio-optimization) How should you weight assets over time, and what does rebalancing cost? VBT runs portfolio optimization in Python on any schedule: write your own allocation function or call PyPortfolioOpt, Riskfolio-Lib, or Universal Portfolios, then backtest the weights with fees. ```python title="Backtest monthly max Sharpe, inverse volatility, and equal weight on 10 ETFs" >>> symbols = ["SPY", "QQQ", "IWM", "EFA", "EEM", "TLT", "IEF", "GLD", "VNQ", "DBC"] >>> data = vbt.YFData.pull(symbols, start="2016-01-01", end="2025-01-01") >>> def inverse_vol(returns): ... inv = 1 / returns.std() ... return inv / inv.sum() >>> wrapper = data.symbol_wrapper >>> returns = vbt.RepEval("data.returns.iloc[index_slice]", context=dict(data=data)) >>> schedule = dict(every="M", lookback_period="365D") # (1) >>> optimizers = { ... "Equal weight": vbt.PFO.from_uniform(wrapper, every="M", start="2017"), ... "Inverse volatility": vbt.PFO.from_optimize_func( ... wrapper, inverse_vol, returns, **schedule ... ), ... "Max Sharpe": vbt.PFO.from_pypfopt( ... prices=data.close, target="max_sharpe", **schedule ... ), ... } >>> pfs = { ... name: pfo.simulate(data, init_cash=10_000, fees=0.001).loc["2017":] # (2) ... for name, pfo in optimizers.items() ... } >>> metrics = ["total_return", "sharpe_ratio", "max_dd", "total_fees_paid"] >>> stats = {name: pf.stats(metrics) for name, pf in pfs.items()} >>> pd.DataFrame(stats).astype(float).round(2) Equal weight Inverse volatility Max Sharpe Total Return [%] 85.49 60.56 58.00 Sharpe Ratio 0.85 0.79 0.59 Max Drawdown [%] 23.17 21.80 28.11 Total Fees Paid 46.63 53.14 479.83 ``` 1. Every month, each optimizer looks at the previous 365 days. The first window ends in January 2017, so the equal-weight portfolio also starts then. 2. New weights are traded at the close of the first bar after each window, so no weight uses prices it could not have seen. Slicing from 2017 compares the three over the same period. Portfolio value of equal weight, inverse volatility, and max Sharpe allocations on 10 ETFs from 2017 to 2024. [Figure data (JSON)](/assets/figures/features/optimization/allocation-comparison.7195e06f1cfb.json) The max Sharpe optimizer picks the weights with the best Sharpe ratio on each trailing year, yet it finished last on the months that followed: the lowest Sharpe ratio, the deepest drawdown, and ten times the fees, because its weights jump between a few assets. Equal weight, the simplest allocation, did best. Results like this are why a baseline belongs next to every optimizer. ## Backtest your own weights \[#backtest-your-own-weights] Already have allocations from a model, a spreadsheet, or another optimizer? Pass them as a pandas DataFrame, with assets in columns and rebalancing dates in the index. VBT turns those targets into a portfolio simulation, so you can inspect the resulting trades, fees, and performance. This example uses made-up prices and two weight changes supplied in advance. The portfolio starts 60% in A and 40% in B, then switches to 30% and 70% on January 3. ```python title="Backtest a supplied weight table" >>> close = pd.DataFrame( ... {"A": [100, 120, 110, 121], "B": [100, 100, 110, 110]}, ... index=pd.date_range("2025-01-01", periods=4), ... ) >>> weights = pd.DataFrame( ... [[0.6, 0.4], [0.3, 0.7]], ... index=close.index[[0, 2]], ... columns=close.columns, ... ) >>> pfo = vbt.PFO.from_allocations(close.vbt.wrapper, weights) >>> portfolio = pfo.simulate(close, init_cash=1000, fees=0.001, freq="1D") >>> pfo.allocations A B 2025-01-01 0.6 0.4 2025-01-03 0.3 0.7 >>> portfolio.get_allocations().round(3) A B 2025-01-01 0.600 0.400 2025-01-02 0.642 0.358 2025-01-03 0.300 0.700 2025-01-04 0.321 0.679 >>> round(portfolio.orders.fees.sum(), 2) 1.66 ``` The target weights change only on the two supplied dates. Actual weights drift with prices between them, and the simulation records 1.66 in fees. For a basket you buy once and then hold, use `from_initial` with one set of weights. To keep returning to fixed weights, use `from_allocations` with a rebalancing schedule. ## Allocation and optimization functions \[#allocation-and-optimization-functions] VBT separates when to rebalance from how to weight: | Constructor | Weights come from | | -------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `vbt.PFO.from_allocate_func` | Your function, called at each rebalancing date | | `vbt.PFO.from_optimize_func` | Your function, called on a window of past data before each date | | `vbt.PFO.from_uniform`, `vbt.PFO.from_random` | Equal weights, or seeded random weights | | `vbt.PFO.from_initial`, `vbt.PFO.from_allocations` | Fixed weights you supply, applied once or on a schedule | | `vbt.PFO.from_filled_allocations` | A weight table you computed in advance, one row per bar, rebalancing whenever a row changes | An optimization function receives whatever arguments you pass, with templates such as `index_slice`, `index_start`, and `index_end` filled in for the current window. It returns one weight per asset, so volatility targeting, risk parity, or weights proportional to a forecast are each a few lines of pandas. `lookback_period` sets how much history each window holds, separately from the schedule, and `alloc_wait` controls how many bars after the window the new weights take effect. Wrap any argument in `vbt.Param` to test several values in one call, and use `jitted_loop=True` with a Numba function to run thousands of windows quickly. Your function can also screen the asset universe inside each window, such as excluding assets with too little history or volume before calculating the remaining weights. Return a weight for each asset, including zero for assets you want to leave out. Each window starts without history, so a rolling indicator computed inside the function loses its first bars in every window. Compute indicators once on the full history and slice them with `index_slice` instead. Weights are fractions of the portfolio's value and do not have to sum to one. Whatever is not allocated stays in cash, which turns volatility targeting into a few lines: ```python title="Scale equal weights down to target 8% annual volatility" >>> def vol_target(returns, target=0.08): ... vol = returns.mean(axis=1).std() * np.sqrt(252) # (1) ... weight = min(1, target / vol) / returns.shape[1] ... return np.full(returns.shape[1], weight) >>> pfo = vbt.PFO.from_optimize_func(wrapper, vol_target, returns, **schedule) >>> pf_target = pfo.simulate(data, init_cash=10_000, fees=0.001).loc["2017":] >>> compare = {"Equal weight": pfs["Equal weight"], "Vol target 8%": pf_target} >>> pd.DataFrame({ ... name: { ... "invested": pf.get_allocations().sum(axis=1).mean(), # (2) ... "volatility": pf.annualized_volatility, ... "sharpe": pf.sharpe_ratio, ... "max_dd": pf.max_drawdown, ... } ... for name, pf in compare.items() ... }).T.round(2) invested volatility sharpe max_dd Equal weight 1.00 0.14 0.85 -0.23 Vol target 8% 0.75 0.11 0.57 -0.23 ``` 1. The volatility of the equal-weight basket over the previous 365 days, annualized. 2. The share of the portfolio's value held in assets on each bar, averaged over the period. The target held about a quarter of the portfolio in cash and lowered volatility, but missed 8% because the trailing year lags the market. It also gave up a third of the Sharpe ratio and none of the drawdown: the COVID crash came after a calm year, when the target was fully invested, and the cash was held through the recovery that followed. ## Optimizer libraries \[#optimizer-libraries] `vbt.PFO.from_pypfopt`, `vbt.PFO.from_riskfolio`, and `vbt.PFO.from_universal_algo` run [PyPortfolioOpt](#pyportfolioopt), [Riskfolio-Lib](#riskfolio-lib), and [Universal Portfolios](#universal-portfolios) on the same schedule as your own functions. Each library's models, constraints, and objectives are passed as keyword arguments, so they can be parameterized like any other argument. When an optimizer returns no weights for a window, VBT drops that window with a warning and the portfolio keeps its current holdings until the next date. That happened once in the max Sharpe run above. An optimizer that raises an error stops the run unless you pass `ignore_errors=True`, which drops that window the same way. The PyPortfolioOpt integration also accepts custom objectives, weight bounds, and sector limits. For example, you can compare a default allocation with one that caps individual assets or sectors, then measure the difference after rebalancing costs. The library chooses weights under those constraints, while VBT evaluates the resulting trades over time. Universal Portfolios works differently: it runs its algorithm once over the whole price history and returns weights for every bar, so VBT rebalances whenever those weights change, unless you pass rebalancing dates through `on`. The library iterates bar by bar in plain Python, which makes it much slower than the other two on long histories. ## Rebalancing schedules \[#rebalancing-schedules] `every` takes a pandas frequency such as weekly, monthly, or quarterly. Allocation functions also accept exact dates through `on` or `index_points`, and optimization functions accept exact windows through `index_ranges`. Testing several schedules shows what rebalancing costs: ```python title="Rebalance equal weights weekly, monthly, quarterly, and yearly" >>> uniform = vbt.PFO.from_uniform( ... data.symbol_wrapper, every=vbt.Param(["W", "M", "Q", "Y"]), start="2017" ... ) >>> pf = uniform.simulate(data, init_cash=10_000, fees=0.001).loc["2017":] >>> pd.DataFrame({ ... "sharpe": pf.sharpe_ratio, ... "fees": pf.orders.fees.sum(), ... "orders": pf.orders.count(), ... }).round(2) sharpe fees orders every W 0.85 87.74 4180 M 0.85 46.63 960 Q 0.88 32.06 320 Y 0.86 20.07 80 ``` Rebalancing every week instead of every quarter nearly tripled fees without improving the Sharpe ratio. To rebalance only when weights drift past a threshold, or to compute weights from the current state of the simulated portfolio, write the rebalancing logic as a simulation callback with `vbt.PF.from_order_func`, as the members-only [Dynamic portfolio optimization](https://members.vectorbt.pro/tutorials/portfolio-optimization/dynamic/) tutorial shows. ## From allocations to a portfolio \[#from-allocations-to-a-portfolio] `pfo.simulate(data)` turns the allocation history into target-percent orders with shared cash, using `vbt.PF.from_orders` by default. Pass `pf_method="from_signals"` to add stop losses and other exits from the [Stop loss and take profit](/features/backtesting/stop-loss-and-take-profit/) page. Before simulating, the optimizer itself can be inspected: * `pfo.allocations` holds the weights at each rebalancing date, and `pfo.alloc_records` links each one to the window of data it came from. * `pfo.mean_allocation`, `pfo.stats()`, and `pfo.plot()` summarize and chart the weights. * `rescale_to` maps positive and negative weights into a range, such as -1 to 1 for a long-short book, and `pf.get_allocations()` shows how the actual weights drift between rebalancing dates. * `pfo.replace(allocations=...)` swaps in edited weights, and `vbt.PFO.column_stack` combines optimizers built separately on different columns, such as one per strategy, into one simulation. ### Compare and combine allocation methods \[#compare-and-combine-allocation-methods] Allocation histories are available before simulation, so you can average the weights from two models or apply your own adjustments, then backtest the revised targets. Match the assets and rebalancing dates before combining them. This is useful when you want to compare each model with a blended allocation under the same fees and schedule. When comparing lookback periods, evaluate the portfolios over a common period after every method has enough history, as the opening example does. Inspect the [orders](/features/backtesting/orders-and-execution/) to see how often the targets actually trade, and compare [drawdowns](/features/analytics/drawdown-analysis/) and fees alongside returns. The [Walk-forward and cross-validation](/features/optimization/time-series-cross-validation/) page shows how to repeat selection and evaluation across time. New weights take effect `alloc_wait` bars after their window ends, one by default. A window that ends on the last bar of the data therefore has nowhere to place its weights, and VBT warns about it. To get the weights for the next trade in live use, pass `alloc_wait=0` so they land on the last bar. !!! info "Tutorial" The members-only [Portfolio optimization](https://members.vectorbt.pro/tutorials/portfolio-optimization/) tutorial covers allocation and optimization functions, index points and ranges, the library integrations, and dynamic rebalancing. ## Riskfolio-Lib \[#riskfolio-lib] New in 1.7.0 ✅ [Riskfolio-Lib](https://github.com/dcajasn/Riskfolio-Lib) is another increasingly popular library for portfolio optimization that has been integrated into VBT. Integration was done by automating typical workflows inside Riskfolio-Lib and putting them into a single function, so many portfolio optimization problems can be expressed using a single set of keyword arguments and easily parameterized. ```python title="Run hierarchical risk parity (HRP) with Riskfolio-Lib on a monthly basis" >>> data = vbt.YFData.pull( ... ["SPY", "TLT", "XLF", "XLE", "XLU", "XLK", "XLB", "XLP", "XLY", "XLI", "XLV"], ... start="2020", ... end="2023", ... missing_index="drop" ... ) >>> pfo = vbt.PFO.from_riskfolio( ... returns=data.close.vbt.to_returns(), ... port_cls="hc", ... every="M" ... ) >>> pfo.plot().show() ``` Monthly asset weights from Riskfolio-Lib hierarchical risk parity from 2020 through 2022. [Figure data (JSON)](/assets/figures/features/optimization/riskfolio-lib.c10fa4f9b800.json) !!! info "Tutorial" Learn more in the [Portfolio optimization](/tutorials/portfolio-optimization) tutorial. ## Portfolio optimization \[#portfolio-optimization] New in 1.2.0 ✅ Portfolio optimization is the process of creating a portfolio of assets that aims to maximize return and minimize risk. Usually, this process is performed periodically and involves generating new weights to rebalance an existing portfolio. As with most things in VBT, the weight generation step is implemented as a callback by the user, while the optimizer calls that callback periodically. The final result is a collection of returned weight allocations that can be analyzed, visualized, and used in actual simulations 🥧 ```python title="Allocate assets inversely to their total return in the last month" >>> def regime_change_optimize_func(data): ... returns = data.returns ... total_return = returns.vbt.returns.total() ... weights = data.symbol_wrapper.fill_reduced(0) ... pos_mask = total_return > 0 ... if pos_mask.any(): ... weights[pos_mask] = total_return[pos_mask] / total_return.abs().sum() ... neg_mask = total_return < 0 ... if neg_mask.any(): ... weights[neg_mask] = total_return[neg_mask] / total_return.abs().sum() ... return -1 * weights >>> data = vbt.YFData.pull( ... ["SPY", "TLT", "XLF", "XLE", "XLU", "XLK", "XLB", "XLP", "XLY", "XLI", "XLV"], ... start="2020", ... end="2023", ... missing_index="drop" ... ) >>> pfo = vbt.PFO.from_optimize_func( ... data.symbol_wrapper, ... regime_change_optimize_func, ... vbt.RepEval("data[index_slice]", context=dict(data=data)), ... every="M" ... ) >>> pfo.plot().show() ``` Monthly regime-change portfolio allocations across eleven assets from 2020 through 2022. [Figure data (JSON)](/assets/figures/features/optimization/portfolio-optimization.f2d874e1afd4.json) !!! info "Tutorial" Learn more in the [Portfolio optimization](/tutorials/portfolio-optimization) tutorial. ## PyPortfolioOpt \[#pyportfolioopt] New in 1.2.0 ✅ [PyPortfolioOpt](https://github.com/robertmartin8/PyPortfolioOpt) is a popular financial portfolio optimization package that includes both classical methods (Markowitz 1952 and Black-Litterman), suggested best practices (such as covariance shrinkage), and many recent developments and novel features, like L2 regularization, shrunk covariance, and hierarchical risk parity. ```python title="Run hierarchical risk parity (HRP) with PyPortfolioOpt on a monthly basis" >>> data = vbt.YFData.pull( ... ["SPY", "TLT", "XLF", "XLE", "XLU", "XLK", "XLB", "XLP", "XLY", "XLI", "XLV"], ... start="2020", ... end="2023", ... missing_index="drop" ... ) >>> pfo = vbt.PFO.from_pypfopt( ... returns=data.returns, ... optimizer="hrp", ... target="optimize", ... every="M" ... ) >>> pfo.plot().show() ``` Monthly asset weights from PyPortfolioOpt hierarchical risk parity from 2020 through 2022. [Figure data (JSON)](/assets/figures/features/optimization/pyportfolioopt.71817c556f5b.json) !!! info "Tutorial" Learn more in the [Portfolio optimization](/tutorials/portfolio-optimization) tutorial. ## Universal Portfolios \[#universal-portfolios] New in 1.2.0 ✅ [Universal Portfolios](https://github.com/Marigold/universal-portfolios) is a package that brings together various Online Portfolio Selection (OLPS) algorithms. ```python title="Simulate an online minimum-variance portfolio on a weekly timeframe" >>> data = vbt.YFData.pull( ... ["SPY", "TLT", "XLF", "XLE", "XLU", "XLK", "XLB", "XLP", "XLY", "XLI", "XLV"], ... start="2020", ... end="2023", ... missing_index="drop" ... ) >>> pfo = vbt.PFO.from_universal_algo( ... "MPT", ... data.resample("W").close, ... window=52, ... min_history=4, ... mu_estimator='historical', ... cov_estimator='empirical', ... method='mpt', ... q=0 ... ) >>> pfo.plot().show() ``` Weekly online minimum-variance portfolio weights across eleven assets from 2020 through 2022. [Figure data (JSON)](/assets/figures/features/optimization/universal-portfolios.2016998532d6.json) !!! info "Tutorial" Learn more in the [Portfolio optimization](/tutorials/portfolio-optimization) tutorial. # Robustness and overfitting (/features/optimization/robustness-and-overfitting) Is the edge in a backtest real, or did the search just find the luckiest parameters? VBT tests backtest overfitting in Python with baselines, parameter sensitivity, permutation tests on shuffled data, and the probabilistic and deflated Sharpe ratios. ```python title="Compare the best of 72 strategies with the best on 1,000 shuffled histories" >>> from itertools import product >>> data = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2025-01-01") >>> pairs = list(product(range(10, 55, 5), range(60, 220, 20))) >>> def best_sharpe(close): # (1) ... sharpe = [] ... for fast_window, slow_window in pairs: ... fast = close.rolling(fast_window).mean() ... slow = close.rolling(slow_window).mean() ... pf = vbt.PF.from_signals( ... close, fast > slow, fast < slow, fees=0.001, freq="1D" ... ) ... sharpe.append(pf.sharpe_ratio) ... return pd.concat(sharpe, axis=1).max(axis=1) >>> real_best = best_sharpe(data.close.to_frame()).iloc[0] >>> returns = data.close.pct_change().iloc[1:] >>> shuffled = pd.DataFrame(np.tile(returns.values[:, None], 1000), index=returns.index) >>> shuffled = shuffled.vbt.shuffle(seed=42) # (2) >>> perm_best = best_sharpe(data.close.iloc[0] * (1 + shuffled).cumprod()) >>> p_value = ((perm_best >= real_best).sum() + 1) / (len(perm_best) + 1) >>> print(round(real_best, 3), round(perm_best.median(), 3), round(p_value, 3)) 1.406 1.162 0.154 ``` 1. Runs all 72 moving average pairs on every column and keeps the best Sharpe ratio per column. With 1,000 columns, that is 72,000 backtests, which took 12 seconds on an Apple M3. 2. Shuffles the daily returns separately in each of the 1,000 columns. Every shuffled history has the same returns and the same final price as Bitcoin, in a random order. Histogram of the best Sharpe ratio on 1,000 shuffled Bitcoin histories, with the best Sharpe ratio on real prices marked. [Figure data (JSON)](/assets/figures/features/optimization/permutation-test.56a0e3418d25.json) The best crossover on real Bitcoin prices reached a Sharpe ratio of 1.41. Searching the same 72 pairs on prices reconstructed from shuffled returns found a better result 15% of the time. A p-value of 0.15 means the search cannot show that the crossover timing adds anything beyond Bitcoin's rise. ```python title="Deflate the best Sharpe ratio for 72 trials" >>> fast = vbt.MA.run(data.close, window=[f for f, _ in pairs], short_name="fast") >>> slow = vbt.MA.run(data.close, window=[s for _, s in pairs], short_name="slow") >>> pf = vbt.PF.from_signals(data, fast.ma_above(slow), fast.ma_below(slow), fees=0.001) >>> best = pf.sharpe_ratio.idxmax() # (1) >>> print(round(pf.deflated_sharpe_ratio[best], 3), round(pf.prob_sharpe_ratio[best], 3)) 0.995 0.737 ``` 1. The same winner as above: a 25-day fast and a 100-day slow average. The deflated Sharpe ratio gives a 99.5% probability that the best pair's true Sharpe ratio is above what the luckiest of 72 skill-free trials would show, but it says nothing about holding. The probabilistic Sharpe ratio compares the same pair with buying and holding Bitcoin and puts the chance of beating it at 74%. Each test asks a different question, which is why one is rarely enough. ## Choose a robustness test \[#choose-a-robustness-test] Different tests help explain different weaknesses. You can use the same strategy function and compare the results in labeled pandas tables. | What you want to check | What to compare | | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Whether entry timing adds value | [Buy and hold and random entries](#baselines) | | Whether a precise setting drives the result | [Nearby parameters](#parameter-sensitivity) | | Whether an extra rule helps | [The strategy with each filter on and off](#test-which-filters-help) | | Whether execution assumptions drive the result | [Signal delays and higher costs](#execution-sensitivity) | | Whether the search could find a similar winner by chance | [Repeated searches on shuffled data](#perturbed-and-permuted-data) and [adjusted Sharpe measures](#statistical-tests) | For each comparison, keep the dates, sizing, and execution assumptions consistent unless those are what you are testing. Alongside returns, inspect [drawdowns](/features/analytics/drawdown-analysis/) and [trade counts and exposure](/features/analytics/trade-analytics/) to see what changed. ## Baselines \[#baselines] Every result needs something to beat. `vbt.PF.from_holding` buys once and holds, and `vbt.PF.from_random_signals` enters and exits at random with a seed, using either a fixed number of signals or a probability per bar. ```python title="Compare with buy and hold and 1,000 random portfolios" >>> hold = vbt.PF.from_holding(data, fees=0.001) >>> n_trades = pf.trades.count()[best] >>> rand = vbt.PF.from_random_signals(data, n=[n_trades] * 1000, seed=42, fees=0.001) >>> print(n_trades, round(hold.sharpe_ratio, 3), round(rand.sharpe_ratio.median(), 3)) 8 1.126 1.015 ``` The best pair beats holding and every one of the 1,000 random portfolios with the same 8 trades. That is still one strategy chosen after the fact from 72, so it does not settle the question. The permutation test above repeats the whole search on each shuffled history, which accounts for the search itself. ## Parameter sensitivity \[#parameter-sensitivity] A robust strategy has a plateau: neighboring parameters perform about as well as the best one. A single peak surrounded by weak results usually means one lucky trade or one lucky period. Laying the Sharpe ratios out by parameter shows which kind of result you have. ```python title="Sharpe ratio for each pair of windows" >>> pf.sharpe_ratio.unstack("slow_window").iloc[:5, :6].round(2) slow_window 60 80 100 120 140 160 fast_window 10 1.23 1.17 1.37 1.32 1.17 1.29 15 1.25 1.12 1.37 1.16 1.17 1.17 20 1.30 1.14 1.22 1.15 1.22 1.25 25 1.21 1.24 1.41 1.20 1.32 1.27 30 1.02 1.19 1.32 1.20 1.20 1.27 ``` The eight neighbors of 25 and 100 score between 1.14 and 1.32, so this result is not an isolated spike. The same layout works for ablation tests: pass each filter of a strategy as an on and off parameter and compare the strategy with and without it. The [Parameter optimization](/features/optimization/strategy-optimization/) page covers heatmaps and large parameter grids. ### Test which filters help \[#test-which-filters-help] An extra filter can improve the headline return simply by leaving fewer trades. An ablation test shows what each rule contributes. Build one signal column per variant and backtest them together, using the same prices, exits, and fees. This small example uses made-up prices and volumes. It compares a core entry rule with a trend filter, a volume filter, and both filters together. All signals move forward one bar before trading. ```python title="Compare a strategy with and without entry filters" >>> close = pd.Series([100, 102, 105, 103, 99, 101, 106, 110, 107, 102, 104, 109, 114, 111, 106, 108, 115, 118, 113, 110]) >>> volume = pd.Series([90, 110, 80, 120, 90, 130, 140, 80, 110, 90, 120, 80, 140, 100, 90, 120, 80, 130, 110, 90]) >>> core = close > close.shift(1) >>> trend_filter = close > close.rolling(4).mean() >>> volume_filter = volume >= 100 >>> entries = pd.DataFrame({ ... "Core": core, ... "Trend": core & trend_filter, ... "Volume": core & volume_filter, ... "Both": core & trend_filter & volume_filter, ... }).vbt.signals.fshift(1) >>> exits = (close < close.shift(1)).vbt.signals.fshift(1) >>> variants = vbt.PF.from_signals(close, entries, exits, fees=0.001, freq="1D") >>> comparison = pd.DataFrame({ ... "Return [%]": variants.total_return * 100, ... "Max drawdown [%]": variants.max_drawdown * 100, ... "Closed trades": variants.trades.status_closed.count(), ... }) >>> comparison.round(2) Return [%] Max drawdown [%] Closed trades Core -16.28 -16.28 4 Trend -20.11 -20.11 3 Volume -16.28 -16.28 4 Both -14.32 -14.32 3 ``` See exactly what each rule contributes: the volume filter alone leaves the result unchanged, while combining both filters produces the smallest loss on this sample. Use the same comparison to test entry rules across a larger strategy, with filter switches as parameters and repeated [walk-forward test periods](/features/optimization/time-series-cross-validation/). ## Execution sensitivity \[#execution-sensitivity] Stress-test execution by delaying signals and raising costs. Compare how the strategy responds to a one-bar delay, a two-bar delay, and different fee levels. Each delay is one column and each fee level one parameter value, so the grid runs as a single backtest. ```python title="Delay the best pair's signals and raise its fees" >>> entries = fast.ma_above(slow)[best] >>> exits = fast.ma_below(slow)[best] >>> delays = pd.Index([0, 1, 2], name="delay") >>> pf_exec = vbt.PF.from_signals( ... data, ... pd.concat([entries.vbt.signals.fshift(d) for d in delays], axis=1, keys=delays), ... pd.concat([exits.vbt.signals.fshift(d) for d in delays], axis=1, keys=delays), ... fees=vbt.Param([0.001, 0.002, 0.005], name="fees"), ... ) >>> pf_exec.sharpe_ratio.unstack("fees").round(2) fees 0.001 0.002 0.005 delay 0 1.41 1.40 1.38 1 1.33 1.33 1.31 2 1.32 1.31 1.29 ``` With only 8 trades, even 0.5% fees barely move the result, while a one-bar delay costs more than all of them. A strategy that trades more often pays more for each step in fees. The [Backtest realism](/features/backtesting/backtest-realism/) page covers slippage, order delays, and other execution assumptions. ## Perturbed and permuted data \[#perturbed-and-permuted-data] A strategy that only works on the exact price history it was tuned on is fragile. Each of these varies the data in a different way: * **Shuffled returns.** `.vbt.shuffle(seed=...)` shuffles each column separately, as in the first example, to break the original ordering while keeping the return distribution. * **Noise.** Adding small random noise to prices, for example with `np.random.default_rng(seed)` scaled to each bar's range, tests whether signals depend on exact price levels. * **Mirrored prices.** `data.mirror_ohlc()` turns rises into falls and keeps each bar's high and low consistent, which tests whether a long-only result depends on the market's direction. * **Block bootstrap.** `vbt.Splitter.from_n_random` draws random windows, and `shuffle_splits` with `replace=True` resamples existing windows, keeping the order of prices inside each block. * **Synthetic prices.** `vbt.GBMOHLCData` and `vbt.RandomOHLCData` generate seeded price paths with chosen drift and volatility, as the [Synthetic data](/features/data/synthetic-data/) page shows. Each variant is one more column, so hundreds of perturbed histories run as one backtest. ## Statistical tests \[#statistical-tests] The returns accessor and the portfolio both compute the Sharpe ratio tests by López de Prado and Bailey: | Method | Answers | | ----------------------- | -------------------------------------------------------------------------------------- | | `sharpe_ratio_std` | How uncertain the Sharpe ratio is, given the sample's length, skew, and kurtosis | | `prob_sharpe_ratio` | How likely the true Sharpe ratio is above a benchmark's, such as buy and hold | | `deflated_sharpe_ratio` | How likely the Sharpe ratio exceeds a benchmark adjusted for the search across columns | `prob_sharpe_ratio` on a portfolio compares with its benchmark, which is buying and holding the traded asset unless you pass `bm_returns`. To compare with a Sharpe ratio of zero instead, call it on `pf.get_returns_acc(bm_returns=False)`. `deflated_sharpe_ratio` treats each column as one trial, so call it on the returns of every combination you tested, not only on the winner. A single column returns NaN, and a grouped portfolio counts each group as one trial. ### Probability of backtest overfitting \[#probability-of-backtest-overfitting] VBT provides splitters and labeled results for calculating the probability of backtest overfitting (PBO) in a research workflow. Compare the in-sample and out-of-sample results of every combination over combinatorial splits, using half the folds for training and half for testing. Build those splits with `vbt.Splitter.from_purged_kfold`, covered on the [Walk-forward and cross-validation](/features/optimization/time-series-cross-validation/) page. PBO is the share of splits in which the best combination on the training half ranks below the median on the test half. Values near 0.5 or higher mean the selection does no better than picking a combination at random. !!! warning "Correlated trials" The deflated Sharpe ratio assumes the trials are independent. Neighboring parameters of one strategy are strongly correlated, so a grid of 72 pairs behaves like far fewer independent trials. The permutation example complements this by rerunning the same correlated parameter grid on each shuffled history. !!! info "Tutorial" The members-only [Cross-validation](https://members.vectorbt.pro/tutorials/cross-validation/workflow/) tutorial carries each period's winning parameters into the next period and compares them with every alternative out of sample. # Parameter optimization (/features/optimization/strategy-optimization) Which parameters work, and how do you test millions of combinations without running out of time or memory? VBT turns any function into a parameter sweep with one decorator, builds grids with conditions, and can run compiled functions in chunks across all cores. Start with your existing Python strategy, then scale from a few parameter values to millions. ```python title="Backtest 1,000,000 parameter combinations and keep only the Sharpe ratio" >>> close = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2025-01-01").close >>> @vbt.parameterized( # (1) ... merge_func="concat", ... engine="threadpool", ... chunk_len="auto", ... warmup=True, ... ) ... @njit(nogil=True) # (2) ... def sharpe_nb(close, fast_window, slow_window, sl_stops): ... fast = vbt.nb.rolling_mean_1d_nb(close, fast_window) ... slow = vbt.nb.rolling_mean_1d_nb(close, slow_window) ... entries = vbt.nb.crossed_above_1d_nb(fast, slow) ... exits = vbt.nb.crossed_above_1d_nb(slow, fast) ... n = len(sl_stops) ... sim_out = vbt.pf_nb.from_signals_nb( # (3) ... target_shape=(len(close), n), ... group_lens=np.full(n, 1), ... close=close, ... long_entries=entries, ... long_exits=exits, ... sl_stop=sl_stops.reshape(1, -1), ... fees=0.001, ... save_returns=True, ... ) ... return vbt.ret_nb.sharpe_ratio_nb(sim_out.in_outputs.returns, 365.0) >>> sl_stops = np.linspace(0.01, 0.30, 100) >>> sharpe = sharpe_nb( ... close.values, ... vbt.Param(np.arange(2, 102), name="fast_window"), ... vbt.Param(np.arange(105, 305, 2), name="slow_window"), ... sl_stops, ... ) >>> len(sharpe) # (4) 1000000 >>> sharpe.index = sharpe.index.set_levels(sl_stops.round(4), level=2) >>> sharpe.index = sharpe.index.set_names("sl_stop", level=2) >>> sharpe.nlargest(5).round(3) fast_window slow_window sl_stop 2 107 0.0129 1.608 0.0159 1.607 119 0.0246 1.603 117 0.0510 1.594 0.0539 1.594 dtype: float64 >>> best_per_pair = sharpe.groupby(["fast_window", "slow_window"]).max() >>> best_per_pair.vbt.heatmap(x_level="fast_window", y_level="slow_window").show() ``` 1. Run the function once per pair of windows, in parallel threads, and concatenate the results. 2. A compiled function that releases the GIL, so the threads truly run in parallel. 3. Each call backtests one window pair against all 100 stop levels at once, as 100 columns. 4. 100 fast windows × 100 slow windows × 100 stop levels. On an Apple M3, the sweep took about 18 seconds after compilation. Heatmap of the best Sharpe ratio across 100 fast and 100 slow moving average windows for Bitcoin from 2020 to 2024. [Figure data (JSON)](/assets/figures/features/optimization/strategy-optimization-million.ab407f76961c.json) Only one number per backtest is kept, so a million backtests fit in a few megabytes. The heatmap shows the best Sharpe ratio of each window pair across all stop levels. In this bull market, 95% of the combinations had a positive Sharpe ratio, which is why a single best value says little on its own. ## Parameterize any function \[#parameterize-any-function] `@vbt.parameterized` wraps any function, from a few lines of pandas to a full backtest. Arguments wrapped in `vbt.Param` become parameters, every combination is passed to the function, and the results are merged into one labeled object, with the parameter values as index levels. Merging can concatenate, stack columns, or return the raw list, and parameters can be nested, shared across calls, or functions themselves. The [Parameterized decorator](#parameterized-decorator) highlight below shows the pattern on a full strategy. You can keep your existing pandas calculations and Python strategy logic. Parameter values can also be functions, so the same pipeline can compare different entry rules as well as different lookback windows. Give each rule a label to keep the results easy to identify. ### Reuse calculations across combinations \[#reuse-calculations-across-combinations] A moving average used in 100 window pairs only needs to be calculated once. Precompute the indicators, then pass their outputs into the search. The [Paramables](#paramables) example below runs all moving averages first and combines the resulting indicator objects into fast/slow pairs. You can also search in stages: find useful entry settings, reuse those signals, then explore [stops](/features/backtesting/stop-loss-and-take-profit/) and [position sizes](/features/backtesting/position-sizing/). ## Cartesian, zipped, and lazy grids \[#cartesian-zipped-and-lazy-grids] Parameters combine as a Cartesian product by default, or element by element when they share a `level`. Conditions remove combinations that make no sense, such as a fast window longer than the slow one, before anything runs, as in the [Conditional parameters](#conditional-parameters) highlight. Large grids are generated lazily, so a grid of billions of potential combinations does not need to fit in memory before a random subset is drawn from it, as [Lazy parameter grids](#lazy-parameter-grids) shows. ## Search strategies \[#search-strategies] Exhaustive search is only one option. `random_subset` tests a random sample of the grid, which often finds the same good region at a fraction of the cost, as the [Random search](#random-search) highlight shows. Staged searches narrow a coarse grid into a finer one around the best area. Set a seed when sampling so you can repeat the same selection of parameter combinations. ### Optimize a VBT backtest with Optuna or Hyperopt \[#optimize-a-vbt-backtest-with-optuna-or-hyperopt] For Bayesian or evolutionary search, use your VBT backtest as the objective function for [Optuna](https://optuna.org/) or [Hyperopt](https://hyperopt.github.io/hyperopt/). The optimizer proposes a parameter combination, your function calculates signals and runs the backtest, then returns the metric you want to optimize. You can search lookback windows, signal thresholds, stop levels, or model settings without calculating the entire grid first. The objective is yours to define. For example, maximize a return metric after fees, or combine return and drawdown into a score. You can use the same backtest function for an initial grid search and a later optimizer-driven search. VBT handles the simulation and metrics, while the external optimizer chooses which parameters to try next. ## Big sweeps \[#big-sweeps] Three settings keep large sweeps fast: * **Chunks.** `chunk_len` splits the combinations into groups that run in parallel threads or processes. For a Numba function, `warmup=True` runs the first task before distributing the rest so compilation happens up front. * **Mono-chunks.** Combine many parameter values into one call so the function processes them as columns, as the example above does with stop levels and the [Mono-chunks](#mono-chunks) highlight does with two parameters. * **Metrics only.** Return a single metric per combination instead of a portfolio, and save the returns during the simulation so the metric does not have to reconstruct them. For long runs, chunk caching can save completed results to disk and reuse them when you resume the same search. See [Parallel execution and caching](/features/performance/parallel-execution-and-caching/). A pipeline can also return `vbt.NoResult` to leave an unwanted combination out of the merged results, such as a strategy that produces too few trades to evaluate. ## Choosing among results \[#choosing-among-results] The highest Sharpe ratio in a large grid is usually an outlier. Rank on more than one number: results come back as pandas objects indexed by parameters, so several metrics, such as Sharpe ratio, maximum drawdown, and trade count, can be normalized and averaged into one score in a few lines. Prefer regions where neighboring parameters also do well, and when several strategies are needed, choose combinations that differ from each other rather than the top few, which tend to be near-duplicates. Compare [trade duration and exposure](/features/analytics/trade-analytics/) to see whether those variants actually trade differently. Walk-forward testing on the [Walk-forward and cross-validation](/features/optimization/time-series-cross-validation/) page checks whether a choice holds outside the data it was picked on. For tests of parameter sensitivity and selection bias, see [Robustness and overfitting](/features/optimization/robustness-and-overfitting/). ### Compare several metrics in one table \[#compare-several-metrics-in-one-table] Keep the numbers you need for selection and leave the full portfolio inside the function. This small example uses made-up prices and three moving average windows. Signals are shifted by one bar, and each backtest includes fees. ```python title="Compare return, drawdown, and trade count" >>> close = pd.Series( ... [100, 102, 105, 103, 99, 101, 106, 110, 107, 102, 104, 109, 114, 111, 106, 108, 115, 118, 113, 110], ... index=pd.date_range("2025-01-01", periods=20), ... ) >>> @vbt.parameterized(merge_func="column_stack") ... def compare_windows(close, window): ... average = close.rolling(window).mean() ... entries = (close > average).shift(1, fill_value=False) ... exits = (close < average).shift(1, fill_value=False) ... pf = vbt.PF.from_signals(close, entries, exits, fees=0.001, freq="1D") ... return pd.Series({ ... "Return [%]": pf.total_return * 100, ... "Max drawdown [%]": pf.max_drawdown * 100, ... "Closed trades": pf.trades.status_closed.count(), ... }) >>> results = compare_windows(close, vbt.Param([2, 3, 5])).T >>> results.round(2) Return [%] Max drawdown [%] Closed trades window 2 -16.28 -16.28 4.0 3 -23.36 -23.36 4.0 5 -16.92 -16.92 2.0 >>> results.index[results["Closed trades"] >= 3].tolist() [2, 3] ``` The last line selects windows with at least three closed trades. Change the filter to your own criteria, or add [performance metrics](/features/analytics/performance-metrics/) to the returned Series. One result table gives you returns, drawdowns, and trade counts for every setting, ready for your own selection rule. ## Paramables \[#paramables] New in v2024.4.1 ✅ Each analyzable VBT object (such as data, indicator, or portfolio) can now be split into items, which are multiple objects of the same type, each containing only one column or group. This makes it possible to use VBT objects as standalone parameters and process only a subset of information at a time, such as a symbol in a data instance or a parameter combination in an indicator. ```python title="Combine outputs of a SMA indicator combinatorially" >>> @vbt.parameterized(merge_func="column_stack") ... def get_signals(fast_sma, slow_sma): # (1) ... entries = fast_sma.crossed_above(slow_sma) ... exits = fast_sma.crossed_below(slow_sma) ... return entries, exits >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"]) >>> sma = data.run("talib:sma", timeperiod=range(20, 50, 2)) # (2) >>> fast_sma = sma.rename_levels({"sma_timeperiod": "fast"}) # (3) >>> slow_sma = sma.rename_levels({"sma_timeperiod": "slow"}) >>> entries, exits = get_signals( ... vbt.Param(fast_sma, condition="__fast__ < __slow__"), # (4) ... vbt.Param(slow_sma) ... ) >>> entries.columns MultiIndex([(20, 22, 'BTC-USD'), (20, 22, 'ETH-USD'), (20, 24, 'BTC-USD'), (20, 24, 'ETH-USD'), (20, 26, 'BTC-USD'), (20, 26, 'ETH-USD'), ... (44, 46, 'BTC-USD'), (44, 46, 'ETH-USD'), (44, 48, 'BTC-USD'), (44, 48, 'ETH-USD'), (46, 48, 'BTC-USD'), (46, 48, 'ETH-USD')], names=['fast', 'slow', 'symbol'], length=210) ``` 1. Regular function that takes two indicators and returns signals. 2. Run an SMA indicator once on all time periods. 3. Copy the indicator and rename the parameter level to get a distinct indicator instance. 4. Pass both indicator instances as parameters. This splits each instance into smaller instances with only one column. Also, remove all columns where the fast window is greater than or equal to the slow window. ## Lazy parameter grids \[#lazy-parameter-grids] New in v2023.12.23 ✅ The [parameterized decorator](#parameterized-decorator) no longer needs to materialize parameter grids if you are only interested in a subset of all parameter combinations. This change enables the generation of random parameter combinations almost instantly, no matter how large the total number of possible combinations is. ```python title="Test a random subset of a huge number of parameter combinations" >>> @vbt.parameterized(merge_func="concat") ... def test_combination(data, n, sl_stop, tsl_stop, tp_stop): ... return data.run( ... "from_random_signals", ... n=n, ... sl_stop=sl_stop, ... tsl_stop=tsl_stop, ... tp_stop=tp_stop, ... seed=42, ... ).total_return >>> n = np.arange(10, 100) >>> sl_stop = np.arange(1, 1000) / 1000 >>> tsl_stop = np.arange(1, 1000) / 1000 >>> tp_stop = np.arange(1, 1000) / 1000 >>> len(n) * len(sl_stop) * len(tsl_stop) * len(tp_stop) 89730269910 >>> test_combination( ... vbt.YFData.pull("BTC-USD"), ... n=vbt.Param(n), ... sl_stop=vbt.Param(sl_stop), ... tsl_stop=vbt.Param(tsl_stop), ... tp_stop=vbt.Param(tp_stop), ... _random_subset=10, ... _seed=42 ... ) n sl_stop tsl_stop tp_stop 18 0.476 0.485 0.862 2.233997 21 0.530 0.697 0.017 0.091041 49 0.499 0.560 0.954 15.987541 50 0.535 0.200 0.477 2.182477 72 0.763 0.360 0.129 -0.040304 78 0.503 0.071 0.533 10.851910 79 0.656 0.388 0.930 11.854461 80 0.746 0.042 0.644 0.702603 87 0.274 0.539 0.434 2.072847 97 0.806 0.206 0.426 7.136395 dtype: float64 ``` ## Mono-chunks \[#mono-chunks] New in 1.13.0 ✅ The [parameterized decorator](#parameterized-decorator) now supports splitting parameter combinations into "mono-chunks," merging the parameter values within each chunk into a single value, and running the entire chunk with a single function call. This means you are no longer limited to processing only one parameter combination at a time 🌪️ Keep in mind that your function must be adapted to handle multiple parameter values, and you should modify the merging function as needed. ```python title="Test 100 combinations of SL and TP values per thread" >>> @vbt.parameterized( ... merge_func="concat", ... mono_chunk_len=100, # (1) ... chunk_len="auto", # (2) ... engine="threadpool", # (3) ... warmup=True # (4) ... ) ... @njit(nogil=True) ... def test_stops_nb(close, entries, exits, sl_stop, tp_stop): ... sim_out = vbt.pf_nb.from_signals_nb( ... target_shape=(close.shape[0], sl_stop.shape[1]), ... group_lens=np.full(sl_stop.shape[1], 1), ... close=close, ... long_entries=entries, ... short_entries=exits, ... sl_stop=sl_stop, ... tp_stop=tp_stop, ... save_returns=True ... ) ... return vbt.ret_nb.total_return_nb(sim_out.in_outputs.returns) >>> data = vbt.YFData.pull("BTC-USD", start="2020") # (5) >>> entries, exits = data.run("randnx", n=10, seed=42, hide_params=True, unpack=True) # (6) >>> sharpe_ratios = test_stops_nb( ... vbt.to_2d_array(data.close), ... vbt.to_2d_array(entries), ... vbt.to_2d_array(exits), ... sl_stop=vbt.Param(np.arange(0.01, 1.0, 0.01), mono_merge_func=np.column_stack), # (7) ... tp_stop=vbt.Param(np.arange(0.01, 1.0, 0.01), mono_merge_func=np.column_stack) ... ) >>> sharpe_ratios.vbt.heatmap().show() ``` 1. 100 values are combined into one array, forming a single mono-chunk. 2. Execute N mono-chunks in parallel, where N is the number of cores. 3. Use multithreading. 4. Execute one mono-chunk to compile the function before distributing other chunks. 5. The function above operates with only one symbol. 6. Pick 10 entries and exits randomly. 7. For each mono-chunk, stack all values into a two-dimensional array. Heatmap of BTC-USD total returns across stop-loss and take-profit combinations. [Figure data (JSON)](/assets/figures/features/optimization/chunked-parameters.faa469abe97f.json) ## Conditional parameters \[#conditional-parameters] New in 1.8.1 ✅ Parameters can depend on each other. For example, when testing a crossover of moving averages, it makes no sense to test a fast window that is longer than the slow window. By filtering out such cases, you only need to evaluate about half as many parameter combinations. ```python title="Test slow windows being longer than fast windows by at least 5" >>> @vbt.parameterized(merge_func="column_stack") ... def ma_crossover_signals(data, fast_window, slow_window): ... fast_sma = data.run("sma", fast_window, short_name="fast_sma") ... slow_sma = data.run("sma", slow_window, short_name="slow_sma") ... entries = fast_sma.real_crossed_above(slow_sma.real) ... exits = fast_sma.real_crossed_below(slow_sma.real) ... return entries, exits >>> entries, exits = ma_crossover_signals( ... vbt.YFData.pull("BTC-USD", start="one year ago UTC"), ... vbt.Param(np.arange(5, 50), condition="slow_window - fast_window >= 5"), ... vbt.Param(np.arange(5, 50)) ... ) >>> entries.columns MultiIndex([( 5, 10), ( 5, 11), ( 5, 12), ( 5, 13), ( 5, 14), ... (42, 48), (42, 49), (43, 48), (43, 49), (44, 49)], names=['fast_window', 'slow_window'], length=820) ``` ## Random search \[#random-search] New in 1.7.0 ✅ While grid search tests every possible combination of hyperparameters, random search selects and tests random combinations of hyperparameters. This is especially useful when there is a huge number of parameter combinations. Random search has also been shown to find equal or better values than grid search with fewer function evaluations. The indicator factory, parameterized decorator, and any method that performs broadcasting now support random search out of the box. ```python title="Test a random subset of SL, TSL, and TP combinations" >>> data = vbt.YFData.pull("BTC-USD", start="2020") >>> stop_values = np.arange(1, 100) / 100 # (1) >>> pf = vbt.PF.from_random_signals( ... data, ... n=100, ... seed=42, ... sl_stop=vbt.Param(stop_values), ... tsl_stop=vbt.Param(stop_values), ... tp_stop=vbt.Param(stop_values), ... broadcast_kwargs=dict(random_subset=1000, seed=42) # (2) ... ) >>> pf.total_return.sort_values(ascending=False) sl_stop tsl_stop tp_stop 0.02 0.22 0.55 1.093685 0.93 0.60 0.99 1.091450 0.88 0.68 0.99 1.091450 0.79 0.69 0.99 1.091450 0.62 0.99 1.091450 ... 0.08 0.84 0.14 -0.466277 0.14 0.09 0.12 -0.502329 0.80 0.11 0.11 -0.509395 0.19 0.11 0.09 -0.529528 0.29 0.11 0.06 -0.563992 Name: total_return, Length: 1000, dtype: float64 ``` 1. 99 values of each parameter = 99³ = 970,299 combinations, of which 1,000 are sampled. 2. The indicator factory and parameterized decorator accept this argument directly. ## Parameterized decorator \[#parameterized-decorator] New in 1.7.0 ✅ There is a special decorator that allows any Python function to accept multiple parameter combinations, even if the function itself supports only one. The decorator wraps the function, gains access to its arguments, identifies all arguments acting as parameters, builds a grid from them, and calls the underlying function on each parameter combination from that grid. The execution can be easily parallelized. Once all outputs are ready, it merges them into a single object. Use cases are endless: from running indicators that cannot be wrapped with the indicator factory, to parameterizing entire pipelines! 🪄 === "Example 1: Basic SMA indicator" ```python title="Parameterize a basic SMA indicator without Indicator Factory" >>> @vbt.parameterized(merge_func="column_stack") # (1) ... def sma(close, window): ... return close.rolling(window).mean() >>> data = vbt.YFData.pull("BTC-USD") >>> sma(data.close, vbt.Param(range(20, 50))) ``` 1. Use `column_stack` to merge time series in the form of DataFrames and complex VBT objects such as portfolios. Combination 30/30: 100% ```text title="Output" window 20 21 22 \ Date 2014-09-17 00:00:00+00:00 NaN NaN NaN 2014-09-18 00:00:00+00:00 NaN NaN NaN 2014-09-19 00:00:00+00:00 NaN NaN NaN ... ... ... ... 2024-03-07 00:00:00+00:00 57657.135156 57395.376488 57147.339134 2024-03-08 00:00:00+00:00 58488.990039 58163.942708 57891.045455 2024-03-09 00:00:00+00:00 59297.836523 58956.156064 58624.648793 ... window 48 49 Date 2014-09-17 00:00:00+00:00 NaN NaN 2014-09-18 00:00:00+00:00 NaN NaN 2014-09-19 00:00:00+00:00 NaN NaN ... ... ... 2024-03-07 00:00:00+00:00 49928.186686 49758.599330 2024-03-08 00:00:00+00:00 50483.072266 50303.123565 2024-03-09 00:00:00+00:00 51040.440837 50846.672353 [3462 rows x 30 columns] ``` === "Example 2: Bollinger Bands pipeline" ```python title="Parameterize an entire Bollinger Bands pipeline" >>> @vbt.parameterized(merge_func="concat") # (1) ... def bbands_sharpe(data, timeperiod=14, nbdevup=2, nbdevdn=2, thup=0.3, thdn=0.1): ... bb = data.run( ... "talib_bbands", ... timeperiod=timeperiod, ... nbdevup=nbdevup, ... nbdevdn=nbdevdn ... ) ... bandwidth = (bb.upperband - bb.lowerband) / bb.middleband ... cond1 = data.low < bb.lowerband ... cond2 = bandwidth > thup ... cond3 = data.high > bb.upperband ... cond4 = bandwidth < thdn ... entries = (cond1 & cond2) | (cond3 & cond4) ... exits = (cond1 & cond4) | (cond3 & cond2) ... pf = vbt.PF.from_signals(data, entries, exits) ... return pf.sharpe_ratio >>> bbands_sharpe( ... vbt.YFData.pull("BTC-USD"), ... nbdevup=vbt.Param([1, 2]), # (2) ... nbdevdn=vbt.Param([1, 2]), ... thup=vbt.Param([0.4, 0.5]), ... thdn=vbt.Param([0.1, 0.2]) ... ) ``` 1. Use `concat` to merge metrics in the form of scalars and Series. 2. Builds the Cartesian product of 4 parameters. Combination 16/16: 100% ```text title="Output" nbdevup nbdevdn thup thdn 1 1 0.4 0.1 1.681532 0.2 1.617400 0.5 0.1 1.424175 0.2 1.563520 2 0.4 0.1 1.218554 0.2 1.520852 0.5 0.1 1.242523 0.2 1.317883 2 1 0.4 0.1 1.174562 0.2 1.469828 0.5 0.1 1.427940 0.2 1.460635 2 0.4 0.1 1.000210 0.2 1.378108 0.5 0.1 1.196087 0.2 1.782502 dtype: float64 ``` ## Array-like parameters \[#array-like-parameters] New in 1.5.0 ✅ The broadcasting mechanism has been completely refactored and now supports parameters. Many parameters in VBT, such as SL and TP, are array-like and can be provided per row, per column, or even per element. Internally, even a scalar is treated as a regular time series and is broadcast along with other proper time series. Previously, to test multiple parameter combinations, you had to tile other time series so that all shapes matched perfectly. With this feature, the tiling procedure is performed automatically! ```python title="Write a steep slope indicator without indicator factory" >>> def steep_slope(close, up_th): ... r = vbt.broadcast(dict(close=close, up_th=up_th)) ... return r["close"].pct_change() >= r["up_th"] >>> data = vbt.YFData.pull("BTC-USD", start="2020", end="2022") >>> fig = data.plot(plot_volume=False) >>> sma = vbt.talib("SMA").run(data.close, timeperiod=50).real >>> sma.rename("SMA").vbt.plot(fig=fig) >>> mask = steep_slope(sma, vbt.Param([0.005, 0.01, 0.015])) # (1) >>> def plot_mask_ranges(column, color): ... mask.vbt.ranges.plot_shapes( ... column=column, ... plot_close=False, ... add_shape_kwargs=dict(fillcolor=color), ... fig=fig ... ) >>> plot_mask_ranges(0.005, "orangered") >>> plot_mask_ranges(0.010, "orange") >>> plot_mask_ranges(0.015, "yellow") >>> fig.update_xaxes(showgrid=False) >>> fig.update_yaxes(showgrid=False) >>> fig.show() ``` 1. Tests three parameters and generates a mask with three columns, one for each parameter. BTC-USD OHLC and 50-day SMA with steep-slope ranges at three thresholds from 2020 through 2021. [Figure data (JSON)](/assets/figures/features/optimization/steep-slope.27dbe5be055b.json) ## Parameters \[#parameters] New in 1.5.0 ✅ There is a new module for working with parameters. ```python title="Generate 10,000 random parameter combinations for MACD" >>> from itertools import combinations >>> window_space = np.arange(100) >>> fastk_windows, slowk_windows = list(zip(*combinations(window_space, 2))) # (1) >>> window_type_space = list(vbt.enums.WType) >>> param_product = vbt.combine_params( ... dict( ... fast_window=vbt.Param(fastk_windows, level=0), # (2) ... slow_window=vbt.Param(slowk_windows, level=0), ... signal_window=vbt.Param(window_space, level=1), ... macd_wtype=vbt.Param(window_type_space, level=2), # (3) ... signal_wtype=vbt.Param(window_type_space, level=2), ... ), ... random_subset=10_000, ... seed=42, ... build_index=False ... ) >>> pd.DataFrame(param_product) fast_window slow_window signal_window macd_wtype signal_wtype 0 0 1 0 2 2 1 0 3 5 1 1 2 0 3 55 4 4 3 0 3 80 2 2 4 0 4 17 2 2 ... ... ... ... ... ... 9995 97 99 14 0 0 9996 97 99 35 2 2 9997 98 99 6 2 2 9998 98 99 44 4 4 9999 98 99 78 4 4 [10000 rows x 5 columns] ``` 1. Fast windows should be shorter than slow windows. 2. Fast and slow windows were already combined, so they share the same product level. 3. Window types do not need to be combined, so they share the same product level. # Walk-forward and cross-validation (/features/optimization/time-series-cross-validation) Does an optimized strategy hold up on data it has never seen? VBT runs walk-forward optimization and time-series cross-validation in Python: split history into training and test periods, pick parameters on each training period, and judge them only on the period that follows. ```python title="Walk-forward optimize a moving average strategy over 16 quarters" >>> from itertools import product >>> data = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2025-01-01") >>> splitter = vbt.Splitter.from_rolling( # (1) ... data.index, ... length=455, ... split=365, ... offset=90, ... offset_anchor="prev_start", ... set_labels=["train", "test"], ... ) >>> splitter.n_splits 16 >>> pairs = [(f, s) for f, s in product(range(10, 55, 5), range(60, 220, 20))] >>> fast_windows, slow_windows = zip(*pairs) >>> fast = vbt.MA.run(data.close, window=list(fast_windows), short_name="fast") >>> slow = vbt.MA.run(data.close, window=list(slow_windows), short_name="slow") >>> entries = fast.ma_above(slow) # (2) >>> exits = fast.ma_below(slow) >>> bounds = splitter.get_bounds(index_bounds=True) >>> rows, oos_returns = [], [] >>> for split in range(splitter.n_splits): ... train_start, train_end = bounds.loc[(split, "train")] ... test_start, test_end = bounds.loc[(split, "test")] ... train = slice(train_start, train_end - pd.Timedelta(days=1)) ... test = slice(test_start, test_end - pd.Timedelta(days=1)) ... train_pf = vbt.PF.from_signals( ... data.loc[train], entries.loc[train], exits.loc[train], fees=0.001 ... ) ... best = train_pf.sharpe_ratio.idxmax() # (3) ... test_pf = vbt.PF.from_signals( ... data.loc[test], entries.loc[test, best], exits.loc[test, best], fees=0.001 ... ) ... rows.append(dict( ... test_start=test_start.date(), ... fast=best[0], ... slow=best[1], ... train_sharpe=train_pf.sharpe_ratio[best], ... test_sharpe=test_pf.sharpe_ratio, ... )) ... oos_returns.append(test_pf.returns) >>> summary = pd.DataFrame(rows) >>> summary.head(6).round(2) test_start fast slow train_sharpe test_sharpe 0 2020-12-31 10 200 3.19 3.56 1 2021-03-31 10 200 3.42 -2.00 2 2021-06-29 20 60 2.83 0.98 3 2021-09-27 20 60 2.97 0.12 4 2021-12-26 20 80 1.86 -2.01 5 2022-03-26 20 80 0.80 -1.74 >>> summary[["train_sharpe", "test_sharpe"]].mean().round(2) train_sharpe 1.92 test_sharpe 0.24 dtype: float64 >>> oos = pd.concat(oos_returns) # (4) >>> hold = data.close.loc[oos.index] / data.close.loc[oos.index].iloc[0] >>> print(round((1 + oos).prod(), 3), round(hold.iloc[-1], 3)) 2.744 3.36 ``` 1. Each split trains on 365 days and tests on the next 90, then moves forward by 90 days. 2. Indicators are computed on the full history so the test periods need no warm-up. Being in the market whenever the fast average is above the slow one lets each test period start in the right position. 3. Choose the window pair with the best Sharpe ratio in the training year. 4. Join the 16 test quarters into one out-of-sample return series. Equity of a walk-forward optimized Bitcoin moving average strategy compared with buy and hold from 2021 to 2024. [Figure data (JSON)](/assets/figures/features/optimization/walk-forward-equity.a8892d15ae61.json) The parameters that looked best in each training year had an average Sharpe ratio of 1.92 there, and 0.24 in the quarter that followed. Stitched together, the out-of-sample strategy grew 2.7 times while holding Bitcoin grew 3.4 times. That gap between in-sample and out-of-sample results is what walk-forward testing exists to reveal. ## Walk-forward optimization \[#walk-forward-optimization] Walk-forward testing repeats one cycle: optimize on a training window, apply the result to the next window, and move forward. Join the test returns to evaluate the repeated selection process. Each test window above is simulated separately and can enter on its first bar when the fast average is above the slow one. For strategies that must be flat at each boundary, add an exit on the last bar of every test window, and for strategies whose state must carry over, continue the portfolio from one window to the next as described on the [Live simulation](/features/backtesting/live-simulation/) page. Test-period portfolios join along time with `vbt.PF.row_stack`, which gives one out-of-sample portfolio with every metric and chart. You choose how much history each decision uses. Rolling windows keep a fixed amount of recent data, such as the latest year. Expanding windows retain the earlier history as new observations arrive. Calendar-based splits let you match a research schedule, such as selecting parameters monthly or retraining a model each quarter. ## Splitters \[#splitters] `vbt.Splitter` builds the splits: | Constructor | Splits | Useful for | | ---------------------------------------------- | -------------------------------------------- | -------------------------------------------- | | `from_rolling`, `from_n_rolling` | Windows of fixed length that move forward | Re-optimizing on recent history | | `from_expanding`, `from_n_expanding` | Windows that grow from a fixed start | Keeping all available training history | | `from_grouper` | Calendar periods, such as months or quarters | Comparing performance by period | | `from_n_random` | Random windows for robustness checks | Testing different historical starting points | | `from_ranges`, `from_splits` | Exact ranges you define | Custom research schedules | | `from_purged_walkforward`, `from_purged_kfold` | Purged splits | Separating overlapping label information | Each split can hold several sets, such as training and test, sized in bars, fractions, or time periods, with gaps between them. `splitter.plot()` shows every split on a timeline, and `get_coverage` and `get_overlap_matrix` measure how much of the data each set covers and how much splits overlap, as the [Splitter](#splitter) highlight below shows. ### Leave a gap between training and testing \[#leave-a-gap-between-training-and-testing] An expanding window can grow its training history while reserving a fixed test period and a gap between the two. Here, every test covers three days, with two days left out before it starts. The table shows the first and last included dates of each set. ```python title="Inspect expanding windows with a gap" >>> index = pd.date_range("2025-01-01", periods=18, freq="D") >>> splitter = vbt.Splitter.from_expanding( ... index, ... min_length=12, ... offset=3, ... split=(1.0, vbt.RelRange(length=2, is_gap=True), 3), ... split_range_kwargs=dict(backwards=True), ... set_labels=["train", "test"], ... ) >>> splitter.get_bounds(index_bounds=True, right_inclusive=True) bound start end split set 0 train 2025-01-01 2025-01-07 test 2025-01-10 2025-01-12 1 train 2025-01-01 2025-01-10 test 2025-01-13 2025-01-15 2 train 2025-01-01 2025-01-13 test 2025-01-16 2025-01-18 ``` `is_gap=True` leaves those dates out of both sets. Splitting backwards reserves the test period and gap first, then gives the remaining history to training. Use the same splitter to take matching slices from your prices, features, and labels. ## Applying splits \[#applying-splits] `splitter.take(obj)` cuts data, indicators, or portfolios into the splits, and `splitter.apply` runs a function on each one. The `@vbt.split` decorator adds splitting to any function, and `@vbt.cv_split` combines splitting with a parameter search: it optimizes on each training set, picks the best combination, and evaluates it on the test set in one call, as the [CV decorator](#cv-decorator) and [Split decorator](#split-decorator) highlights below show. Results come back labeled by split and set, ready to compare. By default, `cv_split` keeps the combination with the highest result, so the function should return one number per combination, such as a Sharpe ratio. With `selection="min"` it keeps the lowest, and a template over the grid results can apply any other rule, for example a score built from several metrics. ### Inspect full parameter grids \[#inspect-full-parameter-grids] Keep the training grid with `return_grid=True`, or evaluate the full grid on each set with `return_grid="all"`. This lets you compare the surrounding parameter values and see whether a strong training result belongs to a broad region or one isolated combination. The selection still comes from the training results. Use the extra test results to study [robustness](/features/optimization/robustness-and-overfitting/). ### Validate across assets and timeframes \[#validate-across-assets-and-timeframes] You can run the validation workflow separately for each asset by placing a parameterized function around `cv_split`. The outer search selects the asset, while the inner search selects strategy parameters within each training window. Results retain labels so you can compare which settings work across symbols and which depend on one market. Split boundaries can also be defined on one time index and applied to data at another frequency. For example, define daily training and test boundaries, then slice the minute bars used by your [backtest](/features/backtesting/intraday-and-tick-backtesting/). ### Keep indicator history available \[#keep-indicator-history-available] A test window can use earlier prices to warm up a moving average without counting those earlier bars in its performance. Precompute indicators that only use present and past prices, as in the opening example, or give the function a history buffer and trim it before simulation. This is useful when a long lookback would otherwise leave much of a short test window without signals. ## Purged and combinatorial cross-validation \[#purged-and-combinatorial-cross-validation] When labels look into the future, as many machine learning targets do, a training sample near a test period can contain information from that period. Purging removes those samples, and an embargo leaves a gap after each test period, following López de Prado. `PurgedWalkForwardCV` purges walk-forward folds, and `PurgedKFoldCV` runs combinatorial purged cross-validation: every combination of a chosen number of folds becomes a test set, so one history yields many out-of-sample tests instead of one, as the [Purged CV](#purged-cv) highlight below shows. For [labels](/features/indicators/machine-learning-labels/) whose outcomes become known at different times, supply prediction and evaluation times so purging can account for each sample's information period. Use purged walk-forward splits for chronological retraining, or combinatorial purged splits to compare many train/test arrangements. The ten-fold, two-test-fold example below produces 45 combinations. ## scikit-learn \[#scikit-learn] Splitters work with scikit-learn in both directions. `vbt.SplitterCV` turns a VBT splitter into a scikit-learn cross-validator for `GridSearchCV` or `cross_val_score`, and `vbt.Splitter.from_sklearn` turns a scikit-learn splitter into a VBT one for plotting and analysis. This also gives an existing scikit-learn model a route into the workflow. Split features and labels together, fit the model on training data, then score predictions on the matching test set. You can take the same slices into your own Python pipeline when fitting a model, generating signals, and backtesting predictions require separate steps. !!! info "Tutorial" The members-only [Cross-validation](https://members.vectorbt.pro/tutorials/cross-validation/workflow/) tutorial walks through a complete validation workflow with splitters and decorators. ## Purged CV \[#purged-cv] New in v2024.4.1 ✅ Added support for walk-forward cross-validation (CV) with purging, as well as combinatorial CV with purging and embargoing, based on Marcos Lopez de Prado's [Advances in Financial Machine Learning](https://www.wiley.com/en-us/Advances+in+Financial+Machine+Learning-p-9781119482086). ```python title="Create and plot a combinatorial splitter with purging and embargoing" >>> splitter = vbt.Splitter.from_purged_kfold( ... vbt.date_range("2024", "2025"), ... n_folds=10, ... n_test_folds=2, ... purge_td="3 days", ... embargo_td="3 days" ... ) >>> splitter.plots().show() ``` Purged combinatorial cross-validation folds with train and test sets during 2024. [Figure data (JSON)](/assets/figures/features/optimization/purged-cross-validation.dfd99f035a1b.json) ## CV decorator \[#cv-decorator] New in 1.8.1 ✅ Most cross-validation tasks involve testing a grid of parameter combinations on the training data, selecting the best parameter combination, and validating it on the test data. This process must be repeated for each split. The cross-validation decorator combines the parameterized and split decorators to automate this task. ```python title="Cross-validate a SMA crossover using random search" >>> @vbt.cv_split( ... splitter="from_rolling", ... splitter_kwargs=dict(length=365, split=0.5, set_labels=["train", "test"]), ... takeable_args=["data"], ... parameterized_kwargs=dict(random_subset=100, seed=42), ... merge_func="concat" ... ) ... def sma_crossover_cv(data, fast_period, slow_period, metric): ... fast_sma = data.run("sma", fast_period, hide_params=True) ... slow_sma = data.run("sma", slow_period, hide_params=True) ... entries = fast_sma.real_crossed_above(slow_sma) ... exits = fast_sma.real_crossed_below(slow_sma) ... pf = vbt.PF.from_signals(data, entries, exits, direction="both") ... return pf.deep_getattr(metric) >>> sma_crossover_cv( ... vbt.YFData.pull("BTC-USD", start="4 years ago"), ... vbt.Param(np.arange(20, 50), condition="x < slow_period"), ... vbt.Param(np.arange(20, 50)), ... "trades.expectancy" ... ) ``` Split 7/7: 100% ```text title="Output" split set fast_period slow_period 0 train 20 25 8.015725 test 20 23 0.573465 1 train 40 48 -4.356317 test 39 40 5.666271 2 train 24 45 18.253340 test 22 36 111.202831 3 train 20 31 54.626024 test 20 25 -1.596945 4 train 25 48 41.328588 test 25 30 6.620254 5 train 26 32 7.178085 test 24 29 4.087456 6 train 22 23 -0.581255 test 22 31 -2.494519 dtype: float64 ``` !!! info "Tutorial" Learn more in the [Cross-validation](/tutorials/cross-validation) tutorial. ## Split decorator \[#split-decorator] New in 1.8.1 ✅ Normally, to run a function on each split, you need to build a splitter specifically targeted at the input data provided to the function. This means that each time the input data changes, you must recreate the splitter. The split decorator automates this process by wrapping the function, giving it access to all arguments so it can make splitting decisions as needed. Essentially, it can "infect" any Python function with splitting functionality 🦠 ```python title="Get total return from holding in each quarter" >>> @vbt.split( ... splitter="from_grouper", ... splitter_kwargs=dict(by="Q"), ... takeable_args=["data"], ... merge_func="concat" ... ) ... def get_quarter_return(data): ... return data.returns.vbt.returns.total() >>> data = vbt.YFData.pull("BTC-USD") >>> get_quarter_return(data.loc["2021"]) Date 2021Q1 1.005805 2021Q2 -0.407050 2021Q3 0.304383 2021Q4 -0.037627 Freq: Q-DEC, dtype: float64 >>> get_quarter_return(data.loc["2022"]) Date 2022Q1 -0.045047 2022Q2 -0.572515 2022Q3 0.008429 2022Q4 -0.143154 Freq: Q-DEC, dtype: float64 ``` !!! info "Tutorial" Learn more in the [Cross-validation](/tutorials/cross-validation) tutorial. ## Splitter \[#splitter] New in 1.8.0 ✅ Splitters in [scikit-learn](https://scikit-learn.org/stable/) are not ideal for validating ML-based and rule-based trading strategies. VBT provides a juggernaut class that supports many splitting schemes that are safe for backtesting, including rolling windows, expanding windows, time-anchored windows, random windows for block bootstraps, and even Pandas-native `groupby` and `resample` instructions such as "M" for monthly frequency. As a bonus, the produced splits can be easily analyzed and visualized! For example, you can detect any split or set overlaps, convert all splits into a single boolean mask for custom analysis, group splits and sets, and analyze their distribution relative to each other. This class contains more lines of code than the entire [backtesting.py](https://github.com/kernc/backtesting.py) package, so do not underestimate the new king in town! 🦏 ```python title="Roll a 360-day window and split it equally into train and test sets" >>> data = vbt.YFData.pull("BTC-USD", start="4 years ago") >>> splitter = vbt.Splitter.from_rolling( ... data.index, ... length="360 days", ... split=0.5, ... set_labels=["train", "test"], ... freq="daily" ... ) >>> splitter.plots().show() ``` Rolling 360-day BTC-USD windows divided equally into train and test sets. [Figure data (JSON)](/assets/figures/features/optimization/splitter.102d7b03605c.json) !!! info "Tutorial" Learn more in the [Cross-validation](/tutorials/cross-validation) tutorial. # Benchmarks (/features/performance/benchmarks) See VBT's backtesting speed across millions of bars and orders. Explore the interactive comparisons below, from high-level Python calls to low-level Rust simulation. Each result uses matching data and orders, passes a correctness check, and comes with code you can run on your own machine. ## Compare backtesting speed \[#compare-backtesting-speed] Choose a workload and the number of rows per column below. Sparse orders show the cost of scanning a long history with occasional trades. Dense orders show the cost when every bar produces an order. The high-level results are the starting point if you want to use VBT's Python portfolio API. Interactive simulator benchmark across backtesting libraries and input sizes. [Benchmark suite (ZIP)](/downloads/simulator-showdown.zip) Each simulator receives the same one-minute bars and the same orders: a sparse workload with a few orders per column, or a dense one with an order on every bar. A result counts only after its filled orders, final positions, and portfolio value match. VBT runs at three API levels: high-level portfolio construction, mid-level simulation with prepared inputs, and low-level order processing, each on Numba and on Rust. With 1,000,000 bars in each of 8 columns run in parallel, the sparse workload took 1.7 ms on the low-level Rust simulator and 25 ms through high-level Rust, against 42 ms for Manifold-BT and 65 seconds for Backtrader. In the dense workload, with 8,000,000 orders, high-level Rust took 178 ms, Manifold-BT 213 ms, and Backtrader did not finish within the 300-second limit. The translucent markers show the first call: Numba compiles on first use, which took about 16 seconds at the high level, while Rust is compiled ahead of time. All numbers were measured on an Apple M3 with 8 cores, with each library's version shown in the chart's tooltips. The ZIP contains the full harness to rerun them. ## Which benchmark matches your research? \[#which-benchmark-matches-your-research] | Your workflow | What to compare | | ------------------------------------------------------------ | ------------------------------------------------------------------------- | | Build portfolios from Python and inspect their results | High-level calls, including input preparation and portfolio construction. | | Reuse prepared arrays in repeated simulations | Mid-level calls that time the simulator with those inputs ready. | | Write a custom numerical simulation loop | Low-level order processing, where you handle the surrounding workflow. | | Spend most of your time on indicators or performance metrics | The function benchmarks below, using shapes close to your own data. | The warm timings help estimate repeated research runs. First-call timings matter when you start a new script or worker process. Both are shown so you can judge the cost that applies to your workflow. The [Rust engine](/features/performance/native-rust/) page also demonstrates a strategy with callbacks that react to fills, while [parallel execution and caching](/features/performance/parallel-execution-and-caching/) shows a large parameter sweep with measured memory usage. ## Benchmarking your functions \[#benchmarking-your-functions] The package includes a benchmark engine for its own functions. `vbt.run_benchmarks` generates seeded inputs of a chosen shape, checks backend outputs for agreement, and then times each one. The checks include returned values and registered in-place outputs, so timings are tied to the calculation being tested: ```python title="Compare Numba and Rust on six functions with 100,000 × 10 inputs" >>> results = vbt.run_benchmarks( ... input_model="2d", ... backend_ids=("nb", "rs"), ... patterns=[ ... "generic.rolling.rolling_mean", ... "generic.rolling.ewm_mean", ... "generic.base.crossed_above", ... "returns.sharpe_ratio", ... "returns.max_drawdown", ... "portfolio.from_signals.from_signals", ... ], ... rows=100_000, ... cols=10, ... ) >>> rows = {} >>> for r in results: ... ms = {backend: s * 1e3 for backend, s in r.runtime_by_backend.items()} ... rows[r.name] = ms | {"speedup": r.speedup} >>> pd.DataFrame(rows).T.round(2) # (1) nb rs speedup generic.base.crossed_above 4.45 5.67 0.78 generic.rolling.ewm_mean 5.46 2.35 2.32 generic.rolling.rolling_mean 3.81 3.96 0.96 portfolio.from_signals.from_signals[dense] 167.33 180.72 0.93 portfolio.from_signals.from_signals[grouped] 134.67 129.49 1.04 portfolio.from_signals.from_signals[sparse] 14.15 11.91 1.19 returns.max_drawdown 2.73 0.94 2.92 returns.sharpe_ratio 4.55 1.09 4.19 ``` 1. Milliseconds per call, the best of five runs after two warmup calls, on an Apple M3. The speedup is the Numba time divided by the Rust time. Rust was more than four times faster on the Sharpe ratio and nearly three times on maximum drawdown, and slightly slower on the rolling mean, crossovers, and the dense simulation. Results like these are why VBT does not assume one backend is always faster. The command-line version runs the same engine over whole families of functions, and the full matrix covers almost every function in the package, as the [Benchmarks](#benchmarks) highlight below shows. Generated matrix reports record the CPU, operating system, Python and package versions, Rust tools, and selected thread settings alongside the results. You can save the reports with your research and compare a new environment against the same workloads. Start with the functions you use most, then expand to the full matrix when you need broader coverage. ## Measured backend selection \[#measured-backend-selection] AutoBench uses those measurements. After you build a benchmark cache on your machine, setting `vbt.settings.jitting["backends"]["auto_mode"] = "bench"` uses stored timings and the input shape to choose an eligible backend, and `"bench_mixed"` also chooses between serial and parallel versions. Policies keep the choice conservative: a backend must beat the default by at least 5% by default, and the comparison can use the minimum or another statistic of the measured runs. The [Compute backends](/features/performance/compute-backends/) page covers the other ways to choose a backend. ## Measuring your code \[#measuring-your-code] `vbt.Timer` and `vbt.MemTracer` measure elapsed time and peak traced memory for a block of code, as the [Resource management](#resource-management) highlight below shows. `vbt.timeit` times a function and returns a readable duration, and the `@vbt.with_timer` and `@vbt.with_memtracer` decorators print the time or memory of every call to a function. Measure the stages you actually run: preparing data, calculating signals, simulating orders, and building the statistics you want to keep. This shows where a faster backend, reused inputs, or smaller [chunks](/features/performance/parallel-execution-and-caching/#splitting-work-into-chunks) would help. `MemTracer` uses Python's `tracemalloc` to track allocations during the block. Use whole-process memory measurements as well when planning how many workers fit in RAM. Small inputs mostly measure fixed costs. On the machine that built this page, one `vbt.PF.from_signals` call took 5.3 ms on 365 bars and 6.4 ms on 100,000 bars: nearly all of it went to preparing inputs and building the portfolio, not to the simulation. A comparison on one year of daily data therefore says little about speed at scale. Many small backtests run faster as columns of one call, or through the lower-level functions the showdown above includes. !!! tip "Benchmark what you run" Speed depends on the function, the input shape and memory layout, the number of cores, and whether code is already compiled. Time the calls that dominate your workload, on your data and hardware, after a warmup call. ## Benchmarks \[#benchmarks] New in v2026.6.27 ✅ VBT now ships with correctness-aware backend benchmarks for almost the entire codebase. The latest benchmark overview covers **748** functions, **768** variants, **1,976** kernels, **15,709** cases, and **59,600** benchmark runs across Numba, Rust, raw backend calls, AutoBench, and AutoBenchMixed. This makes performance inspectable: users can see which backend wins, at which input size, and whether parallel execution is worth it for their workload. === "Targeted run" ```bash title="Benchmark one family from the terminal" python -m vectorbtpro.benchmarks.bench_engine_cli \ --backend nb \ --backend rs \ --input-model 1d \ --pattern returns ``` ```python title="Run the same benchmark from Python" >>> results = vbt.run_benchmarks( ... input_model="1d", ... backend_ids=("nb", "rs"), ... patterns=["returns"], ... ) >>> print(results) # (1) function,task_id,ndim,shape,nb_s,rs_s,speedup,auto_bench_backend,nb_elapsed_s,rs_elapsed_s ... ``` 1. Results are emitted as CSV with per-backend runtimes, speedup, elapsed benchmark time, and the backend selected by AutoBench when applicable. Outputs are checked for parity before timing by default. === "Full matrix" ```bash title="Generate cache, reports, and SVG plots" python -m vectorbtpro.benchmarks.bench_matrix_cli --full --write-plots ``` !!! info "Note" The full matrix can take a long time because it benchmarks thousands of cases across multiple backends, shapes, and execution modes. The full run writes Markdown reports, `cache.json`, `runtime.svg`, and `speedup.svg`. Writing plots also requires a Plotly static image export engine such as Kaleido. Benchmark median runtime ranks by backend and total element count. [Figure data (JSON)](/assets/figures/features/productivity/benchmark-runtime.7d417eb67553.json) ## Resource management \[#resource-management] New in 1.0.0 ✅ New profiling tools help you measure the execution time and memory usage of any code block 🧰 ```python title="Profile getting the Sharpe ratio of a random portfolio" >>> data = vbt.YFData.pull("BTC-USD") >>> with ( ... vbt.Timer() as timer, ... vbt.MemTracer() as mem_tracer ... ): ... print(vbt.PF.from_random_signals(data.close, n=100, seed=42).sharpe_ratio) 1.0410760501518814 >>> print(timer.elapsed()) 74.15 milliseconds >>> print(mem_tracer.peak_usage()) 459.7 kB ``` # Compute backends (/features/performance/compute-backends) Why is VBT fast, and how do you control what runs where? VBT PRO moves heavy backtesting and analysis operations into Numba-compiled functions. Supported functions can also run in parallel, use the optional Rust extension, or use a NumPy implementation you register. Choose a backend per call or globally while keeping the same Python research workflow. ## Faster calculations from pandas \[#faster-calculations-from-pandas] You can start with a pandas Series or DataFrame and call VBT's rolling statistics, indicators, and portfolio simulators without writing a compiled function yourself. VBT passes numerical arrays to the calculation and wraps results with their labels. Your dates, symbols, and parameter combinations remain available for analysis. For custom logic, Numba lets you write numerical loops in Python and compile them. This is useful for a signal that depends on an open position or an indicator that updates its state at each bar. Your compiled functions work with NumPy arrays, while data preparation and reporting can stay in pandas. See [custom indicators](/features/indicators/indicator-development/) and [event-driven backtesting](/features/backtesting/event-driven-backtesting/) for examples. ## Compare NumPy, Numba, and Rust \[#compare-numpy-numba-and-rust] ```python title="Time one rolling mean on 50 million values across backends and memory layouts" >>> import timeit >>> @vbt.register_jitted(task_id_or_func=vbt.nb.rolling_mean_nb) # (1) ... def rolling_mean_np(arr, window, minp=None): ... csum = np.cumsum(arr, axis=0) ... out = np.full(arr.shape, np.nan) ... out[window - 1] = csum[window - 1] ... out[window:] = csum[window:] - csum[:-window] ... return out / window >>> np.random.seed(42) >>> values = 100 + np.random.normal(0, 0.01, size=(100_000, 500)).cumsum(axis=0) >>> layouts = { ... "row-major": pd.DataFrame(np.ascontiguousarray(values)), # (2) ... "column-major": pd.DataFrame(np.asfortranarray(values)), ... } >>> backends = { ... "pandas": None, ... "NumPy": "np", ... "Numba": "nb", ... "Numba parallel": dict(jitter="nb", parallel=True), ... "Rust": "rs", ... "Rust parallel": dict(jitter="rs", parallel=True), ... } >>> def ms(func): ... return min(timeit.repeat(func, number=3, repeat=5)) / 3 * 1000 >>> timings = {} >>> for layout, prices in layouts.items(): ... for backend, jitted in backends.items(): ... if jitted is None: ... func = lambda: prices.rolling(50).mean() ... else: ... func = lambda: prices.vbt.rolling_mean(50, jitted=jitted) ... timings[(backend, layout)] = ms(func) >>> pd.Series(timings).unstack().loc[list(backends), list(layouts)].round(0).astype(int) row-major column-major pandas 693 360 NumPy 489 204 Numba 561 163 Numba parallel 379 32 Rust 87 145 Rust parallel 71 67 ``` 1. Registers a NumPy implementation of the built-in rolling mean under the `np` jitter, so `jitted="np"` can select it. 2. Row-major arrays store each row's values together, column-major arrays each column's. A DataFrame built from separate columns is usually column-major. The table shows milliseconds per call on an Apple M3, and every backend returned the same values. The fastest run took 32 ms against 360 ms for pandas on the same array, but the winner changed with the layout: parallel Numba on column-major data and parallel Rust on row-major data. Rust's rolling mean walks the array row by row and first copies column-major input into row order, while Numba's runs down each column and gains the most when columns are contiguous. That is why VBT lets you choose a backend per call, set one globally, or let measured timings choose. ## Which backend fits your workload? \[#which-backend-fits-your-workload] | Your workload | What to try | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------ | | Backtests with your own Python trading rules | Numba compiles numerical callbacks and simulation loops. | | Rolling calculations across many symbols or parameter combinations | Parallel Numba or Rust can spread supported calculations across CPU cores. | | Repeated calls to supported built-in functions | Rust runs native code without waiting for Numba to compile that function. | | An existing NumPy implementation you want to reuse | Register it alongside the built-in implementation and select it with `jitted`. | | A research pipeline with different calculation shapes | Measure the important calls and use per-call choices or AutoBench. | Columns can represent both instruments and strategy configurations. Simulations parallelize independent columns or groups, while processing each strategy's bars in order. For distributing whole backtests across workers or splitting large arrays into chunks, see [parallel execution and caching](/features/performance/parallel-execution-and-caching/). ## Numba compilation \[#numba-compilation] Most numerical functions in VBT are compiled with Numba, from rolling statistics and signal generators to the simulators behind `vbt.PF.from_signals`. The simulators are compiled loops over bars rather than whole-array operations, which is why path-dependent rules such as stops and position sizing from the current balance run at compiled speed. Compiled functions release the GIL, so threads can run them side by side, and cache-enabled built-in functions store compiled code on disk for reuse in later Python sessions. Changing data or parameter values does not itself require recompilation when the argument types stay the same, making repeated research runs a good fit. The first call in a fresh environment still compiles, which can take seconds. Your own callbacks, such as a signal function for `from_signals`, are compiled too, and the simulator is compiled again for each new callback, which took about 20 seconds on the machine that built this page. Redefining the callback, for example by rerunning the notebook cell that defines it, counts as new, so keep callbacks in their own cell or module. The [`staticized` option](/features/backtesting/backtesting-engine/#staticization) turns a simulation that calls them into a function that can be cached on disk as well, so it survives restarts and new worker processes. This caches the compiled simulator, so you can still run it on new market data and parameters. For debugging, `jitted=False` runs the underlying Python function, as the cumulative-sum example below shows. You can also disable Numba before importing VBT through the `numba.disable` configuration setting. This controls Numba compilation, while backend selection controls whether a call uses Rust. ## Backends and jitters \[#backends-and-jitters] A jitted function in VBT is a registry entry with one or more implementations: `nb` for Numba, `rs` for the optional Rust extension, `np` for vectorized NumPy, or any jitter you register. The `jitted` argument picks one per call and passes options such as `parallel=True`, as the [Jitting](#jitting) and [Parallel Numba](#parallel-numba) highlights below show. Parallel versions process columns on several cores, which pays off on wide arrays and costs a little on narrow ones. Rolling return metrics, such as the rolling Sharpe and Sortino ratios, update running sums in one pass instead of recomputing each window, as the [Hyperfast rolling metrics](#hyperfast-rolling-metrics) highlight below shows. ## Backend selection \[#backend-selection] With the Rust extension installed, compatible calls go to Rust by default and fall back to Numba when Rust cannot handle the inputs. In the example above, the default call took 86 ms on row-major data and 147 ms on column-major data, the Rust timings. Three settings change that: * **Per call:** `jitted="nb"`, `jitted="rs"`, or a dictionary with options. * **By module:** resolution overrides set a backend for every function whose path matches, such as everything under `vectorbtpro.returns`. * **By measurement:** AutoBench reads a benchmark cache built on your machine and sends each call to an eligible backend using those measurements and, where needed, the input shape. The [Rust backend](/features/performance/native-rust/#rust-backend) highlight on the Rust engine page shows each option. Backend selection happens inside the calculation, so you can keep the same pandas inputs and result handling when switching supported implementations. !!! tip "Find your fastest backend" Compare backends on your own arrays with VBT's benchmark tools, then use the timings to select a backend for each calculation. Keep the same Python inputs and labeled results. ## Parallel Numba \[#parallel-numba] New in 1.0.0 ✅ Most Numba-compiled functions have been rewritten to process columns in parallel using [automatic parallelization with `@jit`](https://numba.readthedocs.io/en/stable/user/parallel.html). You can enable this with a single command. This approach is best for lightweight functions that are applied to wide arrays. ```python title="Benchmark the rolling mean without and with parallelization" >>> np.random.seed(42) >>> df = pd.DataFrame(np.random.uniform(size=(1000, 1000))) >>> %timeit df.rolling(10).mean() # (1) 45.6 ms ± 138 µs per loop (mean ± std. dev. of 7 runs, 10 loops each) >>> %timeit df.vbt.rolling_mean(10) # (2) 5.33 ms ± 302 µs per loop (mean ± std. dev. of 7 runs, 1 loop each) >>> %timeit df.vbt.rolling_mean(10, jitted=dict(parallel=True)) # (3) 1.82 ms ± 5.21 µs per loop (mean ± std. dev. of 7 runs, 1000 loops each) ``` 1. Using Pandas. 2. Using Numba without parallelization. 3. Using Numba with parallelization. ## Jitting \[#jitting] New in 1.0.0 ✅ Jitting stands for just-in-time compiling. In the VBT universe, however, jitting simply means accelerating. While Numba remains the primary jitter, VBT now allows you to implement custom jitter classes, such as those for vectorized NumPy or even [JAX](https://github.com/google/jax) with GPU support. Every jitted function is registered globally, so you can switch between different implementations or even disable jitting entirely with a single command. ```python title="Run different implementations of the cumulative sum" >>> data = vbt.YFData.pull("BTC-USD", start="7 days ago") >>> log_returns = np.log1p(data.close.pct_change()) >>> log_returns.vbt.cumsum() # (1) Date 2023-01-31 00:00:00+00:00 0.000000 2023-02-01 00:00:00+00:00 0.024946 2023-02-02 00:00:00+00:00 0.014271 2023-02-03 00:00:00+00:00 0.013310 2023-02-04 00:00:00+00:00 0.008288 2023-02-05 00:00:00+00:00 -0.007967 2023-02-06 00:00:00+00:00 -0.010087 Freq: D, Name: Close, dtype: float64 >>> log_returns.vbt.cumsum(jitted=False) # (2) Date 2023-01-31 00:00:00+00:00 0.000000 2023-02-01 00:00:00+00:00 0.024946 2023-02-02 00:00:00+00:00 0.014271 2023-02-03 00:00:00+00:00 0.013310 2023-02-04 00:00:00+00:00 0.008288 2023-02-05 00:00:00+00:00 -0.007967 2023-02-06 00:00:00+00:00 -0.010087 Freq: D, Name: Close, dtype: float64 >>> @vbt.register_jitted(task_id_or_func=vbt.nb.nancumsum_nb) # (3) ... def nancumsum_np(arr): ... return np.nancumsum(arr, axis=0) >>> log_returns.vbt.cumsum(jitted="np") # (4) Date 2023-01-31 00:00:00+00:00 0.000000 2023-02-01 00:00:00+00:00 0.024946 2023-02-02 00:00:00+00:00 0.014271 2023-02-03 00:00:00+00:00 0.013310 2023-02-04 00:00:00+00:00 0.008288 2023-02-05 00:00:00+00:00 -0.007967 2023-02-06 00:00:00+00:00 -0.010087 Freq: D, Name: Close, dtype: float64 ``` 1. Using the built-in Numba-compiled function. 2. Using the built-in function but with Numba disabled → regular Python → slow! 3. Register a NumPy version for the built-in Numba function. 4. Using the NumPy version. ## Hyperfast rolling metrics \[#hyperfast-rolling-metrics] New in 1.0.0 ✅ Rolling metrics based on returns have been optimized for maximum performance, with up to 1000x speedup! ```python title="Benchmark the rolling Sortino ratio" >>> import quantstats as qs >>> index = vbt.date_range("2020", periods=100000, freq="1min") >>> np.random.seed(42) >>> returns = pd.Series(np.random.normal(0, 0.001, size=len(index)), index=index) >>> %timeit qs.stats.rolling_sortino(returns, rolling_period=10) # (1) 2.79 s ± 24.8 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) >>> %timeit returns.vbt.returns.rolling_sortino_ratio(window=10) # (2) 8.12 ms ± 199 µs per loop (mean ± std. dev. of 7 runs, 1 loop each) ``` 1. Using QuantStats. 2. Using VBT. # Performance (/features/performance) Run quantitative workloads efficiently, from compiled array operations to portfolio simulation. VBT PRO combines Numba, optional Rust kernels, and custom NumPy implementations with chunking, caching, and parallel execution. You can speed up calculations in a Python research workflow, spread independent backtests across workers, or build a native Rust strategy. See VBT process millions of backtests, run stateful strategies in Rust, and spread research across CPU cores. The examples and interactive benchmarks show the speed and memory use directly. ## Find the right starting point \[#find-the-right-starting-point] | What you need | Explore | | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Faster indicators, return metrics, or simulations from Python | [Compute backends](/features/performance/compute-backends/) compares Numba, Rust, parallel kernels, and custom implementations. | | Precompiled calculations or strategies written directly in Rust | [Rust engine](/features/performance/native-rust/) covers Python acceleration, native callbacks, and streaming simulation. | | Larger parameter searches with control over memory and completed work | [Parallel execution and caching](/features/performance/parallel-execution-and-caching/) covers chunks, threads, processes, Ray, and reusable results. | | Measured speed across simulators and workloads | [Benchmarks](/features/performance/benchmarks/) compares simulators and shows how to measure your own code. | * [Compute backends](/features/performance/compute-backends): Run kernels with Numba, parallel Numba, Rust, or NumPy and choose the backend per call * [Rust engine](/features/performance/native-rust): Run simulations on the native Rust engine and write strategy callbacks in Rust * [Parallel execution and caching](/features/performance/parallel-execution-and-caching): Chunk work across threads, processes, or Ray, cache results, and keep memory bounded * [Benchmarks](/features/performance/benchmarks): Compare simulators on the same orders and measure each backend on your own machine ## Keep your Python workflow \[#keep-your-python-workflow] You can use the high-level pandas and portfolio APIs while supported numerical calculations run in compiled code. Numba handles custom numerical callbacks, and the optional Rust extension can accelerate supported built-in calls without requiring you to write Rust. Backend selection and parallel workers give you separate controls over how a calculation runs and how independent work is distributed. For a large [strategy search](/features/optimization/strategy-optimization/), combine the two: run the calculations through a suitable backend, process combinations in manageable chunks, and keep the metrics you need. If you want to write the strategy in Rust, the native simulators also support stateful callbacks and processing new bars as they arrive. ## Start here \[#start-here] Start with the [benchmark comparisons](/features/performance/benchmarks/) to see measured examples, or follow [From Python to Rust](/tutorials/from-python-to-rust/) to explore the same strategy at different execution levels. See the [Rust documentation](/documentation/rust/) for the native backend and the [Benchmarks](/documentation/benchmarks/) for measured performance examples. # Rust engine (/features/performance/native-rust) Bring Rust speed to your Python research, or write the entire strategy in Rust. VBT PRO ships a native Rust backtesting engine for both workflows. Python users get precompiled calculations through the optional extension. Rust users can also write stateful strategy callbacks and run independent simulations across CPU cores. ## Choose your route to Rust \[#choose-your-route-to-rust] | What you want to do | Where to start | | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | | Speed up supported calculations in an existing Python notebook or script | Install the optional extension and keep using the Python API. | | Keep custom trading rules written in Python | Use Numba callbacks, with Rust available for supported calculations elsewhere in the pipeline. | | Write a Rust strategy that reacts to fills, cash, or positions | Use the native simulators and give the strategy its own state. | | Process new bars as they arrive in a Rust program | Use a streaming stepper to carry the portfolio and strategy state forward. | The Python extension and native Rust library share calculation code. You can adopt the extension without learning Rust, and use the native library to build standalone Rust strategies. Native Rust programs can use the library without a Python runtime. ## A stateful strategy in Python and Rust \[#a-stateful-strategy-in-python-and-rust] The same strategy below runs twice: once as Numba callbacks through the Python API, once as a Rust strategy. It trades 100 synthetic assets over 50,000 hourly bars, enters on a moving average crossover, exits on the opposite cross or a 3% stop loss or 6% take profit, and waits 24 bars after any stop before entering that asset again. Whether that wait applies depends on fills the simulation itself produces, so it cannot be precomputed as an array. ```python title="Write the cooldown as Numba callbacks and run it through the Python API" >>> from collections import namedtuple >>> COOLDOWN_BARS = 24 >>> np.random.seed(42) >>> returns = np.random.normal(0, 0.01, size=(50_000, 100)) >>> close = pd.DataFrame(100 * np.exp(returns.cumsum(axis=0))) >>> fast = close.rolling(20).mean() >>> slow = close.rolling(100).mean() >>> entries = fast.vbt.crossed_above(slow) >>> exits = fast.vbt.crossed_below(slow) >>> Memory = namedtuple("Memory", ["blocked_until"]) >>> @njit ... def cooldown_signal_func_nb(c, entries, exits, memory): ... cooling = c.i < memory.blocked_until[c.col] ... entry = vbt.nb.flex_select_nb(entries, c.i, c.col) and not cooling ... exit = vbt.nb.flex_select_nb(exits, c.i, c.col) ... return entry, exit, False, False >>> @njit ... def cooldown_post_order_func_nb(c, memory): ... if vbt.pf_nb.order_closed_position_nb(c): # (1) ... if vbt.pf_nb.get_last_order_nb(c)["stop_type"] >= 0: ... memory.blocked_until[c.col] = c.i + 1 + COOLDOWN_BARS >>> memory = Memory(blocked_until=np.zeros(close.shape[1], dtype=int_)) >>> pf = vbt.PF.from_signals( ... close, ... signal_func_nb=cooldown_signal_func_nb, ... signal_args=(vbt.Rep("entries"), vbt.Rep("exits"), memory), ... broadcast_named_args=dict(entries=entries, exits=exits), ... post_order_func_nb=cooldown_post_order_func_nb, ... post_order_args=(memory,), ... size=1.0, ... fees=0.001, ... sl_stop=0.03, ... tp_stop=0.06, ... ) ``` 1. Runs after every order. When an order closed the position and its record carries a stop type, the asset is blocked for the next 24 bars. ```rust title="Write the same cooldown as a Rust strategy" const COOLDOWN_BARS: usize = 24; struct Cooldown<'a> { entries: ArrayView2<'a, bool>, exits: ArrayView2<'a, bool>, blocked_until: Vec, // (1) } impl SignalStrategy for Cooldown<'_> { fn signals(&mut self, ctx: &mut SignalContext<'_, '_>) -> VbtResult { let cell = [ctx.i(), ctx.col()]; let cooling = ctx.i() < self.blocked_until[ctx.local_col()]; Ok(Signals { long_entry: self.entries[cell] && !cooling, long_exit: self.exits[cell], ..Signals::default() }) } fn on_order_end( &mut self, ctx: &mut OrderEndContext<'_, '_, SignalOrderRecord>, report: &ExecutionReport, ) -> VbtResult<()> { if report.before.position != 0.0 && report.after.position == 0.0 { let record = ctx.order_record_now().expect("a close emits a record"); if record.stop_type >= 0 { self.blocked_until[ctx.local_col()] = ctx.i() + 1 + COOLDOWN_BARS; } } Ok(()) } } ``` 1. A Rust strategy owns its state, so the memory tuple becomes a field. ```rust title="Run it on one core and on all cores" let simulator = SignalSimulator::builder() .config( SimulationConfig::builder() .target_shape(close.dim()) .group_lens(group_lens.view()) .close(close.view()) .build()?, ) .signal_config( SignalConfig::builder().size(1.0).fees(0.001).sl_stop(0.03).tp_stop(0.06).build(), ) .build()?; let new_cooldown = |info: GroupInfo| { Ok(Cooldown { entries: entries.view(), exits: exits.view(), blocked_until: vec![0; info.to_col - info.from_col], }) }; let serial = simulator.run(new_cooldown)?; // (1) let parallel = simulator.run_parallel(new_cooldown)?; ``` 1. `run` creates one strategy per group and runs the groups in order. `run_parallel` distributes independent groups across CPU cores, and the combined output keeps the same order. Both versions produced the same 65,278 orders, matching on every column, bar, size, and price. Measured on an Apple M3 with 8 cores, best of five runs: | Run | Milliseconds | | --------------------------------------------- | -----------: | | Numba callbacks through `vbt.PF.from_signals` | 1,129 | | Rust strategy, one core | 538 | | Rust strategy, all cores | 201 | The Python time includes argument preparation and portfolio construction, and the Rust times cover the simulation alone. The table therefore measures the two workflows at different levels. The research script that produced it builds the Rust program, runs both versions, and compares their orders. ## Drop-in Rust kernels \[#drop-in-rust-kernels] Python users get the Rust engine without writing Rust. With the optional `vectorbtpro-rust` package installed, supported functions such as rolling statistics, signal helpers, return metrics, and the `from_signals` and `from_orders` simulators run as precompiled Rust kernels, and fall back to Numba for anything Rust does not cover. Install it from the platform wheels of the matching release before installing `vectorbtpro`, as described in the [installation guide](https://members.vectorbt.pro/installation/#rust-backend). VBT uses it only when its version matches exactly. `jitted=dict(jitter="rs", parallel=True)` spreads supported calculations across cores, over columns or independent portfolio groups. Because the kernels are compiled ahead of time, the first call in a session does not wait for Numba. On the machine that built this page, the first call of a rolling standard deviation in a fresh process took about 0.08 seconds with Rust. Numba took 1.3 seconds the first time it saw those inputs, since it compiled the function, and about 0.17 seconds in later processes, which load the compiled version from disk. Later calls in the same process took under a millisecond either way, so short scripts, scheduled jobs, and new worker processes gain the most. The [Compute backends](/features/performance/compute-backends/) page shows when Rust wins and how to choose a backend per call, and the [Rust backend](#rust-backend) highlight below shows the controls. ## Native simulators \[#native-simulators] The same simulators are a Rust library. A Rust program can run a whole history at once with `run_single`, `run`, or `run_parallel`, or feed bars one at a time to a stepper such as `SignalStepper` and receive each bar's fills as they happen, with checkpoints to save and restore its state. You can replay a history and then continue as new bars arrive, keeping cash, positions, and strategy memory such as the cooldown above. See [live simulation](/features/backtesting/live-simulation/) for this workflow. Batch and streaming runs can be compared with `ensure_simulation_eq`, which checks records and terminal portfolio state and reports the first mismatch. This gives you a way to check that moving a strategy from a full-history run to a bar-by-bar feed preserves its simulated trades. The crate's test suite compares its simulators with the Numba ones, as the example above did with orders. ## Rust callbacks \[#rust-callbacks] Strategies in Rust are types that implement a trait, such as `SignalStrategy` for signals, `OrderStrategy` for one order per element, and `FlexOrderStrategy` for any number of orders per bar. Their methods receive a context with the current bar, column, cash, and positions, and an execution report after each order. Other native engines take callbacks for signal generation, apply and reduce operations, and portfolio allocation. Each parallel simulation group gets its own strategy instance. A group can contain several assets that share cash, so you can keep portfolio-level decisions together while running independent portfolios in parallel. Rows and callbacks within each group still run in order. Rust callbacks run inside Rust programs. From Python, strategy logic is written as Numba callbacks like the ones above, which run on the Numba simulators. Errors in Rust carry a category, such as an invalid value or a rejected order, and surface in Python as the matching exception type. ## Bring Rust results back to Python \[#bring-rust-results-back-to-python] A native Rust simulation can save its output to a NumPy-compatible archive with `save_npz`. Load it with `vbt.load_simulation_npz` and build a Portfolio using the same prices, labels, initial cash, and grouping as the simulation. You can then use VBT's [performance analysis](/features/analytics/performance-metrics/) and [trade analytics](/features/analytics/trade-analytics/) on the Rust results. This lets you run the simulation in Rust and keep your Python analysis and reporting workflow. !!! info "Tutorial" The members-only [From Python to Rust](https://members.vectorbt.pro/tutorials/from-python-to-rust/) tutorial builds one strategy with the high-level API, Numba kernels, Python bindings, and native Rust, then moves it to streaming. ## Native Rust simulators \[#native-rust-simulators] New in v2026.9.5 ✅ Take your strategy directly to Rust. VBT's native simulators let the same strategy process a full price array or step through individual bars as they arrive. Strategy callbacks can inspect cash, positions, and orders during execution, keeping portfolio state within reach of your trading logic. !!! note "Note" The examples below share the strategy definition and require `vectorbtpro-rust` and `ndarray = "0.16"`. See the [Rust setup guide](/documentation/rust/) for installation. ```rust title="Define a strategy with price and position conditions" use vectorbtpro_rust::error::VbtResult; use vectorbtpro_rust::portfolio::enums::Order; use vectorbtpro_rust::portfolio::simulator::{ FnOrderStrategy, OrderContext, OrderStrategy, }; fn buy_the_dip() -> impl OrderStrategy { FnOrderStrategy::new(|ctx: &OrderContext<'_, '_>| { let price = ctx.close(ctx.col()); let position = ctx.position(ctx.col()); let size = if price <= 100.0 && position == 0.0 { // (1) 1.0 } else if price >= 110.0 && position > 0.0 { -position } else { return Ok(None); }; Ok(Some(Order::builder().size(size).build())) }) } ``` 1. Buy one share only when flat. The position check prevents another buy at $98. === "Batch" ```rust title="Run a batch simulation" use ndarray::array; use vectorbtpro_rust::portfolio::simulator::{OrderSimulator, SimulationConfig}; fn main() -> VbtResult<()> { let close = array![[100.0], [98.0], [105.0], [112.0]]; let groups = array![1]; let config = SimulationConfig::builder() .target_shape(close.dim()) .group_lens(groups.view()) .close(close.view()) .init_cash(1000.0) .build()?; let simulator = OrderSimulator::builder().config(config).build()?; let output = simulator.run_single(&mut buy_the_dip())?; for order in &output.order_records { println!("row {}: {:.0} share at ${:.0}", order.idx, order.size, order.price); } Ok(()) } ``` ```text title="Output" row 0: 1 share at $100 row 3: 1 share at $112 ``` === "Streaming" ```rust title="Run a streaming simulation" use ndarray::array; use vectorbtpro_rust::portfolio::simulator::{OrderStepper, StreamConfig, StreamRow}; fn main() -> VbtResult<()> { let close = array![[100.0], [98.0], [105.0], [112.0]]; let groups = array![1]; let config = StreamConfig::builder() .group_lens(groups.view()) .init_cash(1000.0) .build()?; let mut live = OrderStepper::new_single(config, None, buy_the_dip())?; for row in close.rows() { let step = live.step(StreamRow::builder().close(row).build())?; // (1) for order in step.order_records() { println!("row {}: {:.0} share at ${:.0}", order.idx, order.size, order.price); } } Ok(()) } ``` 1. Preserve portfolio state between calls and return the current bar's fills. The stepper does not retain the complete record history by default. ```text title="Output" row 0: 1 share at $100 row 3: 1 share at $112 ``` !!! info "Tutorial" Learn more in the [From Python to Rust](/tutorials/from-python-to-rust/) tutorial. ## Rust backend \[#rust-backend] New in v2026.6.27 ✅ Install the optional `vectorbtpro-rust` extension and compatible jitted calls can take the Rust fast lane automatically. VBT exposes the extension as `vbt.rs`, registers Rust kernels under `jitted="rs"`, and falls back to the normal implementation, usually Numba, when Rust is unavailable or unsupported. === "Out of the box" ```python title="Keep your workflow, get the Rust lane" >>> data = vbt.YFData.pull("BTC-USD", start="2024") >>> fast_ma = data.close.vbt.rolling_mean(20) # (1) >>> slow_ma = data.close.vbt.rolling_mean(50) >>> entries = fast_ma.vbt.crossed_above(slow_ma) # (2) >>> exits = fast_ma.vbt.crossed_below(slow_ma) >>> pf = vbt.Portfolio.from_signals( # (3) ... data, ... entries=entries, ... exits=exits, ... sl_stop=0.05, ... tp_stop=0.15, ... fees=0.001, ... ) ``` 1. `rolling_mean_nb` routes to `vbt.rs.generic.rolling.rolling_mean_rs`. 2. `crossed_above_nb` routes to `vbt.rs.generic.base.crossed_above_rs`. 3. `from_signals_nb` routes to `vbt.rs.portfolio.from_signals.from_signals_rs`. === "Speed check" ```python title="Compare Numba, parallel Numba, Rust, and parallel Rust" >>> np.random.seed(42) >>> returns = pd.DataFrame(np.random.normal(0, 0.01, size=(200_000, 64))) # (1) >>> nb = lambda: returns.vbt.returns.rolling_profit_factor( ... window=50, ... jitted="nb" ... ) >>> nb_parallel = lambda: returns.vbt.returns.rolling_profit_factor( ... window=50, ... jitted=dict(jitter="nb", parallel=True) ... ) >>> rs = lambda: returns.vbt.returns.rolling_profit_factor( ... window=50, ... jitted="rs" ... ) >>> rs_parallel = lambda: returns.vbt.returns.rolling_profit_factor( ... window=50, ... jitted=dict(jitter="rs", parallel=True) ... ) >>> nb(); nb_parallel(); rs(); rs_parallel() # (2) >>> %timeit nb() 1.21 s ± 655 μs per loop (mean ± std. dev. of 7 runs, 1 loop each) >>> %timeit nb_parallel() 214 ms ± 15.6 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) >>> %timeit rs() 272 ms ± 736 μs per loop (mean ± std. dev. of 7 runs, 1 loop each) >>> %timeit rs_parallel() 54.6 ms ± 1.23 ms per loop (mean ± std. dev. of 7 runs, 10 loops each) ``` 1. Use a wide enough array to give parallel kernels room to stretch. 2. Warm up first so Numba compilation stays out of the race. These timings were measured on an Apple M3 and will vary by machine. === "AutoBench" ```bash title="Build the benchmark cache first" python -m vectorbtpro.benchmarks.bench_matrix_cli --full ``` !!! info "Note" The full benchmark matrix can take several hours to finish, depending on your machine. ```python title="Let local timings pick the lane" >>> vbt.settings.jitting["backends"]["auto_bench_path"] = "benchmarks/cache.json" # (1) >>> vbt.settings.jitting["backends"]["auto_mode"] = "bench" # (2) >>> data = vbt.YFData.pull("BTC-USD", start="2024") >>> sharpe_ratio = data.returns.vbt.returns.sharpe_ratio() # (3) ``` 1. Run benchmarks before enabling AutoBench. The matrix command writes this cache by default. Change the path if you pass a custom `--output-dir` or `--cache`. 2. Use `"bench"` for AutoBench or `"bench_mixed"` for AutoBenchMixed. AutoBenchMixed can pick across serial and parallel candidates automatically. 3. Leave `jitted` empty. Compatible calls consult your machine's benchmark cache automatically. === "Control panel" ```python title="Tune Rust preference" >>> vbt.settings.jitting["backends"]["auto_mode"] = False # (1) >>> vbt.settings.jitting["resolve_overrides"]["returns_module"] = dict( # (2) ... match="vectorbtpro.returns", ... resolve_kwargs=dict(auto_mode=True), ... ) >>> data = vbt.YFData.pull("BTC-USD", start="2024") >>> sharpe_ratio = data.returns.vbt.returns.sharpe_ratio() ``` 1. Disable Rust-first automatic dispatch globally. 2. Re-enable automatic backend dispatch only for returns-module calls. === "Raw Rust, fastest lane" ```python title="Resolve or call the Rust function directly" >>> total_return_rs = vbt.resolve_jitted( # (1) ... vbt.ret_nb.total_return_nb, ... jitted="rs", ... use_backend_wrapper=False, ... ) >>> data = vbt.YFData.pull("BTC-USD", start="2024") >>> returns = data.returns.vbt.to_2d_array() # (2) >>> total_return_rs(returns) # (3) array([0.652341]) >>> vbt.rs.returns.total_return_rs(returns) # (4) array([0.652341]) ``` 1. Let VBT find the Rust backend registered for `total_return_nb`. With `use_backend_wrapper=False`, this returns the raw Rust function itself. 2. Prepare arguments. Raw kernels expect raw arrays, not wrapped Series/DataFrames. 3. Call the resolved Rust function with raw-array arguments. 4. Or import the same Rust function from its module path. The API page for each Numba function lists its Rust counterpart path when one exists. !!! info Raw Rust functions bypass the registry's compatibility checks, argument preparation, and fallbacks. Use them only when you have prepared arguments in the exact format expected by the Rust function. # Parallel execution and caching (/features/performance/parallel-execution-and-caching) How do you scale research beyond one core and one machine's memory? VBT splits work into chunks, runs them across threads, processes, or a Ray cluster, and reuses completed results. You control how much work runs at once and what each run keeps, so parallel backtesting in Python can scale to millions of combinations. ## Start with your own backtest function \[#start-with-your-own-backtest-function] Keep data preparation, signals, and portfolio analysis in one function, then let VBT run it for each parameter combination. This small example tests three entry thresholds in threads and returns one metric per threshold: ```python title="Run a small threshold sweep across threads" >>> close = pd.Series([100.0, 102.0, 101.0, 104.0, 103.0, 106.0]) >>> @vbt.parameterized(merge_func="concat", engine="threadpool", chunk_len=2, show_progress=False) ... def test_entry_price(close, entry_price): ... pf = vbt.PF.from_signals( ... close, ... entries=close.vbt.crossed_above(entry_price), ... exits=close.vbt.crossed_below(entry_price), ... fees=0.001, ... ) ... return pf.total_return >>> result = test_entry_price(close, vbt.Param([100.0, 102.0, 104.0], name="entry_price")) >>> result.round(4) entry_price 100.0 0.0000 102.0 0.0182 104.0 -0.0010 dtype: float64 ``` Here, `chunk_len=2` submits two parameter calls at a time. Each call returns total return as a fraction, and VBT labels the combined result with its parameter value. Set `engine="serial"` to run the same function sequentially. Scale this pattern to larger tasks and search spaces, as the ten-million-combination example below demonstrates. See [strategy optimization](/features/optimization/strategy-optimization/) for larger search spaces. ## Ten million combinations with compact results \[#ten-million-combinations-with-compact-results] ```python title="Backtest 10,000,000 combinations and keep the best stop per window pair" >>> close = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2025-01-01").close >>> @vbt.parameterized( ... merge_func="row_stack", ... engine="threadpool", # (1) ... chunk_len="auto", ... warmup=True, ... ) ... @njit(nogil=True) ... def best_stop_nb(close, fast_window, slow_window, sl_stops): ... fast = vbt.nb.rolling_mean_1d_nb(close, fast_window) ... slow = vbt.nb.rolling_mean_1d_nb(close, slow_window) ... entries = vbt.nb.crossed_above_1d_nb(fast, slow) ... exits = vbt.nb.crossed_above_1d_nb(slow, fast) ... n = len(sl_stops) ... sim_out = vbt.pf_nb.from_signals_nb( ... target_shape=(len(close), n), ... group_lens=np.full(n, 1), ... close=close, ... long_entries=entries, ... long_exits=exits, ... sl_stop=sl_stops.reshape(1, -1), ... fees=0.001, ... save_returns=True, ... ) ... sharpe = vbt.ret_nb.sharpe_ratio_nb(sim_out.in_outputs.returns, 365.0) ... best = 0 ... for i in range(n): # (2) ... if sharpe[i] > sharpe[best]: ... best = i ... return np.array([sharpe[best], sl_stops[best]]) >>> sl_stops = np.linspace(0.001, 0.30, 1000) >>> best = best_stop_nb( ... close.values, ... vbt.Param(np.arange(2, 102), name="fast_window"), ... vbt.Param(np.arange(105, 305, 2), name="slow_window"), ... sl_stops, ... ) >>> best = best.unstack().set_axis(["sharpe", "sl_stop"], axis=1) >>> best.shape (10000, 2) >>> best.nlargest(3, "sharpe").round(3) sharpe sl_stop fast_window slow_window 2 107 1.612 0.011 119 1.603 0.023 117 1.594 0.050 ``` 1. Runs chunks of window pairs in threads. The compiled function releases the GIL, so the threads use every core. 2. Each call backtests 1,000 stop levels and returns only the best one, so 10,000,000 backtests leave 10,000 rows behind. The same sweep ran with `engine="threadpool"` and `engine="pathos"`, which sends chunks to separate processes. Measured on an Apple M3 with 8 cores, both found the same results: | Engine | Seconds | | ------------ | ------: | | `threadpool` | 330 | | `pathos` | 246 | The threaded run peaked at 802 MB of memory, and importing VBT and loading the data alone took 412 MB, so 10,000,000 backtests added about 390 MB: each worker holds one chunk of 1,000 backtests at a time, and only two numbers per window pair survive. Processes won here even though each worker started fresh and compiled the function itself. The faster engine depends on the workload, so time a small slice with each before a long run. ## Splitting work into chunks \[#splitting-work-into-chunks] Chunking splits the arguments of a function into pieces, calls the function on each piece, and merges the results. `@vbt.parameterized` chunks parameter combinations, `@vbt.chunked` chunks any array along any axis, and most compiled functions in VBT, including the simulators, come with chunking rules for every argument, so `chunked="threadpool"` on a portfolio method splits its columns without extra code, as the [Chunking](#chunking) highlight below shows. Chunks can nest: an outer loop over batches controls memory while an inner loop runs each batch in parallel. Choose the split around independent research tasks, such as parameter combinations or portfolios. The built-in simulation rules keep shared-cash groups together, and record merging adjusts column indexes so orders still belong to the right asset or strategy. This lets you keep full records when you need trade-level analysis, or reduce each chunk to metrics when you only need rankings. ## Execution engines \[#execution-engines] `vbt.execute` runs a list of tasks on one of several engines, chosen by name: | Engine | Runs tasks | Suited for | | -------------------------------- | -------------------------------- | ----------------------------------- | | `serial` | One after another | Debugging and bounding memory | | `threadpool` | In threads of one process | Compiled code that releases the GIL | | `pathos`, `processpool`, `mpire` | In separate processes | Python code that holds the GIL | | `dask` | In Dask threads or workers | Existing Dask setups | | `ray` | On a local or remote Ray cluster | Work larger than one machine | The execution framework provides shared controls for chunk sizes, progress bars, clearing caches or collecting garbage after each chunk, and hooks that run before and after each chunk. Keep worker functions and their dependencies available to the workers, for example by defining them in an importable module. Starting workers can involve importing VBT and compiling callbacks, so give each process many combinations, for example with `distribute="chunks"`, rather than one at a time. Pick one level of parallelism: Numba or Rust `parallel=True` inside tasks that already run in a thread pool or in Dask makes the threads compete for the same cores. See the [Multithreading](#multithreading) and [Multiprocessing](#multiprocessing) highlights below. ### From a laptop to a Ray cluster \[#from-a-laptop-to-a-ray-cluster] You can use the same parameterized function with a local engine or connect Ray to an existing cluster through `init_kwargs`. VBT submits the work through Ray, while Ray manages the cluster. Batch enough calculations into each task to make worker startup and data transfer worthwhile. This is useful for independent strategy trials, data-processing jobs, or validation runs that outgrow one machine. For repeated jobs, an existing `vbt.Executor` can be passed back to `vbt.execute` to reuse its configuration. Execution hooks also let you prepare shared resources or save summaries around chunks, so the same framework can handle a complete research pipeline. ## Reusing results \[#reusing-results] Portfolios, indicators, and records cache the results of their properties and methods, so `pf.stats()` computes trades or drawdowns once and reuses them. A central registry tracks every cache, reports hits, misses, and sizes, and clears them by object or class, as the [Caching](#caching) highlight below shows. For long jobs, `cache_chunks=True` saves each finished chunk to disk, so a restarted run can reuse matching completed chunks, as the [Chunk caching](#chunk-caching) highlight below shows. These serve different needs. Object caches speed up repeated analysis in the current process. Chunk caches preserve completed work across restarts. Numba's compilation cache reuses compiled code and is covered under [compute backends](/features/performance/compute-backends/#numba-compilation). You can inspect and clear selected object caches, or disable caching around a one-off calculation when keeping its results would only use more memory. ## Memory \[#memory] Start with a small batch, then choose chunk size and worker count together. Several workers each holding a chunk can use more memory than one serial worker. Returning only the metrics you need also keeps the final merged result small, as the ten-million-combination example demonstrates. * **Reduce inside the function:** return a metric or a summary instead of a portfolio, as the example above does. * **Limit records:** `max_order_records` and `max_log_records` size the record arrays a simulation allocates when you know how many orders a column can produce. * **Skip results:** returning `vbt.NoResult` from a function leaves that combination out of the merged result, and `skip_errored=True` does the same for combinations that raise an error. `raise_no_results=False` returns nothing instead of raising when every combination was skipped. * **Drop what you do not need:** `pf.replace(open=None, high=None, low=None)` keeps a stored portfolio from carrying three price arrays, at the cost of charts and trade statistics that read them, such as the maximum favorable and adverse excursion. * **Free memory between chunks:** `clear_cache` and `collect_garbage` in the execution options run after each chunk. For process-based jobs, clean up inside the worker that owns the memory. Engines such as Pathos also support recycling workers after a chosen number of tasks. !!! info "Tutorial" The members-only [Superfast SuperTrend](https://members.vectorbt.pro/tutorials/superfast-supertrend/) tutorial builds an indicator from pandas to Numba and then runs it across threads and chunks. ## Chunk caching \[#chunk-caching] New in v2024.5.15 ✅ Most workflows that use the VBT's execution framework, including data pulling, chunking, parameterization, splitting, and optimization, can now offload intermediate results to disk and reload them if the workflow crashes and restarts. You can confidently test billions of parameter combinations on cloud instances without worrying about losing your data. ```python title="Execute a basic range with random fallouts while caching successful attempts" >>> np.random.seed(42) >>> @vbt.parameterized(cache_chunks=True, chunk_len=1) # (1) ... def basic_iterator(i): ... print("i:", i) ... rand_number = np.random.uniform() ... if rand_number < 0.2: ... print("failed ⛔") ... raise ValueError ... return i >>> attempt = 0 >>> while True: ... attempt += 1 ... print("attempt", attempt) ... try: ... basic_iterator(vbt.Param(np.arange(10))) ... print("completed 🎉") ... break ... except ValueError: ... pass attempt 1 i: 0 i: 1 i: 2 i: 3 i: 4 failed ⛔ attempt 2 i: 4 failed ⛔ attempt 3 i: 4 failed ⛔ attempt 4 i: 4 i: 5 i: 6 i: 7 failed ⛔ attempt 5 i: 7 i: 8 i: 9 completed 🎉 ``` 1. Cache each function call. ## Chunking \[#chunking] New in 1.0.0 ✅ A new, innovative chunking mechanism lets you specify how arguments should be chunked. It automatically splits array-like arguments, passes each chunk to the function for execution, and then merges the results. This enables you to split large arrays and run any function in a distributed manner. VBT also features a central registry and provides chunking specifications for all arguments of most Numba-compiled functions, including simulation functions. Chunking can be enabled with a single command. Process a large search in smaller pieces that fit your available memory! 🎉 ```python title="Backtest at most 100 parameter combinations at once" >>> @vbt.chunked( ... chunk_len=100, ... merge_func="concat", # (1) ... execute_kwargs=dict( # (2) ... clear_cache=True, ... collect_garbage=True ... ) ... ) ... def backtest(data, fast_windows, slow_windows): # (3) ... fast_ma = vbt.MA.run(data.close, fast_windows, short_name="fast") ... slow_ma = vbt.MA.run(data.close, slow_windows, short_name="slow") ... entries = fast_ma.ma_crossed_above(slow_ma) ... exits = fast_ma.ma_crossed_below(slow_ma) ... pf = vbt.PF.from_signals(data.close, entries, exits) ... return pf.total_return >>> param_product = vbt.combine_params( # (4) ... dict( ... fast_window=vbt.Param(range(2, 100), condition="fast_window < slow_window"), ... slow_window=vbt.Param(range(2, 100)), ... ), ... build_index=False ... ) >>> backtest( ... vbt.YFData.pull(["BTC-USD", "ETH-USD"]), # (5) ... vbt.Chunked(param_product["fast_window"]), # (6) ... vbt.Chunked(param_product["slow_window"]) ... ) ``` 1. Concatenate the Series returned by each chunk into one Series. 2. Show a progress bar, and also clear cache and collect garbage after processing each chunk. 3. This function takes a data instance, as well as two parameter arrays: fast and slow window lengths. Both arrays will have the same number of values. For example, the first combination matches the first value in `fast_windows` with the first value in `slow_windows`. 4. Generate conditional parameter combinations. 5. Do not split the data into chunks. 6. Split both parameter arrays into chunks. Chunk 48/48: 100% ```text title="Output" fast_window slow_window symbol 2 3 BTC-USD 193.124482 ETH-USD 12.247315 4 BTC-USD 159.600953 ETH-USD 15.825041 5 BTC-USD 124.703676 ... 97 98 ETH-USD 3.947346 99 BTC-USD 25.551881 ETH-USD 3.442949 98 99 BTC-USD 27.943574 ETH-USD 3.540720 Name: total_return, Length: 9506, dtype: float64 ``` ## Multithreading \[#multithreading] New in 1.0.0 ✅ Integration of [ThreadPoolExecutor](https://docs.python.org/3/library/concurrent.futures.html#threadpoolexecutor) from `concurrent.futures`, [ThreadPool](https://pathos.readthedocs.io/en/latest/pathos.html#pathos.pools.ThreadPool) from `pathos`, and [Dask](https://dask.org/) backend for running multiple chunks across multiple threads. This is best for speeding up heavyweight functions that release the GIL, such as Numba and C functions. Multithreading + Chunking + Numba = 💪 ```python title="Benchmark 1000 random portfolios without and with multithreading" >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"]) >>> %timeit vbt.PF.from_random_signals(data.close, n=[100] * 1000, seed=42) 613 ms ± 37.2 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) >>> %timeit vbt.PF.from_random_signals(data.close, n=[100] * 1000, seed=42, chunked="threadpool") 294 ms ± 8.91 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) ``` ## Multiprocessing \[#multiprocessing] New in 1.0.0 ✅ Integration of [ProcessPoolExecutor](https://docs.python.org/3/library/concurrent.futures.html#processpoolexecutor) from `concurrent.futures`, [ProcessPool](https://pathos.readthedocs.io/en/latest/pathos.html#pathos.pools.ProcessPool) and [ParallelPool](https://pathos.readthedocs.io/en/latest/pathos.html#pathos.pools.ParallelPool) from `pathos`, [WorkerPool](https://sybrenjansen.github.io/mpire/usage/workerpool/index.html) from `mpire`, and [Ray](https://www.ray.io/) backend for running multiple chunks across multiple processes. This is best for speeding up heavyweight functions that do not release the GIL, such as regular Python functions, as well as lightweight arguments that are easy to serialize. Ever wanted to test billions of hyperparameter combinations across multiple machines? Scale functions and entire applications in the cloud using [Ray clusters](https://docs.ray.io/en/latest/cluster/getting-started.html) 👀 ```python title="Benchmark running a slow function on each column without and with multiprocessing" >>> @vbt.chunked( ... size=vbt.ArraySizer(arg_query="items", axis=1), ... arg_take_spec=dict( ... items=vbt.ArraySelector(axis=1) ... ), ... merge_func=np.column_stack ... ) ... def bubble_sort(items): ... items = items.copy() ... for i in range(len(items)): ... for j in range(len(items) - 1 - i): ... if items[j] > items[j + 1]: ... items[j], items[j + 1] = items[j + 1], items[j] ... return items >>> np.random.seed(42) >>> items = np.random.uniform(size=(1000, 3)) >>> %timeit bubble_sort(items) 456 ms ± 1.36 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) >>> %timeit bubble_sort(items, _execute_kwargs=dict(engine="pathos")) 165 ms ± 1.51 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) ``` ## Caching \[#caching] New in 1.0.0 ✅ Caching has been completely reimplemented and is now managed by a central registry. This enables tracking useful statistics for all cacheable parts of VBT, such as showing the total cached size in MB. You get full control and transparency 🪟 ```python title="Get the cache statistics after computing the statistics of a random portfolio" >>> data = vbt.YFData.pull("BTC-USD") >>> pf = vbt.PF.from_random_signals(data.close, n=5, seed=42) >>> _ = pf.stats() >>> pf.get_ca_setup().get_status_overview( ... filter_func=lambda setup: setup.caching_enabled, ... include=["hits", "misses", "total_size"] ... ) hits misses total_size object portfolio:0.drawdowns 0 1 70.9 kB portfolio:0.exit_trades 0 1 70.5 kB portfolio:0.filled_close 6 1 24.3 kB portfolio:0.init_cash 3 1 32 Bytes portfolio:0.init_position 0 1 32 Bytes portfolio:0.init_position_value 0 1 32 Bytes portfolio:0.init_value 5 1 32 Bytes portfolio:0.input_value 1 1 32 Bytes portfolio:0.orders 9 1 69.7 kB portfolio:0.total_profit 1 1 32 Bytes portfolio:0.trades 0 1 70.5 kB ``` # Cross-sectional strategies (/features/strategies/cross-sectional-strategies) How do you rank a universe and trade the best and worst names? This page backtests cross-sectional momentum rotation in Python: rank 37 ETFs every month by their past year's return, hold the leaders, and check the factor across quintiles on a universe whose members change over time. ```python title="Rotate monthly into the five ETFs with the strongest 12-1 momentum" >>> symbols = [ ... "XLB", "XLE", "XLF", "XLI", "XLK", "XLP", "XLU", "XLV", "XLY", "XLRE", "XLC", ... "EWA", "EWC", "EWG", "EWH", "EWJ", "EWU", "EWZ", "EWW", "EWY", "EWT", "EWS", ... "EWL", "EWQ", "EWP", "EWI", "EWD", "EWN", "FXI", "INDA", "EIDO", ... "TLT", "IEF", "GLD", "SLV", "DBC", "VNQ", ... ] >>> close = vbt.YFData.pull(symbols, start="2007-01-01", end="2025-01-01").close >>> month = pd.Series(close.index.month, index=close.index) >>> dates = close.index[month != month.shift(-1)] # (1) >>> momentum = (close.shift(21) / close.shift(252) - 1).loc[dates] # (2) >>> top = momentum.rank(axis=1, ascending=False) <= 5 >>> eligible = momentum.notna() # (3) >>> def simulate(weights): ... return vbt.PF.from_orders( ... close, ... size=weights.loc["2008":].reindex(close.index), # (4) ... size_type="targetpercent", ... group_by=True, ... cash_sharing=True, ... call_seq="auto", ... fees=0.001, ... ) >>> pfs = { ... "Top 5 momentum": simulate(top.div(top.sum(axis=1), axis=0)), ... "Equal weight": simulate(eligible.div(eligible.sum(axis=1), axis=0)), ... } >>> metrics = ["total_return", "sharpe_ratio", "max_dd"] >>> pd.DataFrame({k: pf.stats(metrics) for k, pf in pfs.items()}).astype(float).round(2) Top 5 momentum Equal weight Total Return [%] 84.61 152.43 Sharpe Ratio 0.35 0.45 Max Drawdown [%] 37.41 51.90 ``` 1. The last trading day of each month. 2. The return from twelve months ago to one month ago. Skipping the latest month avoids its short-term reversals, and every value is known before the rebalancing day. 3. An ETF becomes eligible once it has a year of history. XLRE launched in 2015 and XLC in 2018, so the universe grows from 33 to 37 funds. 4. Weights apply on the rebalancing days only. Between them, the holdings drift with prices. Over 2008 to 2024, the five strongest ETFs each month returned 85% against 152% for holding every eligible ETF equally, with a smaller drawdown. Momentum lowered risk here but did not add return. The same workflow accepts your own scores: technical indicators, fundamental factors, or model predictions. Supply a table of scores by date and symbol, choose how many names to hold, and compare the resulting portfolios. Momentum is one example. ## Ranking and selection \[#ranking-and-selection] Ranking is a pandas operation on a table with one column per symbol, so `rank(axis=1)` ranks every date at once and `rank <= 5` selects the leaders. Symbols without data on a date get NaN and drop out of the ranking. The selection becomes weights, which `vbt.PF.from_orders` trades as target percentages with shared cash, as above, or signals for `vbt.PF.from_signals`. The [Portfolio optimization](/features/optimization/portfolio-optimization/) page computes the same weights with `vbt.PFO.from_allocate_func` on any schedule. Negative weights short a name, so a long-short book is the leaders' weights minus the laggards'. For thousands of symbols, split the score table by time, rank each period, and join the results with `split_apply`. Each period keeps the full universe, so a stock is still ranked against all its peers while the intermediate ranking tables use less memory. A ranking table works when the whole selection is known before the bar. When entries come from each symbol's own signals and the limit depends on what is already held, such as at most five open positions, the decision needs the portfolio's state, as in the [Event-driven backtesting](/features/backtesting/event-driven-backtesting/#stateful-trading-rules) page. ## Factor research \[#factor-research] A factor works if its ranks sort future returns, so split the universe into quintiles by rank and compare them. Each quintile is a group of columns in one portfolio: ```python title="Backtest the five momentum quintiles in one simulation" >>> quintile = np.ceil(momentum.rank(axis=1, pct=True) * 5) >>> members = {q: quintile == q for q in range(1, 6)} >>> q_weights = pd.concat( ... {q: m.div(m.sum(axis=1), axis=0) for q, m in members.items()}, ... axis=1, ... names=["quintile"], ... ) >>> q_close = pd.concat({q: close for q in range(1, 6)}, axis=1, names=["quintile"]) >>> q_pf = vbt.PF.from_orders( ... q_close, ... size=q_weights.loc["2008":].reindex(close.index), ... size_type="targetpercent", ... group_by="quintile", # (1) ... cash_sharing=True, ... call_seq="auto", ... fees=0.001, ... ) >>> q_pf.stats(metrics, agg_func=None).astype(float).round(2) Total Return [%] Sharpe Ratio Max Drawdown [%] quintile 1 132.68 0.38 57.79 2 67.94 0.29 55.03 3 100.37 0.36 58.13 4 136.40 0.42 51.06 5 118.17 0.42 40.87 ``` 1. Five portfolios of 37 columns each, one per quintile, each with its own cash. Value of five ETF portfolios formed by monthly 12-1 momentum quintile from 2008 to 2024. [Figure data (JSON)](/assets/figures/features/strategies/momentum-quintiles.fc5d3c32b26b.json) A working factor would show returns rising steadily from quintile 1, the weakest momentum, to quintile 5, the strongest. Here the returns did not line up, and only the drawdown fell with higher momentum. The rank information coefficient, the correlation between each month's ranks and the next month's returns, puts a number on it: ```python title="Measure the rank information coefficient of momentum" >>> fwd = close.loc[dates].pct_change().shift(-1) # (1) >>> ic = momentum.corrwith(fwd, axis=1, method="spearman").loc["2008":].dropna() >>> t_stat = ic.mean() / ic.std() * np.sqrt(ic.count()) >>> print(round(ic.mean(), 3), round(t_stat, 2), round((ic > 0).mean(), 2)) 0.006 0.29 0.52 ``` 1. Each ETF's return over the month after each rebalancing day. An average IC of 0.006, positive in 52% of months, is indistinguishable from zero. A long-short book that buys quintile 5 and shorts quintile 1, half the capital on each side, lost about a quarter of its value over the same period. VBT has no built-in factor tear sheet like Alphalens, but the ranks, forward returns, and quintile portfolios are ordinary tables, so each statistic is a line of pandas. To test a factor on its own, remove its exposure to other characteristics first: regress it on them within each date and keep the residual, or subtract the average within each group, such as a sector. Indicator expressions provide `cs_rank`, `cs_demean`, and `cs_rescale` for ranking, group demeaning, and rescaling. `cs_rank` produces percentile ranks, which are useful when the number of eligible symbols changes. These functions also power the WorldQuant 101 Alphas on the [Technical indicators](/features/indicators/technical-indicators/) page. ## Changing universes \[#changing-universes] Symbols that join or leave a universe stay in the table for the whole period, with NaN before they join and after they leave, so the asset axis never changes and every simulation stays vectorized. Momentum here also requires a year of history, which excludes new ETFs until they qualify. For stock indexes, a point-in-time membership table masks each stock outside its membership dates, which avoids testing only on today's survivors, as the [Realistic backtests](/features/backtesting/backtest-realism/#point-in-time-universes) page explains. A strategy that holds one symbol at a time can also stitch the chosen symbols' prices into a single series, closing the position at each switch. ### Rank only eligible assets \[#rank-only-eligible-assets] Eligibility can combine index membership, enough price history, and your own liquidity filters. Apply it before ranking so an unavailable asset cannot take a place in the selection. Here are made-up scores for three assets on four rebalancing dates: ```python title="Select up to two eligible assets and turn the rankings into allocations" >>> dates = pd.to_datetime(["2025-01-31", "2025-02-28", "2025-03-31", "2025-04-30"]) >>> scores = pd.DataFrame( ... {"A": [8, 9, 7, 8], "B": [6, 5, 8, 9], "C": [4, 10, 9, 7]}, ... index=dates, ... ) >>> eligible = pd.DataFrame( ... {"A": [True, False, False, False], "B": [True, True, False, False], "C": [True, True, True, False]}, ... index=dates, ... ) >>> ranks = scores.where(eligible).rank(axis=1, ascending=False, method="first") >>> selected = ranks <= 2 >>> weights = selected.div(selected.sum(axis=1).replace(0, np.nan), axis=0).fillna(0.0) >>> pfo = vbt.PFO.from_allocations(scores.vbt.wrapper, weights) >>> pfo.allocations A B C 2025-01-31 0.5 0.5 0.0 2025-02-28 0.0 0.5 0.5 2025-03-31 0.0 0.0 1.0 2025-04-30 0.0 0.0 0.0 ``` A drops out in February even though its score beats B's. In March, C is the only eligible asset and gets the full target allocation. April has no eligible assets, so the target is all cash. Ties go to the earlier column with `method="first"`. The allocation table can then be simulated against prices with fees and slippage, as shown on the [Portfolio optimization](/features/optimization/portfolio-optimization/#backtest-your-own-weights) page. ## Compare rotation rules \[#compare-rotation-rules] Does the result depend on holding five names, using a one-year lookback, or rebalancing monthly? Wrap the score, selection, and simulation steps in a function and use [Parameter optimization](/features/optimization/strategy-optimization/) to compare those choices. Keep an equal-weight portfolio alongside the ranked portfolios, as in the opening example, to see what the selection adds over holding the universe. Take a factor from rank IC to a traded portfolio. Compare performance after costs, then inspect its [orders](/features/backtesting/orders-and-execution/) to see how often positions change and how much the rotation costs. The quintile portfolios help separate a factor that sorts returns across the universe from one whose result depends on a few top names. !!! info "Tutorial" The members-only [Portfolio optimization](https://members.vectorbt.pro/tutorials/portfolio-optimization/) tutorial allocates across a universe with custom functions and optimizer libraries. # Strategies (/features/strategies) Build pairs trades, rank a universe, or combine several strategies into one portfolio. These worked examples bring VBT's data, indicators, signals, and analytics together on real market data, with code and plots you can adapt to your own ideas. ## Choose a strategy workflow \[#choose-a-strategy-workflow] | What do you want to research? | Where to start | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Trade the spread between two related assets | [Pairs trading](/features/strategies/pairs-trading/) covers pair selection, rolling hedge ratios, spread signals, and two-leg backtests. | | Rank a universe and rotate into selected assets | [Cross-sectional strategies](/features/strategies/cross-sectional-strategies/) covers momentum, custom factor scores, quintile portfolios, and changing eligibility. | | Allocate between several trading strategies | [Multi-strategy portfolios](/features/strategies/multi-strategy-portfolios/) compares static weights, scheduled rebalancing, and shared trading cash. | | Compare regular contributions with investing at once | [Recurring investing](/features/strategies/multi-strategy-portfolios/#recurring-investing-and-dollar-cost-averaging) backtests monthly deposits against a lump sum. | * [Pairs trading](/features/strategies/pairs-trading): Screen cointegrated pairs, trade spread z-scores with shared cash, and validate them * [Cross-sectional strategies](/features/strategies/cross-sectional-strategies): Rank a universe each period, rotate into the leaders, and test factors by quintile * [Multi-strategy portfolios](/features/strategies/multi-strategy-portfolios): Stack strategies as one portfolio, weight them, and compare recurring investing plans ## Build on the examples \[#build-on-the-examples] The examples use Python functions, pandas tables, and VBT portfolios, so you can replace their symbols, scores, signals, and allocation rules with your own. Use [signal backtesting](/features/backtesting/signal-backtesting/) when you have entry and exit arrays, or [event-driven backtesting](/features/backtesting/event-driven-backtesting/) when a decision depends on the positions and cash already in the portfolio. The same research tools work across these strategy families. Compare lookbacks, thresholds, and position sizes with [parameter optimization](/features/optimization/strategy-optimization/), then check the selected settings on later data with [walk-forward testing](/features/optimization/time-series-cross-validation/). Inspect [trades](/features/analytics/trade-analytics/) and [drawdowns](/features/analytics/drawdown-analysis/) to understand what drives the result. Compare each idea with a baseline, inspect its trades, and see the effect of costs and allocation rules. The examples give you a complete starting point for the next experiment. ## Start here \[#start-here] Follow the [Pairs trading tutorial](/tutorials/pairs-trading/) to build a pairs strategy from screening to a custom simulator. For a first signals-based example, the [Basic RSI tutorial](/tutorials/basic-rsi/) goes from indicator values to a backtest. The [Portfolio optimization tutorial](/tutorials/portfolio-optimization/) develops allocation functions and connects them to portfolio simulation. # Multi-strategy portfolios (/features/strategies/multi-strategy-portfolios) How do you combine trading strategies and allocate between them? In VBT, each strategy's portfolio can be treated as an asset: stack the strategies as columns, then weight them equally or by an optimizer and rebalance on a schedule, with fees, in one more backtest. ```python title="Combine a trend and a mean-reversion strategy, equally and by inverse volatility" >>> spy = vbt.YFData.pull("SPY", start="2010-01-01", end="2025-01-01") >>> fast = spy.close.vbt.rolling_mean(50) >>> slow = spy.close.vbt.rolling_mean(200) >>> trend = vbt.PF.from_signals(spy, fast > slow, fast < slow, fees=0.001) >>> rsi = vbt.RSI.run(spy.close, window=2).rsi >>> reversion = vbt.PF.from_signals(spy, rsi < 10, rsi > 70, fees=0.001) >>> strategies = pd.concat( # (1) ... {"trend": trend.value, "reversion": reversion.value}, axis=1 ... ) >>> returns = vbt.RepEval( ... "strategies.pct_change().iloc[index_slice]", context=dict(strategies=strategies) ... ) >>> def inverse_vol(returns): ... inv = 1 / returns.std() ... return inv / inv.sum() >>> wrapper = vbt.ArrayWrapper.from_obj(strategies) >>> fifty = vbt.PFO.from_uniform(wrapper, every="M") # (2) >>> inv_vol = vbt.PFO.from_optimize_func( ... wrapper, inverse_vol, returns, every="M", lookback_period="63D" ... ) >>> period = slice("2010-05", None) # (3) >>> pfs = { ... "Trend": trend, ... "Mean reversion": reversion, ... "50/50 monthly": fifty.simulate(strategies, fees=0.001), ... "Inverse volatility": inv_vol.simulate(strategies, fees=0.001), ... } >>> metrics = ["total_return", "sharpe_ratio", "max_dd"] >>> stats = {k: pf.loc[period].stats(metrics) for k, pf in pfs.items()} >>> pd.DataFrame(stats).astype(float).round(2) Trend Mean reversion 50/50 monthly Inverse volatility Total Return [%] 285.49 51.41 145.83 86.76 Sharpe Ratio 0.89 0.39 0.74 0.57 Max Drawdown [%] 33.72 31.79 27.95 28.11 ``` 1. The value of each strategy's portfolio becomes the price of a synthetic asset. 2. Each month, the allocation resets the two strategies to half of the combined value each. 3. Compares every portfolio from May 2010, after the first inverse-volatility allocation. Growth of a trend strategy, a mean-reversion strategy, and two combinations of both on SPY from 2010 to 2024. [Figure data (JSON)](/assets/figures/features/strategies/multi-strategy-value.561b3ace1ecb.json) Combining the two strategies lowered the drawdown below that of either one, but it did not beat the trend strategy on return or Sharpe ratio, since the strategies were 62% correlated and both held SPY. Inverse volatility did worse than equal weights: the mean-reversion strategy spends most days in cash, looks less volatile, and so received more capital despite earning less. Combinations help most when strategies trade different markets or behave differently. ## Choose how strategies work together \[#choose-how-strategies-work-together] You can combine different entry rules, parameter sets, or markets. The choice is how their capital should interact: | What you want to test | How to combine the strategies | | -------------------------------------------------------------- | -------------------------------------------------------------------- | | Give each strategy a fixed starting allocation and let it grow | Stack finished portfolios and apply static weights. | | Move capital between strategies on a schedule | Treat their portfolio values as prices and backtest the allocations. | | Let strategies compete for the same cash as they trade | Simulate their orders together in one cash-sharing group. | ## Strategies as columns \[#strategies-as-columns] Strategies with the same index are columns of one portfolio. They can use different simulation methods, such as signals for one and explicit orders for another, and still be analyzed together. `vbt.PF.column_stack` joins finished portfolios, and `group_by=True` treats them as one account that never rebalances, so each strategy keeps the capital it started with and grows or shrinks with its own results. `apply_weights` scales each strategy's capital, orders, and cash flows by a fixed weight without simulating again: ```python title="Hold the two strategies without rebalancing" >>> combined = vbt.PF.column_stack( ... [trend, reversion], wrapper_kwargs=dict(group_by=True) ... ) >>> static = { ... "50/50 static": combined, ... "70/30 static": combined.apply_weights([0.7, 0.3], rescale=True), # (1) ... } >>> stats.update({k: pf.loc[period].stats(metrics) for k, pf in static.items()}) >>> pd.DataFrame(stats).iloc[:, 2:].astype(float).round(2) 50/50 monthly Inverse volatility 50/50 static 70/30 static Total Return [%] 145.83 86.76 166.90 213.95 Sharpe Ratio 0.74 0.57 0.77 0.83 Max Drawdown [%] 27.95 28.11 29.88 31.70 ``` 1. `rescale=True` keeps the total capital: weights of 0.7 and 0.3 become multipliers of 1.4 and 0.6. Left alone, the 50/50 mix drifted toward the trend strategy as it outgrew mean reversion, which earned more than rebalancing monthly back to half each, with a slightly deeper drawdown. Weights apply per strategy for the whole period, not per bar. To rebalance between strategies, use their values as prices for a portfolio optimizer, as in the first example. Every allocation method on the [Portfolio optimization](/features/optimization/portfolio-optimization/) page applies, from fixed weights to PyPortfolioOpt and Riskfolio-Lib, and the fees of rebalancing are charged on the strategy level. ### Share cash while strategies trade \[#share-cash-while-strategies-trade] When strategies must draw from one cash balance, put their strategy and asset columns in the same simulation group with `group_by=True` and `cash_sharing=True`. Separate groups give each group its own cash. The [Portfolio accounting](/features/backtesting/portfolio-accounting/) page shows how cash, positions, and value are tracked. This lets one strategy use cash released by another. Position sizes and the order sequence decide how that cash is used when several signals arrive together. For rules that depend on current holdings, such as a limit on total open positions, use the callbacks described in [Event-driven backtesting](/features/backtesting/event-driven-backtesting/#stateful-trading-rules). ## Inspect the mix and its components \[#inspect-the-mix-and-its-components] Stacking keeps the original order records, so you can inspect a strategy's trades as well as the combined return and drawdown. Give the stacked portfolios strategy names to select them later, including when several trade the same symbol. Compare their return series and correlations to see whether another strategy adds different behavior or mostly repeats an existing one. The rebalanced example has two levels of results: the original trend and mean-reversion portfolios contain their SPY trades, while the combined portfolio records allocations between those strategies. Keep both to connect the combined performance to the underlying trades. The [Trade analytics](/features/analytics/trade-analytics/) page covers winners, losers, and holding periods. Compare candidate weights and rebalance schedules over several periods, including periods held out from fitting the allocation. [Walk-forward optimization](/features/optimization/time-series-cross-validation/) applies that process to rolling training and test windows. ## Recurring investing and dollar-cost averaging \[#recurring-investing-and-dollar-cost-averaging] Cash deposits model saving on a schedule. Depositing $100 at the start of each month and buying with it compares to investing the same total at once: ```python title="Invest $100 every month, or $12,000 at the start" >>> close = spy.close.loc["2015":"2024"] >>> month = pd.Series(close.index.month, index=close.index) >>> first_days = month != month.shift(1) >>> deposits = pd.Series(np.where(first_days, 100.0, 0.0), index=close.index) >>> dca = vbt.PF.from_orders( ... close, ... size=np.where(first_days, np.inf, np.nan), # (1) ... init_cash=0, ... cash_deposits=deposits, ... ) >>> lump = vbt.PF.from_orders( ... close, ... size=np.where(np.arange(len(close)) == 0, np.inf, np.nan), ... init_cash=deposits.sum(), ... ) >>> print(deposits.sum(), round(dca.final_value, 2), round(lump.final_value, 2)) 12000.0 25724.02 40748.85 ``` 1. Buys with all available cash on each deposit day and does nothing on other days. In a market that rose for most of the decade, investing everything at once ended with 58% more. Monthly deposits buy at many prices, which smooths the entry, but leave most of the money uninvested for years. The same deposits work with any strategy, so a rule such as buying more after drawdowns can be tested against plain monthly buying. Deposits can also fund a portfolio optimizer's scheduled allocations, so recurring contributions and rebalancing can be tested together. Use portfolio returns to compare strategy performance alongside final account values. VBT's return calculation accounts for cash deposits and withdrawals, so adding money is not counted as a trading gain. [Portfolio accounting](/features/backtesting/portfolio-accounting/#cash-deposits) covers the cash-flow side of the comparison. !!! info "Tutorial" The members-only [Portfolio optimization](https://members.vectorbt.pro/tutorials/portfolio-optimization/) tutorial builds allocation and optimization functions, including allocations that react to the simulated portfolio. # Pairs trading (/features/strategies/pairs-trading) How do you find, trade, and validate pairs? This pairs trading backtest in Python screens 105 crypto pairs for cointegration, trades the ten strongest on the z-score of a rolling regression spread, and then checks whether the relationship held while it was being traded. VBT gives you the parts to build your own statistical arbitrage workflow: rolling regression, threshold signals, long and short positions, shared cash, and parameter comparisons. You choose the pair-selection rule, spread model, sizing, and exits. ```python title="Screen 105 pairs for cointegration on two years of data" >>> from itertools import combinations >>> import statsmodels.tsa.stattools as ts >>> symbols = [ ... "BTCUSDT", "ETHUSDT", "BNBUSDT", "XRPUSDT", "ADAUSDT", "SOLUSDT", "DOGEUSDT", ... "LTCUSDT", "LINKUSDT", "DOTUSDT", "TRXUSDT", "BCHUSDT", "XLMUSDT", "ETCUSDT", ... "ATOMUSDT", ... ] >>> data = vbt.BinanceData.pull(symbols, start="2021-01-01", end="2025-01-01") >>> log_close = np.log(data.close) >>> select = log_close.loc["2021":"2022"] # (1) >>> pairs = list(combinations(symbols, 2)) # (2) >>> pvalues = pd.Series( ... {(s1, s2): ts.coint(select[s1], select[s2])[1] for s1, s2 in pairs}, ... name="pvalue", ... ).rename_axis(["s1", "s2"]) >>> top = pvalues.nsmallest(10) >>> top.round(4) s1 s2 LINKUSDT XLMUSDT 0.0003 BCHUSDT XLMUSDT 0.0005 BNBUSDT BCHUSDT 0.0005 XLMUSDT 0.0006 DOTUSDT 0.0007 LTCUSDT 0.0007 ATOMUSDT 0.0007 ADAUSDT BCHUSDT 0.0009 BNBUSDT LINKUSDT 0.0012 ETCUSDT 0.0012 Name: pvalue, dtype: float64 ``` 1. Pairs are chosen on 2021 and 2022 only. Trading starts in 2023, on data the screen never saw. 2. Each unordered pair once: 15 symbols give 105 pairs. All ten pairs pass the Engle-Granger test with p-values near 0.001. Each pair is then traded as a group of two columns that share one cash balance: ```python title="Trade every pair on z-score thresholds with shared cash" >>> y = pd.concat({p: data.close[p[0]] for p in top.index}, axis=1, names=["s1", "s2"]) >>> x = pd.concat({p: data.close[p[1]] for p in top.index}, axis=1, names=["s1", "s2"]) >>> zscore = vbt.OLS.run(np.log(x), np.log(y), window=60, hide_params=True).zscore # (1) >>> def legs(y_signal, x_signal): # (2) ... both = pd.concat({"y": y_signal, "x": x_signal}, axis=1, names=["leg"]) ... return both.reorder_levels(["s1", "s2", "leg"], axis=1).sort_index(axis=1) >>> def trade_pairs(period, threshold): ... z = zscore.loc[period] ... wide = z.vbt.crossed_above(threshold) # (3) ... narrow = z.vbt.crossed_below(-threshold) ... revert = z.vbt.crossed_above(0) | z.vbt.crossed_below(0) ... return vbt.PF.from_signals( ... legs(y.loc[period], x.loc[period]), ... long_entries=legs(narrow, wide), ... short_entries=legs(wide, narrow), ... long_exits=legs(revert, revert), ... short_exits=legs(revert, revert), ... size=0.5, ... size_type="valuepercent", # (4) ... fees=0.001, ... group_by=["s1", "s2"], ... cash_sharing=True, ... call_seq="auto", ... ) >>> pf = trade_pairs("2023", 2.0) >>> metrics = ["total_return", "sharpe_ratio", "max_dd", "total_trades"] >>> pf.stats(metrics, agg_func=None).round(2) Total Return [%] Sharpe Ratio Max Drawdown [%] Total Trades s1 s2 ADAUSDT BCHUSDT -90.43 -1.73 94.77 12 BCHUSDT XLMUSDT -35.72 0.28 74.99 10 BNBUSDT ATOMUSDT -2.12 -0.05 13.81 12 BCHUSDT -55.64 -1.56 61.99 12 DOTUSDT -11.63 -0.57 23.42 16 ETCUSDT 9.38 0.58 10.82 16 LINKUSDT 7.50 0.40 20.72 12 LTCUSDT -16.03 -0.53 30.92 12 XLMUSDT 3.72 0.30 15.77 16 LINKUSDT XLMUSDT -18.92 -0.76 33.01 18 ``` 1. A 60-day rolling regression of one log price on the other gives the hedge ratio and the z-score of the spread, using current and earlier observations. 2. Builds one column per leg, ordered so that both legs of a pair sit next to each other. 3. When the spread is unusually wide, short the first asset and buy the second. When it is unusually narrow, do the opposite. Exit both legs when the spread returns to its mean. 4. Each leg takes half of the pair's current value, and selling runs before buying within a bar. The side-by-side results separate the three profitable pairs from the rest, including two that lost more than half their capital. Now inspect how the selected relationships changed: ```python title="Test the same pairs for cointegration while they were traded" >>> later = log_close.loc["2023":"2024"] >>> still = pd.Series( ... {(s1, s2): ts.coint(later[s1], later[s2])[1] for s1, s2 in top.index} ... ) >>> pd.DataFrame({"2021-2022": top, "2023-2024": still}).round(3) 2021-2022 2023-2024 LINKUSDT XLMUSDT 0.000 0.712 BCHUSDT XLMUSDT 0.001 0.594 BNBUSDT BCHUSDT 0.001 0.864 XLMUSDT 0.001 0.925 DOTUSDT 0.001 0.964 LTCUSDT 0.001 0.963 ATOMUSDT 0.001 0.826 ADAUSDT BCHUSDT 0.001 0.175 BNBUSDT LINKUSDT 0.001 0.902 ETCUSDT 0.001 0.825 ``` The later test finds that none of the ten pairs retained significance at the 5% level. VBT brings the screen, rolling model, and trade results into one workflow, so you can investigate changing relationships and compare new selection rules or exits. ## Finding pairs \[#finding-pairs] Cointegration matters more than correlation: two correlated assets can drift apart for good, while a cointegrated pair has a spread that returns to its mean. The [Engle-Granger test from statsmodels](https://www.statsmodels.org/stable/generated/statsmodels.tsa.stattools.coint.html) regresses one price on the other and tests the residual for stationarity. Testing every pair of a large universe increases the chance of false positives. At a 5% significance level, some pairs with no cointegrating relationship will pass by chance. Choose pairs on one period and trade them on a later one, as above. The test is not symmetric. It regresses the first price on the second, so swapping the two gives a somewhat different p-value and hedge ratio. Testing each unordered pair once halves the work, at the cost of ignoring the other direction. For a larger universe, `@vbt.parameterized` can run the test over all pairs in parallel threads, and `vbt.Param` with a condition such as `"s1 < s2"` builds each unordered pair once. The cointegration test itself comes from `statsmodels` and runs in plain Python, so a rolling cointegration test over many pairs and windows is slow. Only the rolling regression is compiled. See the [Parameter optimization](/features/optimization/strategy-optimization/) page. ## Spread signals \[#spread-signals] You can inspect the rolling model as well as its trades. `vbt.OLS` exposes the slope, intercept, predicted value, residual, z-score, and R-squared. Its regression and z-score normalization windows can be set separately, so you can compare how quickly the model and its entry thresholds adapt. See [Rolling OLS](/features/indicators/technical-indicators/#rolling-ols). The strategy can also use a spread you calculate yourself in pandas or another model. Convert that spread into boolean entry and exit arrays and pass them to the same simulator. For example, compare exiting at zero with exiting inside a narrower band, using the crossing helpers on the [Trading signals](/features/indicators/trading-signals/) page. The rolling regression from `vbt.OLS` gives the hedge ratio, the spread, and its z-score, and `zscore_crossed_above` and `zscore_crossed_below` turn thresholds into signals. Both legs of a pair go into one group with shared cash, so an entry sells one asset and buys the other with the same capital, and `call_seq="auto"` places the sell first. Because every pair is two columns of one portfolio, ten or a thousand pairs run in one simulation, and a symbol can appear in several pairs. The legs above are dollar-neutral: each takes half of the pair's value, and the hedge ratio only shapes the spread and its z-score. To size the legs by the hedge ratio instead, pass a `size` array per leg built from the regression's `slope` output. On these pairs, the 60-day slope ranged from -1.5 to 4.1 during 2023, so hedge-ratio sizing would also swing between legs from one trade to the next. ## Inspect each pair and each leg \[#inspect-each-pair-and-each-leg] The example gives each pair its own cash pool, shared by its two legs. That lets you compare pairs independently, even when the same asset appears in several pairs. Pair labels keep those positions separate in the results. For strategies that compete for one account's capital, configure the shared group around that account, as explained in [Portfolio accounting](/features/backtesting/portfolio-accounting/). A pair's combined return can hide very different results on its long and short legs. Inspect [orders and fills](/features/backtesting/orders-and-execution/), [trade records](/features/analytics/trade-analytics/), and `pf.get_allocations()` to see how the positions were entered, exited, and sized. Fees and slippage can be set per asset, so you can test what happens when one leg costs more to trade than the other. ## Validate pair selection and trading rules \[#validate-pair-selection-and-trading-rules] The thresholds, the regression window, and the exit rule are parameters, which the next step tests out of sample: ```python title="Choose the threshold on 2023, then test it on 2024" >>> thresholds = [1.5, 2.0, 2.5] >>> in_sample = {t: trade_pairs("2023", t).sharpe_ratio.mean() for t in thresholds} >>> best = max(in_sample, key=in_sample.get) >>> print(best, round(in_sample[best], 2)) 2.5 -0.34 >>> out_pf = trade_pairs("2024", best) >>> print(round(out_pf.sharpe_ratio.mean(), 2), (out_pf.sharpe_ratio > 0).mean()) 0.05 0.3 ``` The least bad threshold in 2023 also did best in 2024, but three pairs in ten were profitable and the average Sharpe ratio was close to zero. For more windows and a rolling selection of pairs, use the splitters on the [Walk-forward and cross-validation](/features/optimization/time-series-cross-validation/) page. !!! info "Tutorial" The members-only [Pairs trading](https://members.vectorbt.pro/tutorials/pairs-trading/) tutorial screens a larger universe and builds the same strategy with indicators, Numba, and a custom simulator. # Configuration and persistence (/features/tooling/configuration-and-persistence) How do you save research state and make it reproducible? VBT can save any of its objects, from data to a 10,000-column portfolio, to one file with optional compression, reload it for analysis, and keep settings in configuration files instead of scattered through code. ```python title="Save a 10,000-column portfolio with four compression settings and reload it" >>> import time >>> from itertools import product >>> data = vbt.YFData.pull("BTC-USD", start="2020-01-01", end="2025-01-01") >>> pairs = list(product(range(2, 102), range(105, 305, 2))) >>> fast = vbt.MA.run(data.close, window=[f for f, _ in pairs], short_name="fast") >>> slow = vbt.MA.run(data.close, window=[s for _, s in pairs], short_name="slow") >>> entries = fast.ma_crossed_above(slow) >>> exits = fast.ma_crossed_below(slow) >>> pf = vbt.PF.from_signals(data, entries, exits, fees=0.001) >>> rows = {} >>> for compression in [None, "blosc2", "gzip", "lzma"]: ... start = time.perf_counter() ... path = pf.save("sweep", compression=compression) # (1) ... save_s = time.perf_counter() - start ... start = time.perf_counter() ... loaded = vbt.PF.load(path) ... load_s = time.perf_counter() - start ... rows[str(compression)] = dict( ... file=str(path), ... size=vbt.file_size(path), ... save_s=round(save_s, 2), ... load_s=round(load_s, 2), ... ) >>> pd.DataFrame(rows).T file size save_s load_s None sweep.pickle 11.7 MB 0.01 0.0 blosc2 sweep.pickle.blosc2 2.2 MB 0.06 0.09 gzip sweep.pickle.gzip 1.9 MB 1.15 0.01 lzma sweep.pickle.lzma 1.0 MB 1.93 0.06 >>> loaded.wrapper.shape, np.allclose(loaded.total_return, pf.total_return) ((1827, 10000), True) ``` 1. The compression name becomes the file extension, so `vbt.PF.load` and `vbt.load` detect it when reading the file back. Every file reloads as a full portfolio with all 10,000 strategies, ready for metrics and charts. Measured on an Apple M3, blosc2 cut the file to a fifth of its size and still saved and loaded in under 0.1 seconds. lzma made the smallest file but took about two seconds to write. ## Saving and loading \[#saving-and-loading] Every VBT object, including data, indicators, portfolios, and splitters, has `save` and `load`, and `vbt.save` and `vbt.load` handle any Python object, such as a dictionary of portfolios. Only an object's state is saved, not its class, so files load with the current version of VBT, and renamed or moved classes can be mapped to their new names when loading older files. VBT includes reconstruction hooks for loading older objects when class arguments change. Use matching package versions when moving an experiment between machines, or register a state conversion when an older object needs it. * **Compression:** zip, gzip, bz2, and lzma, plus lz4, blosc, and blosc2 when installed. * **Formats:** pickle by default, or readable `.cfg`, `.yaml`, and `.toml` files with `file_format`, which round-trip back to the same object. * **Containers:** `vbt.pdict` is a dictionary that saves and loads like any VBT object. * **Data updates:** `vbt.CSVDataSaver`, `vbt.HDFDataSaver`, and `vbt.DuckDBDataSaver` keep a dataset current on disk, as the [Data storage](/features/data/data-storage-and-databases/) page shows. ### Keep an experiment together \[#keep-an-experiment-together] Save the inputs, parameters, and result in one dictionary so reopening a backtest also tells you what produced it. The objects keep their own shapes and labels, so prices and parameterized indicator outputs can sit together without being forced into one table: ```python title="Save prices, settings, and a portfolio in one research bundle" >>> import os >>> import tempfile >>> close = pd.Series([100.0, 105.0, 103.0], index=pd.date_range("2025-01-01", periods=3)) >>> parameters = dict(fees=0.001, init_cash=1000) >>> pf = vbt.PF.from_holding(close, **parameters) >>> research = vbt.pdict(close=close, parameters=parameters, portfolio=pf, version=vbt.__version__) >>> with tempfile.TemporaryDirectory() as directory: ... path = research.save(os.path.join(directory, "research"), compression="gzip") ... restored = vbt.pdict.load(path) >>> print(list(restored)) ['close', 'parameters', 'portfolio', 'version'] >>> print(restored["parameters"]) {'fees': 0.001, 'init_cash': 1000} >>> print(restored["close"].equals(close), np.isclose(restored["portfolio"].total_return, pf.total_return)) True True ``` The temporary directory keeps this example self-contained. Use a project path to keep the file between sessions. Add indicator outputs, signals, or your own notes to the same dictionary, then load the portfolio for new charts and metrics without repeating the backtest. ### Restart data updates \[#restart-data-updates] A saved research object and a growing market-data store serve different purposes. To restart a data-saving job, load the stored data, create a new saver around it, and resume scheduled updates with `init_save=False`. This continues the save cycle without writing the initial dataset again. [Data storage](/features/data/data-storage-and-databases/) covers the storage choices, and [Workflow automation](/features/tooling/workflow-automation/) covers scheduling. ## Settings \[#settings] `vbt.settings` holds the defaults of the whole package, grouped by area, such as `vbt.settings.portfolio["fees"]` or `vbt.settings.plotting["default_theme"]`. Change a value once and later calls that use that default pick it up. Explicit call arguments let you override it for one experiment. To make the change permanent, put it in a `vbt.cfg`, `vbt.yml`, or `vbt.toml` file in the working directory, or point the `VBT_SETTINGS_PATH` environment variable at a file. VBT applies it on import, as the [Configuration files](#configuration-files) highlight below shows. A `.env` file in the working directory is loaded on import as well, which keeps API keys out of code. You can save just one settings section, such as the portfolio defaults, and reload it with `load_update`. Use `reset()` on that section to return to its initial settings. This makes it easy to reuse a project's fees, starting capital, and plotting preferences across notebooks. ## Configured objects and templates \[#configured-objects-and-templates] Most VBT objects are immutable: a portfolio, indicator, or data instance does not change after it is created. `replace` returns a copy with some arguments changed, such as `pf.replace(init_cash=500)`, and the original stays untouched, so earlier results can always be inspected. `replace` rebuilds the object from its configuration. It does not rerun a strategy's order decisions, so test new trading rules with a new simulation. Immutability is a convention, not a copy: inputs are stored as passed, so changing a DataFrame in place after creating an object from it can leave the object out of step with results it has already cached. Copy the input or create the object again. Settings and arguments are merged with `vbt.merge_dicts`, which combines nested dictionaries key by key, so an argument you pass overrides only that key of the default. Pass `vbt.unsetkey` as a value to remove a default key, and wrap a dictionary in `vbt.atomic_dict` to replace it whole. Templates delay a value until the information it needs exists. `vbt.Rep("name")` is replaced by a value from the current context, `vbt.RepEval("expression")` evaluates an expression in it, and `vbt.RepFunc(func)` calls a function with it. The [Portfolio optimization](/features/optimization/portfolio-optimization/) page uses one to give each rebalancing window its slice of returns, as the [Templates](#templates) highlight below explains. !!! info "Cookbook" The members-only [Persistence](https://members.vectorbt.pro/cookbook/persistence/) and [Configuration](https://members.vectorbt.pro/cookbook/configuration/) cookbook pages collect short recipes for saving objects and changing settings. ## Configuration files \[#configuration-files] New in v2025.10.15 ✅ VBT extends popular configuration formats (INI, YAML, TOML) to define its own configuration format that allows users to save, introspect, modify, and load any complex in-house object. The main advantages of this format are readability and round-tripping: any object can be encoded and then decoded back without loss of information. The main features include nested structures, references, literal parsing, and evaluation of arbitrary Python expressions. Additionally, you can now create a configuration file for VBT and place it in the working directory. It will be used to update the default settings whenever the package is imported. === "INI" ```ini title="Define global settings in vbt.cfg" [plotting] default_theme = "dark" [portfolio] init_cash = 5000 [data.custom.binance.client_config] api_key = "" api_secret = "" [data.custom.ccxt.exchanges.binance.exchange_config] apiKey = &data.custom.binance.client_config.api_key secret = &data.custom.binance.client_config.api_secret ``` === "YAML" ```yaml title="Define global settings in vbt.yml" plotting: default_theme: dark portfolio: init_cash: 5000 data.custom.binance.client_config: api_key: &api_key api_secret: &api_secret data.custom.ccxt.exchanges.binance.exchange_config: apiKey: *api_key secret: *api_secret ``` === "TOML" ```toml title="Define global settings in vbt.toml" [plotting] default_theme = "dark" [portfolio] init_cash = 5000 [data.custom.binance.client_config] api_key = "" api_secret = "" [data.custom.ccxt.exchanges.binance.exchange_config] apiKey = { __vbt_ref__ = "data.custom.binance.client_config.api_key" } secret = { __vbt_ref__ = "data.custom.binance.client_config.api_secret" } ``` ```python title="Verify that the settings have been loaded correctly" >>> from vectorbtpro import * >>> vbt.settings.portfolio["init_cash"] 5000 ``` ## Compression \[#compression] New in 1.10.0 ✅ Serialized VBT objects can sometimes use a lot of disk space. With this update, VBT now supports a variety of compression algorithms to make files as light as possible! 🪶 ```python title="Save data without and with compression" >>> data = vbt.RandomOHLCData.pull( ... "RAND", ... start="2022", ... end="2023", ... timeframe="1 minute", ... seed=42 ... ) >>> file_path = data.save() >>> print(vbt.file_size(file_path)) 21.0 MB >>> file_path = data.save(compression="blosc") >>> print(vbt.file_size(file_path)) 13.3 MB ``` ## Faster loading \[#faster-loading] New in 1.10.0 ✅ If your pipeline does not need accessors, Plotly graphs, or most other optional features, you can disable the auto-import feature entirely to reduce VBT's loading time to under a second ⏳ === "INI" ```ini title="Define importing settings in vbt.cfg" [importing] auto_import = False ``` === "YAML" ```yaml title="Define importing settings in vbt.yml" importing: auto_import: false ``` === "TOML" ```toml title="Define importing settings in vbt.toml" [importing] auto_import = false ``` ```python title="Measure the loading time" >>> start = utc_time() >>> from vectorbtpro import * >>> end = utc_time() >>> end - start 0.580937910079956 ``` ## Serialization \[#serialization] New in 1.9.0 ✅ Just like machine learning models, every native VBT object can be serialized and saved to a binary file. It has never been easier to share data and insights! Another benefit is that only the actual content of each object is serialized, not its class definition, so the loaded object always uses the most up-to-date class definition. There is also special logic implemented to help you "reconstruct" objects if VBT introduces any breaking API changes 🏗️ ```python title="Backtest each month of data and save the results for later" >>> data = vbt.YFData.pull("BTC-USD", start="2022-01-01", end="2022-06-01") >>> def backtest_month(close): ... return vbt.PF.from_random_signals(close, n=10, seed=42) >>> month_pfs = data.close.resample(vbt.offset("M")).apply(backtest_month) >>> month_pfs Date 2022-01-01 00:00:00+00:00 Portfolio(\n wrapper=ArrayWrapper(\n ... 2022-02-01 00:00:00+00:00 Portfolio(\n wrapper=ArrayWrapper(\n ... 2022-03-01 00:00:00+00:00 Portfolio(\n wrapper=ArrayWrapper(\n ... 2022-04-01 00:00:00+00:00 Portfolio(\n wrapper=ArrayWrapper(\n ... 2022-05-01 00:00:00+00:00 Portfolio(\n wrapper=ArrayWrapper(\n ... Freq: MS, Name: Close, dtype: object >>> vbt.save(month_pfs, "month_pfs") # (1) >>> month_pfs = vbt.load("month_pfs") # (2) >>> month_pfs.apply(lambda pf: pf.total_return) Date 2022-01-01 00:00:00+00:00 -0.083672 2022-02-01 00:00:00+00:00 0.173909 2022-03-01 00:00:00+00:00 -0.006249 2022-04-01 00:00:00+00:00 -0.057868 2022-05-01 00:00:00+00:00 0.019209 Freq: MS, Name: Close, dtype: float64 ``` 1. Save to disk. 2. Load from disk later. ## Templates \[#templates] New in 1.0.0 ✅ It is easy to extend classes, but since VBT revolves around functions, how do we enhance them or change their workflow? The easiest way is to introduce a small function (i.e., callback) that the user can provide and that the main function calls at some point. However, this would require the main function to know what arguments to pass to the callback and how to handle its outputs. Here is a better idea: allow most arguments of the main function to become callbacks, then execute those to obtain their actual values. These arguments are called "templates" and this process is known as "substitution". Templates are especially useful when some arguments (such as arrays) should be built only once all required information is available, for example, when other arrays have already been broadcast. Each substitution opportunity has its own identifier so you can control when a template should be substituted. In VBT, templates are first-class citizens and are integrated into most functions for unmatched flexibility! 🧞 ```python title="Design a template-enhanced resampling functionality" >>> def resample_apply(index, by, apply_func, *args, template_context={}, **kwargs): ... grouper = index.vbt.get_grouper(by) # (1) ... results = {} ... with vbt.ProgressBar() as pbar: ... for group, group_idxs in grouper: # (2) ... group_index = index[group_idxs] ... context = {"group": group, "group_index": group_index, **template_context} # (3) ... final_apply_func = vbt.substitute_templates(apply_func, context, eval_id="apply_func") # (4) ... final_args = vbt.substitute_templates(args, context, eval_id="args") ... final_kwargs = vbt.substitute_templates(kwargs, context, eval_id="kwargs") ... results[group] = final_apply_func(*final_args, **final_kwargs) ... pbar.update() ... return pd.Series(results) >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"], missing_index="drop") >>> resample_apply( ... data.index, "Y", ... lambda x, y: x.corr(y), # (5) ... vbt.RepEval("btc_close[group_index]"), # (6) ... vbt.RepEval("eth_close[group_index]"), ... template_context=dict( ... btc_close=data.get("Close", "BTC-USD"), # (7) ... eth_close=data.get("Close", "ETH-USD") ... ) ... ) ``` 1. Builds a grouper. Accepts both group-by and resample instructions. 2. Iterates over groups in the grouper. Each group contains a label (such as `2017-01-01 00:00:00+00:00`) and the row indices corresponding to this label. 3. Creates a new context with information about the current group and any external information provided by the user. 4. Substitutes the function and arguments using the newly populated context. 5. Simple function to compute the correlation coefficient between two arrays. 6. Defines both arguments as expression templates where data is selected for each group. All variables in these expressions will be automatically recognized and replaced by the current context. After evaluation, the templates will be replaced by their outputs. 7. Specifies any additional information your templates depend on. Group 7/7: 100% ```text title="Output" 2017 0.808930 2018 0.897112 2019 0.753659 2020 0.940741 2021 0.553255 2022 0.975911 2023 0.974914 Freq: A-DEC, dtype: float64 ``` # Developer tools (/features/tooling/developer-tools) How do you find your way around a library with thousands of classes and functions, and extend it? VBT includes developer tools for API search and Python object inspection: search the package, read any object's source and documentation, and draw what each function depends on. ```python title="Find every function that takes freq, read one, and graph its dependencies" >>> import inspect >>> from vectorbtpro.utils.module_ import search_package >>> from vectorbtpro.utils.source import get_source >>> def accepts_freq(name, obj): ... return inspect.isfunction(obj) and "freq" in inspect.signature(obj).parameters >>> found = search_package("vectorbtpro", accepts_freq) # (1) >>> names = sorted({f"{func.__module__}.{func.__name__}" for func in found.values()}) >>> len(names) 14 >>> print("\n".join(names[-6:])) vectorbtpro.utils.datetime_.readable_datetime vectorbtpro.utils.datetime_.to_freq vectorbtpro.utils.datetime_.to_offset vectorbtpro.utils.datetime_.to_timedelta vectorbtpro.utils.datetime_.to_timedelta64 vectorbtpro.utils.schedule_.wait >>> from vectorbtpro.utils.datetime_ import infer_index_freq >>> print("\n".join(get_source(infer_index_freq).splitlines()[:7])) def infer_index_freq( index: tp.Index, freq: tp.Optional[tp.FrequencyLike] = None, allow_offset: bool = True, allow_numeric: bool = True, freq_from_n: tp.Union[None, bool, int] = None, ) -> tp.Union[None, int, float, tp.PandasFrequency]: >>> ref_index = vbt.RefIndex(incl_modules="vectorbtpro") >>> graph = ref_index.build_graph(infer_index_freq) # (2) >>> print("\n".join(graph.get_dependencies(graph.root, relation="direct"))) vectorbtpro._typing.FrequencyLike vectorbtpro._typing.PandasFrequency vectorbtpro.utils.checks.is_number vectorbtpro.utils.datetime_.auto_detect_freq vectorbtpro.utils.datetime_.freq_depends_on_index vectorbtpro.utils.datetime_.parse_index_freq vectorbtpro.utils.datetime_.to_freq >>> fig = graph.plot(interactive=False, showlegend=False) >>> for trace in fig.data: # (3) ... if trace.name.endswith("_nodes_hl") and len(trace.x) > 0: ... labels = [info[1] or info[0] for info in trace.customdata] ... trace.update(mode="markers+text", text=labels, textposition="top center") >>> fig.show() ``` 1. Walks every module of the package and keeps the module-level functions that match. Methods of classes need a separate search. 2. Indexes the source code for references and follows those defined in the function's own module. 3. Names show on hover by default. This loop prints them next to each node. Reference graph of the infer\_index\_freq function and the functions and types it uses. [Figure data (JSON)](/assets/figures/features/tooling/reference-graph-infer-freq.11ed1169f1ab.json) Fourteen module-level functions accept a `freq` argument. The graph places `infer_index_freq` and the seven names it uses inside the modules that define them, which shows where to look when a frequency is not what you expected. ## Discovery \[#discovery] Most questions about VBT can be answered from Python itself: | Tool | Answers | | ----------------------------------------------- | ---------------------------------------------------------------------- | | `vbt.phelp(obj)` | What a function takes and what its docstring says | | `vbt.pdir(obj)` | Which attributes an object has, their kinds, and where each is defined | | `vbt.pprint(obj)` | What an object holds, formatted as readable nested text | | `vbt.ptable(obj)` | What an array, DataFrame, or record array holds, as a table | | `get_source(obj)` | The source code of any function, class, or module | | `vbt.get_api_ref(obj)`, `vbt.open_api_ref(obj)` | The API documentation page for an object | | `vbt.RefIndex` | What an object uses, what uses it, and how modules connect | | `vbt.get_capabilities()` | How many indicators, data sources, metrics, and engines are installed | `deep_getattr` resolves a dotted path of attributes and method calls, such as `pf.deep_getattr("trades.expectancy")`. For questions in plain language, the [Knowledge search](/features/ai/knowledge-search/) page covers `vbt.find_api` and `vbt.search`. These tools work together when an unfamiliar object or argument blocks your research. Start with `phelp` for the call signature, use `pdir` to find the relevant property or method, then open the source or API reference for the details. Configured objects expose their constructor arguments in `config`, so you can inspect the settings that created a data instance, indicator, or portfolio. ## Formatting and annotations \[#formatting-and-annotations] The formatting engine behind `vbt.pprint` and `vbt.phelp` renders configured objects, dictionaries, arrays, and signatures the same way in a terminal and in a notebook, as the [Formatting engine](#formatting-engine) highlight below shows. Annotations carry meaning in a function's signature: `vbt.Param`, `vbt.Takeable`, and `vbt.MergeFunc` tell the parameterization and splitting decorators how to treat each argument, as the [Annotations](#annotations) highlight below shows. ## Validation and debugging \[#validation-and-debugging] * **Equality:** `vbt.is_deep_equal` compares nested objects, arrays, and their metadata, and every configured object has `equals`. * **Warnings:** VBT warnings share one format, and `vbt.WarningsFiltered()` silences them inside a `with` block. * **Hashing:** `vbt.hdict` and configured objects can be hashed, which is how VBT caches results by their arguments. * **Bounds checks:** an invalid array index in a custom Numba callback can return incorrect data or crash the kernel. Setting `boundscheck` under `numba` in a configuration file makes compiled functions raise an error instead, and Numba's `NUMBA_DISABLE_JIT=1` environment variable disables Numba compilation for Python-level debugging. Set it before importing VBT. * **Preparers:** simulation methods split argument checking from execution. Pass `return_preparer=True` to inspect the prepared arguments of a portfolio before it runs, or `return_prep_result=True` to get the final arrays the simulator would receive, in `target_args`. ### Inspect what the simulator will receive \[#inspect-what-the-simulator-will-receive] Preparers let you check shapes, defaults, and converted arguments before running a long backtest. Here, two assets have different order values but share the same fee: ```python title="Inspect prepared order sizes and fees without running the simulation" >>> close = pd.DataFrame( ... {"A": [100.0, 105.0, 103.0], "B": [50.0, 49.0, 52.0]}, ... index=pd.date_range("2025-01-01", periods=3), ... ) >>> prepared = vbt.PF.from_orders( ... close, ... size=np.array([[100.0, 200.0]]), ... size_type="value", ... fees=0.001, ... return_prep_result=True, ... ) >>> print(prepared.pf_args["wrapper"].shape) (3, 2) >>> print(prepared.target_args["size"]) [[100. 200.]] >>> print(prepared.target_args["fees"]) [[0.001]] ``` The target has three rows and two assets. Order values stay in a single row, and the shared fee stays in a single cell, ready for flexible indexing inside the simulator. This makes it easier to see whether an unexpected result starts with the inputs or with the trading logic. The [Backtesting engine](/features/backtesting/backtesting-engine/#portfolio-preparers) page shows how to modify a preparation result and run it. Runtime checks also validate shapes, indexes, and data types. You can use the same assertion helpers in your own functions, while deep equality checks help compare nested outputs after a refactor. For a callback that behaves unexpectedly, inspect a small input slice first, then use bounds checking or Python-level debugging to follow its decisions. ## Extending \[#extending] VBT is built from the same factories it exposes. `vbt.IF` builds indicator classes, as the [Custom indicators](/features/indicators/indicator-development/) page shows, and `vbt.SignalFactory` builds signal generators. Configured classes get declarative fields, cached properties, and shortcut methods from decorators, and `vbt.evaluate` evaluates expressions against a context, which is how indicator expressions and templates find their inputs. You can keep a custom calculation as a function, expose it as an indicator with named inputs and parameters, or register a compiled implementation and its chunking rules. This lets custom work participate in the same parameter searches and labeled results as built-in calculations. [Compute backends](/features/performance/compute-backends/) and [Parallel execution](/features/performance/parallel-execution-and-caching/) cover those execution choices. For logic that needs current positions and cash, extend the simulation through [Event-driven callbacks](/features/backtesting/event-driven-backtesting/). ## Utilities \[#utilities] Smaller tools cover everyday tasks: searching and replacing values deep inside nested objects, reading and writing nested keys by path, matching names with regular expressions, managing files and folders, and rescaling arrays. They are the same helpers VBT uses internally. To save memory, `vbt.settings.wrapping["max_precision"] = 32` casts results to 32-bit floats when they are wrapped into pandas, at the cost of precision. Member pages with Python downloads provide examples in Jupytext format, so you can open them as notebooks and adapt them locally. The [tutorials](/tutorials/) give you complete research workflows to inspect alongside the individual API objects. ## Reference graphs \[#reference-graphs] New in v2025.12.31 ✅ When analyzing complex codebases like VBT, it can be challenging to keep track of all the interdependencies between modules, classes, and functions. To address this, VBT now includes a functionality that can index the source code of any codebase for object references and generate reference graphs from any specified entry point. These graphs provide a visual representation of how different components relate to each other, making it easier to understand the overall structure and flow of the code. ```python title="Generate a reference graph for Pandas and display it in a new browser tab" >>> ref_index = vbt.RefIndex(container_kinds=["module", "class"], incl_modules="pandas") >>> ref_graph = ref_index.build_graph("pandas") >>> ref_graph.plot( ... interactive="dash", ... to_dash_kwargs=dict(fit_to_window=True), ... dash_run_kwargs=dict(jupyter_mode="tab") ... ) ``` Reference graph of Pandas modules, classes, callables, and data dependencies. [Figure data (JSON)](/assets/figures/features/productivity/reference-graph.0345cbe42aad.json) !!! info "Online explorer" Explore the VBT's reference graph in the [`API`](/api/) → Reference graph. ## Annotations \[#annotations] New in v2023.12.23 ✅ When writing a function, you can specify the meaning of each argument using an annotation immediately next to the argument. VBT now provides a rich set of in-house annotations tailored to specific tasks. For example, whether an argument is a parameter can be specified directly in the function instead of in the [parameterized decorator](/features/optimization/strategy-optimization/#parameterized-decorator). ```python title="Test a cross-validation function with annotations" >>> @vbt.cv_split( ... splitter="from_rolling", ... splitter_kwargs=dict(length=365, split=0.5, set_labels=["train", "test"]), ... parameterized_kwargs=dict(random_subset=100, seed=42), ... ) ... def sma_crossover_cv( ... data: vbt.Takeable, # (1) ... fast_period: vbt.Param(condition="x < slow_period"), # (2) ... slow_period: vbt.Param, # (3) ... metric ... ) -> vbt.MergeFunc("concat"): ... fast_sma = data.run("sma", fast_period, hide_params=True) ... slow_sma = data.run("sma", slow_period, hide_params=True) ... entries = fast_sma.real_crossed_above(slow_sma) ... exits = fast_sma.real_crossed_below(slow_sma) ... pf = vbt.PF.from_signals(data, entries, exits, direction="both") ... return pf.deep_getattr(metric) >>> sma_crossover_cv( ... vbt.YFData.pull("BTC-USD", start="4 years ago"), ... np.arange(20, 50), ... np.arange(20, 50), ... "trades.expectancy" ... ) split set fast_period slow_period 0 train 25 26 2.822879 test 25 26 4.740533 1 train 22 37 16.967189 test 22 37 -16.101936 2 train 30 41 308.879034 test 30 41 14.445511 3 train 29 49 32.328702 test 29 49 13.546335 4 train 27 48 20.695292 test 27 48 6.539824 5 train 22 46 19.143686 test 22 46 -4.664139 6 train 34 45 5.235739 test 34 45 -2.697966 dtype: float64 ``` 1. The passed argument must be takeable (for selecting subsets by split). 2. Parameter with a condition requiring it to be less than the slow period. 3. Parameter for the slow period. ## Formatting engine \[#formatting-engine] New in 1.0.2 ✅ VBT is a comprehensive library that defines thousands of classes, functions, and objects. When working with these, you may want to "look inside" an object to better understand its attributes and contents. Fortunately, there is a formatting engine that can accurately format any in-house object as a human-readable string. Did you know the API documentation is partly powered by this engine? 😉 ```python title="Introspect a data instance" >>> data = vbt.YFData.pull("BTC-USD", start="2020", end="2021") >>> vbt.pprint(data) # (1) YFData( wrapper=ArrayWrapper(...), data=symbol_dict({ 'BTC-USD': }), single_key=True, classes=symbol_dict(), fetch_kwargs=symbol_dict({ 'BTC-USD': dict( start='2020', end='2021' ) }), returned_kwargs=symbol_dict({ 'BTC-USD': dict() }), last_index=symbol_dict({ 'BTC-USD': Timestamp('2020-12-31 00:00:00+0000', tz='UTC') }), tz_localize=datetime.timezone.utc, tz_convert='UTC', missing_index='nan', missing_columns='raise' ) >>> vbt.pdir(data) # (2) type path attr align_columns classmethod vectorbtpro.data.base.Data align_index classmethod vectorbtpro.data.base.Data build_feature_config_doc classmethod vectorbtpro.data.base.Data ... ... ... vwap property vectorbtpro.data.base.Data wrapper property vectorbtpro.base.wrapping.Wrapping xs function vectorbtpro.base.indexing.PandasIndexer >>> vbt.phelp(data.get) # (3) YFData.get( columns=None, symbols=None, **kwargs ): Get one or more columns of one or more symbols of data. ``` 1. Similar to Python's `print` command, pretty-prints the contents of any VBT object. 2. Similar to Python's `dir` command, pretty-prints the attributes of a class, object, or module. 3. Similar to Python's `help` command, pretty-prints the signature and docstring of a function. # Research toolkit (/features/tooling) The labeled-array model, pandas extensions, persistence, automation, and introspection behind every VBT workflow. These pages cover how many experiments fit into one array, the compiled operations that run on them, and the tools that save, schedule, and inspect your research. This section is for readers who already run backtests and want to understand why VBT shapes data the way it does, work faster with it, or build on it. ## Find the tool for your next step \[#find-the-tool-for-your-next-step] | What do you want to do? | Where to start | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Compare assets, parameter sets, or strategies without losing their labels | [Multidimensional research](/features/tooling/multidimensional-research/) explains broadcasting, selection, grouping, and stacking. | | Calculate rolling statistics or apply date and session rules | [Time-series operations](/features/tooling/time-series-operations/) adds compiled calculations to pandas objects. | | Reopen a backtest or reuse a project's settings | [Configuration and persistence](/features/tooling/configuration-and-persistence/) saves objects, inputs, and configuration. | | Run updates or research jobs on a schedule | [Workflow automation](/features/tooling/workflow-automation/) covers tasks, scheduling, progress, and notifications. | | Inspect an unfamiliar object or debug custom code | [Developer tools](/features/tooling/developer-tools/) covers help, source, prepared inputs, and extension tools. | * [Multidimensional research](/features/tooling/multidimensional-research): Run assets, parameters, and strategies as labeled columns, then index and stack them * [Time-series operations](/features/tooling/time-series-operations): Run compiled rolling windows, reductions, and date logic on labeled pandas data * [Configuration and persistence](/features/tooling/configuration-and-persistence): Save any research object with compression, reload it fast, and keep settings in files * [Workflow automation](/features/tooling/workflow-automation): Schedule data updates, send Telegram alerts, run tasks in parallel, and track progress * [Developer tools](/features/tooling/developer-tools): Search the API, read source, draw reference graphs, and extend classes with factories ## Keep your Python workflow \[#keep-your-python-workflow] Start with the pandas Series and DataFrames you already use. The `.vbt` accessor adds calculations and array operations while keeping labeled results, so you can move between pandas analysis and VBT's compiled functions. As the experiment grows, named column levels keep symbols, parameter values, and strategies attached to the results they produced. A typical workflow calculates signals, compares backtests, saves the chosen inputs and portfolios, and reopens them later for more analysis. The same calculation can run across a list of symbols or on a schedule. You can inspect its arguments and source when you need to change it, then turn a reusable calculation into a [custom indicator](/features/indicators/indicator-development/). For larger workloads, [Parallel execution and caching](/features/performance/parallel-execution-and-caching/) covers dividing work into batches and reusing calculations. For preparing market data before the experiment, see [Financial data pipelines](/features/data/financial-data-pipelines/). ## Start here \[#start-here] Browse the [Cookbook](/cookbook/) for practical recipes on arrays, indexing, configuration, and persistence. # Multidimensional research (/features/tooling/multidimensional-research) How does VBT test thousands of strategy variants in one pass, and how do you find your way around the result? Every asset, parameter value, and strategy becomes a labeled column. Inputs broadcast against each other, computation runs on NumPy arrays, and results come back as pandas objects you can select, group, and stack like any DataFrame. ```python title="Run 3 assets × 4 fast windows × 4 slow windows as 48 columns" >>> from itertools import product >>> data = vbt.YFData.pull( ... ["BTC-USD", "ETH-USD", "SOL-USD"], ... start="2022-01-01", ... end="2025-01-01", ... ) >>> fast_windows, slow_windows = zip(*product([5, 10, 15, 20], [30, 50, 70, 90])) >>> fast = vbt.MA.run(data.close, window=list(fast_windows), short_name="fast") >>> slow = vbt.MA.run(data.close, window=list(slow_windows), short_name="slow") >>> entries = fast.ma_crossed_above(slow) >>> exits = fast.ma_crossed_below(slow) >>> entries.shape (1096, 48) >>> entries.columns[:4] MultiIndex([(5, 30, 'BTC-USD'), (5, 30, 'ETH-USD'), (5, 30, 'SOL-USD'), (5, 50, 'BTC-USD')], names=['fast_window', 'slow_window', 'symbol']) >>> pf = vbt.PF.from_signals(data, entries, exits, fees=0.001) # (1) >>> pf.total_return.groupby("symbol").describe()[["mean", "min", "max"]].round(3) mean min max symbol BTC-USD 0.758 0.174 1.481 ETH-USD 0.051 -0.195 0.474 SOL-USD 1.394 0.104 4.285 >>> print(round(pf[(10, 50, "ETH-USD")].total_return, 4)) # (2) 0.1389 >>> pf.xs("ETH-USD", level="symbol", axis=1).wrapper.shape # (3) (1096, 16) ``` 1. Three columns of prices broadcast against 48 columns of signals. Each price column is reused for its 16 parameter pairs. 2. One backtest, selected by its labels. 3. All 16 parameter pairs of one asset. Each column is a complete backtest with its own orders, trades, and metrics, and the column labels carry every parameter, so results can be summarized with ordinary pandas. That lets you ask several questions of the same experiment: which assets behave consistently, which parameter ranges hold up, and how much the result changes under different cost assumptions. You keep the labels from the inputs through to the final trades and performance tables. ## The research model \[#the-research-model] A VBT object is a NumPy array plus a wrapper that remembers the index, the columns, the frequency, and any grouping. Computation runs on the raw arrays in compiled code, and results are wrapped back into pandas with the right labels, whether the result is a time series, one value per column, or one value per group. Series and DataFrames go through the same code, so a function written for one asset works for a thousand. For market data, each feature has its own array: close prices in one table, highs in another, and entry signals in another. Columns identify symbols and experiments. A VBT data object can supply its price features directly, as in the opening example, or you can pass separate arrays from your own data pipeline. ## Broadcasting \[#broadcasting] Inputs of different shapes are combined by broadcasting: a scalar applies everywhere, a Series applies to every column, a one-row DataFrame applies to every bar, and a full DataFrame applies element by element. Labeled columns are matched by their levels, so three price columns line up with 48 signal columns that share the `symbol` level, as above. Small inputs stay small: inside the simulation, a scalar fee is read as a scalar rather than expanded into a full array. A one-dimensional NumPy array is a time series, so it must have one value per bar. Per-column values go in a one-row array such as `np.array([[0.001, 0.002, 0.003]])`, or a labeled object. Rows are matched by their dates: inputs with different dates are joined on all dates and filled with NaN, so data on different timeframes must be resampled to one index first, as the [Multi-timeframe analysis](/features/data/multi-timeframe-analysis/) page shows. Plain pandas operators match labels exactly, so comparing two indicator outputs with different parameter levels fails. Putting `.vbt` in front of the left operand applies VBT's broadcasting instead, as the [Trading signals](/features/indicators/trading-signals/#combining-conditions) page shows. Match price and signal columns for one backtest per column, or expand your experiment with the DataFrame product below. It lets you compare combinations while keeping each symbol attached to its own prices. The [DataFrame product](#dataframe-product) highlight below combines every column of one DataFrame with every column of another, and [Index dictionaries](#index-dictionaries) set values at chosen dates and columns without building an array first. ### Compare assumptions as labeled scenarios \[#compare-assumptions-as-labeled-scenarios] Parameters can describe execution assumptions as well as indicators. Here, two made-up price series are tested with no fees and a 1% fee. Each fee becomes another column level, so the returns can be reshaped into a table without collecting results from separate runs: ```python title="Compare two fee assumptions across two assets" >>> close = pd.DataFrame( ... {"A": [100.0, 105.0, 110.0], "B": [100.0, 98.0, 95.0]}, ... index=pd.date_range("2025-01-01", periods=3), ... ).rename_axis(columns="symbol") >>> scenarios = vbt.PF.from_holding(close, fees=vbt.Param([0.0, 0.01], name="fee")) >>> scenarios.total_return.unstack("symbol").round(4) symbol A B fee 0.00 0.1000 -0.0500 0.01 0.0891 -0.0594 ``` These are total returns as fractions, with the positions still open at the end. The fee reduces how much each backtest can buy at entry. The same approach lets you compare slippage or sizing assumptions. [Parameter optimization](/features/optimization/strategy-optimization/) covers larger searches, conditional combinations, and random samples. ## Grouping \[#grouping] Columns can be grouped for reporting or for simulation. `group_by` combines columns into groups by a level, a list of labels, or `True` for everything, and `cash_sharing=True` turns a group into one account. Grouping set after the fact changes only how results are reported, so the same backtests can be read per asset, per parameter value, or as a whole, as long as each group's columns are next to each other. In the opening example, the pandas summary groups the 16 returns for each symbol to compare parameter choices. That is different from grouping the portfolio itself, which can report the performance of several columns held together. Use [Portfolio accounting](/features/backtesting/portfolio-accounting/) for shared-capital portfolios and [Multi-strategy portfolios](/features/strategies/multi-strategy-portfolios/) for allocating between separate strategies. ## Stacking runs \[#stacking-runs] Separate runs can be joined into one object. Column stacking puts different experiments side by side, for example a strategy grid next to buy-and-hold: ```python title="Put buy-and-hold next to the 48 crossover backtests" >>> hold_pf = vbt.PF.from_holding(data) >>> both = vbt.PF.column_stack( ... pf, ... hold_pf, ... wrapper_kwargs=dict(keys=pd.Index(["crossover", "hold"], name="strategy")), ... ) >>> both.wrapper.shape (1096, 51) >>> both.total_return["hold"].round(3) BTC-USD 0.959 ETH-USD -0.116 SOL-USD 0.060 Name: total_return, dtype: float64 ``` Row stacking joins consecutive periods, such as the test windows of a walk-forward run, into one history. Stacked portfolios keep their records and recompute cash and value from them. Each window simulated on its own starts with fresh capital: the first window's initial cash becomes the stacked portfolio's, and each later window's initial cash is added as a deposit at its start, so returns stay correct while the value jumps. `combine_init_cash=True` counts all of it as initial cash instead, which leaves the later windows' cash idle during the earlier ones and dilutes their returns. To carry one account through every window, continue each window from the previous one's final state and stack them with `chained=True`, as on the [Live simulation](/features/backtesting/live-simulation/) page. The [Column stacking](#column-stacking) and [Row stacking](#row-stacking) highlights below show both on full portfolios. This also lets you work with a long history in smaller segments, or simulate data windows around groups of entry and exit events. Keep the intended cash and position state at the boundaries, then row-stack the results for analysis. For large sets of independent experiments, [Parallel execution and caching](/features/performance/parallel-execution-and-caching/) covers splitting the work into batches. ## Indexing \[#indexing] Every VBT object can be indexed like pandas: by column labels, by `.loc` and `.iloc` on dates and positions, by parameter level, or with `xs`. Slicing a portfolio by date gives a new portfolio for that period without rerunning the simulation, with records and metrics adjusted to the window. Setters work the same way in reverse: assign values by date, time of day, label, or mask with the data's wrapper. The [Slicing](#slicing) and [Index alignment](#index-alignment) highlights below show both. Select a symbol or parameter combination before inspecting its orders, plotting its value, or comparing its drawdowns. The labels let you move from a summary table back to the backtest that produced an interesting result. You can also rename, reorder, or drop index levels to keep reports readable when an experiment has many dimensions. ## Pandas accessors \[#pandas-accessors] Importing VBT adds a `.vbt` accessor to every Series, DataFrame, and Index, with specialized namespaces such as `.vbt.returns`, `.vbt.signals`, and `.vbt.ohlcv`. Data stays a regular pandas object, so VBT operations and pandas operations can be mixed in one line. Because the accessors are registered at runtime, some editors do not complete them. Notebooks do. `vbt.df_acc(df)` and `vbt.sr_acc(sr)` return the same accessors as explicit objects, which editors can introspect. ## DataFrame product \[#dataframe-product] New in 1.13.0 ✅ Several parameterized indicators can produce DataFrames with different shapes and columns, which makes creating a Cartesian product tricky because they often share common column levels (such as "symbol") that should not be combined. There is now a method to cross-join multiple DataFrames block-wise. ```python title="Enter when SMA goes above WMA, exit when EMA goes below WMA" >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"], missing_index="drop") >>> sma = data.run("sma", timeperiod=[10, 20], unpack=True) >>> ema = data.run("ema", timeperiod=[30, 40], unpack=True) >>> wma = data.run("wma", timeperiod=[50, 60], unpack=True) >>> sma, ema, wma = sma.vbt.x(ema, wma) # (1) >>> entries = sma.vbt.crossed_above(wma) >>> exits = ema.vbt.crossed_below(wma) >>> entries.columns MultiIndex([(10, 30, 50, 'BTC-USD'), (10, 30, 50, 'ETH-USD'), (10, 30, 60, 'BTC-USD'), (10, 30, 60, 'ETH-USD'), (10, 40, 50, 'BTC-USD'), (10, 40, 50, 'ETH-USD'), (10, 40, 60, 'BTC-USD'), (10, 40, 60, 'ETH-USD'), (20, 30, 50, 'BTC-USD'), (20, 30, 50, 'ETH-USD'), (20, 30, 60, 'BTC-USD'), (20, 30, 60, 'ETH-USD'), (20, 40, 50, 'BTC-USD'), (20, 40, 50, 'ETH-USD'), (20, 40, 60, 'BTC-USD'), (20, 40, 60, 'ETH-USD')], names=['sma_timeperiod', 'ema_timeperiod', 'wma_timeperiod', 'symbol']) ``` 1. Build a Cartesian product of three DataFrames while keeping the column level "symbol" untouched. This can also be done with `vbt.pd_acc.cross(sma, ema, wma)`. ## Index dictionaries \[#index-dictionaries] New in 1.3.0 Manually creating arrays and setting their data with Pandas can often be challenging. Luckily, there is now a feature that offers much-needed assistance! Any broadcastable argument can become an index dictionary, which contains instructions on where to set values in the array and fills them in for you. It knows exactly which axis needs to be updated and does not create a full array unless necessary, saving RAM ❤️ ```python title="1) Accumulate daily and exit on Sunday vs 2) accumulate weekly and exit on month end" >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"]) >>> tile = pd.Index(["daily", "weekly"], name="strategy") # (1) >>> pf = vbt.PF.from_orders( ... data.close, ... size=vbt.index_dict({ # (2) ... vbt.idx( ... vbt.pointidx(every="day"), ... vbt.colidx("daily", level="strategy")): 100, # (3) ... vbt.idx( ... vbt.pointidx(every="sunday"), ... vbt.colidx("daily", level="strategy")): -np.inf, # (4) ... vbt.idx( ... vbt.pointidx(every="monday"), ... vbt.colidx("weekly", level="strategy")): 100, ... vbt.idx( ... vbt.pointidx(every="monthend"), ... vbt.colidx("weekly", level="strategy")): -np.inf, ... }), ... size_type="value", ... direction="longonly", ... init_cash="auto", ... broadcast_kwargs=dict(tile=tile) ... ) >>> pf.sharpe_ratio strategy symbol daily BTC-USD 0.702259 ETH-USD 0.782296 weekly BTC-USD 0.838895 ETH-USD 0.524215 Name: sharpe_ratio, dtype: float64 ``` 1. To represent two strategies, you need to tile the same data twice. Create a parameter with strategy names and pass it as `tile` to the broadcaster so it tiles the columns of each array (such as price) twice. 2. The index dictionary includes index instructions as keys and data as values to set. Keys can be row indices, labels, or custom indexer classes such as `PointIdxr`. 3. Find the indices of the rows for the start of each day and the column index of "daily", then set each element at those indices to 100 (= accumulate). 4. Find the indices of the rows that correspond to Sunday. If any value at those indices has already been set by a previous instruction, it will be overridden. ## Slicing \[#slicing] New in 1.3.0 ✅ Similar to selecting columns, each VBT object can now slice rows using the same mechanism as in Pandas 🔪 This makes it easy to analyze and plot any subset of simulated data, without needing to re-simulate! ```python title="Analyze multiple date ranges of the same portfolio" >>> data = vbt.YFData.pull("BTC-USD") >>> pf = vbt.PF.from_holding(data, freq="d") >>> pf.sharpe_ratio 1.116727709477293 >>> pf.loc[:"2020"].sharpe_ratio # (1) 1.2699801554196481 >>> pf.loc["2021": "2021"].sharpe_ratio # (2) 0.9825161170278687 >>> pf.loc["2022":].sharpe_ratio # (3) -1.0423271337174647 ``` 1. Get the Sharpe ratio during the year 2020 and before. 2. Get the Sharpe ratio during the year 2021. 3. Get the Sharpe ratio during the year 2022 and after. ## Column stacking \[#column-stacking] New in 1.3.0 ✅ Complex VBT objects of the same type can be easily stacked along columns. For example, you can combine multiple unrelated trading strategies into one portfolio for analysis. Under the hood, the final object is still represented as a monolithic multi-dimensional structure that can be processed even faster than separate merged objects 🫁 ```python title="Analyze two trading strategies separately and then jointly" >>> def strategy1(data): ... fast_ma = vbt.MA.run(data.close, 50, short_name="fast_ma") ... slow_ma = vbt.MA.run(data.close, 200, short_name="slow_ma") ... entries = fast_ma.ma_crossed_above(slow_ma) ... exits = fast_ma.ma_crossed_below(slow_ma) ... return vbt.PF.from_signals( ... data.close, ... entries, ... exits, ... size=100, ... size_type="value", ... init_cash="auto" ... ) >>> def strategy2(data): ... bbands = vbt.BBANDS.run(data.close, window=14) ... entries = bbands.close_crossed_below(bbands.lower) ... exits = bbands.close_crossed_above(bbands.upper) ... return vbt.PF.from_signals( ... data.close, ... entries, ... exits, ... init_cash=200 ... ) >>> data1 = vbt.BinanceData.pull("BTCUSDT") >>> pf1 = strategy1(data1) # (1) >>> pf1.sharpe_ratio 0.9100317671866922 >>> data2 = vbt.BinanceData.pull("ETHUSDT") >>> pf2 = strategy2(data2) # (2) >>> pf2.sharpe_ratio -0.11596286232734827 >>> pf_sep = vbt.PF.column_stack((pf1, pf2)) # (3) >>> pf_sep.sharpe_ratio 0 0.910032 1 -0.115963 Name: sharpe_ratio, dtype: float64 >>> pf_join = vbt.PF.column_stack((pf1, pf2), group_by=True) # (4) >>> pf_join.sharpe_ratio 0.42820898354646514 ``` 1. Analyze the first strategy in its own portfolio. 2. Analyze the second strategy in its own portfolio. 3. Analyze both strategies separately in the same portfolio. 4. Analyze both strategies jointly in the same portfolio. ## Row stacking \[#row-stacking] New in 1.3.0 ✅ Complex VBT objects of the same type can be easily stacked along rows. For example, you can append new data to an existing portfolio, or concatenate in-sample portfolios with their out-of-sample counterparts 🧬 ```python title="Analyze two date ranges separately and then jointly" >>> def strategy(data, start=None, end=None): ... fast_ma = vbt.MA.run(data.close, 50, short_name="fast_ma") ... slow_ma = vbt.MA.run(data.close, 200, short_name="slow_ma") ... entries = fast_ma.ma_crossed_above(slow_ma) ... exits = fast_ma.ma_crossed_below(slow_ma) ... return vbt.PF.from_signals( ... data.close[start:end], ... entries[start:end], ... exits[start:end], ... size=100, ... size_type="value", ... init_cash="auto" ... ) >>> data = vbt.BinanceData.pull("BTCUSDT") >>> pf_whole = strategy(data) # (1) >>> pf_whole.sharpe_ratio 0.9100317671866922 >>> pf_sub1 = strategy(data, end="2019-12-31") # (2) >>> pf_sub1.sharpe_ratio 0.7810397448678937 >>> pf_sub2 = strategy(data, start="2020-01-01") # (3) >>> pf_sub2.sharpe_ratio 1.070339534746574 >>> pf_join = vbt.PF.row_stack((pf_sub1, pf_sub2)) # (4) >>> pf_join.sharpe_ratio 0.9100317671866922 ``` 1. Analyze the entire range. 2. Analyze the first date range. 3. Analyze the second date range. 4. Combine both date ranges and analyze them together. ## Index alignment \[#index-alignment] New in 1.3.0 ✅ There is no longer a limitation requiring each Pandas array to have the same index. Indexes of all arrays that should broadcast against each other are automatically aligned, as long as they have the same data type. ```python title="Predict ETH price with BTC price using linear regression" >>> btc_data = vbt.YFData.pull("BTC-USD") >>> btc_data.wrapper.shape (2817, 7) >>> eth_data = vbt.YFData.pull("ETH-USD") # (1) >>> eth_data.wrapper.shape (1668, 7) >>> ols = vbt.OLS.run( # (2) ... btc_data.close, ... eth_data.close ... ) >>> ols.pred Date 2014-09-17 00:00:00+00:00 NaN 2014-09-18 00:00:00+00:00 NaN 2014-09-19 00:00:00+00:00 NaN 2014-09-20 00:00:00+00:00 NaN 2014-09-21 00:00:00+00:00 NaN ... ... 2022-05-30 00:00:00+00:00 2109.769242 2022-05-31 00:00:00+00:00 2028.856767 2022-06-01 00:00:00+00:00 1911.555689 2022-06-02 00:00:00+00:00 1930.169725 2022-06-03 00:00:00+00:00 1882.573170 Freq: D, Name: Close, Length: 2817, dtype: float64 ``` 1. ETH-USD history is shorter than BTC-USD history. 2. This now works! Make sure all arrays share the same timeframe and timezone. # Time-series operations (/features/tooling/time-series-operations) How do you run rolling windows, reductions, and date logic over hundreds of columns quickly without losing pandas labels? VBT adds compiled time-series operations to every Series and DataFrame through the `.vbt` accessor. Run calculations in Numba and get labeled pandas objects back, ready to use in indicators, signals, and performance analysis. ```python title="Compute a rolling z-score on 500 columns with pandas and with VBT" >>> import timeit >>> np.random.seed(42) >>> df = pd.DataFrame( ... np.random.normal(size=(5000, 500)).cumsum(axis=0), ... index=pd.date_range("2020-01-01", periods=5000, freq="h"), ... ) >>> pd_z = (df - df.rolling(20).mean()) / df.rolling(20).std() >>> vbt_z = df.vbt.rolling_zscore(20) >>> np.allclose(pd_z, vbt_z, equal_nan=True), vbt_z.shape (True, (5000, 500)) >>> def best_ms(func): # (1) ... return min(timeit.repeat(func, number=1, repeat=7)) * 1000 >>> best_ms(lambda: (df - df.rolling(20).mean()) / df.rolling(20).std()) 67.0 >>> best_ms(lambda: df.vbt.rolling_zscore(20)) 12.0 >>> best_ms(lambda: df.vbt.rolling_zscore(20, jitted=dict(parallel=True))) # (2) 8.2 ``` 1. Best of seven runs, after the function has been compiled once. 2. Run the 500 columns in parallel threads. The output is identical to pandas. On the Apple M3 that built this page, the compiled version took 12 ms instead of 67 ms, and 8 ms across eight cores. Timings depend on the machine and the data, so measure on yours. Use these operations to normalize a price series, estimate rolling volatility, compare assets' correlations, or build a signal from several input arrays. They work on your existing pandas data, so you can add a VBT calculation to a notebook without moving the whole workflow. ## Windows \[#windows] Rolling and expanding versions of mean, sum, standard deviation, min, max, the position of the min and max, rank, z-score, covariance, correlation, and regression are compiled, as are exponentially weighted mean and standard deviation and a linearly weighted mean. Median and quantiles are not, so they run through `rolling_apply` with your own function or through pandas. Every window function takes a minimum number of observations, works on Series and DataFrames alike, and broadcasts a second input where one is needed: ```python title="Compute a 30-day rolling correlation between Bitcoin and Ether" >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"], start="2024-01-01", end="2025-01-01") >>> rets = data.close.pct_change() >>> rets["BTC-USD"].vbt.rolling_corr(rets["ETH-USD"], 30).describe().round(3) count 336.000 mean 0.796 std 0.094 min 0.443 25% 0.749 50% 0.818 75% 0.861 max 0.948 dtype: float64 ``` For anything else, `rolling_apply`, `expanding_apply`, and `groupby_apply` run your own compiled function over each window or group. Use a fixed window for recent behavior, an expanding window for a statistic since the start, or exponential weights when newer observations should count more. Use `minp` to require enough recent observations before an exponential calculation returns a value, giving you control over how gaps in the data affect your signals. ## Dates and times \[#dates-and-times] Data instances keep timezone-aware timestamps. By default, timestamps without a timezone are read as UTC, and everything is stored in UTC. `tz_localize` sets the timezone that naive timestamps were recorded in, and `tz_convert` sets the one to keep, such as the exchange's local time. One data instance holds one timezone, so symbols from different exchanges share it. Date strings, relative dates such as `"3 months ago"`, and timedeltas are parsed wherever dates are accepted. Inside compiled code, datetimes are integers, and helper functions extract the hour, weekday, or month and find the next session boundary, as the [Numba datetime](#numba-datetime) highlight below shows. `.vbt.xloc["09:30":"16:00"]` selects a time of day across all dates. `vbt.wait` and index masks for calendar intervals help with schedules, and `.vbt.ago` reads values a fixed time back rather than a fixed number of bars, as shown in [Periods ago](#periods-ago). !!! warning "Daylight saving time" Time-of-day rules in local time move by an hour twice a year relative to UTC. Keep the index in the exchange's timezone when a rule refers to its session times. ### Look back by bars or elapsed time \[#look-back-by-bars-or-elapsed-time] A previous bar can be more than an hour old when observations are missing. Choose the lookback that matches the rule you want to test: ```python title="Compare the previous bar with exactly one hour ago" >>> price = pd.Series( ... [100.0, 101.0, 104.0, 102.0], ... index=pd.to_datetime([ ... "2025-01-01 09:00", "2025-01-01 10:00", ... "2025-01-01 12:00", "2025-01-01 13:00", ... ]), ... ) >>> lookbacks = pd.DataFrame({ ... "price": price, ... "previous_bar": price.vbt.ago(1), ... "one_hour_ago": price.vbt.ago("1h"), ... }) >>> lookbacks price previous_bar one_hour_ago 2025-01-01 09:00:00 100.0 NaN NaN 2025-01-01 10:00:00 101.0 100.0 100.0 2025-01-01 12:00:00 104.0 101.0 NaN 2025-01-01 13:00:00 102.0 104.0 104.0 ``` At noon, the previous bar is from 10:00, while the exact one-hour lookup has no observation to return. `any_ago` and `all_ago` extend the idea to recent events, such as whether a condition was true at any point during the last hour or throughout the last five bars. Calendar rules can also select recurring points and intervals, such as a weekday entry time or a trading-session window. Combine these masks with price conditions for [Trading signals](/features/indicators/trading-signals/), or use them to compare behavior by session on the [Intraday backtesting](/features/backtesting/intraday-and-tick-backtesting/) page. ## Cleaning and precision \[#cleaning-and-precision] `fillna`, `ffill`, `bfill`, and shifts work column by column in compiled code. Shifting with `fshift` and `bshift` fills the new gaps with a value of your choice, so an integer or boolean array keeps its type. Crossover checks can skip missing values with `skipna=True` instead of treating each gap as a break. For custom compiled rules, numerical helpers such as `is_close_nb` compare values with explicit absolute and relative tolerances. This is useful when rounding noise would otherwise turn an intended equality into a different decision. ## Apply, map, and reduce \[#apply-map-and-reduce] `map` transforms values one by one, `apply_along_axis` runs a function per column or row, and `reduce` turns each column into one value or one array, all with your own compiled functions. Meta methods go a step further and run one function over several aligned arrays at once, which is how custom indicators and metrics are built without writing loops in Python. The [Meta methods](#meta-methods) highlight below shows the pattern, and [Array expressions](#array-expressions) evaluate a formula string over named arrays. Group operations let you summarize observations by a calendar period or another label, while transformations can demean or normalize values for a signal. A custom rolling calculation can combine price, volume, and a benchmark through the same meta-method pattern. When the calculation becomes a reusable indicator, [Indicator development](/features/indicators/indicator-development/) adds named inputs, parameters, and outputs around it. ## Other utilities \[#other-utilities] `rebase` restarts a series at a chosen value, `proximity_apply` reduces windows around each element, `shuffle` reorders values within columns for randomized tests, and `squeeze_grouped` and `flatten_grouped` combine the columns of each group into one. Lower-level kernels also provide causal FIR filtering with your own coefficients and polynomial fitting for custom numerical work. ## Numba datetime \[#numba-datetime] New in 1.2.3 ✅ Numba functions cannot take a pandas datetime index directly. So, how do you connect data to time? VBT provides a collection of functions that work on timestamp integers to extract information from each timestamp, such as the current time and day of the week, to determine whether the bar is during trading hours. ```python title="Plot the percentage change from the start of the month to now" >>> @njit ... def month_start_pct_change_nb(arr, index): ... out = np.full(arr.shape, np.nan) ... for col in range(arr.shape[1]): ... for i in range(arr.shape[0]): ... if i == 0 or vbt.dt_nb.month_nb(index[i - 1]) != vbt.dt_nb.month_nb(index[i]): ... month_start_value = arr[i, col] ... else: ... out[i, col] = (arr[i, col] - month_start_value) / month_start_value ... return out >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"], start="2022", end="2023") >>> pct_change = month_start_pct_change_nb( ... vbt.to_2d_array(data.close), ... data.index.vbt.to_ns() # (1) ... ) >>> pct_change = data.symbol_wrapper.wrap(pct_change) >>> pct_change.vbt.plot().show() ``` 1. Convert the datetime index to nanosecond format. Bitcoin and Ethereum percentage change from the start of each month in 2022. [Figure data (JSON)](/assets/figures/features/productivity/numba-datetime.b4837f52d042.json) !!! info "Tutorial" Learn more in the [Signal development](/tutorials/signal-development) tutorial. ## Periods ago \[#periods-ago] New in 1.2.3 ✅ Instead of writing Numba functions, comparing values at different bars can also be done in a vectorized way with Pandas. VBT adds convenient accessor methods for looking back by timedeltas and checking whether events happened during a past period. ```python title="Check whether the price dropped for 5 consecutive bars" >>> data = vbt.YFData.pull("BTC-USD", start="2022-05", end="2022-08") >>> mask = (data.close < data.close.vbt.ago(1)).vbt.all_ago(5) >>> fig = data.plot(plot_volume=False) >>> mask.vbt.signals.ranges.plot_shapes( ... plot_close=False, ... fig=fig, ... add_shape_kwargs=dict(fillcolor="orangered") ... ) >>> fig.show() ``` Bitcoin price with highlighted ranges where price dropped for five consecutive bars. [Figure data (JSON)](/assets/figures/features/productivity/periods-ago.ce2f9924664f.json) !!! info "Tutorial" Learn more in the [Signal development](/tutorials/signal-development) tutorial. ## Meta methods \[#meta-methods] New in 1.0.0 ✅ Many methods, such as rolling apply, now come in two versions: regular (instance methods) and meta (class methods). Regular methods are bound to a single array and do not need metadata, while meta methods are not tied to any array. Their broadcasting and templating logic lets a custom function work with several named arrays at once, using the window boundaries and column index supplied by VBT. ```python title="Compute the rolling z-score on one array and the rolling correlation coefficient on two arrays" >>> @njit ... def zscore_nb(x): # (1) ... return (x[-1] - np.mean(x)) / np.std(x) >>> data = vbt.YFData.pull("BTC-USD", start="2020", end="2021") >>> data.close.rolling(14).apply(zscore_nb, raw=True) # (2) Date 2020-01-01 00:00:00+00:00 NaN ... 2020-12-27 00:00:00+00:00 1.543527 2020-12-28 00:00:00+00:00 1.734715 2020-12-29 00:00:00+00:00 1.755125 2020-12-30 00:00:00+00:00 2.107147 2020-12-31 00:00:00+00:00 1.781800 Freq: D, Name: Close, Length: 366, dtype: float64 >>> data.close.vbt.rolling_apply(14, zscore_nb) # (3) 2020-01-01 00:00:00+00:00 NaN ... 2020-12-27 00:00:00+00:00 1.543527 2020-12-28 00:00:00+00:00 1.734715 2020-12-29 00:00:00+00:00 1.755125 2020-12-30 00:00:00+00:00 2.107147 2020-12-31 00:00:00+00:00 1.781800 Freq: D, Name: Close, Length: 366, dtype: float64 >>> @njit ... def corr_meta_nb(from_i, to_i, col, a, b): # (4) ... a_window = a[from_i:to_i, col] ... b_window = b[from_i:to_i, col] ... return np.corrcoef(a_window, b_window)[1, 0] >>> data2 = vbt.YFData.pull(["ETH-USD", "XRP-USD"], start="2020", end="2021") >>> vbt.pd_acc.rolling_apply( # (5) ... 14, ... corr_meta_nb, ... vbt.Rep("a"), ... vbt.Rep("b"), ... broadcast_named_args=dict(a=data.close, b=data2.close) ... ) symbol ETH-USD XRP-USD Date 2020-01-01 00:00:00+00:00 NaN NaN ... ... ... 2020-12-27 00:00:00+00:00 0.636862 -0.511303 2020-12-28 00:00:00+00:00 0.674514 -0.622894 2020-12-29 00:00:00+00:00 0.712531 -0.773791 2020-12-30 00:00:00+00:00 0.839355 -0.772295 2020-12-31 00:00:00+00:00 0.878897 -0.764446 [366 rows x 2 columns] ``` 1. Provides access to the window only. 2. Using Pandas. 3. Using the regular method, which accepts the same function as Pandas. 4. Provides access to one or more entire arrays. 5. Using the meta method, which accepts metadata and variable arguments. ## Array expressions \[#array-expressions] New in 1.0.0 ✅ When combining multiple arrays, they often need to be aligned and broadcast before the operation itself. Pandas alone often falls short because it can be too strict. Fortunately, VBT includes an accessor class method that can take a regular Python expression, identify all variable names, extract the arrays from the current context, broadcast them, and then evaluate the expression (with support for [NumExpr](https://github.com/pydata/numexpr)!) ⌨️ ```python title="Evaluate a multiline array expression based on a Bollinger Bands indicator" >>> data = vbt.YFData.pull(["BTC-USD", "ETH-USD"]) >>> low = data.low >>> high = data.high >>> bb = vbt.talib("BBANDS").run(data.close) >>> upperband = bb.upperband >>> lowerband = bb.lowerband >>> bandwidth = (bb.upperband - bb.lowerband) / bb.middleband >>> up_th = vbt.Param([0.3, 0.4]) >>> low_th = vbt.Param([0.1, 0.2]) >>> expr = """ ... narrow_bands = bandwidth < low_th ... above_upperband = high > upperband ... wide_bands = bandwidth > up_th ... below_lowerband = low < lowerband ... (narrow_bands & above_upperband) | (wide_bands & below_lowerband) ... """ >>> mask = vbt.pd_acc.eval(expr) >>> mask.sum() low_th up_th symbol 0.1 0.3 BTC-USD 344 ETH-USD 171 0.4 BTC-USD 334 ETH-USD 158 0.2 0.3 BTC-USD 444 ETH-USD 253 0.4 BTC-USD 434 ETH-USD 240 dtype: int64 ``` # Workflow automation (/features/tooling/workflow-automation) How do you run research and data updates unattended and hear when something happens? VBT schedules Python jobs for trading research, such as an hourly data update that sends a Telegram alert when a signal fires, and adds parallel tasks, nested progress bars, and a command-line interface. ```python title="Update BTCUSDT hourly and alert on moving average crossovers, replayed over one week" >>> def signal_message(data): ... close = data.close.iloc[:-1] # (1) ... fast = vbt.MA.run(close, window=20) ... slow = vbt.MA.run(close, window=50) ... bar = f"{close.index[-1]:%Y-%m-%d %H:%M} BTCUSDT 20h MA crossed" ... if fast.ma_crossed_above(slow).iloc[-1]: ... return f"{bar} above 50h MA at {close.iloc[-1]:,.0f}" ... if fast.ma_crossed_below(slow).iloc[-1]: ... return f"{bar} below 50h MA at {close.iloc[-1]:,.0f}" >>> class AlertUpdater(vbt.DataUpdater): ... def __init__(self, data, notify, **kwargs): ... vbt.DataUpdater.__init__(self, data, notify=notify, **kwargs) ... self._notify = notify ... ... def update(self, **kwargs): ... vbt.DataUpdater.update(self, **kwargs) # (2) ... message = signal_message(self.data) ... if message is not None: ... self._notify(message) >>> data = vbt.BinanceData.pull( ... "BTCUSDT", timeframe="1h", start="2024-11-24", end="2024-12-01 00:01" ... ) >>> updater = AlertUpdater(data, notify=print) >>> for hour in pd.date_range("2024-12-01 01:00", periods=7 * 24, freq="h", tz="UTC"): ... updater.update(end=hour + pd.Timedelta(minutes=1)) # (3) 2024-12-01 20:00 BTCUSDT 20h MA crossed above 50h MA at 97,100 2024-12-02 12:00 BTCUSDT 20h MA crossed below 50h MA at 94,972 2024-12-04 07:00 BTCUSDT 20h MA crossed above 50h MA at 96,589 2024-12-06 09:00 BTCUSDT 20h MA crossed below 50h MA at 98,000 2024-12-07 07:00 BTCUSDT 20h MA crossed above 50h MA at 99,405 ``` 1. One minute after the hour, the newest bar has just opened and is still forming, so the check uses the bar that just closed. The time in each message is when that bar opened. 2. Fetches from the latest stored bar, refreshes that bar, and appends any newer bars. 3. Replays a week as if the job ran at one minute past every hour. A live run leaves out `end`. Five crossovers fired in that week. Each update fetched only the newest bars from Binance, so the same object can run for months without downloading the history again. To run it live, send the messages through a Telegram bot instead of `print` and let the scheduler call `update`: ```python title="Run the same job every hour and send alerts to Telegram" >>> bot = vbt.TelegramBot(token="YOUR_BOT_TOKEN") # (1) >>> bot.start(in_background=True) >>> updater = AlertUpdater(data, notify=bot.send_message_to_all) # (2) >>> updater.update_every("hour", "01:00") # (3) ``` 1. Requires the optional `python-telegram-bot` package and a token from Telegram's BotFather. 2. Sends each alert to every chat that has sent `/start` to the bot. 3. Runs at one minute past every hour until the process stops or `update` raises `vbt.CancelledError`. ## Choose a recurring workflow \[#choose-a-recurring-workflow] The same tools can run a data feed, a batch of backtests, or a regular report. Your Python function defines the work, and VBT handles when it runs and how repeated calls are collected: | What you want to automate | Tools to use | | -------------------------------------------------------- | --------------------------------------------------------------------------------- | | Refresh prices and check the latest signal | `DataUpdater` with a scheduled update and your own signal function. | | Keep market data on disk as new bars arrive | A data saver with scheduled updates. | | Repeat research across symbols, dates, or configurations | `Task`, `execute`, or the `iterated` decorator. | | Run a daily analysis and save the result | `ScheduleManager` calling a function that builds and saves your research objects. | ## Scheduling \[#scheduling] `vbt.ScheduleManager` runs any function on a schedule, with the interval, unit, weekday, and time in plain words, such as `every(10, "minutes")`, `every("hour", "01:00")`, or `every("monday", "09:30")`. Jobs run in a blocking loop or as an asyncio task in the background, which keeps a notebook usable while they run. Tags group jobs so they can be replaced or removed together. `vbt.DataUpdater` and the data savers on the [Data storage](/features/data/data-storage-and-databases/) page use the same scheduler, so updating a dataset, saving it to disk, and checking signals can share one job. Run the blocking scheduler in a Python process for an unattended job, or use `start_in_background` in a notebook with an active event loop and stop it with `stop`. The process or notebook session keeps the schedule running. For intervals aligned to clock boundaries, `zero_offset=True` can align recurring jobs, such as checks every ten minutes. A scheduled function can also rebuild indicators, run a parameter search, and save the resulting portfolios for later inspection. [Configuration and persistence](/features/tooling/configuration-and-persistence/) shows how to keep inputs, settings, and results together between runs. ## Tasks and iteration \[#tasks-and-iteration] `vbt.Task` packages a function with its arguments without running it, and `vbt.execute` runs a list of tasks one after another, in threads, or in processes, with a progress bar. `@vbt.iterated` turns a loop over one argument into a parallel run with labeled results, as the [Iterated decorator](#iterated-decorator) and [Tasks](#tasks) highlights below show. For reproducible random runs, `vbt.set_seed` seeds Python, NumPy, and Numba. Give independent randomized tasks their own explicit seeds so the experiment records which random inputs each task used. Use tasks for separate experiments that do not depend on each other's results. Use an iterated function when the same calculation repeats over symbols, time periods, or another argument. The execution and result-merging choices let you keep that calculation as an ordinary Python function. [Parallel execution and caching](/features/performance/parallel-execution-and-caching/) covers the available engines and ways to reuse completed work. ### Chain the steps of a job \[#chain-the-steps-of-a-job] Data objects also support `pipe` and `chain` for steps that depend on earlier outputs. A sequence can pull data, select symbols, add indicators, and pass the result to your own function. This keeps the data preparation you use interactively available to the same scheduled job. The [Data pipelines](/features/data/financial-data-pipelines/) page covers the preparation side. ## Progress \[#progress] Long VBT operations, such as data downloads, parameter sweeps, and task execution, show a progress bar once they run longer than two seconds, and it can be turned off or customized. Bars nest, so a loop over symbols, then parameters, then splits shows one line per level, as the [Nested progress bars](#nested-progress-bars) highlight below shows. Bars drawn from inside parallel workers interfere with each other, so pass `show_progress=False` to VBT calls that run inside workers, such as when another library parallelizes them. ## Command-line workflows \[#command-line-workflows] The `vbt` command runs in a terminal without a Python script. It can ask VBT's documentation assistant a question, search its knowledge base, and start or call the MCP server, as the [CLI](#cli) highlight below shows. ## Notifications \[#notifications] `vbt.TelegramBot` connects to Telegram through `python-telegram-bot`. Besides sending messages, it can answer commands you define, so a chat can ask the bot for the latest price or a portfolio summary. `send_giphy` attaches a GIF found by text through GIPHY. The CCXT and Polygon data classes retry requests that fail with network errors, and the TradingView class retries responses it cannot parse. These retries can recover from temporary failures before the configured attempts are exhausted. Custom HTTP integrations can use `requests_retry_session` to set retry counts, backoff, and retryable status codes. Alerts can report completed research as well as trading signals. Use your job's results to send a short summary, or define a bot command that reads a saved portfolio when you ask for it. The [Live simulation](/features/backtesting/live-simulation/) page shows how a portfolio can continue as new data arrives. ## CLI \[#cli] New in v2026.4.7 ✅ VBT now ships with a [Typer](https://typer.tiangolo.com/)-based command-line interface that lets you chat, search, and invoke MCP tools directly from the terminal. No Python script required. After installing the package, you can run the `vbt` command in your terminal to see all available commands. === "Chat" ```bash title="Ask VBT a question from the terminal" vbt chat "How to backtest a weekly rebalancing strategy?" # (1) ``` 1. Searches the documentation for relevant passages and uses a language model to answer, just like `vbt.chat()`. === "Quick chat" ```bash title="Ask VBT a quick question from the terminal" vbt quick-chat "What does size_type='target_percent' do?" # (1) ``` 1. Uses a faster answer model and BM25 keyword search. The search runs locally without preparing embeddings first. === "Interact" ```bash title="Ask VBT a question from the terminal with function calling enabled" vbt interact "Plot the equity curve for a 10/30 SMA crossover on BTC-USD" # (1) ``` 1. Wraps `vbt.interact()`, which enables function calling so the model can invoke MCP tools, run code, and return results. === "MCP" ```bash title="Start the MCP server or invoke a registered tool directly from the terminal" vbt mcp serve # (1) vbt mcp search "ValueError: group_by must form monolithic, sorted groups" # (2) vbt mcp search --call '{"kwargs": {"query": "ValueError: group_by must form monolithic, sorted groups"}}' # (3) ``` 1. Launch the MCP server for use with external clients. 2. Invoke any registered MCP tool directly from the command line without starting the server. 3. Pass any arguments to the tool using the `--call` option. The value should be a JSON string. !!! info The first time you run most of these commands, it may take a while to prepare documents. However, most of the preparation steps are cached and stored, so future calls will be much faster and will not require repeating the process. ## Iterated decorator \[#iterated-decorator] New in v2024.6.19 ✅ Thinking about parallelizing a for-loop? VBT has a decorator for that. ```python title="Emulate a parallelized nested loop to get Sharpe by year and month" >>> import calendar >>> data = vbt.YFData.pull("BTC-USD") >>> @vbt.iterated(over_arg="year", merge_func="column_stack", engine="pathos") # (1) ... @vbt.iterated(over_arg="month", merge_func="concat") # (2) ... def get_year_month_sharpe(data, year, month): # (3) ... mask = (data.index.year == year) & (data.index.month == month) ... if not mask.any(): ... return np.nan ... year_returns = data.loc[mask].returns ... return year_returns.vbt.returns.sharpe_ratio() >>> years = data.index.year.unique().sort_values().rename("year") >>> months = data.index.month.unique().sort_values().rename("month") >>> sharpe_matrix = get_year_month_sharpe( ... data, ... years, ... {calendar.month_abbr[month]: month for month in months}, # (4) ... ) >>> sharpe_matrix.transpose().vbt.heatmap( ... trace_kwargs=dict(colorscale="RdBu", zmid=0), ... yaxis=dict(autorange="reversed") ... ).show() ``` 1. Iterate over years (in parallel). 2. Iterate over months (sequentially). 3. The function is called for each combination of year and month. 4. Map month numbers to names and pass them as a dict. VBT will extract the keys and use them as labels. Monthly Sharpe ratio heatmap for Bitcoin grouped by year. [Figure data (JSON)](/assets/figures/features/productivity/iterated-decorator.a87ce0622201.json) ## Tasks \[#tasks] New in v2024.6.19 ✅ Testing multiple parameter combinations usually involves using the `@vbt.parameterized` decorator. But what if you want to test entirely uncorrelated configurations or even different functions? The latest addition to VBT lets you execute any sequence of unrelated tests in parallel by assigning each test to a task. ```python title="Simulate SL, TSL, and TP parameters in three separate processes and compare their expectancy" >>> data = vbt.YFData.pull("BTC-USD") >>> task1 = vbt.Task( # (1) ... vbt.PF.from_random_signals, ... data, ... n=100, seed=42, ... sl_stop=vbt.Param(np.arange(1, 51) / 100) ... ) >>> task2 = vbt.Task( ... vbt.PF.from_random_signals, ... data, ... n=100, seed=42, ... tsl_stop=vbt.Param(np.arange(1, 51) / 100) ... ) >>> task3 = vbt.Task( ... vbt.PF.from_random_signals, ... data, ... n=100, seed=42, ... tp_stop=vbt.Param(np.arange(1, 51) / 100) ... ) >>> pf1, pf2, pf3 = vbt.execute([task1, task2, task3], engine="pathos") # (2) >>> fig = pf1.trades.expectancy.rename("SL").vbt.plot() >>> pf2.trades.expectancy.rename("TSL").vbt.plot(fig=fig) >>> pf3.trades.expectancy.rename("TP").vbt.plot(fig=fig) >>> fig.show() ``` 1. A task consists of a function and the arguments you want to pass to that function. Just creating a task does not execute the function! 2. Execute all three tasks using multiprocessing. Expectancy across stop-loss, trailing stop-loss, and take-profit levels. [Figure data (JSON)](/assets/figures/features/productivity/tasks.f161dc45cfc4.json) ## Nested progress bars \[#nested-progress-bars] New in v2024.5.15 ✅ Progress bars are now aware of each other. When a new progress bar starts, it checks whether another progress bar with the same identifier has already finished its task. If so, the new progress bar will close itself and delegate its progress to the existing one. ```python title="Display progress of three parameters using nested progress bars" >>> symbols = ["BTC-USD", "ETH-USD"] >>> fast_windows = range(5, 105, 5) >>> slow_windows = range(5, 105, 5) >>> sharpe_ratios = dict() >>> with vbt.ProgressBar(total=len(symbols), bar_id="pbar1") as pbar1: # (1) ... for symbol in symbols: ... pbar1.set_description(dict(symbol=symbol), refresh=True) ... data = vbt.YFData.pull(symbol) ... ... with vbt.ProgressBar(total=len(fast_windows), bar_id="pbar2") as pbar2: # (2) ... for fast_window in fast_windows: ... pbar2.set_description(dict(fast_window=fast_window), refresh=True) ... ... with vbt.ProgressBar(total=len(slow_windows), bar_id="pbar3") as pbar3: # (3) ... for slow_window in slow_windows: ... if fast_window < slow_window: ... pbar3.set_description(dict(slow_window=slow_window), refresh=True) ... fast_sma = data.run("talib_func:sma", fast_window) ... slow_sma = data.run("talib_func:sma", slow_window) ... entries = fast_sma.vbt.crossed_above(slow_sma) ... exits = fast_sma.vbt.crossed_below(slow_sma) ... pf = vbt.PF.from_signals(data, entries, exits) ... sharpe_ratios[(symbol, fast_window, slow_window)] = pf.sharpe_ratio ... pbar3.update() ... ... pbar2.update() ... ... pbar1.update() ``` 1. Track iteration over symbols. 2. Track iteration over fast windows. 3. Track iteration over slow windows. Symbol 2/2: 100% Fast window 20/20: 100% Slow window 20/20: 100% ```python >>> sharpe_ratios = pd.Series(sharpe_ratios) >>> sharpe_ratios.index.names = ["symbol", "fast_window", "slow_window"] >>> sharpe_ratios symbol fast_window slow_window BTC-USD 5 10 1.063616 15 1.218345 20 1.273154 25 1.365664 30 1.394469 ... ETH-USD 80 90 0.582995 95 0.617568 85 90 0.701215 95 0.616037 90 95 0.566650 Length: 342, dtype: float64 ``` # About me (/about-me) I'm Oleg Polakow, the creator of [VectorBT](https://github.com/polakowo/vectorbt) and VectorBT PRO. I build quantitative software for a living and have worked in software for more than a decade. These days, most of that time goes into giving independent developers and traders better ways to test ideas, understand the results, and stay in control of their research. ## A little background \[#a-little-background] ![Oleg Polakow standing by the sea](/assets/images/about/oleg-polakow-travel.webp) I'm from Lviv, Ukraine. As a teenager, I joined Ukraine's Minor Academy of Sciences, where I assisted a professor and learned about quantum mechanics and astrophysics. I then studied physics at the University of Lviv for a year. Back then, I hoped to become a physicist. As part of my studies, I wrote a program in Pascal that calculated astronomical events. That was when I discovered that I enjoyed writing code even more than studying physics. At seventeen, I moved to Berlin alone and started over in a new country. I began studying Computer Science at TU Berlin. I later moved to Munich, switched to Information Systems with a stronger focus on business, and earned my master's degree from the Technical University of Munich. It wasn't an especially linear route, and I learned a lot as I went. Somewhere along the way, I also earned a black belt in Karate-Do. Science, software, and Karate may look unrelated, but all three reward curiosity, patience, and the ability to fail repeatedly without taking it personally. ## Before VectorBT \[#before-vectorbt] My education combined physics, computer science, software engineering, data, and business. I studied at the Technical University of Munich and spent an exchange year at the Technical University of Denmark. I was especially drawn to machine learning and big data. I liked taking a pile of numbers and finding out what it was actually trying to tell me. I learned most by building. My early work ranged from fraud detection with SAP HANA and research software for analyzing digital transformation to an iOS and server-side product with ZEISS and Python analytics at Peergrade. The projects were different, but each helped me discover how much I enjoyed building software around practical problems. ## How VectorBT began \[#how-vectorbt-began] I started building VectorBT in 2017 while working on a crypto monitoring system that followed hundreds of coins. I needed a faster and more flexible way to explore the data and test many ideas. Instead of running one strategy configuration after another, I represented many configurations as arrays and evaluated them together. That simple shift became the foundation of the project. I released VectorBT publicly in 2020 and have kept evolving it ever since. What began as a tool for high-speed parameter exploration grew into an open-source library, a professional research platform, and a community around both. The original architecture is still at the center of it all. VectorBT was supposed to solve one research problem. It responded by becoming my full-time job. ## How I think about research \[#how-i-think-about-research] VectorBT was built for exploring many possibilities, but I don't believe research should end by selecting the single "best" result. That is often a shortcut to overfitting. I would rather inspect the whole parameter surface, test different assets and periods, and understand why a strategy behaves the way it does. Speed matters because it gives us more room to ask better questions. I also prefer building blocks over black boxes. Data, indicators, signals, simulation, and analysis should be understandable on their own and flexible enough to combine in unusual ways. Many useful improvements began with a user showing me a problem I hadn't seen before. Real examples often make it clear what VectorBT needs next. ## How I build software \[#how-i-build-software] Software has never been easier to start building, and I like how many new ideas that makes possible. My own focus is on what happens after the prototype: making a system correct, coherent, and maintainable after years of growth. I stay close to the code and the people using it. I personally review, test, and revise every significant change. Sometimes I spend an unreasonable amount of time on something most users will never notice. Ideally, that is why they never notice it! ## Beyond the code \[#beyond-the-code] Away from work, I enjoy traveling, discovering new cultures, and practicing Shotokan Karate-Do. I tend to like activities where progress comes from curiosity, repetition, and occasionally being reminded that I know less than I thought. That may also explain why I still enjoy software. You can find my work and writing on [GitHub](https://github.com/polakowo) and [Medium](https://polakowo.medium.com/), connect with me on [LinkedIn](https://www.linkedin.com/in/polakowo/), or contact me at . # Python API (/api) [Members-only Python API](https://members.vectorbt.pro/api/) Access the API documentation for `vectorbtpro` to explore every class, function, and argument. Learn how they work together to create Pandas for quants! 🧬 Use the reference to verify signatures, parameters, return values, and relationships between objects while writing or debugging code. Also, explore the VBT's ecosystem visually with an interactive graph. For native interfaces, see the [Rust API](/rust-api/). # Pricing and membership (/become-a-member) Once you become an eligible member, you receive: **Private GitHub repository** You will be added as a collaborator. **Quant community** You will be invited to our community on Discord. **Exclusive content** You will be granted access to exclusive website content ✨ ## Choose your access \[#choose-your-access] ### Monthly Pay monthly and cancel anytime. Starts at **$25 a month** * [Join on GitHub](https://github.com/sponsors/polakowo/sponsorships?pay_prorated=false\&tier_id=124816): Card payments only. * [Join on Ko-fi](https://ko-fi.com/vectorbtpro/tiers): All major payment methods. * [Join on Patreon](https://github.com/sponsors/patreon/become-sponsor/polakowo?campaign_id=12220591\¢s=2500): PayPal, Apple Pay, Venmo, and card payments. For Patreon sponsorships, please subscribe via [GitHub Sponsors](https://github.com/sponsors/polakowo/) by clicking "Become a patron". ### 12-Month Pay once for one year of access. Starts at ~~$300~~ **$240** or ~~$25~~ **$20 a month** * [Join on Ko-fi](https://ko-fi.com/s/88d8ca176c): All major payment methods. * [Join on GitHub](https://github.com/sponsors/polakowo/sponsorships?tier_id=591330): Card payments only. * [Join on Stripe](https://buy.stripe.com/dRmfZh2uUfvw9fggYWdwc00): All major payment methods. * [Join on Patreon](https://www.patreon.com/posts/12-month-access-151073945?utm_medium=clipboard_copy\&utm_source=copyLink\&utm_campaign=postshare_creator\&utm_content=join_link): PayPal, Apple Pay, Venmo, and card payments. * [Join on Paddle](/become-a-member/): All major payment methods. Open the membership page to use Paddle checkout. * [Join on Gumroad](https://vectorbtpro.gumroad.com/l/12-month-access): PayPal, Apple Pay, Google Pay, Venmo, and card payments. ### Lifetime Pay once for lifetime access. Starts at **$500 one time** * [Join on Ko-fi](https://ko-fi.com/s/0a60e96ab8): All major payment methods. * [Join on GitHub](https://github.com/sponsors/polakowo/sponsorships?tier_id=591331): Card payments only. * [Join on Stripe](https://buy.stripe.com/9B64gzglK3MO9fgfUSdwc01): All major payment methods. * [Join on Patreon](https://www.patreon.com/posts/lifetime-access-151074215?utm_medium=clipboard_copy\&utm_source=copyLink\&utm_campaign=postshare_creator\&utm_content=join_link): PayPal, Apple Pay, Venmo, and card payments. * [Join on Paddle](/become-a-member/): All major payment methods. Open the membership page to use Paddle checkout. * [Join on Gumroad](https://vectorbtpro.gumroad.com/l/lifetime-access): PayPal, Apple Pay, Google Pay, Venmo, and card payments. For cryptocurrency, please contact me at . !!! tip "Tip" This is a limited-time offer for early contributors. With each new milestone, the price will gradually increase to match that of competitors. By sponsoring now, you become an early contributor and lock in this price to access all features that will be released. ## Questions before joining? \[#questions-before-joining] * [Which membership plan should I choose?](/faq/#membership-plan) * [Is there a free trial?](/faq/#free-trial) * [How soon will I receive access after payment?](/faq/#access-timing) * [What support is included?](/faq/#support) * [What does lifetime access include?](/faq/#lifetime-access) * [Can my team or company use VectorBT PRO?](/faq/#organization-access) * [Can I cancel a monthly membership?](/faq/#cancellation) [View all frequently asked questions](/faq/). Individual memberships are for personal, non-commercial use only. By becoming a member, you agree to the [Terms of Use](/terms/terms-of-use/). Sales tax may apply depending on your location. # Cookbook (/cookbook) [Members-only cookbook](https://members.vectorbt.pro/cookbook/) Explore concise and practical code snippets designed to help you tackle common backtesting challenges! 🧑‍🍳 Each recipe focuses on a recurring task, making it easy to find a useful pattern without reading a full tutorial. Explore the [tutorials](/tutorials/) for real-world use cases, or visit the [documentation](/documentation/) for an in-depth discussion of the underlying concepts and APIs. # Frequently asked questions (/faq) Browse by topic: [Plans and access](#plans-and-access) · [Using VectorBT PRO](#using-vectorbt-pro) · [Setup and compatibility](#setup-and-compatibility) ## Plans and access \[#plans-and-access] ### What does membership include? You get the complete VectorBT PRO package: the private GitHub repository, documentation and API references, tutorials, cookbook recipes, release notes, product updates, Discord support, and access to the private community. ### Is there a free trial? We use open-source [VectorBT](https://github.com/polakowo/vectorbt) as the trial. It is free, gives you a real feel for the array-based workflow, and lets you decide whether this way of working clicks with you. The public documentation and feature pages show what PRO adds on top. ### Which membership plan should I choose? Pick monthly if you want maximum flexibility, 12-month access if you are ready to commit for a year and save on the monthly price, or lifetime if you prefer one payment with no renewals. The product and member benefits are the same on every active plan. ### What does lifetime access include? Pay once and get lifetime access to the complete VectorBT PRO membership with no renewals. This includes the repository and its updates, the private website, Discord, and support, subject to the [Terms of Use](/terms/terms-of-use/). ### Can I switch to lifetime access? Yes. We credit half of your previous monthly payments toward lifetime access, with a minimum upgrade payment of $150. If you are still in your first month, the full first payment counts as credit. Email and we will calculate the upgrade for you ### Can my team or company use VectorBT PRO? Yes, organization access is available for internal, non-commercial work. If you want to use VectorBT PRO in a commercial product or service, email and we will find the right setup. The [software license](/terms/software-license/) has the full details. ### How soon will I receive access after payment? GitHub Sponsors is the fastest route: repository access is granted immediately. Other payment routes are processed within 24 hours. For Discord, join the server and post your GitHub username in the verification channel; we will review it and grant access within 24 hours. ### What support is included? Ask us anything about VectorBT PRO on Discord. We help with installation, APIs, research workflows, debugging, and your own implementations. The community is also a great place to compare approaches and learn how other members solve similar problems. ### Can I cancel a monthly membership? Absolutely. Cancel through your payment provider whenever you like, and your access will stay active until the end of the paid term. Refunds and statutory withdrawal rights depend on applicable law and any additional policy offered by the payment provider. The [Terms of Use](/terms/terms-of-use/) cover the details. ### What happens when my paid access ends? The latest version you installed keeps working. Access to the private repository, website, Discord, new releases, bug fixes, and support ends with the paid term. You can find more detail in the [license remarks](/terms/remarks/). ## Using VectorBT PRO \[#using-vectorbt-pro] ### What kind of product is VectorBT PRO? VectorBT PRO is a code-first toolkit for quantitative analysis, backtesting, and algorithmic trading research. It provides a Python package and a native Rust crate, both designed to run in your own environment and integrate into existing workflows. ### Which markets and asset classes can I research? VectorBT PRO is market-agnostic. Members use it with equities, cryptocurrencies, futures, foreign exchange, options, and other instruments. Supply the data you need and model the details that matter for that market, such as contract rules, fees, slippage, and execution behavior. ### Can I use my own data, broker, or exchange? Yes. Bring Pandas or array-based data, load local files and databases, use a built-in adapter, or write a custom data class. VectorBT PRO keeps the research layer flexible, so you can connect whichever data source, broker, or exchange fits your workflow. ### Does VectorBT PRO support live trading? Yes, as the research and signal engine inside your own trading system. A typical workflow pulls fresh data, runs VBT, extracts the latest signals or orders, and passes them to your broker or exchange interface. Your execution layer handles connectivity, state, and live risk controls. With the MCP server and modern coding agents, building that interface is more approachable than ever. ### How does VectorBT PRO help me avoid overfitting? VBT includes flexible cross-validation, robustness tests, and tools for analyzing out-of-sample behavior and parameter stability. Together, they help you understand whether an idea holds up across different market periods and configurations instead of trusting a single strong backtest. ### Can I use VectorBT PRO with a coding agent? Yes. The MCP server, CLI commands, LLM-ready documentation, and agent tools help compatible coding agents navigate the APIs, run real VBT code, and automate research workflows. You spend less time looking up syntax and more time working on the idea. ### Why buy VectorBT PRO when I can build my own with AI? AI can generate code quickly, but building and maintaining a serious research engine still takes time, tokens, and engineering judgment. Models need context, steering, and review, even for changes that look small. When you start from scratch, you also have to make every architectural choice, handle edge cases, test performance, and maintain the result. Ask an AI for a custom system to help you find an edge, and it may quietly steer you toward familiar patterns and a solution much like what everyone else is building. With VBT, thousands of hours of this work are already done and shared across members. You get a specialized system shaped by deliberate design decisions, lessons from real research, and improvements made every day. Because VBT includes the source code, MCP server, and agent tools, your AI can inspect and extend an existing system. You can spend your time and tokens on strategy ideas instead of rebuilding the same foundation. ## Setup and compatibility \[#setup-and-compatibility] ### How much Python experience do I need? Basic Python and some familiarity with Pandas or NumPy are enough to get started. VectorBT PRO is code-first, but you do not need to be an expert. Tutorials, cookbook recipes, documentation, Discord, and coding-agent tools can take you from a small example to a serious research workflow. ### Which operating systems and hardware are supported? VectorBT PRO runs on Linux, macOS, and Windows. We recommend WSL on Windows for the smoothest development experience. CPU and memory needs depend on the size of your data and parameter space. Chunking, caching, parallel execution, and distributed execution help when a workload grows. ### How do I install VectorBT PRO? Once GitHub access is active, install directly from the private repository with `uv` or `pip`. You can also clone it for development, use the included Docker environment, or run it in Google Colab. The private installation guide walks through every option. ### Can I use it in notebooks and existing projects? Yes. Use VectorBT PRO in scripts, applications, IDEs, Jupyter notebooks, or Google Colab like any other Python package. The repository also includes a ready-to-build JupyterLab Docker environment. ### Do I need Rust to use VectorBT PRO? No. The complete high-level workflow is available from Python, with Numba handling compatible numerical operations. The optional Rust extension comes as platform wheels, so you can use it without setting up a Rust toolchain. The Rust implementation is also available as a native crate if that is where you want to work. ### Can I migrate from open-source VectorBT? Yes. The core array-based ideas will feel familiar, but PRO is a substantial redesign rather than a drop-in replacement. Start in a dedicated environment, import `vectorbtpro` instead of `vectorbt`, and use the current documentation and examples while adapting your code. See [VectorBT PRO vs vectorbt](/getting-started/vectorbt-pro-vs-vectorbt/) for the differences and a migration example. ### How do I receive updates? New releases arrive through the private GitHub repository. Re-run your `uv` or `pip` install command to update, pull the latest changes if you work from a clone, or rebuild the Docker image if that is your setup. ### Can I use VectorBT PRO without an internet connection? Yes. Once installed, core calculations, local-data workflows, and offline knowledge tools work without an internet connection. Naturally, installing updates, fetching remote data, calling cloud services, and opening the website or Discord still need a connection. # Rust API (/rust-api) [Members-only Rust API](https://members.vectorbt.pro/rust-api/) Access the native API documentation for `vectorbtpro-rust` to explore its modules, functions, structs, enums, and traits. Learn how the same compute kernels power both native Rust projects and VBT's optional Python extension. Use the reference when building native integrations or tracing the kernels behind accelerated Python operations. For Python-facing objects, see the [Python API](/api/). # Benchmarks (/documentation/benchmarks) [Members-only documentation](https://members.vectorbt.pro/documentation/benchmarks/) Performance depends on the function, input shape, backend, and execution mode. This section explains VBT's correctness-aware benchmark system, targeted and full-matrix runs, generated reports, and the benchmark cache used by automatic backend selection. # Building blocks (/documentation/building-blocks) [Members-only documentation](https://members.vectorbt.pro/documentation/building-blocks/) This section explores the sub-packages, modules, and core classes that serve as building blocks for advanced functionality throughout VBT. It explains how these pieces fit together by gradually constructing a custom analysis class, covering the foundations needed to build efficient and flexible extensions of your own. # Data (/documentation/data) [Members-only documentation](https://members.vectorbt.pro/documentation/data/) Financial data rarely arrives in the shape a strategy needs. This section explains how VBT represents features and symbols, aligns time series, and manages the full lifecycle of a dataset through the `Data` class and its specialized subclasses. * [Management](https://members.vectorbt.pro/documentation/data/management): Understand data objects, symbols, features, alignment, and the dataset lifecycle * [Local](https://members.vectorbt.pro/documentation/data/local): Save, load, query, and update local data * [Remote](https://members.vectorbt.pro/documentation/data/remote): Retrieve and update data from remote providers * [Synthetic](https://members.vectorbt.pro/documentation/data/synthetic): Generate synthetic market data for testing and research * [Scheduling](https://members.vectorbt.pro/documentation/data/scheduling): Schedule recurring data updates and saves # Indicators (/documentation/indicators) [Members-only documentation](https://members.vectorbt.pro/documentation/indicators/) The indicator system turns calculation functions into reusable pipelines that accept inputs and parameters, produce labeled outputs, and support analysis across many configurations at once. * [Pipeline](https://members.vectorbt.pro/documentation/indicators/pipeline): Understand indicator pipelines, inputs, parameters, outputs, and execution * [Development](https://members.vectorbt.pro/documentation/indicators/development): Turn custom calculations into reusable indicators * [Analysis](https://members.vectorbt.pro/documentation/indicators/analysis): Analyze indicator outputs with helper methods, indexing, statistics, and plots * [Parsers](https://members.vectorbt.pro/documentation/indicators/parsers): Parse third-party indicators and build indicators from expressions # Internals (/documentation/internals) [Members-only documentation](https://members.vectorbt.pro/documentation/internals/) Membership includes the full source code. This section maps the repository layers, traces how a call becomes a result, defines the terms used across the codebase, and documents the patterns, style, and tests that new code follows. * [Architecture](https://members.vectorbt.pro/documentation/internals/architecture): Find where each concern lives and which layers may depend on which * [Lifecycle](https://members.vectorbt.pro/documentation/internals/lifecycle): Trace a call from its entry point to the wrapped result * [Patterns](https://members.vectorbt.pro/documentation/internals/patterns): Apply the structural patterns used across the codebase * [Performance](https://members.vectorbt.pro/documentation/internals/performance): Write fast kernels, Rust mirrors, and the Python layers around them * [Glossary](https://members.vectorbt.pro/documentation/internals/glossary): Look up domain and codebase terms * [Installation from source](https://members.vectorbt.pro/documentation/internals/installation): Install and update VBT from a repository checkout * [Development](https://members.vectorbt.pro/documentation/internals/development): Follow checklists for changes that span several files * [Testing](https://members.vectorbt.pro/documentation/internals/testing): Run, write, and debug tests, and pick which to run for a change * [Style guide](https://members.vectorbt.pro/documentation/internals/style): Follow the style rules for code, docstrings, documentation, and tests # Portfolio (/documentation/portfolio) [Members-only documentation](https://members.vectorbt.pro/documentation/portfolio/) Portfolio modeling connects trading rules with a realistic simulation state and reconstructs the result into orders, trades, positions, drawdowns, returns, and other analysis objects. This section explains that lifecycle and the main simulation interfaces. * [Simulation](https://members.vectorbt.pro/documentation/portfolio/simulation): Understand simulation, reconstruction, portfolio state, and analysis objects * [From orders](https://members.vectorbt.pro/documentation/portfolio/from-orders): Simulate portfolios from explicit order information * [From signals](https://members.vectorbt.pro/documentation/portfolio/from-signals): Simulate portfolios from entries, exits, and stop logic # Rust (/documentation/rust) [Members-only documentation](https://members.vectorbt.pro/documentation/rust/) VBT can route compatible operations through its optional Rust extension while preserving the familiar Python interface. This section explains installation, automatic backend dispatch, interoperability with Numba, and direct access to native kernels when lower-level control is required. # Getting started (/getting-started) ![VectorBT PRO](/assets/logo/header.svg) Version: v2026.10.5 · Python: 3.11 · 3.12 · 3.13 · 3.14 · License: Proprietary · Build: Passing VectorBT® PRO is a high-performance, production-grade Python engine for backtesting, algorithmic trading, and quantitative research. It represents trading systems as multidimensional arrays, evaluates large parameter spaces at C speed, and keeps the full workflow accessible through familiar tools such as NumPy, Pandas, Plotly, and the broader scientific Python ecosystem. It is the actively developed, proprietary successor to the [vectorbt](https://github.com/polakowo/vectorbt) package. The PRO version extends those core ideas into a more complete research workflow: faster large-scale testing, stronger analysis tools, private documentation and tutorials, and built-in support for modern AI workflows. The result is a research environment that stays flexible as projects become more demanding, without forcing you into a closed platform or custom infrastructure. ## Highlights **Fast by design** Run broad parameter sweeps on arrays with Numba, chunking, and parallel execution. Test **more ideas in less time** without leaving Python. **Built for rigor** Use walk-forward optimization, purged and combinatorial cross-validation, robustness checks, split analytics, and parameter-surface inspection to evaluate ideas **more carefully** before deployment. **Practical workflow** Build strategies from **familiar components** such as data, indicators, signals, and portfolios. Examples and tutorials help you learn the workflow step by step. **AI-native** Built-in MCP server and CLI commands, function calling, LLM-friendly documentation, and agent support. Designed for **seamless integration with AI tools** for research, automation, and faster access to the docs. **Private community** Get access to a private Discord community with **1,000+ members** for support, discussion, updates, and shared ideas, plus a private GitHub repository and exclusive website content. **Modern Python stack** Whether you are new to coding or a seasoned programming expert, you will learn how to use **the latest Python tools** to your advantage in trading. **Appreciation** VBT is powered by its community. Financial contributions like yours ensure that the software remains safe to use for years to come. Thank you! ## What is VBT? \[#what-is-vbt] VBT is a high-performance Python package for researching trading strategies with fast array-based computation and rich analysis tools. A core idea in VBT is representing each trading setup as a set of multidimensional arrays, where each column corresponds to a distinct configuration of a strategy and its environment. That makes it possible to backtest large parameter grids at C speed while still inspecting the results with Python tools, giving you the best of both worlds. [Learn more about VBT fundamentals](/documentation/fundamentals/). ## Why VBT? \[#why-vbt] Many backtesting tools run as a single monolithic process. VBT takes a different approach and breaks the workflow into reusable components such as data, indicators, signals, allocations, and portfolios. You can test and analyze each part independently, combine them as needed, and inspect intermediate results before running the full backtest. This modular structure also makes it easier to integrate machine learning wherever it fits. VBT is also built for parameter exploration. Even large search spaces can often be tested quickly enough to build dashboards, inspect sensitivity, and see how small parameter changes affect results in real time. !!! example "Example" Pull the daily history of the BTC/USDT and ETH/USDT pairs from Binance, backtest nearly 20,000 MACD configurations in a RAM-efficient way, and visualize win rate as a function of the parameters, *in less than 30 seconds* 🧊 ```python from vectorbtpro import * @vbt.parameterized # (1) @vbt.chunked(chunk_len=1000) # (2) def pipeline( # (3) data: vbt.Param, fast: vbt.Chunked, slow: vbt.Chunked, signal: vbt.Chunked ) -> "concat": macd = vbt.talib("MACD").run(data.get("Close"), fast, slow, signal) entries = macd.macd_above(0) & macd.macd_above(macd.macdsignal) # (4) exits = macd.macd_below(0) | macd.macd_below(macd.macdsignal) # (5) pf = vbt.Portfolio.from_signals(data, entries, exits, freq="d") return pf.trades.win_rate data = vbt.BinanceData.pull(["BTCUSDT", "ETHUSDT"]) # (6) param_product = vbt.combine_params( # (7) dict( fast=np.arange(4, 31), slow=np.arange(4, 31), signal=np.arange(4, 31) ), build_index=False ) win_rates = pipeline(data, **param_product) # (8) win_rates.vbt.volume( # (9) slider_level="symbol", trace_kwargs=dict( colorscale="icefire", colorbar=dict(title='win_rate', tickformat='.0%'), cmid=0.5 ), ).show() ``` 1. Enhance the function to be parameterized. This allows running the same logic for each parameter combination in a loop. In this case, we define only one parameter: symbols (data). Other parameters will be pre-generated and chunked. 2. Enhance the function to be chunked. This allows splitting the parameter space into smaller chunks of 1000 combinations each. One chunk is processed at a time to save RAM. 3. Create a pipeline that returns the win rate for each parameter combination in the chunk. 4. Enter a position whenever the MACD line is above zero and the signal line. 5. Exit the position whenever the MACD line is below zero or the signal line. 6. Fetch both datasets. We will run the chunked pipeline for each dataset separately. 7. Generate 27 x 27 x 27 = 19,683 parameter combinations. Since fast and slow periods are conditionally bound, we could (and should) filter out combinations where the fast period is longer than the slow period, but this would only colorize half the cube. 8. Run the pipeline for both datasets and all parameter combinations. The results will be automatically concatenated into a single Series with a parameter multi-index. 9. Visualize the Series as a 3D volume plot. Since we have 4 parameters (symbol, fast, slow, signal), use the symbol parameter as a slider to switch between datasets. MACD parameter volume showing strategy win rate by fast, slow, and signal periods for Bitcoin and Ethereum. [Figure data (JSON)](/assets/figures/getting-started/macd-cube.8981ed37eae6.json) To reduce overfitting risk, VBT supports many cross-validation schemes and robustness tests to bring backtests closer to reality. We do not recommend blindly selecting the best parameter set. The main value of this workflow is understanding why a certain configuration behaves the way it does. ## What are prerequisites? \[#what-are-prerequisites] VBT is not a narrow, command-driven backtesting framework. Instead of forcing the full workflow into a fixed set of commands, it follows a data science approach: working with arrays, combining Python packages, building visualizations, and inspecting intermediate results along the way. That flexibility is one of its strengths, but it also means some familiarity with Python and scientific computing will help you get productive faster. If you are still building that background, the documentation, tutorials, and community can help you get started 🤝 ## Coming from vectorbt? \[#coming-from-vectorbt] VectorBT PRO is the successor to the open-source vectorbt, developed by the same author. It keeps the array-based approach, so your ideas, notebooks, and habits carry over. On top of it, PRO adds tools for validating strategies out of sample, simulating more realistic orders, scaling research across cores and machines, optimizing portfolios, and working with AI coding assistants. PRO is a redesign rather than a drop-in replacement, so existing code needs some changes. The [VectorBT PRO vs vectorbt](/getting-started/vectorbt-pro-vs-vectorbt/) comparison covers the differences and walks through a migration. ## What members get? \[#what-members-get] ### Installation Guide + Subscriber Perks on YouTube [YouTube video player](https://www.youtube.com/watch?v=GkJEQ4fm2_E) VBT is distributed through a private GitHub repository. Eligible sponsors receive collaborator access, which means new features are available as they ship, along with private documentation, tutorials, and examples. ### Screen capture of the private repository \[#screen-capture-of-the-private-repository] ![Screen capture of the private repository](/assets/screencapture-github.light.png#only-light) ![Screen capture of the private repository](/assets/screencapture-github.dark.png#only-dark) Eligible sponsors are also invited to a private Discord server for announcements, support, feature discussions, and direct feedback. ### Screen capture of the private Discord server \[#screen-capture-of-the-private-discord-server] ![Screen capture of the private Discord server](/assets/screencapture-discord.light.png#only-light) ![Screen capture of the private Discord server](/assets/screencapture-discord.dark.png#only-dark) ## How to get access? \[#how-to-get-access] [Become a member](/become-a-member/) and choose the plan that fits your needs. Membership gives you access to the private repository, exclusive documentation and tutorials, the Discord community, and ongoing product updates. The focus is practical: faster access to new capabilities, clearer learning material, and direct support while you build and test strategies. # Migrating from vectorbt (/getting-started/vectorbt-pro-vs-vectorbt) If you know the open-source vectorbt, what does VectorBT PRO add, what changes, and how do you move your code? This page compares vectorbt vs VectorBT PRO and shows a migration that reproduces the same backtest in both. ## Short answer \[#short-answer] VectorBT PRO takes the array-based research approach of vectorbt further: automate out-of-sample validation, simulate more detailed orders, scale searches across cores and machines, optimize portfolios, and work with AI coding assistants. It is the successor developed by the same author, with a redesigned API and a much broader set of research tools. The migration example below shows how to bring an existing strategy into PRO. ## What stays familiar \[#what-stays-familiar] Both editions represent each strategy configuration as a column of an array and run many of them at once. Both build on pandas accessors, broadcast inputs across assets and parameters, use an indicator factory with TA-Lib and other integrations, simulate portfolios from signals or orders with optional Numba callbacks, and analyze trades, drawdowns, and returns with Plotly charts. Your experience with vectorbt carries over, so you can build on familiar research patterns while adopting PRO's tools. ## Why upgrade to VectorBT PRO? \[#why-upgrade-to-vectorbt-pro] PRO gives you more control over the backtest and more ways to develop, validate, and scale your research. Build on your existing indicator sweeps and signal strategies with: * **Repeated research:** run your own function over parameter combinations, divide the work into chunks, and resume completed tasks instead of starting a long search again. * **More detailed simulation:** add limit orders, scale out through stop ladders, or continue the same portfolio as new bars arrive. * **Out-of-sample evaluation:** select settings on training periods, test them on later periods, and compare results across splits and randomized baselines. * **Help developing the code:** use current examples, member support, and tools that let your coding assistant inspect the installed API and run a backtest. You can bring your own data, indicators, and trading rules. Python remains the main high-level interface, and using PRO does not require learning Rust. The linked feature pages below show what each addition looks like in code. ## What PRO adds \[#what-pro-adds] | Area | VectorBT PRO adds | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Data | More [data sources](/features/data/market-data-sources/), [databases and file formats](/features/data/data-storage-and-databases/), and [safe alignment across timeframes](/features/data/multi-timeframe-analysis/) | | Indicators and signals | [Indicator expressions and more indicator libraries](/features/indicators/technical-indicators/), and [streaming indicators](/features/indicators/streaming-indicators/) that update one bar at a time | | Backtesting | [Limit and stop-entry orders](/features/backtesting/orders-and-execution/), [stop ladders and time stops](/features/backtesting/stop-loss-and-take-profit/), [leverage and contract multipliers](/features/backtesting/fees-slippage-and-leverage/), [cash deposits, withdrawals, and dividends](/features/backtesting/portfolio-accounting/), and [continuing a portfolio as new bars arrive](/features/backtesting/live-simulation/) | | Analysis | [Pattern search and event studies](/features/analytics/patterns-and-event-studies/), [MAE and MFE for every trade](/features/analytics/trade-analytics/), and [slicing and stacking](/features/tooling/multidimensional-research/) or [resampling](/features/data/multi-timeframe-analysis/) whole portfolios | | Strategy optimization and validation | [Parameter sweeps over any function](/features/optimization/strategy-optimization/), [walk-forward and purged cross-validation](/features/optimization/time-series-cross-validation/), and [robustness tests](/features/optimization/robustness-and-overfitting/) | | Portfolio optimization | [Scheduled rebalancing and allocation functions](/features/optimization/portfolio-optimization/), with external optimizers such as PyPortfolioOpt and Riskfolio-Lib | | Performance | [Chunking across threads, processes, and Ray, with resumable runs](/features/performance/parallel-execution-and-caching/), and the [`vectorbtpro-rust` crate](/features/performance/native-rust/) for strategies written and run in Rust, without Python | | Tooling and AI | [Configuration files](/features/tooling/configuration-and-persistence/), a [command-line interface](/features/tooling/workflow-automation/), [documentation search](/features/ai/knowledge-search/), an [AI research assistant](/features/ai/ai-research-assistant/), and an [MCP server](/features/ai/mcp-server/) for coding assistants | ### Cross-validation beyond basic splits \[#cross-validation-beyond-basic-splits] The community edition's rolling and expanding splitters divide arrays into windows. PRO adds a full cross-validation workflow: define rolling, expanding, calendar-based, purged, or custom splits, run your research function on them, select parameters on each training set, and evaluate the selected parameters on its test set. You can inspect the splits, apply purging and embargoing, and compare the resulting out-of-sample performance. This turns a repeated process of splitting data, running searches, selecting settings, and collecting test results into a reusable workflow. See [Walk-forward and cross-validation](/features/optimization/time-series-cross-validation/) for worked examples. PRO also includes the full source code, private documentation, tutorials, and cookbook recipes, and a Discord community for support and feature requests. The [features overview](/features/) covers these additions with examples. ## Performance \[#performance] PRO gives you several ways to scale a research workload: parallel kernels in Numba and Rust, chunked execution across threads, processes, and Ray, and backend selection from measured timings. Both editions support Numba and Rust kernels from Python. PRO builds on compiled calculations with tools for distributing work, controlling memory use, and reusing completed results. Beyond a Rust backend, PRO ships an entire native Rust crate, with simulators, steppers, and strategy callbacks that run in Rust programs without Python. How much faster a workload runs depends on its size and shape. The [Benchmarks](/features/performance/benchmarks/) page shows measured results with their hardware and library versions. ## Migrating code \[#migrating-code] The same strategy, a crossover of two exponential moving averages with a 10% trailing stop, in both editions on the same daily Bitcoin OHLC bars, saved to a CSV file. Passing open, high, and low lets the stop trigger inside a bar instead of only at the close: ```python title="Before: vectorbt" import pandas as pd import vectorbt as vbt ohlc = pd.read_csv("btc.csv", index_col=0, parse_dates=True) fast = vbt.MA.run(ohlc["Close"], 10, ewm=True) slow = vbt.MA.run(ohlc["Close"], 50, ewm=True) entries = fast.ma_crossed_above(slow) exits = fast.ma_crossed_below(slow) pf = vbt.Portfolio.from_signals( ohlc["Close"], entries, exits, open=ohlc["Open"], high=ohlc["High"], low=ohlc["Low"], sl_stop=0.1, sl_trail=True, fees=0.001, freq="1D", ) print(round(pf.total_return(), 4), round(pf.sharpe_ratio(), 4), pf.trades.count()) ``` The direct port changes only what PRO renamed: ```python title="After: VectorBT PRO, direct port" import pandas as pd import vectorbtpro as vbt ohlc = pd.read_csv("btc.csv", index_col=0, parse_dates=True) fast = vbt.MA.run(ohlc["Close"], 10, wtype="exp") # (1) slow = vbt.MA.run(ohlc["Close"], 50, wtype="exp") entries = fast.ma_crossed_above(slow) exits = fast.ma_crossed_below(slow) pf = vbt.PF.from_signals( ohlc["Close"], entries, exits, open=ohlc["Open"], high=ohlc["High"], low=ohlc["Low"], tsl_stop=0.1, # (2) fees=0.001, freq="1D", ) print(round(pf.total_return, 4), round(pf.sharpe_ratio, 4), pf.trades.count()) # (3) ``` 1. The moving average type is a parameter, `wtype`, instead of the `ewm` flag. 2. A trailing stop has its own argument, `tsl_stop`, instead of `sl_stop` with `sl_trail=True`. 3. `total_return` and `sharpe_ratio` are properties, so they take no parentheses. `pf.get_total_return()` accepts arguments. The upgrade path loads the file into a data object, which keeps the columns together and hands them to indicators and the portfolio by name: ```python title="After: VectorBT PRO, with a data object" import vectorbtpro as vbt data = vbt.CSVData.pull("btc.csv") # (1) fast = data.run(vbt.MA, 10, wtype="exp") # (2) slow = data.run(vbt.MA, 50, wtype="exp") entries = fast.ma_crossed_above(slow) exits = fast.ma_crossed_below(slow) pf = vbt.PF.from_signals(data, entries, exits, tsl_stop=0.1, fees=0.001) # (3) print(round(pf.total_return, 4), round(pf.sharpe_ratio, 4), pf.trades.count()) ``` 1. Each column becomes a feature of one data object, and the frequency is inferred from the index. 2. `data.run` passes the close to the indicator because it matches the indicator's `close` input. 3. The portfolio takes open, high, low, close, and frequency from the data object. ```text title="Output of all three" 3.6274 1.3232 20 ``` All three versions returned 362.74% with a Sharpe ratio of 1.32 over 20 trades on daily Bitcoin bars from 2020 to 2024. Other common changes: * Import `vectorbtpro` instead of `vectorbt`. Both use the `vbt` alias, so install PRO in its own environment. * Data classes load with `pull`, as in `vbt.YFData.pull("BTC-USD")`. `download` still works as an alias. * When a call fails, `vbt.phelp` prints the current signature and documentation of any function. Start by porting one small backtest on the same saved data, as above. Compare its signals, orders, and results before adding PRO features, since defaults and behavior can differ between the editions. The [Developer tools](/features/tooling/developer-tools/) page shows how to inspect signatures, source, and prepared inputs when adapting a more involved strategy. ## Access \[#access] VectorBT PRO is distributed through a private GitHub repository to members, who also get the private documentation, tutorials, and Discord community. Monthly, 12-month, and lifetime plans are available with the same product and member benefits while active. A version you installed keeps working after your access ends. Access to the private repository, website, Discord, updates, and support ends with the paid term. The open-source vectorbt serves as the free trial. See [Pricing and membership](/become-a-member/) and the [FAQ](/faq/) for details. ## Related pages \[#related-pages] * [Getting started](/getting-started/): Learn what VectorBT PRO is and how to get access * [Features](/features/): Explore backtesting, indicators, optimization, and analysis across instruments, parameters, and time * [Benchmarks](/features/performance/benchmarks/): Compare simulators on the same orders and measure each backend on your own machine * [Frequently asked questions](/faq/#oss-migration): Get straight answers about VectorBT PRO, membership, access, setup, and usage # Basic RSI strategy (/tutorials/basic-rsi) [Members-only tutorial](https://members.vectorbt.pro/tutorials/basic-rsi/) ✅ Learn the essentials of VBT by backtesting a basic RSI strategy. # Cross-validation (/tutorials/cross-validation) [Members-only tutorial](https://members.vectorbt.pro/tutorials/cross-validation/) When trading strategies that have shown strong performance in backtesting are applied to new data, they often prove to be fragile or may even fail catastrophically. This usually happens due to backtest overfitting, which can be detected and avoided with proper cross-validation. ✅ We will start with manual cross-validation, then cover different splitting schemes and techniques for analyzing split distributions. Finally, we will go over how to automate various cross-validation steps, from splitting regular arrays and complex VBT objects to testing entire parameter-based and ML-based pipelines 🔥 * [Workflow](https://members.vectorbt.pro/tutorials/cross-validation/workflow): Understand validation schemes and diagnose backtest overfitting * [Splitter](https://members.vectorbt.pro/tutorials/cross-validation/splitter): Build a splitter for cross-validation * [Applications](https://members.vectorbt.pro/tutorials/cross-validation/applications): Apply a splitter for cross-validation # From Python to Rust (/tutorials/from-python-to-rust) [Members-only tutorial](https://members.vectorbt.pro/tutorials/from-python-to-rust/) Backtesting code often grows up with its strategy. It starts as a few lines in a notebook, and it can end up as a service with no Python in it at all. This three-part tutorial takes one volatility-squeeze breakout along that path. The data and the rules never change, so the only difference between the versions is how they are written. ✅ Learn how to write the same strategy four times, from short research code down to a standalone program that runs without Python. All four are then checked against each other, order for order. ✅ Some rules cannot be prepared in advance, because they depend on what the strategy just did. Learn where a rule like that belongs, and see it produce the one result in this tutorial that could not have been worked out before the simulation ran. ✅ Finally, learn how to carry one portfolio forward as new bars arrive, instead of rerunning the whole backtest each time, and how a Rust process picks up where it left off after a restart 🔄 * [Static simulation](https://members.vectorbt.pro/tutorials/from-python-to-rust/static): Backtest the same strategy with high-level VBT, Numba, PyO3 Rust, and native Rust * [Dynamic simulation](https://members.vectorbt.pro/tutorials/from-python-to-rust/dynamic): Implement stateful portfolio callbacks and stream the same strategy in native Rust * [Live simulation](https://members.vectorbt.pro/tutorials/from-python-to-rust/live): Continue a path-dependent simulation as new bars arrive and preserve it across restarts # MTF analysis (/tutorials/mtf-analysis) [Members-only tutorial](https://members.vectorbt.pro/tutorials/mtf-analysis/) ✅ Learn about resampling and how to properly change the timeframe of retrieved data. ✅ Learn how to align multiple time series with different timeframes. In particular, we will discuss how to avoid look-ahead bias when doing this, and how to build multi-timeframe (MTF) indicators and graphs. ✅ Aggregation is a powerful technique for discovering larger trends. Learn how to aggregate data effectively, and how to model a portfolio using the most granular data, then downsample it afterward for analysis ☄️ * [Resampling](https://members.vectorbt.pro/tutorials/mtf-analysis/resampling): Resample market data and establish a multi-timeframe workflow * [Alignment](https://members.vectorbt.pro/tutorials/mtf-analysis/alignment): Align data across multiple timeframes * [Aggregation](https://members.vectorbt.pro/tutorials/mtf-analysis/aggregation): Aggregate data across multiple timeframes # Pairs trading (/tutorials/pairs-trading) [Members-only tutorial](https://members.vectorbt.pro/tutorials/pairs-trading/) ✅ Learn how to design and develop a pairs trading strategy! You will explore how to implement the strategy using four different approaches, each suited to a specific purpose. You will also perform large-scale parameter optimization using parameterization, chunking, infinite search, and [Optuna](https://optuna.org/) to fine-tune the strategy for the best results 👌 # Patterns and projections (/tutorials/patterns-and-projections) [Members-only tutorial](https://members.vectorbt.pro/tutorials/patterns-and-projections/) Chart patterns are a fundamental aspect of technical analysis. With VBT's excellent performance, you can detect chart patterns in your data using traditional methods, without needing to rely on costly machine learning models. ✅ Learn how to detect chart patterns, analyze them both visually and technically, combine multiple patterns to identify convergence, divergence, and other complex events, and convert them into a format suitable for backtesting. ✅ Learn how to analyze and visualize the impact of events on price movement using projections. Just like [Toggle](https://toggle.ai/), but with unlimited customization and analysis capabilities. * [Patterns](https://members.vectorbt.pro/tutorials/patterns-and-projections/patterns): Identify patterns in price data * [Projections](https://members.vectorbt.pro/tutorials/patterns-and-projections/projections): Generate projections of future prices # Portfolio optimization (/tutorials/portfolio-optimization) [Members-only tutorial](https://members.vectorbt.pro/tutorials/portfolio-optimization/) Are you looking to build a portfolio that achieves the highest possible return while keeping the risk at a level you are comfortable with? ✅ Learn how to design and implement your own portfolio optimization models 🎂 ✅ Discover how VBT integrates with third-party libraries such as [PyPortfolioOpt](https://pyportfolioopt.readthedocs.io/en/latest/), [Riskfolio-Lib](https://github.com/dcajasn/Riskfolio-Lib), and [Universal Portfolios](https://github.com/Marigold/universal-portfolios) to enable rebalancing with just a few lines of code! ✅ Learn how to rebalance dynamically using Numba. We will implement a threshold rebalancing template that can be used with any optimization function. As a bonus, we will build a mean-variance optimizer (MVO) from scratch for a significant performance boost 💨 * [Models](https://members.vectorbt.pro/tutorials/portfolio-optimization/models): Design and implement portfolio optimization models * [Integrations](https://members.vectorbt.pro/tutorials/portfolio-optimization/integrations): Integrate third-party portfolio optimization libraries * [Dynamic](https://members.vectorbt.pro/tutorials/portfolio-optimization/dynamic): Optimize portfolios dynamically # Signal development (/tutorials/signal-development) [Members-only tutorial](https://members.vectorbt.pro/tutorials/signal-development/) Signals are among the most powerful tools for simulating trading strategies with VBT. ✅ Learn how to convert any trading strategy into signals using both vectorized and iterative methods, and how to analyze their distribution to uncover logical flaws in the strategy 🌗 * [Generation](https://members.vectorbt.pro/tutorials/signal-development/generation): Generate trading signals * [Pre-analysis](https://members.vectorbt.pro/tutorials/signal-development/pre-analysis): Pre-analyze and rank signals # Stop signals (/tutorials/stop-signals) [Members-only tutorial](https://members.vectorbt.pro/tutorials/stop-signals/) Stop orders are a vital part of an investor's toolkit. They help limit losses on a security position and secure profits. But what would be the optimal combination of stop types and values for a specific market regime? ✅ Learn how to run 2 million tests in just a few minutes to answer this question for top cryptocurrency markets. Unlike [the open-source article](https://medium.datadriveninvestor.com/stop-loss-trailing-stop-or-take-profit-2-million-backtests-shed-light-dde23bda40be), we will also include the stop price in our analysis to improve accuracy! # SuperFast SuperTrend (/tutorials/superfast-supertrend) [Members-only tutorial](https://members.vectorbt.pro/tutorials/superfast-supertrend/) ✅ Learn how to design and unit test a streaming indicator that processes data in a single pass and updates with each new data point. We will use the streaming SuperTrend indicator as our example, making it the fastest SuperTrend ever built in Python! ✅ Due to the [GIL](https://realpython.com/python-gil/), most Python operations use only one core. Learn how to work around this limitation and build an indicator that uses all available cores! ✅ Learn how to design a proper backtesting pipeline. We will discuss and implement four different designs, ranging from the most modular and flexible to the fastest. As the cherry on top, we will perform 67,200 SuperTrend backtests in just one second! * [SuperTrend](https://members.vectorbt.pro/tutorials/superfast-supertrend/supertrend): Build the fastest SuperTrend indicator in Python * [Streaming](https://members.vectorbt.pro/tutorials/superfast-supertrend/streaming): Build a streaming SuperTrend indicator * [Multithreading](https://members.vectorbt.pro/tutorials/superfast-supertrend/multithreading): Parallelize a SuperTrend indicator * [Pipelines](https://members.vectorbt.pro/tutorials/superfast-supertrend/pipelines): Backtest a SuperTrend indicator