Skip to content

wrapping module

Classes for wrapping NumPy arrays into Series/DataFrames.

ArrayWrapper class

ArrayWrapper(
    index,
    columns=None,
    ndim=None,
    freq=None,
    parse_index=None,
    column_only_select=None,
    range_only_select=None,
    group_select=None,
    grouped_ndim=None,
    grouper=None,
    **kwargs
)

Class that stores index, columns, and shape metadata for wrapping NumPy arrays. Tightly integrated with Grouper for grouping columns.

If the underlying object is a Series, pass [sr.name] as columns.

**kwargs are passed to Grouper.

Note

This class is meant to be immutable. To change any attribute, use Configured.replace().

Use methods that begin with get_ to get group-aware results.

Superclasses

Inherited members

any_freq property

See BaseIDXAccessor.any_freq.

arr_to_timedelta method

ArrayWrapper.arr_to_timedelta(
    *args,
    **kwargs
)

See BaseIDXAccessor.arr_to_timedelta().

column_only_select property

Whether to perform indexing on columns only.

column_stack class method

ArrayWrapper.column_stack(
    *wrappers,
    index=None,
    columns=None,
    freq=None,
    group_by=None,
    union_index=True,
    col_concat_method='append',
    group_concat_method=('append', 'factorize_each'),
    keys=None,
    clean_index_kwargs=None,
    verify_integrity=True,
    **kwargs
)

Stack multiple ArrayWrapper instances along columns.

If indexes are the same in each wrapper index, will use that index. If indexes differ and union_index is True, they will be merged into a single one by the set union operation. Otherwise, an error will be raised. The merged index must have no duplicates or mixed data, and must be monotonically increasing. A custom index can be provided via index.

Frequency must be the same across all indexes. A custom frequency can be provided via freq.

Concatenates columns and groups using concat_indexes().

If any of the instances has column_only_select being enabled, the final wrapper will also enable it. If any of the instances has group_select or other grouping-related flags being disabled, the final wrapper will also disable them.

All instances must contain the same keys and values in their configs and configs of their grouper instances, apart from those arguments provided explicitly via kwargs.

column_stack_arrs method

ArrayWrapper.column_stack_arrs(
    *objs,
    reindex_kwargs=None,
    group_by=None,
    wrap=True,
    **kwargs
)

Stack objects along columns and wrap the final object.

reindex_kwargs will be passed to pandas.DataFrame.reindex.

columns property

Columns.

concat_arrs method

ArrayWrapper.concat_arrs(
    *objs,
    group_by=None,
    wrap=True,
    **kwargs
)

Stack reduced objects along columns and wrap the final object.

dt_period property

See BaseIDXAccessor.dt_period.

dummy method

ArrayWrapper.dummy(
    group_by=None,
    **kwargs
)

Create a dummy Series/DataFrame.

extract_init_kwargs static method

ArrayWrapper.extract_init_kwargs(
    **kwargs
)

Extract keyword arguments that can be passed to ArrayWrapper or Grouper.

fill method

ArrayWrapper.fill(
    fill_value=nan,
    group_by=None,
    **kwargs
)

Fill a Series/DataFrame.

fill_and_set method

ArrayWrapper.fill_and_set(
    idx_setter,
    keep_flex=False,
    fill_value=nan,
    **kwargs
)

Fill a new array using an index object such as index_dict.

Will be wrapped with IdxSetter if not already.

Will call IdxSetter.fill_and_set().

Usage

  • Set a single row:
>>> from vectorbtpro import *

>>> index = pd.date_range("2020", periods=5)
>>> columns = pd.Index(["a", "b", "c"])
>>> wrapper = vbt.ArrayWrapper(index, columns)

>>> wrapper.fill_and_set(vbt.index_dict({
...     1: 2
... }))
              a    b    c
2020-01-01  NaN  NaN  NaN
2020-01-02  2.0  2.0  2.0
2020-01-03  NaN  NaN  NaN
2020-01-04  NaN  NaN  NaN
2020-01-05  NaN  NaN  NaN

>>> wrapper.fill_and_set(vbt.index_dict({
...     "2020-01-02": 2
... }))
              a    b    c
