Skip to content

accessors module

Custom pandas accessors.

Methods can be accessed as follows:

For example:

>>> import pandas as pd
>>> import vectorbt as vbt

>>> # vectorbt.base.accessors.BaseAccessor.make_symmetric
>>> pd.Series([1, 2, 3]).vbt.make_symmetric()
     0    1    2
0  1.0  2.0  3.0
1  2.0  NaN  NaN
2  3.0  NaN  NaN

It contains base methods for working with pandas objects. Most of these methods are adaptations of combine/reshape/index functions that can work with pandas objects. For example, broadcast() can take an arbitrary number of pandas objects, thus you can find its variations as accessor methods.

>>> sr = pd.Series([1])
>>> df = pd.DataFrame([1, 2, 3])

>>> vbt.base.reshape_fns.broadcast_to(sr, df)
   0
0  1
1  1
2  1
>>> sr.vbt.broadcast_to(df)
   0
0  1
1  1
2  1

Additionally, BaseAccessor implements arithmetic (such as +), comparison (such as >) and logical operators (such as &) by doing 1) NumPy-like broadcasting and 2) the compuation with NumPy under the hood, which is mostly much faster than with pandas.

>>> df = pd.DataFrame(np.random.uniform(size=(1000, 1000)))

>>> %timeit df * 2  # pandas
296 ms ± 27.4 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
>>> %timeit df.vbt * 2  # vectorbt
5.48 ms ± 1.12 ms per loop (mean ± std. dev. of 7 runs, 100 loops each)

Note

You should ensure that your *.vbt operand is on the left if the other operand is an array.

Accessors do not utilize caching.

Grouping is only supported by the methods that accept the group_by argument.

BaseAccessor class

BaseAccessor(
    obj,
    wrapper=None,
    **kwargs
)

Accessor on top of Series and DataFrames.

Accessible through pd.Series.vbt and pd.DataFrame.vbt, and all child accessors.

Series is just a DataFrame with one column, hence to avoid defining methods exclusively for 1-dim data, we will convert any Series to a DataFrame and perform matrix computation on it. Afterwards, by using BaseAccessor.wrapper, we will convert the 2-dim output back to a Series.

**kwargs will be passed to ArrayWrapper.

Superclasses

Inherited members

Subclasses

align_to method

BaseAccessor.align_to(
    other,
    wrap_kwargs=None
)

Align to other on their axes.

Usage

>>> import vectorbt as vbt
>>> import pandas as pd

>>> df1 = pd.DataFrame([[1, 2], [3, 4]], index=['x', 'y'], columns=['a', 'b'])
>>> df1
   a  b
x  1  2
y  3  4

>>> df2 = pd.DataFrame([[5, 6, 7, 8], [9, 10, 11, 12]], index=['x', 'y'],
...     columns=pd.MultiIndex.from_arrays([[1, 1, 2, 2], ['a', 'b', 'a', 'b']]))
>>> df2
       1       2
   a   b   a   b
x  5   6   7   8
y  9  10  11  12

>>> df1.vbt.align_to(df2)
      1     2
   a  b  a  b
x  1  2  1  2
y  3  4  3  4

apply method

BaseAccessor.apply(
    *args,
    apply_func=None,
    keep_pd=False,
    to_2d=False,
    wrap_kwargs=None,
    **kwargs
)

Apply a function apply_func.

Args

*args
Variable arguments passed to apply_func.
apply_func : callable

Apply function.

Can be Numba-compiled.

keep_pd : bool
Whether to keep inputs as pandas objects, otherwise convert to NumPy arrays.
to_2d : bool
Whether to reshape inputs to 2-dim arrays, otherwise keep as-is.
wrap_kwargs : dict
Keyword arguments passed to ArrayWrapper.wrap().
**kwargs
Keyword arguments passed to combine_func.

Note

The resulted array must have the same shape as the original array.

Usage

>>> import vectorbt as vbt
>>> import pandas as pd

>>> sr = pd.Series([1, 2], index=['x', 'y'])
>>> sr2.vbt.apply(apply_func=lambda x: x ** 2)
i2
x2    1
y2    4
z2    9
Name: a2, dtype: int64

apply_and_concat method

BaseAccessor.apply_and_concat(
    ntimes,
    *args,
    apply_func=None,
    keep_pd=False,
    to_2d=False,
    numba_loop=False,
    use_ray=False,
    keys=None,
    wrap_kwargs=None,
    **kwargs
)

Apply apply_func ntimes times and concatenate the results along columns. See apply_and_concat_one().

Args

ntimes : int
Number of times to call apply_func.
*args
Variable arguments passed to apply_func.
apply_func : callable

Apply function.

Can be Numba-compiled.

keep_pd : bool
Whether to keep inputs as pandas objects, otherwise convert to NumPy arrays.
to_2d : bool
Whether to reshape inputs to 2-dim arrays, otherwise keep as-is.
numba_loop : bool

