Skip to content

nb module

Numba-compiled functions.

Provides an arsenal of Numba-compiled functions that are used by accessors and in many other parts of the backtesting pipeline, such as technical indicators. These only accept NumPy arrays and other Numba-compatible types.

The module can be accessed directly via vbt.nb.

>>> import numpy as np
>>> import vectorbt as vbt

>>> # vectorbt.generic.nb.rolling_mean_1d_nb
>>> vbt.nb.rolling_mean_1d_nb(np.array([1, 2, 3, 4]), 2)
array([nan, 1.5, 2.5, 3.5])

Note

vectorbt treats matrices as first-class citizens and expects input arrays to be 2-dim, unless function has suffix _1d or is meant to be input to another function. Data is processed along index (axis 0).

Rolling functions with minp=None have min_periods set to the window size.

All functions passed as argument should be Numba-compiled.


ol_bshift_1d_nb function

_bshift_1d_nb(
    arr,
    n,
    fill_value
)

ol_bshift_nb function

_bshift_nb(
    arr,
    n,
    fill_value
)

ol_fshift_1d_nb function

_fshift_1d_nb(
    arr,
    n,
    fill_value
)

ol_fshift_nb function

_fshift_nb(
    arr,
    n,
    fill_value
)

ol_nancumprod_nb function

_nancumprod_nb(
    arr
)

ol_nancumsum_nb function

_nancumsum_nb(
    arr
)

ol_nanprod_nb function

_nanprod_nb(
    arr
)

ol_nansum_nb function

_nansum_nb(
    arr
)

ol_set_by_mask_1d_nb function

_set_by_mask_1d_nb(
    arr,
    mask,
    value
)

ol_set_by_mask_mult_1d_nb function

_set_by_mask_mult_1d_nb(
    arr,
    mask,
    values
)

ol_set_by_mask_mult_nb function

_set_by_mask_mult_nb(
    arr,
    mask,
    values
)

ol_set_by_mask_nb function

_set_by_mask_nb(
    arr,
    mask,
    value
)

any_squeeze_nb function

any_squeeze_nb(
    col,
    group,
    a
)

Return any (ignores NaNs) of a group.


apply_and_reduce_nb function

apply_and_reduce_nb(
    a,
    apply_func_nb,
    apply_args,
    reduce_func_nb,
    reduce_args
)

Apply apply_func_nb on each column and reduce into a single value using reduce_func_nb.

apply_func_nb should accept index of the column, the column itself, and *apply_args. Should return an array.

reduce_func_nb should accept index of the column, the array of results from apply_func_nb for that column, and *reduce_args. Should return a single value.


apply_nb function

apply_nb(
    a,
    apply_func_nb,
    *args
)

Apply function on each column.

apply_func_nb should accept index of the column, the array, and *args. Should return a single value or an array of shape a.shape[1].


applymap_nb function

applymap_nb(
    a,
    map_func_nb,
    *args
)

Map non-NA elements element-wise using map_func_nb.

map_func_nb should accept index of the row, index of the column, the element itself, and *args. Should return a single value.


argmax_reduce_nb function

argmax_reduce_nb(
    col,
    a
)

Return position of max.


argmin_reduce_nb function

argmin_reduce_nb(
    col,
    a
)

Return position of min.


bfill_1d_nb function

bfill_1d_nb(
    a
)

Fill NaNs by propagating first valid observation backward.

Numba equivalent to pd.Series(a).fillna(method='bfill').

Warning

This operation looks ahead.


bfill_nb function

bfill_nb(
    a
)

2-dim version of bfill_1d_nb().


bshift_1d_nb function

bshift_1d_nb(
    arr,
    n=1,
    fill_value=nan
)

Shift backward by n positions.

Numba equivalent to pd.Series(arr).shift(-n).

Warning

This operation looks ahead.


bshift_nb function

bshift_nb(
    arr,
    n=1,
    fill_value=nan
)

2-dim version of bshift_1d_nb().


count_reduce_nb function

count_reduce_nb(
    col,
    a
)

Return count (ignores NaNs).


crossed_above_1d_nb function

crossed_above_1d_nb(
    arr1,
    arr2,
    wait=0
)

Get the crossover of the first array going above the second array.


crossed_above_nb function

crossed_above_nb(
    arr1,
    arr2,
    wait=0
)

