reshape_fns module ¶

Functions for reshaping arrays.

Reshape functions transform a pandas object/NumPy array in some way, such as tiling, broadcasting, and unstacking.

IndexFromLike _UnionGenericAlias ¶

Any object that can be coerced into a index_from argument.

broadcast function ¶

broadcast(
    *args,
    to_shape=None,
    to_pd=None,
    to_frame=None,
    align_index=None,
    align_columns=None,
    index_from=None,
    columns_from=None,
    require_kwargs=None,
    keep_raw=False,
    return_meta=False,
    **kwargs
)

Bring any array-like object in args to the same shape by using NumPy broadcasting.

See Broadcasting.

Can broadcast pandas objects by broadcasting their index/columns with broadcast_index().

Args

*args : array_like

Array-like objects.

to_shape : tuple of int

Target shape. If set, will broadcast every element in args to to_shape.

to_pd : bool or list of bool

Whether to convert all output arrays to pandas, otherwise returns raw NumPy arrays. If None, converts only if there is at least one pandas object among them.

If sequence, applies to each argument.

to_frame : bool

Whether to convert all Series to DataFrames.

align_index : bool

Whether to align index of pandas objects using multi-index.

Pass None to use the default.

align_columns : bool

Whether to align columns of pandas objects using multi-index.

Pass None to use the default.

index_from : any

Broadcasting rule for index.

Pass None to use the default.

columns_from : any

Broadcasting rule for columns.

Pass None to use the default.

require_kwargs : dict or list of dict

Keyword arguments passed to np.require.

If sequence, applies to each argument.

keep_raw : bool or list of bool

Whether to keep the unbroadcasted version of the array.

Only makes sure that the array can be broadcast to the target shape.

If sequence, applies to each argument.

return_meta : bool

Whether to also return new shape, index and columns.

**kwargs

Keyword arguments passed to broadcast_index().

For defaults, see broadcasting in settings.

Usage

Without broadcasting index and columns:

>>> import numpy as np
>>> import pandas as pd
>>> from vectorbt.base.reshape_fns import broadcast

>>> v = 0
>>> a = np.array([1, 2, 3])
>>> sr = pd.Series([1, 2, 3], index=pd.Index(['x', 'y', 'z']), name='a')
>>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6], [7, 8, 9]],
...     index=pd.Index(['x2', 'y2', 'z2']),
...     columns=pd.Index(['a2', 'b2', 'c2']))

>>> for i in broadcast(
...     v, a, sr, df,
...     index_from='keep',
...     columns_from='keep',
... ): print(i)
   0  1  2
0  0  0  0
1  0  0  0
2  0  0  0
   0  1  2
0  1  2  3
1  1  2  3
2  1  2  3
   a  a  a
x  1  1  1
y  2  2  2
z  3  3  3
    a2  b2  c2
x2   1   2   3
y2   4   5   6
z2   7   8   9

Taking new index and columns from position:

>>> for i in broadcast(
...     v, a, sr, df,
...     index_from=2,
...     columns_from=3
... ): print(i)
   a2  b2  c2
x   0   0   0
y   0   0   0
z   0   0   0
   a2  b2  c2
x   1   2   3
y   1   2   3
z   1   2   3
   a2  b2  c2
x   1   1   1
y   2   2   2
z   3   3   3
   a2  b2  c2
x   1   2   3
y   4   5   6
z   7   8   9

Broadcasting index and columns through stacking:

>>> for i in broadcast(
...     v, a, sr, df,
...     index_from='stack',
...     columns_from='stack'
... ): print(i)
      a2  b2  c2
x x2   0   0   0
y y2   0   0   0
z z2   0   0   0
      a2  b2  c2
x x2   1   2   3
y y2   1   2   3
z z2   1   2   3
      a2  b2  c2
x x2   1   1   1
y y2   2   2   2
z z2   3   3   3
      a2  b2  c2
x x2   1   2   3
y y2   4   5   6
z z2   7   8   9

Setting index and columns manually:

>>> for i in broadcast(
...     v, a, sr, df,
...     index_from=['a', 'b', 'c'],
...     columns_from=['d', 'e', 'f']
... ): print(i)
   d  e  f
a  0  0  0
b  0  0  0
c  0  0  0
   d  e  f
a  1  2  3
b  1  2  3
c  1  2  3
   d  e  f
a  1  1  1
b  2  2  2
c  3  3  3
   d  e  f
a  1  2  3
b  4  5  6
c  7  8  9

broadcast_index function ¶

broadcast_index(
    args,
    to_shape,
    index_from=None,
    axis=0,
    ignore_sr_names=None,
    **kwargs
)