Whether to loop using Numba.

Set to True when iterating large number of times over small input, but note that Numba doesn't support variable keyword arguments.

use_ray : bool

Whether to use Ray to execute combine_func in parallel.

Only works with numba_loop set to False and concat is set to True. See ray_apply() for related keyword arguments.

keys : index_like
Outermost column level.
wrap_kwargs : dict
Keyword arguments passed to ArrayWrapper.wrap().
**kwargs
Keyword arguments passed to combine_func.

Note

The resulted arrays to be concatenated must have the same shape as broadcast input arrays.

Usage

>>> import vectorbt as vbt
>>> import pandas as pd

>>> df = pd.DataFrame([[3, 4], [5, 6]], index=['x', 'y'], columns=['a', 'b'])
>>> df.vbt.apply_and_concat(3, [1, 2, 3],
...     apply_func=lambda i, a, b: a * b[i], keys=['c', 'd', 'e'])
      c       d       e
   a  b   a   b   a   b
x  3  4   6   8   9  12
y  5  6  10  12  15  18
  • Use Ray for small inputs and large processing times:
>>> def apply_func(i, a):
...     time.sleep(1)
...     return a

>>> sr = pd.Series([1, 2, 3])

>>> %timeit sr.vbt.apply_and_concat(3, apply_func=apply_func)
3.01 s ± 2.15 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

>>> %timeit sr.vbt.apply_and_concat(3, apply_func=apply_func, use_ray=True)
1.01 s ± 2.31 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

apply_on_index method

BaseAccessor.apply_on_index(
    apply_func,
    *args,
    axis=1,
    inplace=False,
    **kwargs
)

Apply function apply_func on index of the pandas object.

Set axis to 1 for columns and 0 for index. If inplace is True, modifies the pandas object. Otherwise, returns a copy.

broadcast class method

BaseAccessor.broadcast(
    *others,
    **kwargs
)

See broadcast().

broadcast_to method

BaseAccessor.broadcast_to(
    other,
    **kwargs
)

See broadcast_to().

combine method

BaseAccessor.combine(
    other,
    *args,
    allow_multiple=True,
    combine_func=None,
    keep_pd=False,
    to_2d=False,
    concat=False,
    numba_loop=False,
    use_ray=False,
    broadcast=True,
    broadcast_kwargs=None,
    keys=None,
    wrap_kwargs=None,
    **kwargs
)

Combine with other using combine_func.

Args

other : array_like
Object to combine this array with.
*args
Variable arguments passed to combine_func.
allow_multiple : bool
Whether a tuple/list will be considered as multiple objects in other.
combine_func : callable

Function to combine two arrays.

Can be Numba-compiled.

keep_pd : bool
Whether to keep inputs as pandas objects, otherwise convert to NumPy arrays.
to_2d : bool
Whether to reshape inputs to 2-dim arrays, otherwise keep as-is.
concat : bool

Whether to concatenate the results along the column axis. Otherwise, pairwise combine into a Series/DataFrame of the same shape.

If True, see combine_and_concat(). If False, see combine_multiple().

numba_loop : bool

Whether to loop using Numba.

Set to True when iterating large number of times over small input, but note that Numba doesn't support variable keyword arguments.

use_ray : bool

Whether to use Ray to execute combine_func in parallel.

Only works with numba_loop set to False and concat is set to True. See ray_apply() for related keyword arguments.

broadcast : bool
Whether to broadcast all inputs.
broadcast_kwargs : dict
Keyword arguments passed to broadcast().
keys : index_like
Outermost column level.
wrap_kwargs : dict
Keyword arguments passed to ArrayWrapper.wrap().
**kwargs
Keyword arguments passed to combine_func.

Note

If combine_func is Numba-compiled, will broadcast using WRITEABLE and C_CONTIGUOUS flags, which can lead to an expensive computation overhead if passed objects are large and have different shape/memory order. You also must ensure that all objects have the same data type.

Also remember to bring each in *args to a Numba-compatible format.

Usage

>>> import vectorbt as vbt
>>> import pandas as pd

>>> sr = pd.Series([1, 2], index=['x', 'y'])
>>> df = pd.DataFrame([[3, 4], [5, 6]], index=['x', 'y'], columns=['a', 'b'])

>>> sr.vbt.combine(df, combine_func=lambda x, y: x + y)
   a  b
x  4  5
y  7  8

>>> sr.vbt.combine([df, df*2], combine_func=lambda x, y: x + y)
    a   b
x  10  13
y  17  20

>>> sr.vbt.combine([df, df*2], combine_func=lambda x, y: x + y, concat=True, keys=['c', 'd'])
      c       d
   a  b   a   b
x  4  5   7   9
y  7  8  12  14
  • Use Ray for small inputs and large processing times:
>>> def combine_func(a, b):
...     time.sleep(1)
...     return a + b

