Skip to content

accessors module

Custom Pandas accessors for base operations with Pandas objects.

BaseAccessor class

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

Accessor on top of Series and DataFrames.

Accessible via 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.

Note

When using magic methods, ensure that .vbt is called on the operand 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.

Usage

  • Build a symmetric matrix:
>>> from vectorbtpro import *

>>> # vectorbtpro.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
  • Broadcast pandas objects:
>>> sr = pd.Series([1])
>>> df = pd.DataFrame([1, 2, 3])

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

>>> sr.vbt.broadcast_to(df)
   0
0  1
1  1
2  1

>>> from vectorbtpro.base.accessors import BaseAccessor

>>> # Same as sr.vbt.broadcast(df)
>>> new_sr, new_df = BaseAccessor.broadcast(sr, df)
>>> new_sr
   0
0  1
1  1
2  1
>>> new_df
   0
0  1
1  2
2  3
  • Instead of explicitly importing BaseAccessor or any other accessor, we can use pd_acc instead:
>>> vbt.pd_acc.broadcast(sr, df)
>>> new_sr
   0
0  1
1  1
2  1
>>> new_df
   0
0  1
1  2
2  3

>>> sr.vbt + df
   0
0  2
1  3
2  4

Many interesting use cases can be implemented this way.

  • For example, let's compare an array with 3 different thresholds:
>>> df.vbt > vbt.Param(np.arange(3), name='threshold')
threshold     0                  1                  2
             a2    b2    c2     a2    b2    c2     a2     b2    c2
x2         True  True  True  False  True  True  False  False  True
y2         True  True  True   True  True  True   True   True  True
z2         True  True  True   True  True  True   True   True  True
  • The same using the broadcasting mechanism:
>>> df.vbt > vbt.Param(np.arange(3), name='threshold')
threshold     0                  1                  2
             a2    b2    c2     a2    b2    c2     a2     b2    c2
x2         True  True  True  False  True  True  False  False  True
y2         True  True  True   True  True  True   True   True  True
z2         True  True  True   True  True  True   True   True  True

Superclasses

Inherited members

Subclasses

align class method

BaseAccessor.align(
    *others,
    **kwargs
)

Align objects using align_indexes.

align_to method

BaseAccessor.align_to(
    other,
    wrap_kwargs=None,
    **kwargs
)

Align to other on their axes using align_index_to.

Usage

>>> 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(
    apply_func,
    *args,
    keep_pd=False,
    to_2d=False,
    broadcast_named_args=None,
    broadcast_kwargs=None,
    template_context=None,
    wrap_kwargs=None,
    **kwargs
)

Apply a function apply_func.

Set keep_pd to True to keep inputs as pandas objects, otherwise convert to NumPy arrays.

Set to_2d to True to reshape inputs to 2-dim arrays, otherwise keep as-is.

*args and **kwargs are passed to apply_func.

Note

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

Usage

  • Using instance method:
>>> sr = pd.Series([1, 2], index=['x', 'y'])
>>> sr.vbt.apply(lambda x: x ** 2)
x    1
y    4
dtype: int64
  • Using class method, templates, and broadcasting:
>>> sr.vbt.apply(
...     lambda x, y: x + y,
...     vbt.Rep('y'),
...     broadcast_named_args=dict(
...         y=pd.DataFrame([[3, 4]], columns=['a', 'b'])
...     )
... )
   a  b
x  4  5
y  5  6

apply_and_concat method

BaseAccessor.apply_and_concat(
    ntimes,
    apply_func,
    *args,
    keep_pd=False,
    to_2d=False,
    keys=None,
    broadcast_named_args=None,
    broadcast_kwargs=None,
    template_context=None,
    wrap_kwargs=None,
    **kwargs
)

Apply apply_func ntimes times and concatenate the results along columns.

See apply_and_concat.

ntimes is the number of times to call apply_func, while n_outputs is the number of outputs to expect.

*args and **kwargs are passed to apply_and_concat.

Note

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

Usage

  • Using instance method:
>>> df = pd.DataFrame([[3, 4], [5, 6]], index=['x', 'y'], columns=['a', 'b'])
>>> df.vbt.apply_and_concat(
...     3,
...     lambda i, a, b: a * b[i],
...     [1, 2, 3],
...     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
  • Using class method, templates, and broadcasting:
>>> sr = pd.Series([1, 2, 3], index=['x', 'y', 'z'])
>>> sr.vbt.apply_and_concat(
...     3,
...     lambda i, a, b: a * b + i,
...     vbt.Rep('df'),
...     broadcast_named_args=dict(
...         df=pd.DataFrame([[1, 2, 3]], columns=['a', 'b', 'c'])
...     )
... )
apply_idx        0         1         2
           a  b  c  a  b   c  a  b   c
x          1  2  3  2  3   4  3  4   5
y          2  4  6  3  5   7  4  6   8
z          3  6  9  4  7  10  5  8  11
  • To change the execution engine or specify other engine-related arguments, use execute_kwargs:
>>> import time

>>> 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)
3.02 s ± 3.76 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

>>> %timeit sr.vbt.apply_and_concat(3, apply_func, execute_kwargs=dict(engine='dask'))
1.02 s ± 927 µs per loop (mean ± std. dev. of 7 runs, 1 loop each)

apply_to_index method

BaseAccessor.apply_to_index(
    *args,
    wrap=False,
    **kwargs
)

See Wrapping.apply_to_index.

Note

If wrap is False, returns Pandas object, not accessor!

broadcast class method

BaseAccessor.broadcast(
    *others,
    **kwargs
)

See broadcast.

broadcast_combs class method

BaseAccessor.broadcast_combs(
    *others,
    **kwargs
)

See broadcast_combs.

broadcast_to method

BaseAccessor.broadcast_to(
    other,
    **kwargs
)

See broadcast_to.

column_stack class method

BaseAccessor.column_stack(
    *objs,
    wrapper_kwargs=None,
    reindex_kwargs=None,
    **kwargs
)

Stack multiple BaseAccessor instances along columns.

Uses ArrayWrapper.column_stack to stack the wrappers.

combine class method

BaseAccessor.combine(
    obj,
    combine_func,
    *args,
    allow_multiple=True,
    keep_pd=False,
    to_2d=False,
    concat=None,
    keys=None,
    broadcast_named_args=None,
    broadcast_kwargs=None,
    template_context=None,
    wrap_kwargs=None,
    **kwargs
)

Combine with other using combine_func.

Args

obj : array_like
Object(s) to combine this array with.
combine_func : callable

Function to combine two arrays.

Can be Numba-compiled.

*args
Variable arguments passed to combine_func.
allow_multiple : bool

Whether a tuple/list/Index will be considered as multiple objects in other.

Takes effect only when using the instance method.

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. If None, becomes True if there are multiple objects to combine.

Can only concatenate using the instance method.

keys : index_like
Outermost column level.
broadcast_named_args : dict
Dictionary with arguments to broadcast against each other.
broadcast_kwargs : dict
Keyword arguments passed to broadcast.
template_context : dict
Context used to substitute templates in args and kwargs.
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

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

>>> # using instance method
>>> sr.vbt.combine(df, np.add)
   a  b
x  4  5
y  7  8

>>> sr.vbt.combine([df, df * 2], np.add, concat=False)
    a   b
x  10  13
y  17  20

>>> sr.vbt.combine([df, df * 2], np.add)
combine_idx     0       1
             a  b   a   b
x            4  5   7   9
y            7  8  12  14

>>> sr.vbt.combine([df, df * 2], np.add, keys=['c', 'd'])
      c       d
   a  b   a   b
x  4  5   7   9
y  7  8  12  14

>>> sr.vbt.combine(vbt.Param([1, 2], name='param'), np.add)
param  1  2
x      2  3
y      3  4

>>> # using class method
>>> sr.vbt.combine([df, df * 2], np.add, concat=False)
    a   b
x  10  13
y  17  20
  • Using class method, templates, and broadcasting:
>>> sr = pd.Series([1, 2, 3], index=['x', 'y', 'z'])
>>> sr.vbt.combine(
...     [1, 2, 3],
...     lambda x, y, z: x + y + z,
...     vbt.Rep('df'),
...     broadcast_named_args=dict(
...         df=pd.DataFrame([[1, 2, 3]], columns=['a', 'b', 'c'])
...     )
... )
combine_idx        0        1        2
             a  b  c  a  b  c  a  b  c
x            3  4  5  4  5  6  5  6  7
y            4  5  6  5  6  7  6  7  8
z            5  6  7  6  7  8  7  8  9
  • To change the execution engine or specify other engine-related arguments, use execute_kwargs:
>>> import time

>>> 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)
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, execute_kwargs=dict(engine='dask'))
1.02 s ± 2.18 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.

Usage

>>> 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

cross class method

BaseAccessor.cross(
    *others
)

Align objects using cross_indexes.

cross_with method

BaseAccessor.cross_with(
    other,
    wrap_kwargs=None
)

Align to other on their axes using cross_index_with.

Usage

>>> df1 = pd.DataFrame(
...     [[1, 2, 3, 4], [5, 6, 7, 8]],
...     index=['x', 'y'],
...     columns=pd.MultiIndex.from_arrays([[1, 1, 2, 2], ['a', 'b', 'a', 'b']])
... )
>>> df1
   1     2
   a  b  a  b
x  1  2  3  4
y  5  6  7  8

>>> df2 = pd.DataFrame(
...     [[9, 10, 11, 12], [13, 14, 15, 16]],
...     index=['x', 'y'],
...     columns=pd.MultiIndex.from_arrays([[3, 3, 4, 4], ['a', 'b', 'a', 'b']])
... )
>>> df2
    3       4
    a   b   a   b
x   9  10  11  12
y  13  14  15  16

>>> df1.vbt.cross_with(df2)
   1           2
   3     4     3     4
   a  b  a  b  a  b  a  b
x  1  2  1  2  3  4  3  4
y  5  6  5  6  7  8  7  8

df_accessor_cls hybrid_property

Accessor class for pd.DataFrame.

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.

eval class method

BaseAccessor.eval(
    expr,
    frames_back=1,
    use_numexpr=False,
    numexpr_kwargs=None,
    local_dict=None,
    global_dict=None,
    broadcast_kwargs=None,
    wrap_kwargs=None
)

Evaluate a simple array expression element-wise using NumExpr or NumPy.

If NumExpr is enables, only one-line statements are supported. Otherwise, uses evaluate.

Note

All required variables will broadcast against each other prior to the evaluation.

Usage

>>> sr = pd.Series([1, 2, 3], index=['x', 'y', 'z'])
>>> df = pd.DataFrame([[4, 5, 6]], index=['x', 'y', 'z'], columns=['a', 'b', 'c'])
>>> vbt.pd_acc.eval('sr + df')
   a  b  c
x  5  6  7
y  6  7  8
z  7  8  9

get method

BaseAccessor.get(
    key=None,
    default=None
)

Get BaseAccessor.obj.

indexing_func method

BaseAccessor.indexing_func(
    *args,
    wrapper_meta=None,
    **kwargs
)

Perform indexing on BaseAccessor.

indexing_setter_func method

BaseAccessor.indexing_setter_func(
    pd_indexing_setter_func,
    **kwargs
)

Perform indexing setter on BaseAccessor.

is_frame class method

BaseAccessor.is_frame()

Whether the object is a DataFrame.

is_series class method

BaseAccessor.is_series()

Whether the object is a Series.

make_symmetric method

BaseAccessor.make_symmetric(
    *args,
    **kwargs
)

See make_symmetric.

ndim hybrid_property

Number of dimensions in the object.

1 -> Series, 2 -> DataFrame.

obj class property

Pandas object.

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.

resolve_column_stack_kwargs class method

BaseAccessor.resolve_column_stack_kwargs(
    *objs,
    reindex_kwargs=None,
    **kwargs
)

Resolve keyword arguments for initializing BaseAccessor after stacking along columns.