2-dim version of crossed_above_1d_nb().


dd_decline_duration_nb function

dd_decline_duration_nb(
    start_idx_arr,
    valley_idx_arr
)

Return the duration of the peak-to-valley phase of each drawdown record.


dd_drawdown_nb function

dd_drawdown_nb(
    peak_val_arr,
    valley_val_arr
)

Return the drawdown of each drawdown record.


dd_recovery_duration_nb function

dd_recovery_duration_nb(
    valley_idx_arr,
    end_idx_arr
)

Return the duration of the valley-to-recovery phase of each drawdown record.


dd_recovery_duration_ratio_nb function

dd_recovery_duration_ratio_nb(
    start_idx_arr,
    valley_idx_arr,
    end_idx_arr
)

Return the ratio of the recovery duration to the decline duration of each drawdown record.


dd_recovery_return_nb function

dd_recovery_return_nb(
    valley_val_arr,
    end_val_arr
)

Return the recovery return of each drawdown record.


describe_reduce_nb function

describe_reduce_nb(
    col,
    a,
    perc,
    ddof
)

Return descriptive statistics (ignores NaNs).

Numba equivalent to pd.Series(a).describe(perc).


diff_1d_nb function

diff_1d_nb(
    a,
    n=1
)

Return the 1-th discrete difference.

Numba equivalent to pd.Series(a).diff().


diff_nb function

diff_nb(
    a,
    n=1
)

2-dim version of diff_1d_nb().


ewm_mean_1d_nb function

ewm_mean_1d_nb(
    a,
    span,
    minp=0,
    adjust=False
)

Return exponential weighted average.

Numba equivalent to pd.Series(a).ewm(span=span, min_periods=minp, adjust=adjust).mean().

Adaptation of pd._libs.window.aggregations.window_aggregations.ewma with default arguments.


ewm_mean_nb function

ewm_mean_nb(
    a,
    span,
    minp=0,
    adjust=False
)

2-dim version of ewm_mean_1d_nb().


ewm_std_1d_nb function

ewm_std_1d_nb(
    a,
    span,
    minp=0,
    adjust=False,
    ddof=0
)

Return exponential weighted standard deviation.

Numba equivalent to pd.Series(a).ewm(span=span, min_periods=minp).std(ddof=ddof).

Adaptation of pd._libs.window.aggregations.window_aggregations.ewmcov with default arguments.


ewm_std_nb function

ewm_std_nb(
    a,
    span,
    minp=0,
    adjust=False,
    ddof=0
)

2-dim version of ewm_std_1d_nb().


expanding_apply_nb function

expanding_apply_nb(
    a,
    minp,
    apply_func_nb,
    *args
)

Expanding version of rolling_apply_nb().


expanding_matrix_apply_nb function

expanding_matrix_apply_nb(
    a,
    minp,
    apply_func_nb,
    *args
)

Expanding version of rolling_matrix_apply_nb().


expanding_max_1d_nb function

expanding_max_1d_nb(
    a,
    minp=1
)

Return expanding max.

Numba equivalent to pd.Series(a).expanding(min_periods=minp).max().


expanding_max_nb function

expanding_max_nb(
    a,
    minp=1
)

2-dim version of expanding_max_1d_nb().


expanding_mean_1d_nb function

expanding_mean_1d_nb(
    a,
    minp=1
)

Return expanding mean.

Numba equivalent to pd.Series(a).expanding(min_periods=minp).mean().


expanding_mean_nb function

expanding_mean_nb(
    a,
    minp=1
)

2-dim version of expanding_mean_1d_nb().


expanding_min_1d_nb function

expanding_min_1d_nb(
    a,
    minp=1
)

Return expanding min.

Numba equivalent to pd.Series(a).expanding(min_periods=minp).min().


expanding_min_nb function

expanding_min_nb(
    a,
    minp=1
)

2-dim version of expanding_min_1d_nb().


expanding_std_1d_nb function

expanding_std_1d_nb(
    a,
    minp=1,
    ddof=0
)

Return expanding standard deviation.

Numba equivalent to pd.Series(a).expanding(min_periods=minp).std(ddof=ddof).


expanding_std_nb function

expanding_std_nb(
    a,
    minp=1,
    ddof=0
)

2-dim version of expanding_std_1d_nb().


ffill_1d_nb function

ffill_1d_nb(
    a
)