>>> sr = pd.Series([1, 2, 3])

>>> %timeit sr.vbt.combine([1, 1, 1], combine_func=combine_func)
3.01 s ± 2.98 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

>>> %timeit sr.vbt.combine([1, 1, 1], combine_func=combine_func, concat=True, use_ray=True)
1.02 s ± 2.32 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

concat class method

BaseAccessor.concat(
    *others,
    broadcast_kwargs=None,
    keys=None
)

Concatenate with others along columns.

Args

*others : array_like
List of objects to be concatenated with this array.
broadcast_kwargs : dict
Keyword arguments passed to broadcast().
keys : index_like
Outermost column level.

Usage

>>> import vectorbt as vbt
>>> import pandas as pd

>>> sr = pd.Series([1, 2], index=['x', 'y'])
>>> df = pd.DataFrame([[3, 4], [5, 6]], index=['x', 'y'], columns=['a', 'b'])
>>> sr.vbt.concat(df, keys=['c', 'd'])
      c     d
   a  b  a  b
x  1  1  3  4
y  2  2  5  6

df_accessor_cls property

Accessor class for pd.DataFrame.

drop_duplicate_levels method

BaseAccessor.drop_duplicate_levels(
    keep=None,
    axis=1,
    inplace=False
)

See drop_duplicate_levels().

See BaseAccessor.apply_on_index() for other keyword arguments.

drop_levels method

BaseAccessor.drop_levels(
    levels,
    axis=1,
    inplace=False,
    strict=True
)

See drop_levels().

See BaseAccessor.apply_on_index() for other keyword arguments.

drop_redundant_levels method

BaseAccessor.drop_redundant_levels(
    axis=1,
    inplace=False
)

See drop_redundant_levels().

See BaseAccessor.apply_on_index() for other keyword arguments.

empty class method

BaseAccessor.empty(
    shape,
    fill_value=nan,
    **kwargs
)

Generate an empty Series/DataFrame of shape shape and fill with fill_value.

empty_like class method

BaseAccessor.empty_like(
    other,
    fill_value=nan,
    **kwargs
)

Generate an empty Series/DataFrame like other and fill with fill_value.

indexing_func method

BaseAccessor.indexing_func(
    pd_indexing_func,
    **kwargs
)

Perform indexing on BaseAccessor.

is_frame class method

BaseAccessor.is_frame()

is_series class method

BaseAccessor.is_series()

make_symmetric method

BaseAccessor.make_symmetric()

See make_symmetric().

obj property

Pandas object.

rename_levels method

BaseAccessor.rename_levels(
    name_dict,
    axis=1,
    inplace=False,
    strict=True
)

See rename_levels().

See BaseAccessor.apply_on_index() for other keyword arguments.

repeat method

BaseAccessor.repeat(
    n,
    keys=None,
    axis=1,
    wrap_kwargs=None
)

See repeat().

Set axis to 1 for columns and 0 for index. Use keys as the outermost level.

select_levels method

BaseAccessor.select_levels(
    level_names,
    axis=1,
    inplace=False
)

See select_levels().

See BaseAccessor.apply_on_index() for other keyword arguments.

sr_accessor_cls property

Accessor class for pd.Series.

stack_index method

BaseAccessor.stack_index(
    index,
    on_top=True,
    axis=1,
    inplace=False,
    **kwargs
)

See stack_indexes().

Set on_top to False to stack at bottom.

See BaseAccessor.apply_on_index() for other keyword arguments.

tile method

BaseAccessor.tile(
    n,
    keys=None,
    axis=1,
    wrap_kwargs=None
)

See tile().

Set axis to 1 for columns and 0 for index. Use keys as the outermost level.

to_1d_array method

BaseAccessor.to_1d_array()

Convert to 1-dim NumPy array

See to_1d().

to_2d_array method

BaseAccessor.to_2d_array()

Convert to 2-dim NumPy array.

See to_2d().

to_dict method

BaseAccessor.to_dict(
    **kwargs
)

See to_dict().

unstack_to_array method

BaseAccessor.unstack_to_array(
    **kwargs
)

See unstack_to_array().

unstack_to_df method

BaseAccessor.unstack_to_df(
    **kwargs
)

See unstack_to_df().

BaseDFAccessor class

BaseDFAccessor(
    obj,
    **kwargs
)

Accessor on top of DataFrames.

Accessible through pd.DataFrame.vbt and all child accessors.

Superclasses

Inherited members

Subclasses

is_frame class method

BaseDFAccessor.is_frame()

is_series class method

BaseDFAccessor.is_series()

BaseSRAccessor class

BaseSRAccessor(
    obj,
    **kwargs
)

Accessor on top of Series.

Accessible through pd.Series.vbt and all child accessors.

Superclasses

Inherited members

Subclasses

is_frame class method

BaseSRAccessor.is_frame()

is_series class method

BaseSRAccessor.is_series()