resolve_row_stack_kwargs class method

BaseAccessor.resolve_row_stack_kwargs(
    *objs,
    **kwargs
)

Resolve keyword arguments for initializing BaseAccessor after stacking along rows.

resolve_shape class method

BaseAccessor.resolve_shape(
    shape
)

Resolve shape.

row_stack class method

BaseAccessor.row_stack(
    *objs,
    wrapper_kwargs=None,
    **kwargs
)

Stack multiple BaseAccessor instances along rows.

Uses ArrayWrapper.row_stack to stack the wrappers.

set method

BaseAccessor.set(
    value_or_func,
    *args,
    inplace=False,
    columns=None,
    template_context=None,
    **kwargs
)

Set value at each index point using get_index_points.

If value_or_func is a function, selects all keyword arguments that were not passed to the get_index_points method, substitutes any templates, and passes everything to the function. As context uses kwargs, template_context, and various variables such as i (iteration index), index_point (absolute position in the index), wrapper, and obj.

set_between method

BaseAccessor.set_between(
    value_or_func,
    *args,
    inplace=False,
    columns=None,
    template_context=None,
    **kwargs
)

Set value at each index range using get_index_ranges.

If value_or_func is a function, selects all keyword arguments that were not passed to the get_index_points method, substitutes any templates, and passes everything to the function. As context uses kwargs, template_context, and various variables such as i (iteration index), index_slice (absolute slice of the index), wrapper, and obj.

sr_accessor_cls hybrid_property

Accessor class for pd.Series.

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()

See to_1d with raw set to True.

to_2d_array method

BaseAccessor.to_2d_array()

See to_2d with raw set to True.

to_data method

BaseAccessor.to_data(
    data_cls=None,
    columns_are_symbols=True,
    **kwargs
)

Convert to a Data instance.

to_dict method

BaseAccessor.to_dict(
    *args,
    **kwargs
)

See to_dict.

unstack_to_array method

BaseAccessor.unstack_to_array(
    *args,
    **kwargs
)

See unstack_to_array.

unstack_to_df method

BaseAccessor.unstack_to_df(
    *args,
    **kwargs
)

See unstack_to_df.

x class method

BaseAccessor.cross(
    *others
)

Align objects using cross_indexes.

BaseDFAccessor class

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

Accessor on top of DataFrames.

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

Superclasses

Inherited members

Subclasses

BaseIDXAccessor class

BaseIDXAccessor(
    obj,
    freq=None,
    **kwargs
)

Accessor on top of Index.

Accessible via pd.Index.vbt and all child accessors.

Superclasses

Inherited members

Subclasses

align class method

BaseIDXAccessor.align(
    *others,
    **kwargs
)

See align_indexes.

align_to method

BaseIDXAccessor.align_to(
    *args,
    **kwargs
)

See align_index_to.

any_freq class property

Index frequency of any type.

arr_to_timedelta method

BaseIDXAccessor.arr_to_timedelta(
    a,
    to_pd=False,
    silence_warnings=None
)

Convert array to duration using BaseIDXAccessor.freq.

chunk method

BaseIDXAccessor.chunk(
    min_size=None,
    n_chunks=None,
    chunk_len=None,
    chunk_meta=None,
    select=False,
    return_chunk_meta=False
)

Chunk this instance.

If axis is None, becomes 0 if the instance is one-dimensional and 1 otherwise.

For arguments related to chunking meta, see iter_chunk_meta.

Note

Splits Pandas object, not accessor!

chunk_apply method

BaseIDXAccessor.chunk_apply(
    apply_func,
    *args,
    chunk_kwargs=None,
    execute_kwargs=None,
    **kwargs
)

Chunk this instance and apply a function to each chunk.

If apply_func is a string, becomes the method name.

For arguments related to chunking, see Wrapping.chunk.

Note

Splits Pandas object, not accessor!

combine class method

BaseIDXAccessor.combine(
    *others,
    on_top=False,
    **kwargs
)

See combine_indexes.

Set on_top to True to stack the second index on top of this one.

concat class method