2020-01-01  NaN  NaN  NaN
2020-01-02  2.0  2.0  2.0
2020-01-03  NaN  NaN  NaN
2020-01-04  NaN  NaN  NaN
2020-01-05  NaN  NaN  NaN

>>> wrapper.fill_and_set(vbt.index_dict({
...     "2020-01-02": [1, 2, 3]
... }))
              a    b    c
2020-01-01  NaN  NaN  NaN
2020-01-02  1.0  2.0  3.0
2020-01-03  NaN  NaN  NaN
2020-01-04  NaN  NaN  NaN
2020-01-05  NaN  NaN  NaN
  • Set multiple rows:
>>> wrapper.fill_and_set(vbt.index_dict({
...     (1, 3): [2, 3]
... }))
              a    b    c
2020-01-01  NaN  NaN  NaN
2020-01-02  2.0  2.0  2.0
2020-01-03  NaN  NaN  NaN
2020-01-04  3.0  3.0  3.0
2020-01-05  NaN  NaN  NaN

>>> wrapper.fill_and_set(vbt.index_dict({
...     ("2020-01-02", "2020-01-04"): [[1, 2, 3], [4, 5, 6]]
... }))
              a    b    c
2020-01-01  NaN  NaN  NaN
2020-01-02  1.0  2.0  3.0
2020-01-03  NaN  NaN  NaN
2020-01-04  4.0  5.0  6.0
2020-01-05  NaN  NaN  NaN

>>> wrapper.fill_and_set(vbt.index_dict({
...     ("2020-01-02", "2020-01-04"): [[1, 2, 3]]
... }))
              a    b    c
2020-01-01  NaN  NaN  NaN
2020-01-02  1.0  2.0  3.0
2020-01-03  NaN  NaN  NaN
2020-01-04  1.0  2.0  3.0
2020-01-05  NaN  NaN  NaN
  • Set rows using slices:
>>> wrapper.fill_and_set(vbt.index_dict({
...     vbt.hslice(1, 3): 2
... }))
              a    b    c
2020-01-01  NaN  NaN  NaN
2020-01-02  2.0  2.0  2.0
2020-01-03  2.0  2.0  2.0
2020-01-04  NaN  NaN  NaN
2020-01-05  NaN  NaN  NaN