Fill NaNs by propagating last valid observation forward.

Numba equivalent to pd.Series(a).fillna(method='ffill').


ffill_nb function

ffill_nb(
    a
)

2-dim version of ffill_1d_nb().


fillna_1d_nb function

fillna_1d_nb(
    a,
    value
)

Replace NaNs with value.

Numba equivalent to pd.Series(a).fillna(value).


fillna_nb function

fillna_nb(
    a,
    value
)

2-dim version of fillna_1d_nb().


filter_nb function

filter_nb(
    a,
    filter_func_nb,
    *args
)

Filter non-NA elements elementwise using filter_func_nb. The filtered out elements will become NA.

filter_func_nb should accept index of the row, index of the column, the element itself, and *args. Should return a bool.


find_ranges_nb function

find_ranges_nb(
    ts,
    gap_value
)

Find ranges and store their information as records to an array.

Usage

  • Find ranges in time series:
>>> import numpy as np
>>> import pandas as pd
>>> from vectorbt.generic.nb import find_ranges_nb

>>> ts = np.asarray([
...     [np.nan, np.nan, np.nan, np.nan],
...     [     2, np.nan, np.nan, np.nan],
...     [     3,      3, np.nan, np.nan],
...     [np.nan,      4,      4, np.nan],
...     [     5, np.nan,      5,      5],
...     [     6,      6, np.nan,      6]
... ])
>>> records = find_ranges_nb(ts, np.nan)

>>> pd.DataFrame.from_records(records)
   id  col  start_idx  end_idx
0   0    0          1        3
1   1    0          4        6
2   2    1          2        4
3   3    1          5        6
4   4    2          3        5
5   5    3          4        6

flat_reduce_grouped_nb function

flat_reduce_grouped_nb(
    a,
    group_lens,
    in_c_order,
    reduce_func_nb,
    *args
)

Same as reduce_grouped_nb() but passes flattened array.


flat_reduce_grouped_to_array_nb function

flat_reduce_grouped_to_array_nb(
    a,
    group_lens,
    in_c_order,
    reduce_func_nb,
    *args
)

Same as reduce_grouped_to_array_nb() but passes flattened 1D array.


flatten_forder_nb function

flatten_forder_nb(
    a
)

Flatten a in F order.


flatten_grouped_nb function

flatten_grouped_nb(
    a,
    group_lens,
    in_c_order
)

Flatten each group of columns.


flatten_uniform_grouped_nb function

flatten_uniform_grouped_nb(
    a,
    group_lens,
    in_c_order
)

Flatten each group of columns of the same length.


fshift_1d_nb function

fshift_1d_nb(
    arr,
    n=1,
    fill_value=nan
)

Shift forward by n positions.

Numba equivalent to pd.Series(arr).shift(n).


fshift_nb function

fshift_nb(
    arr,
    n=1,
    fill_value=nan
)

2-dim version of fshift_1d_nb().


get_drawdowns_nb function

get_drawdowns_nb(
    ts
)

Fill drawdown records by analyzing a time series.

Usage

>>> import numpy as np
>>> import pandas as pd
>>> from vectorbt.generic.nb import get_drawdowns_nb

>>> ts = np.asarray([
...     [1, 5, 1, 3],
...     [2, 4, 2, 2],
...     [3, 3, 3, 1],
...     [4, 2, 2, 2],
...     [5, 1, 1, 3]
... ])
>>> records = get_drawdowns_nb(ts)

>>> pd.DataFrame.from_records(records)
   id  col  peak_idx  start_idx  valley_idx  end_idx  peak_val  valley_val  \
0   0    1         0          1           4        4       5.0         1.0
1   1    2         2          3           4        4       3.0         1.0
2   2    3         0          1           2        4       3.0         1.0

   end_val  status
0      1.0       0
1      1.0       0
2      3.0       1

groupby_apply_nb function

groupby_apply_nb(
    a,
    groups,
    apply_func_nb,
    *args
)

Provide group-by calculations.

groups should be a dictionary, where each key is an index that points to an element in the new array where a group-by result will be stored, while the value should be an array of indices in a to apply apply_func_nb on.

apply_func_nb should accept indices of the group, index of the column, the array, and *args. Should return a single value.


groupby_matrix_apply_nb function

groupby_matrix_apply_nb(
    a,
    groups,
    apply_func_nb,
    *args
)