BaseIDXAccessor.concat(
    *others,
    **kwargs
)

See concat_indexes.

cross class method

BaseIDXAccessor.cross(
    *others,
    **kwargs
)

See cross_indexes.

cross_with method

BaseIDXAccessor.cross_with(
    *args,
    **kwargs
)

See cross_index_with.

dt_periods class property

BaseIDXAccessor.get_dt_periods with default arguments.

find_first_occurrence method

BaseIDXAccessor.find_first_occurrence(
    *args,
    **kwargs
)

See find_first_occurrence.

freq class property

BaseIDXAccessor.get_freq with date offsets and integer frequencies not allowed.

from_values class method

BaseIDXAccessor.from_values(
    *args,
    **kwargs
)

See index_from_values.

get method

BaseIDXAccessor.get()

Get IDXAccessor.obj.

get_dt_periods class method

BaseIDXAccessor.get_dt_periods(
    index=None,
    freq=None
)

Get the number of periods in the index, taking into account its datetime-like properties.

get_freq class method

BaseIDXAccessor.get_freq(
    index=None,
    freq=None,
    **kwargs
)

Index frequency as pd.Timedelta or None if it cannot be converted.

get_grouper method

BaseIDXAccessor.get_grouper(
    by,
    groupby_kwargs=None,
    **kwargs
)

Get an index grouper of type Grouper.

Argument by can be a grouper itself, an instance of Pandas GroupBy, an instance of Pandas Resampler, but also any supported input to any of them such as a frequency or an array of indices.

Keyword arguments groupby_kwargs are passed to the Pandas methods groupby and resample, while **kwargs are passed to initialize Grouper.

get_periods class method

BaseIDXAccessor.get_periods(
    index=None
)

Get the number of periods in the index, without taking into account its datetime-like properties.

get_points method

BaseIDXAccessor.get_points(
    *args,
    **kwargs
)

See get_index_points.

get_ranges method

BaseIDXAccessor.get_ranges(
    *args,
    **kwargs
)

See get_index_ranges.

get_resampler method

BaseIDXAccessor.get_resampler(
    rule,
    freq=None,
    resample_kwargs=None,
    return_pd_resampler=False,
    silence_warnings=None
)

Get an index resampler of type Resampler.

ns_freq class property

Convert frequency to a 64-bit integer.

Timedelta will be converted to nanoseconds.

obj class property

Pandas object.

periods class property

BaseIDXAccessor.get_periods with default arguments.

repeat method

BaseIDXAccessor.repeat(
    *args,
    **kwargs
)

See repeat_index.

split method

BaseIDXAccessor.split(
    *args,
    splitter_cls=None,
    **kwargs
)

Split using Splitter.split_and_take.

Note

Splits Pandas object, not accessor!

split_apply method

BaseIDXAccessor.split_apply(
    apply_func,
    *args,
    splitter_cls=None,
    **kwargs
)

Split using Splitter.split_and_apply.

Note

Splits Pandas object, not accessor!

stack class method

BaseIDXAccessor.stack(
    *others,
    on_top=False,
    **kwargs
)

See stack_indexes.

Set on_top to True to stack the second index on top of this one.

tile method

BaseIDXAccessor.tile(
    *args,
    **kwargs
)

See tile_index.

to_ns method

BaseIDXAccessor.to_ns()

Convert index to an 64-bit integer array.

Timestamps will be converted to nanoseconds.

to_period method

BaseIDXAccessor.to_period(
    freq,
    shift=False
)

Convert index to period.

to_period_ns method

BaseIDXAccessor.to_period_ns(
    *args,
    **kwargs
)

Convert index to period and then to an 64-bit integer array.

Timestamps will be converted to nanoseconds.

to_period_ts method

BaseIDXAccessor.to_period_ts(
    *args,
    **kwargs
)

Convert index to period and then to timestamp.

x class method

BaseIDXAccessor.cross(
    *others,
    **kwargs
)

See cross_indexes.

BaseSRAccessor class

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

Accessor on top of Series.

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

Superclasses

Inherited members

Subclasses