Produce a broadcast index/columns.

Args

args : list of array_like

Array-like objects.

to_shape : tuple of int

Target shape.

index_from : any

Broadcasting rule for this index/these columns.

Accepts the following values:

'keep' or None - keep the original index/columns of the objects in args
'stack' - stack different indexes/columns using stack_indexes()
'strict' - ensure that all pandas objects have the same index/columns
'reset' - reset any index/columns (they become a simple range)
integer - use the index/columns of the i-th object in args
everything else will be converted to pd.Index

axis : int

Set to 0 for index and 1 for columns.

ignore_sr_names : bool

Whether to ignore Series names if they are in conflict.

Conflicting Series names are those that are different but not None.

**kwargs

Keyword arguments passed to stack_indexes().

For defaults, see broadcasting in settings.

Note

Series names are treated as columns with a single element but without a name. If a column level without a name loses its meaning, better to convert Series to DataFrames with one column prior to broadcasting. If the name of a Series is not that important, better to drop it altogether by setting it to None.

broadcast_to function ¶

broadcast_to(
    arg1,
    arg2,
    to_pd=None,
    index_from=None,
    columns_from=None,
    **kwargs
)

Broadcast arg1 to arg2.

Pass None to index_from/columns_from to use index/columns of the second argument.

Keyword arguments **kwargs are passed to broadcast().

Usage

>>> import numpy as np
>>> import pandas as pd
>>> from vectorbt.base.reshape_fns import broadcast_to

>>> a = np.array([1, 2, 3])
>>> sr = pd.Series([4, 5, 6], index=pd.Index(['x', 'y', 'z']), name='a')

>>> broadcast_to(a, sr)
x    1
y    2
z    3
Name: a, dtype: int64

>>> broadcast_to(sr, a)
array([4, 5, 6])

broadcast_to_array_of function ¶

broadcast_to_array_of(
    arg1,
    arg2
)

Broadcast arg1 to the shape (1, *arg2.shape).

arg1 must be either a scalar, a 1-dim array, or have 1 dimension more than arg2.

Usage

>>> import numpy as np
>>> from vectorbt.base.reshape_fns import broadcast_to_array_of

>>> broadcast_to_array_of([0.1, 0.2], np.empty((2, 2)))
[[[0.1 0.1]
  [0.1 0.1]]

 [[0.2 0.2]
  [0.2 0.2]]]

broadcast_to_axis_of function ¶

broadcast_to_axis_of(
    arg1,
    arg2,
    axis,
    require_kwargs=None
)

Broadcast arg1 to an axis of arg2.

If arg2 has less dimensions than requested, will broadcast arg1 to a single number.

For other keyword arguments, see broadcast().

flex_choose_i_and_col_nb function ¶

flex_choose_i_and_col_nb(
    a,
    flex_2d=True
)

Choose selection index and column based on the array's shape.

Instead of expensive broadcasting, keep the original shape and do indexing in a smart way. A nice feature of this is that it has almost no memory footprint and can broadcast in any direction infinitely.

Call it once before using flex_select_nb().

if flex_2d is True, 1-dim array will correspond to columns, otherwise to rows.

flex_select_auto_nb function ¶

flex_select_auto_nb(
    a,
    i,
    col,
    flex_2d=True
)

Combines flex_choose_i_and_col_nb() and flex_select_nb().

flex_select_nb function ¶

flex_select_nb(
    a,
    i,
    col,
    flex_i,
    flex_col,
    flex_2d=True
)

Select element of a as if it has been broadcast.

get_multiindex_series function ¶

get_multiindex_series(
    arg
)

Get Series with a multi-index.

If DataFrame has been passed, should at maximum have one row or column.

make_symmetric function ¶

make_symmetric(
    arg,
    sort=True
)

Make arg symmetric.

The index and columns of the resulting DataFrame will be identical.

Requires the index and columns to have the same number of levels.

Pass sort=False if index and columns should not be sorted, but concatenated and get duplicates removed.

Usage

>>> import pandas as pd
>>> from vectorbt.base.reshape_fns import make_symmetric

>>> df = pd.DataFrame([[1, 2], [3, 4]], index=['a', 'b'], columns=['c', 'd'])

>>> make_symmetric(df)
     a    b    c    d
a  NaN  NaN  1.0  2.0
b  NaN  NaN  3.0  4.0
c  1.0  3.0  NaN  NaN
d  2.0  4.0  NaN  NaN

repeat function ¶

repeat(
    arg,
    n,
    axis=1,
    raw=False
)

Repeat each element in arg n times along the specified axis.

soft_to_ndim function ¶

soft_to_ndim(
    arg,
    ndim,
    raw=False
)