groupby_apply_nb() with apply_func_nb being applied on all columns at once.

apply_func_nb should accept indices of the group, the 2-dim array, and *args. Should return a single value or an array of shape a.shape[1].


max_reduce_nb function

max_reduce_nb(
    col,
    a
)

Return max (ignores NaNs).


max_squeeze_nb function

max_squeeze_nb(
    col,
    group,
    a
)

Return max (ignores NaNs) of a group.


mean_reduce_nb function

mean_reduce_nb(
    col,
    a
)

Return mean (ignores NaNs).


median_reduce_nb function

median_reduce_nb(
    col,
    a
)

Return median (ignores NaNs).


min_reduce_nb function

min_reduce_nb(
    col,
    a
)

Return min (ignores NaNs).


min_squeeze_nb function

min_squeeze_nb(
    col,
    group,
    a
)

Return min (ignores NaNs) of a group.


nancnt_nb function

nancnt_nb(
    a
)

Compute count while ignoring NaNs.


nancumprod_nb function

nancumprod_nb(
    arr
)

Numba equivalent of np.nancumprod along axis 0.


nancumsum_nb function

nancumsum_nb(
    arr
)

Numba equivalent of np.nancumsum along axis 0.


nanmax_nb function

nanmax_nb(
    a
)

Numba-equivalent of np.nanmax along axis 0.


nanmean_nb function

nanmean_nb(
    a
)

Numba-equivalent of np.nanmean along axis 0.


nanmedian_nb function

nanmedian_nb(
    a
)

Numba-equivalent of np.nanmedian along axis 0.


nanmin_nb function

nanmin_nb(
    a
)

Numba-equivalent of np.nanmin along axis 0.


nanprod_nb function

nanprod_nb(
    arr
)

Numba equivalent of np.nanprod along axis 0.


nanstd_1d_nb function

nanstd_1d_nb(
    a,
    ddof=0
)

Numba-equivalent of np.nanstd.


nanstd_nb function

nanstd_nb(
    a,
    ddof=0
)

2-dim version of nanstd_1d_nb().


nansum_nb function

nansum_nb(
    arr
)

Numba equivalent of np.nansum along axis 0.


nth_index_reduce_nb function

nth_index_reduce_nb(
    col,
    a,
    n
)

Return index of n-th element.


nth_reduce_nb function

nth_reduce_nb(
    col,
    a,
    n
)

Return n-th element.


pct_change_1d_nb function

pct_change_1d_nb(
    a,
    n=1
)

Return the percentage change.

Numba equivalent to pd.Series(a).pct_change().


pct_change_nb function

pct_change_nb(
    a,
    n=1
)

2-dim version of pct_change_1d_nb().


range_coverage_nb function

range_coverage_nb(
    start_idx_arr,
    end_idx_arr,
    status_arr,
    col_map,
    index_lens,
    overlapping=False,
    normalize=False
)

Get coverage of range records.

Set overlapping to True to get the number of overlapping steps. Set normalize to True to get the number of steps in relation either to the total number of steps (when overlapping=False) or to the number of covered steps (when overlapping=True).


range_duration_nb function

range_duration_nb(
    start_idx_arr,
    end_idx_arr,
    status_arr
)

Get duration of each duration record.


ranges_to_mask_nb function

ranges_to_mask_nb(
    start_idx_arr,
    end_idx_arr,
    status_arr,
    col_map,
    index_len
)

Convert ranges to 2-dim mask.


reduce_grouped_nb function

reduce_grouped_nb(
    a,
    group_lens,
    reduce_func_nb,
    *args
)

Reduce each group of columns into a single value using reduce_func_nb.

reduce_func_nb should accept index of the group, the array of row values, and *args. Should return a single value.


reduce_grouped_to_array_nb function

reduce_grouped_to_array_nb(
    a,
    group_lens,
    reduce_func_nb,
    *args
)

Reduce each group of columns into an array of values using reduce_func_nb.

reduce_func_nb same as for reduce_grouped_nb() but should return an array.

Note

Output of reduce_func_nb should be strictly homogeneous.


reduce_nb function

reduce_nb(
    a,
    reduce_func_nb,
    *args
)

Reduce each column into a single value using reduce_func_nb.

reduce_func_nb should accept index of the column, the array, and *args. Should return a single value.