```pycon
>>> wrapper.fill_and_set(vbt.index_dict({
...     vbt.hslice("2020-01-02", "2020-01-04"): 2
... }))
              a    b    c
2020-01-01  NaN  NaN  NaN
2020-01-02  2.0  2.0  2.0
2020-01-03  2.0  2.0  2.0
2020-01-04  NaN  NaN  NaN
2020-01-05  NaN  NaN  NaN

>>> wrapper.fill_and_set(vbt.index_dict({
...     ((0, 2), (3, 5)): [[1], [2]]
... }))
              a    b    c
2020-01-01  1.0  1.0  1.0
2020-01-02  1.0  1.0  1.0
2020-01-03  NaN  NaN  NaN
2020-01-04  2.0  2.0  2.0
2020-01-05  2.0  2.0  2.0

>>> wrapper.fill_and_set(vbt.index_dict({
...     ((0, 2), (3, 5)): [[1, 2, 3], [4, 5, 6]]
... }))
              a    b    c
2020-01-01  1.0  2.0  3.0
2020-01-02  1.0  2.0  3.0
2020-01-03  NaN  NaN  NaN
2020-01-04  4.0  5.0  6.0
2020-01-05  4.0  5.0  6.0
  • Set rows using index points:
>>> wrapper.fill_and_set(vbt.index_dict({
...     vbt.pointidx(every="2D"): 2
... }))
              a    b    c
2020-01-01  2.0  2.0  2.0
2020-01-02  NaN  NaN  NaN
2020-01-03  2.0  2.0  2.0
2020-01-04  NaN  NaN  NaN
2020-01-05  2.0  2.0  2.0
  • Set rows using index ranges:
>>> wrapper.fill_and_set(vbt.index_dict({
...     vbt.rangeidx(
...         start=("2020-01-01", "2020-01-03"),
...         end=("2020-01-02", "2020-01-05")
...     ): 2
... }))
              a    b    c
2020-01-01  2.0  2.0  2.0
2020-01-02  NaN  NaN  NaN
2020-01-03  2.0  2.0  2.0
2020-01-04  2.0  2.0  2.0
2020-01-05  NaN  NaN  NaN
  • Set column indices:
>>> wrapper.fill_and_set(vbt.index_dict({
...     vbt.colidx("a"): 2
... }))
              a   b   c
2020-01-01  2.0 NaN NaN
2020-01-02  2.0 NaN NaN
2020-01-03  2.0 NaN NaN
2020-01-04  2.0 NaN NaN
2020-01-05  2.0 NaN NaN

>>> wrapper.fill_and_set(vbt.index_dict({
...     vbt.colidx(("a", "b")): [1, 2]
... }))
              a    b   c
2020-01-01  1.0  2.0 NaN
2020-01-02  1.0  2.0 NaN
2020-01-03  1.0  2.0 NaN
2020-01-04  1.0  2.0 NaN
2020-01-05  1.0  2.0 NaN

>>> multi_columns = pd.MultiIndex.from_arrays(
...     [["a", "a", "b", "b"], [1, 2, 1, 2]],
...     names=["c1", "c2"]
... )
>>> multi_wrapper = vbt.ArrayWrapper(index, multi_columns)

>>> multi_wrapper.fill_and_set(vbt.index_dict({
...     vbt.colidx(("a", 2)): 2
... }))
c1           a        b
c2           1    2   1   2
2020-01-01 NaN  2.0 NaN NaN
2020-01-02 NaN  2.0 NaN NaN
2020-01-03 NaN  2.0 NaN NaN
2020-01-04 NaN  2.0 NaN NaN
2020-01-05 NaN  2.0 NaN NaN

>>> multi_wrapper.fill_and_set(vbt.index_dict({
...     vbt.colidx("b", level="c1"): [3, 4]
... }))
c1           a        b
c2           1   2    1    2
2020-01-01 NaN NaN  3.0  4.0
2020-01-02 NaN NaN  3.0  4.0
2020-01-03 NaN NaN  3.0  4.0
2020-01-04 NaN NaN  3.0  4.0
2020-01-05 NaN NaN  3.0  4.0
  • Set row and column indices:
>>> wrapper.fill_and_set(vbt.index_dict({
...     vbt.idx(2, 2): 2
... }))
             a   b    c
2020-01-01 NaN NaN  NaN
2020-01-02 NaN NaN  NaN
2020-01-03 NaN NaN  2.0
2020-01-04 NaN NaN  NaN
2020-01-05 NaN NaN  NaN

>>> wrapper.fill_and_set(vbt.index_dict({
...     vbt.idx(("2020-01-01", "2020-01-03"), 2): [1, 2]
... }))
             a   b    c
2020-01-01 NaN NaN  1.0
2020-01-02 NaN NaN  NaN
2020-01-03 NaN NaN  2.0
2020-01-04 NaN NaN  NaN
2020-01-05 NaN NaN  NaN

>>> wrapper.fill_and_set(vbt.index_dict({
...     vbt.idx(("2020-01-01", "2020-01-03"), (0, 2)): [[1, 2], [3, 4]]
... }))
              a   b    c
2020-01-01  1.0 NaN  2.0
2020-01-02  NaN NaN  NaN
2020-01-03  3.0 NaN  4.0
2020-01-04  NaN NaN  NaN
2020-01-05  NaN NaN  NaN

>>> multi_wrapper.fill_and_set(vbt.index_dict({
...     vbt.idx(
...         vbt.pointidx(every="2d"),
...         vbt.colidx(1, level="c2")
...     ): [[1, 2]]
... }))
c1            a        b
c2            1   2    1   2
2020-01-01  1.0 NaN  2.0 NaN
2020-01-02  NaN NaN  NaN NaN
2020-01-03  1.0 NaN  2.0 NaN
2020-01-04  NaN NaN  NaN NaN
2020-01-05  1.0 NaN  2.0 NaN

>>> multi_wrapper.fill_and_set(vbt.index_dict({
...     vbt.idx(
...         vbt.pointidx(every="2d"),
...         vbt.colidx(1, level="c2")
...     ): [[1], [2], [3]]
... }))
c1            a        b
c2            1   2    1   2
2020-01-01  1.0 NaN  1.0 NaN
2020-01-02  NaN NaN  NaN NaN
2020-01-03  2.0 NaN  2.0 NaN
2020-01-04  NaN NaN  NaN NaN
2020-01-05  3.0 NaN  3.0 NaN
  • Set rows using a template:
>>> wrapper.fill_and_set(vbt.index_dict({
...     vbt.RepEval("index.day % 2 == 0"): 2
... }))
              a    b    c
2020-01-01  NaN  NaN  NaN
2020-01-02  2.0  2.0  2.0
2020-01-03  NaN  NaN  NaN
2020-01-04  2.0  2.0  2.0
2020-01-05  NaN  NaN  NaN

fill_reduced method

ArrayWrapper.fill_reduced(
    fill_value=nan,
    group_by=None,
    **kwargs
)

Fill a reduced Series/DataFrame.

flip method

ArrayWrapper.flip(
    **kwargs
)

Flip index and columns.

freq property

See BaseIDXAccessor.freq.

from_obj class method

ArrayWrapper.from_obj(
    obj,
    **kwargs
)

Derive metadata from an object.

from_shape class method

ArrayWrapper.from_shape(
    shape,
    index=None,
    columns=None,
    ndim=None,
    *args,
    **kwargs
)

Derive metadata from shape.

get_columns method

ArrayWrapper.get_columns(
    group_by=None
)

Get group-aware ArrayWrapper.columns.

get_freq method

ArrayWrapper.get_freq(
    *args,
    **kwargs
)

See BaseIDXAccessor.get_freq().

get_index_grouper method

ArrayWrapper.get_index_grouper(
    *args,
    **kwargs
)

See BaseIDXAccessor.get_grouper().

get_index_points method

ArrayWrapper.get_index_points(
    *args,
    **kwargs
)

See BaseIDXAccessor.get_points().

get_index_ranges method

ArrayWrapper.get_index_ranges(
    *args,
    **kwargs
)

See BaseIDXAccessor.get_ranges().

get_name method

ArrayWrapper.get_name(
    group_by=None
)

Get group-aware ArrayWrapper.name.

get_ndim method

ArrayWrapper.get_ndim(
    group_by=None
)

Get group-aware ArrayWrapper.ndim.

get_period_ns_index method

ArrayWrapper.get_period_ns_index(
    *args,
    **kwargs
)

See BaseIDXAccessor.to_period_ns().

get_resampler method

ArrayWrapper.get_resampler(
    *args,
    **kwargs
)

See BaseIDXAccessor.get_resampler().

get_shape method

ArrayWrapper.get_shape(
    group_by=None
)

Get group-aware ArrayWrapper.shape.

get_shape_2d method

ArrayWrapper.get_shape_2d(
    group_by=None
)

Get group-aware ArrayWrapper.shape_2d.

group_select property

Whether to allow indexing on groups.

grouped_ndim property

Number of dimensions under column grouping.

grouper property

Column grouper.

index property

Index.

index_acc property

Get index accessor of the type BaseIDXAccessor.

indexing_func method

ArrayWrapper.indexing_func(
    *args,
    **kwargs
)

Perform indexing on ArrayWrapper.

indexing_func_meta method

ArrayWrapper.indexing_func_meta(
    pd_indexing_func,
    index=None,
    columns=None,
    column_only_select=None,
    range_only_select=None,
    group_select=None,
    return_slices=True,
    return_none_slices=True,
    return_scalars=True,
    group_by=None,
    wrapper_kwargs=None
)

Perform indexing on ArrayWrapper and also return metadata.

Takes into account column grouping.

Flipping rows and columns is not allowed. If one row is selected, the result will still be a Series when indexing a Series and a DataFrame when indexing a DataFrame.

Set column_only_select to True to index the array wrapper as a Series of columns/groups. This way, selection of index (axis 0) can be avoided. Set range_only_select to True to allow selection of rows only using slices. Set group_select to True to allow selection of groups. Otherwise, indexing is performed on columns, even if grouping is enabled. Takes effect only if grouping is enabled.

Returns the new array wrapper, row indices, column indices, and group indices. If return_slices is True (default), indices will be returned as a slice if they were identified as a range. If return_none_slices is True (default), indices will be returned as a slice (None, None, None) if the axis hasn't been changed.

Note

If column_only_select is True, make sure to index the array wrapper as a Series of columns rather than a DataFrame. For example, the operation .iloc[:, :2] should become .iloc[:2]. Operations are not allowed if the object is already a Series and thus has only one column/group.

items method

ArrayWrapper.items(
    group_by=None,
    apply_group_by=False,
    keep_2d=False,
    key_as_index=False
)

Iterate over columns or groups (if grouped and Wrapping.group_select is True).

If apply_group_by is False, group_by becomes a grouping instruction for the iteration, not for the final object. In this case, will raise an error if the instance is grouped and that grouping must be changed.

name property

Name.

ndim property

Number of dimensions.

ns_freq property

See BaseIDXAccessor.ns_freq.

ns_index property

See BaseIDXAccessor.to_ns().

parse_index property

Whether to try to convert the index into a datetime index.

Applied during the initialization and passed to prepare_dt_index().

period property

See BaseIDXAccessor.period.

range_only_select property

Whether to perform indexing on rows using slices only.

regroup method

ArrayWrapper.regroup(
    group_by,
    **kwargs
)

Regroup this object.

Only creates a new instance if grouping has changed, otherwise returns itself.

resample method

ArrayWrapper.resample(
    *args,
    **kwargs
)

Perform resampling on ArrayWrapper.

Uses ArrayWrapper.resample_meta().

resample_meta method

ArrayWrapper.resample_meta(
    *args,
    wrapper_kwargs=None,
    **kwargs
)

Perform resampling on ArrayWrapper and also return metadata.

*args and **kwargs are passed to ArrayWrapper.get_resampler().

resolve method

ArrayWrapper.resolve(
    group_by=None,
    **kwargs
)

Resolve this object.

Replaces columns and other metadata with groups.

resolve_stack_kwargs class method

ArrayWrapper.resolve_stack_kwargs(
    *wrappers,
    **kwargs
)

Resolve keyword arguments for initializing ArrayWrapper after stacking.

row_stack class method

ArrayWrapper.row_stack(
    *wrappers,
    index=None,
    columns=None,
    freq=None,
    group_by=None,
    stack_columns=True,
    index_concat_method='append',
    keys=None,
    clean_index_kwargs=None,
    verify_integrity=True,
    **kwargs
)

Stack multiple ArrayWrapper instances along rows.

Concatenates indexes using concat_indexes().

Frequency must be the same across all indexes. A custom frequency can be provided via freq.

If column levels in some instances differ, they will be stacked upon each other. Custom columns can be provided via columns.

If group_by is None, all instances must be either grouped or not, and they must contain the same group values and labels.

All instances must contain the same keys and values in their configs and configs of their grouper instances, apart from those arguments provided explicitly via kwargs.

row_stack_arrs method

ArrayWrapper.row_stack_arrs(
    *objs,
    group_by=None,
    wrap=True,
    **kwargs
)

Stack objects along rows and wrap the final object.

select_col method

ArrayWrapper.select_col(
    column=None,
    group_by=None,
    **kwargs
)

Select one column/group.

column can be a label-based position as well as an integer position (if label fails).

select_col_from_obj method

ArrayWrapper.select_col_from_obj(
    obj,
    column=None,
    obj_ungrouped=False,
    group_by=None,
    **kwargs
)

Select one column/group from a Pandas object.

column can be a label-based position as well as an integer position (if label fails).

select_from_flex_array static method

ArrayWrapper.select_from_flex_array(
    arr,
    row_idxs=None,
    col_idxs=None,
    rows_changed=True,
    columns_changed=True,
    rotate_rows=False,
    rotate_cols=True
)

Select rows and columns from a flexible array.

Always returns a 2-dim NumPy array.

shape property

Shape.

shape_2d property

Shape as if the object was two-dimensional.

split method

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

Split using Splitter.split_and_take().

split_apply method

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

Split using Splitter.split_and_apply().

wrap method

ArrayWrapper.wrap(
    arr,
    group_by=None,
    index=None,
    columns=None,
    zero_to_none=None,
    force_2d=False,
    fillna=None,
    dtype=None,
    min_precision=None,
    max_precision=None,
    prec_float_only=None,
    prec_check_bounds=None,
    prec_strict=None,
    to_timedelta=False,
    to_index=False,
    silence_warnings=None
)

Wrap a NumPy array using the stored metadata.

Runs the following pipeline:

1) Converts to NumPy array 2) Fills NaN (optional) 3) Wraps using index, columns, and dtype (optional) 4) Converts to index (optional) 5) Converts to timedelta using ArrayWrapper.arr_to_timedelta() (optional)

wrap_reduced method

ArrayWrapper.wrap_reduced(
    arr,
    group_by=None,
    name_or_index=None,
    columns=None,
    force_1d=False,
    fillna=None,
    dtype=None,
    to_timedelta=False,
    to_index=False,
    silence_warnings=None
)

Wrap result of reduction.

name_or_index can be the name of the resulting series if reducing to a scalar per column, or the index of the resulting series/dataframe if reducing to an array per column. columns can be set to override object's default columns.

See ArrayWrapper.wrap() for the pipeline.

Wrapping class

Wrapping(
    wrapper,
    **kwargs
)

Class that uses ArrayWrapper globally.

Superclasses

Inherited members

Subclasses

column_only_select property

Overrides ArrayWrapper.column_only_select.

column_stack class method

Wrapping.column_stack(
    *args,
    wrapper_kwargs=None,
    **kwargs
)

Stack multiple Wrapping instances along columns.

Should use ArrayWrapper.column_stack().

group_select property

Overrides ArrayWrapper.group_select.

indexing_func method

Wrapping.indexing_func(
    *args,
    **kwargs
)

Perform indexing on Wrapping.

items method

Wrapping.items(
    group_by=None,
    apply_group_by=False,
    keep_2d=False,
    key_as_index=False
)

Iterate over columns or groups (if grouped and Wrapping.group_select is True).

If apply_group_by is False, group_by becomes a grouping instruction for the iteration, not for the final object. In this case, will raise an error if the instance is grouped and that grouping must be changed.

range_only_select property

Overrides ArrayWrapper.range_only_select.

regroup method

Wrapping.regroup(
    group_by,
    **kwargs
)

Regroup this object.

Only creates a new instance if grouping has changed, otherwise returns itself.

**kwargs will be passed to ArrayWrapper.regroup().

resample method

Wrapping.resample(
    *args,
    **kwargs
)

Perform resampling on Wrapping.

When overriding, make sure to create a resampler by passing *args and **kwargs to ArrayWrapper.get_resampler().

resolve_column_stack_kwargs class method

Wrapping.resolve_column_stack_kwargs(
    *wrappings,
    **kwargs
)

Resolve keyword arguments for initializing Wrapping after stacking along columns.

resolve_row_stack_kwargs class method

Wrapping.resolve_row_stack_kwargs(
    *wrappings,
    **kwargs
)

Resolve keyword arguments for initializing Wrapping after stacking along rows.

resolve_self method

Wrapping.resolve_self(
    cond_kwargs=None,
    custom_arg_names=None,
    impacts_caching=True,
    silence_warnings=None
)

Resolve self.

Creates a copy of this instance if a different freq can be found in cond_kwargs.

resolve_stack_kwargs class method

Wrapping.resolve_stack_kwargs(
    *wrappings,
    **kwargs
)

Resolve keyword arguments for initializing Wrapping after stacking.

Should be called after Wrapping.resolve_row_stack_kwargs() or Wrapping.resolve_column_stack_kwargs().

row_stack class method

Wrapping.row_stack(
    *args,
    wrapper_kwargs=None,
    **kwargs
)

Stack multiple Wrapping instances along rows.

Should use ArrayWrapper.row_stack().

select_col method

Wrapping.select_col(
    column=None,
    group_by=None,
    **kwargs
)

Select one column/group.

column can be a label-based position as well as an integer position (if label fails).

select_col_from_obj class method

Wrapping.select_col_from_obj(
    obj,
    column=None,
    obj_ungrouped=False,
    wrapper=None,
    group_by=None,
    **kwargs
)

See ArrayWrapper.select_col_from_obj().

split method

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

Split using Splitter.split_and_take().

split_apply method

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

Split using Splitter.split_and_apply().

wrapper property

Array wrapper of the type ArrayWrapper.