Try to softly bring arg to the specified number of dimensions ndim (max 2).

tile function ¶

tile(
    arg,
    n,
    axis=1,
    raw=False
)

Repeat the whole arg n times along the specified axis.

to_1d function ¶

to_1d(
    arg,
    raw=False
)

Reshape argument to one dimension.

If raw is True, returns NumPy array. If 2-dim, will collapse along axis 1 (i.e., DataFrame with one column to Series).

to_2d function ¶

to_2d(
    arg,
    raw=False,
    expand_axis=1
)

Reshape argument to two dimensions.

If raw is True, returns NumPy array. If 1-dim, will expand along axis 1 (i.e., Series to DataFrame with one column).

to_any_array function ¶

to_any_array(
    arg,
    raw=False
)

Convert any array-like object to an array.

Pandas objects are kept as-is.

to_dict function ¶

to_dict(
    arg,
    orient='dict'
)

Convert object to dict.

to_pd_array function ¶

to_pd_array(
    arg
)

Convert any array-like object to a pandas object.

unstack_to_array function ¶

unstack_to_array(
    arg,
    levels=None
)

Reshape arg based on its multi-index into a multi-dimensional array.

Use levels to specify what index levels to unstack and in which order.

Usage

>>> import pandas as pd
>>> from vectorbt.base.reshape_fns import unstack_to_array

>>> index = pd.MultiIndex.from_arrays(
...     [[1, 1, 2, 2], [3, 4, 3, 4], ['a', 'b', 'c', 'd']])
>>> sr = pd.Series([1, 2, 3, 4], index=index)

>>> unstack_to_array(sr).shape
(2, 2, 4)

>>> unstack_to_array(sr)
[[[ 1. nan nan nan]
 [nan  2. nan nan]]

 [[nan nan  3. nan]
[nan nan nan  4.]]]

>>> unstack_to_array(sr, levels=(2, 0))
[[ 1. nan]
 [ 2. nan]
 [nan  3.]
 [nan  4.]]

unstack_to_df function ¶

unstack_to_df(
    arg,
    index_levels=None,
    column_levels=None,
    symmetric=False,
    sort=True
)

Reshape arg based on its multi-index into a DataFrame.

Use index_levels to specify what index levels will form new index, and column_levels for new columns. Set symmetric to True to make DataFrame symmetric.

Usage

>>> import pandas as pd
>>> from vectorbt.base.reshape_fns import unstack_to_df

>>> index = pd.MultiIndex.from_arrays(
...     [[1, 1, 2, 2], [3, 4, 3, 4], ['a', 'b', 'c', 'd']],
...     names=['x', 'y', 'z'])
>>> sr = pd.Series([1, 2, 3, 4], index=index)

>>> unstack_to_df(sr, index_levels=(0, 1), column_levels=2)
z      a    b    c    d
x y
1 3  1.0  NaN  NaN  NaN
1 4  NaN  2.0  NaN  NaN
2 3  NaN  NaN  3.0  NaN
2 4  NaN  NaN  NaN  4.0

wrap_broadcasted function ¶

wrap_broadcasted(
    old_arg,
    new_arg,
    is_pd=False,
    new_index=None,
    new_columns=None
)

If the newly brodcasted array was originally a pandas object, make it pandas object again and assign it the newly broadcast index/columns.

reshape_fns module¶

IndexFromLike _UnionGenericAlias¶

broadcast function¶

broadcast_index function¶

broadcast_to function¶

broadcast_to_array_of function¶

broadcast_to_axis_of function¶

flex_choose_i_and_col_nb function¶

flex_select_auto_nb function¶

flex_select_nb function¶

get_multiindex_series function¶

make_symmetric function¶

repeat function¶

soft_to_ndim function¶

tile function¶

to_1d function¶

to_2d function¶

to_any_array function¶

to_dict function¶

to_pd_array function¶

unstack_to_array function¶

unstack_to_df function¶

wrap_broadcasted function¶

reshape_fns module ¶

IndexFromLike _UnionGenericAlias ¶

broadcast function ¶

broadcast_index function ¶

broadcast_to function ¶

broadcast_to_array_of function ¶

broadcast_to_axis_of function ¶

flex_choose_i_and_col_nb function ¶

flex_select_auto_nb function ¶

flex_select_nb function ¶

get_multiindex_series function ¶

make_symmetric function ¶

repeat function ¶

soft_to_ndim function ¶

tile function ¶

to_1d function ¶

to_2d function ¶

to_any_array function ¶

to_dict function ¶

to_pd_array function ¶

unstack_to_array function ¶

unstack_to_df function ¶

wrap_broadcasted function ¶