reduce_to_array_nb function

reduce_to_array_nb(
    a,
    reduce_func_nb,
    *args
)

Reduce each column into an array of values using reduce_func_nb.

reduce_func_nb same as for reduce_nb() but should return an array.

Note

Output of reduce_func_nb should be strictly homogeneous.


rolling_apply_nb function

rolling_apply_nb(
    a,
    window,
    minp,
    apply_func_nb,
    *args
)

Provide rolling window calculations.

apply_func_nb should accept index of the row, index of the column, the array, and *args. Should return a single value.


rolling_matrix_apply_nb function

rolling_matrix_apply_nb(
    a,
    window,
    minp,
    apply_func_nb,
    *args
)

rolling_apply_nb() with apply_func_nb being applied on all columns at once.

apply_func_nb should accept index of the row, the 2-dim array, and *args. Should return a single value or an array of shape a.shape[1].


rolling_max_1d_nb function

rolling_max_1d_nb(
    a,
    window,
    minp=None
)

Return rolling max.

Numba equivalent to pd.Series(a).rolling(window, min_periods=minp).max().


rolling_max_nb function

rolling_max_nb(
    a,
    window,
    minp=None
)

2-dim version of rolling_max_1d_nb().


rolling_mean_1d_nb function

rolling_mean_1d_nb(
    a,
    window,
    minp=None
)

Return rolling mean.

Numba equivalent to pd.Series(a).rolling(window, min_periods=minp).mean().


rolling_mean_nb function

rolling_mean_nb(
    a,
    window,
    minp=None
)

2-dim version of rolling_mean_1d_nb().


rolling_min_1d_nb function

rolling_min_1d_nb(
    a,
    window,
    minp=None
)

Return rolling min.

Numba equivalent to pd.Series(a).rolling(window, min_periods=minp).min().


rolling_min_nb function

rolling_min_nb(
    a,
    window,
    minp=None
)

2-dim version of rolling_min_1d_nb().


rolling_std_1d_nb function

rolling_std_1d_nb(
    a,
    window,
    minp=None,
    ddof=0
)

Return rolling standard deviation.

Numba equivalent to pd.Series(a).rolling(window, min_periods=minp).std(ddof=ddof).


rolling_std_nb function

rolling_std_nb(
    a,
    window,
    minp=None,
    ddof=0
)

2-dim version of rolling_std_1d_nb().


row_apply_nb function

row_apply_nb(
    a,
    apply_func_nb,
    *args
)

Apply function on each row.

apply_func_nb should accept index of the row, the array, and *args. Should return a single value or an array of shape a.shape[1].


set_by_mask_1d_nb function

set_by_mask_1d_nb(
    arr,
    mask,
    value
)

Set each element to a value by boolean mask.


set_by_mask_mult_1d_nb function

set_by_mask_mult_1d_nb(
    arr,
    mask,
    values
)

Set each element in one array to the corresponding element in another by boolean mask.

values must be of the same shape as in the array.


set_by_mask_mult_nb function

set_by_mask_mult_nb(
    arr,
    mask,
    values
)

2-dim version of set_by_mask_mult_1d_nb().


set_by_mask_nb function

set_by_mask_nb(
    arr,
    mask,
    value
)

2-dim version of set_by_mask_1d_nb().


shuffle_1d_nb function

shuffle_1d_nb(
    a,
    seed=None
)

Shuffle each column in a.

Specify seed to make output deterministic.


shuffle_nb function

shuffle_nb(
    a,
    seed=None
)

2-dim version of shuffle_1d_nb().


squeeze_grouped_nb function

squeeze_grouped_nb(
    a,
    group_lens,
    squeeze_func_nb,
    *args
)

Squeeze each group of columns into a single column using squeeze_func_nb.

squeeze_func_nb should accept index of the row, index of the group, the array, and *args. Should return a single value.


std_reduce_nb function

std_reduce_nb(
    col,
    a,
    ddof
)

Return std (ignores NaNs).


sum_reduce_nb function

sum_reduce_nb(
    col,
    a
)

Return sum (ignores NaNs).


sum_squeeze_nb function

sum_squeeze_nb(
    col,
    group,
    a
)

Return sum (ignores NaNs) of a group.


value_counts_nb function

value_counts_nb(
    codes,
    n_uniques,
    group_lens
)

Return value counts per column/group.