params module ¶

Utilities for working with parameters.

broadcast_params function ¶

broadcast_params(
    params_or_dict,
    to_n=None
)

Broadcast parameters in params.

combine_params function ¶

combine_params(
    param_dct,
    build_grid=None,
    grid_indices=None,
    random_subset=None,
    random_replace=False,
    random_sort=True,
    max_guesses=None,
    max_misses=None,
    seed=None,
    clean_index_kwargs=None,
    name_tuple_to_str=None,
    build_index=True,
    raise_empty_error=False
)

Combine a dictionary with parameters of the type Param.

Returns a dictionary with combined parameters and an index if build_index is True.

If build_grid is True, first builds the entire grid and then filters parameter combinations by conditions and selects random combinations. If build_grid is False, doesn't build the entire grid, but selects and combines combinations on the fly. Materializing the grid is recommended only when the number of combinations is relatively low (less than one million) and parameters have conditions.

Argument grid_indices can be a slice (for example, slice(None, None, 2) for ::2) or an array with indices that map to the length of the grid. It can be used to skip a some combinations before a random subset is drawn.

Argument random_subset can be an integer (number of combinations) or a float relative to the length of the grid. If parameters have conditions, random_subset is drawn from the subset of combinations whose conditions have been met, not the other way around. If random_replace is True, draws random combinations with replacement (that is, duplicate combinations will likely occur). If random_replace is False (default), each drawn combination will be unique. If random_sort is True (default), positions of combinations will be sorted. Otherwise, they will remain in their randomly-selected positions.

Arguments max_guesses and max_misses are effective only when the grid is not buildd and parameters have conditions. They mean the maximum number of guesses and misses respectively when doing the search for a valid combination in a while-loop. Once any of these two numbers is reached, the search will stop. They are useful for limiting the number of guesses; without them, the search may continue forever.

If a name of any parameter is a tuple, can convert this tuple into a string by setting name_tuple_to_str either to True or providing a callable that does this.

Keyword arguments clean_index_kwargs are passed to clean_index().

create_param_product function ¶

create_param_product(
    params_or_dict
)

Make Cartesian product out of all params in params.

flatten_param_tuples function ¶

flatten_param_tuples(
    param_tuples
)

Flattens a nested list of iterables using unzipping.

generate_param_combs function ¶

generate_param_combs(
    op_tree,
    depth=0
)

Generate arbitrary parameter combinations from the operation tree op_tree.

op_tree is a tuple with nested instructions to generate parameters. The first element of the tuple must be either the name of a callale from itertools or the callable itself that takes remaining elements as arguments. If one of the elements is a tuple itself and its first argument is a callable, it will be unfolded in the same way as above.

Usage

>>> from vectorbtpro import *

>>> vbt.generate_param_combs(("product", ("combinations", [0, 1, 2, 3], 2), [4, 5]))
[[0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2],
 [1, 1, 2, 2, 3, 3, 2, 2, 3, 3, 3, 3],
 [4, 5, 4, 5, 4, 5, 4, 5, 4, 5, 4, 5]]

>>> vbt.generate_param_combs(("product", (zip, [0, 1, 2, 3], [4, 5, 6, 7]), [8, 9]))
[[0, 0, 1, 1, 2, 2, 3, 3], [4, 4, 5, 5, 6, 6, 7, 7], [8, 9, 8, 9, 8, 9, 8, 9]]

get_param_grid_len function ¶

get_param_grid_len(
    param_grid
)

Get the number of parameter combinations in a parameter grid.

Parameter values can also be an integer to represent the number of values.

is_single_param_value function ¶

is_single_param_value(
    param_values,
    is_tuple=False,
    is_array_like=False
)

Check whether param_values is a single value.

parameterized function ¶

parameterized(
    *args,
    parameterizer_cls=None,
    param_search_kwargs=None,
    skip_single_comb=None,
    template_context=None,
    build_grid=None,
    grid_indices=None,
    random_subset=None,
    random_replace=None,
    random_sort=None,
    max_guesses=None,
    max_misses=None,
    seed=None,
    clean_index_kwargs=None,
    name_tuple_to_str=None,
    selection=None,
    forward_kwargs_as=None,
    mono_min_size=None,
    mono_n_chunks=None,
    mono_chunk_len=None,
    mono_chunk_meta=None,
    mono_reduce=None,
    mono_merge_func=None,
    mono_merge_kwargs=None,
    merge_func=None,
    merge_kwargs=None,
    return_meta=None,
    return_param_index=None,
    execute_kwargs=None,
    merge_to_execute_kwargs=None,
    eval_id=None,
    **kwargs
)

Decorator that parameterizes inputs of a function using Parameterizer.

Returns a new function with the same signature as the passed one.

Each option can be modified in the options attribute of the wrapper function or directly passed as a keyword argument with a leading underscore.

Keyword arguments **kwargs and execute_kwargs are merged into execute_kwargs if merge_to_execute_kwargs is True, otherwise, **kwargs are passed directly to Parameterizer.

Usage

No parameters, no parameter configs:

>>> from vectorbtpro import *

>>> @vbt.parameterized(merge_func="column_stack")
... def my_ma(sr_or_df, window, wtype="simple", minp=0, adjust=False):
...     return sr_or_df.vbt.ma(window, wtype=wtype, minp=minp, adjust=adjust)

>>> sr = pd.Series([1, 2, 3, 4, 3, 2, 1])
>>> my_ma(sr, 3)
0    1.000000
1    1.500000
2    2.000000
3    3.000000
4    3.333333
5    3.000000
6    2.000000
dtype: float64

One parameter, no parameter configs:

>>> my_ma(sr, vbt.Param([3, 4, 5]))
window         3    4    5
0       1.000000  1.0  1.0
1       1.500000  1.5  1.5
2       2.000000  2.0  2.0
3       3.000000  2.5  2.5
4       3.333333  3.0  2.6
5       3.000000  3.0  2.8
6       2.000000  2.5  2.6

Product of two parameters, no parameter configs:

>>> my_ma(
...     sr,
...     vbt.Param([3, 4, 5]),
...     wtype=vbt.Param(["simple", "exp"])
... )
window         3                4                5
wtype     simple       exp simple       exp simple       exp
0       1.000000  1.000000    1.0  1.000000    1.0  1.000000
1       1.500000  1.500000    1.5  1.400000    1.5  1.333333
2       2.000000  2.250000    2.0  2.040000    2.0  1.888889
3       3.000000  3.125000    2.5  2.824000    2.5  2.592593
4       3.333333  3.062500    3.0  2.894400    2.6  2.728395
5       3.000000  2.531250    3.0  2.536640    2.8  2.485597
6       2.000000  1.765625    2.5  1.921984    2.6  1.990398

No parameters, one partial parameter config:

>>> my_ma(sr, param_configs=[dict(window=3)])
param_config         0
0             1.000000
1             1.500000
2             2.000000
3             3.000000
4             3.333333
5             3.000000
6             2.000000

No parameters, one full parameter config:

>>> my_ma(param_configs=[dict(sr_or_df=sr, window=3)])
param_config         0
0             1.000000
1             1.500000
2             2.000000
3             3.000000
4             3.333333
5             3.000000
6             2.000000

No parameters, multiple parameter configs:

>>> my_ma(param_configs=[
...     dict(sr_or_df=sr + 1, window=2),
...     dict(sr_or_df=sr - 1, window=3)
... ], minp=None)
param_config    0         1
0             NaN       NaN
1             2.5       NaN
2             3.5  1.000000
3             4.5  2.000000
4             4.5  2.333333
5             3.5  2.000000
6             2.5  1.000000

Multiple parameters, multiple parameter configs:

>>> my_ma(param_configs=[
...     dict(sr_or_df=sr + 1, minp=0),
...     dict(sr_or_df=sr - 1, minp=None)
... ], window=vbt.Param([2, 3]))
window          2              3
param_config    0    1         0         1
0             2.0  NaN  2.000000       NaN
1             2.5  0.5  2.500000       NaN
2             3.5  1.5  3.000000  1.000000
3             4.5  2.5  4.000000  2.000000
4             4.5  2.5  4.333333  2.333333
5             3.5  1.5  4.000000  2.000000
6             2.5  0.5  3.000000  1.000000

Using annotations:

>>> @vbt.parameterized
... def my_ma(
...     sr_or_df,
...     window: vbt.Param,
...     wtype: vbt.Param = "simple",
...     minp=0,
...     adjust=False
... ) -> vbt.MergeFunc("column_stack"):
...     return sr_or_df.vbt.ma(window, wtype=wtype, minp=minp, adjust=adjust)

>>> my_ma(sr, [3, 4, 5], ["simple", "exp"])
window         3                4                5
wtype     simple       exp simple       exp simple       exp
0       1.000000  1.000000    1.0  1.000000    1.0  1.000000
1       1.500000  1.500000    1.5  1.400000    1.5  1.333333
2       2.000000  2.250000    2.0  2.040000    2.0  1.888889
3       3.000000  3.125000    2.5  2.824000    2.5  2.592593
4       3.333333  3.062500    3.0  2.894400    2.6  2.728395
5       3.000000  2.531250    3.0  2.536640    2.8  2.485597
6       2.000000  1.765625    2.5  1.921984    2.6  1.990398

params_to_list function ¶

params_to_list(
    param_values,
    is_tuple=False,
    is_array_like=False
)

Cast parameters to a list.

pick_from_param_grid function ¶

pick_from_param_grid(
    param_grid,
    i=None
)

Pick one or more parameter combinations from a parameter grid.

Parameter values can also be an integer to represent the number of values.

to_typed_list function ¶

to_typed_list(
    lst
)

Cast Python list to typed list.

Direct construction is flawed in Numba 0.52.0. See https://github.com/numba/numba/issues/6651

Itemable class ¶

Itemable()

Class representing an object that can be returned as items.

Subclasses

items method ¶

Itemable.items(
    **kwargs
)

Return this instance as items.

Param class ¶

Param(
    *args,
    **kwargs
)

Class that represents a parameter.

Superclasses

Inherited members

condition class variable ¶

Keep a parameter combination only if the condition is met.

Condition can be a template or an expression where x (or parameter name) denotes this parameter and any other variable denotes the name of other parameter(s). If passed as an expression, it will be pre-compiled so its execution may be faster than if passed as a template.

To access a parameter index value, prepend and append __ to the level name. For example, use __fast_sma_timeperiod__ if the parameter index contains a level fast_sma_timeperiod.

context class variable ¶

Context used in evaluation of Param.condition and Param.map_template.

eval_id class variable ¶

One or more identifiers at which to evaluate this instance.

hide class variable ¶

Whether to hide the parameter from the parameter index.

is_array_like class variable ¶

Whether Param.value is array-like.

If so, providing a NumPy array will be considered as a single value.

is_tuple class variable ¶

Whether Param.value is a tuple.

If so, providing a tuple will be considered as a single value.

keys class variable ¶

Keys acting as an index level.

If None, converts Param.value to an index using index_from_values().

level class variable ¶

Level of the product the parameter takes part in.

Parameters with the same level are stacked together, while parameters with different levels are combined as usual.

Parameters are processed based on their level: a lower-level parameter is processed before (and thus displayed above) a higher-level parameter. If two parameters share the same level, they are processed in the order they were passed to the function.

Levels must come in a strict order starting with 0 and without gaps. If any of the parameters have a level specified, all parameters must specify their level.

map_template class variable ¶

Template to map Param.value before building parameter combinations.

map_value method ¶

Param.map_value(
    func,
    old_as_keys=False
)

Execute a function on each value in Param.value and create a new Param instance.

If old_as_keys is True, will use old values as keys, unless keys are already provided.

mono_merge_func class variable ¶

Merge function to apply when building a mono-chunk.

Resolved using resolve_merge_func().

mono_merge_kwargs class variable ¶

Keyword arguments passed to Param.mono_merge_func.

mono_reduce class variable ¶

Whether to reduce a mono-chunk of the same values into one value.

name class variable ¶

Name of the parameter.

If None, defaults to the name of the index in Param.keys, or to the key in param_dct passed to combine_params().

random_subset class variable ¶

Random subset of values to select.

value class variable ¶

One or more parameter values.

Paramable class ¶

Paramable()

Class representing an object that can be returned as a parameter.

Subclasses

as_param method ¶

Paramable.as_param(
    **kwargs
)

Return this instance as a parameter.

Parameterizer class ¶

Parameterizer(
    func,
    param_search_kwargs=None,
    skip_single_comb=None,
    template_context=None,
    build_grid=None,
    grid_indices=None,
    random_subset=None,
    random_replace=None,
    random_sort=None,
    max_guesses=None,
    max_misses=None,
    seed=None,
    clean_index_kwargs=None,
    name_tuple_to_str=None,
    selection=None,
    forward_kwargs_as=None,
    mono_min_size=None,
    mono_n_chunks=None,
    mono_chunk_len=None,
    mono_chunk_meta=None,
    mono_reduce=None,
    mono_merge_func=None,
    mono_merge_kwargs=None,
    filter_results=None,
    raise_no_results=None,
    merge_func=None,
    merge_kwargs=None,
    return_meta=None,
    return_param_index=None,
    execute_kwargs=None,
    **kwargs
)

Class responsible for parameterizing and running a function.

Does the following:

Searches for values wrapped with the class Param in any nested dicts and tuples using Parameterizer.find_params_in_obj()
Uses combine_params() to build parameter combinations
Maps parameter combinations to configs using Parameterizer.param_product_to_objs()
Generates and resolves parameter configs by combining combinations from the step above with param_configs that is optionally passed by the user. User-defined param_configs have more priority.
If selection is not None, substitutes it as a template, translates it into indices that can be mapped to param_index, and selects them from all the objects generated above.
Builds mono-chunks if mono_n_chunks, mono_chunk_len, or mono_chunk_meta is not None
Extracts arguments and keyword arguments from each parameter config and substitutes any templates (lazily)
Passes each set of the function and its arguments to execute() for execution
Optionally, post-processes and merges the results by passing them and **merge_kwargs to merge_func

Argument param_configs accepts either a list of dictionaries with arguments named by their names in the signature, or a dictionary of dictionaries, where keys are config names. If a list is passed, each dictionary can also contain the key _name to give the config a name. Variable arguments can be passed either in the rolled (args=(...), kwargs={...}) or unrolled (args_0=..., args_1=..., some_kwarg=...) format.

Important

Defining a parameter and listing the same argument in param_configs will prioritize the config over the parameter, even though the parameter will still be visible in the final columns. There are no checks implemented to raise an error when this happens!

If mono-chunking is enabled, parameter configs will be distributed over chunks. Any argument that is wrapped with Param or appears in mono_merge_func will be aggregated into a list. It will be merged using either Param.mono_merge_func or mono_merge_func in the same way as merge_func. If an argument satisfies neither of the above requirements and all its values within a chunk are same, this value will be passed as a scalar. Arguments mono_merge_func and mono_merge_kwargs must be dictionaries where keys are argument names in the flattened signature and values are functions and keyword arguments respectively.

If NoResult is returned, will skip the current iteration and remove it from the final index.

For defaults, see params.

Superclasses

Inherited members

build_grid property ¶

See combine_params().

build_mono_chunk_config method ¶

Parameterizer.build_mono_chunk_config(
    chunk_indices,
    param_configs,
    param_config_keys,
    ann_args,
    flat_ann_args=None,
    mono_reduce=None,
    mono_merge_func=None,
    mono_merge_kwargs=None,
    template_context=None
)

Build the parameter config for a mono-chunk.

clean_index_kwargs property ¶

See combine_params().

execute_kwargs property ¶

Keyword arguments passed to execute().

filter_results property ¶

Whether to filter NoResult results.

find_params_in_obj class method ¶

Parameterizer.find_params_in_obj(
    obj,
    eval_id=None,
    **kwargs
)

Find values wrapped with Param in a recursive manner.

Uses find_in_obj().

forward_kwargs_as property ¶

Map to rename keyword arguments.

Can also pass any variable from the scope of Parameterized.run.

func property ¶

Function.

get_mono_chunk_indices class method ¶

Parameterizer.get_mono_chunk_indices(
    param_configs,
    mono_min_size=None,
    mono_n_chunks=None,
    mono_chunk_len=None,
    mono_chunk_meta=None
)

Get the indices of each mono-chunk.

get_var_arg_names class method ¶

Parameterizer.get_var_arg_names(
    ann_args
)

Get the name of any packed variable position arguments and keyword arguments.

merge_func property ¶

Merging function.

Resolved using resolve_merge_func().

merge_kwargs property ¶

Keyword arguments passed to the merging function.

When defining a custom merging function, make sure to make use of param_index (via templates) to build the final index hierarchy.

mono_chunk_len property ¶

See yield_chunk_meta().

Applied to generate chunk meta.

mono_chunk_meta property ¶

Chunk meta.

mono_merge_func property ¶

See Param.mono_merge_func.

Can be a dictionary with a value per (unpacked) argument name. Otherwise, gets applied to each parameter, unless the parameter overrides it.

mono_merge_kwargs property ¶

See Param.mono_merge_kwargs.

Can be a dictionary with a value per (unpacked) argument name. Otherwise, gets applied to each parameter, unless the parameter overrides it.

mono_min_size property ¶

See yield_chunk_meta().

Applied to generate chunk meta.

mono_n_chunks property ¶

See yield_chunk_meta().

Applied to generate chunk meta.

mono_reduce property ¶

See Param.mono_reduce.

Can be a dictionary with a value per (unpacked) argument name. Otherwise, gets applied to each parameter, unless the parameter overrides it.

name_tuple_to_str property ¶

See combine_params().

param_product_to_objs class method ¶

Parameterizer.param_product_to_objs(
    obj,
    param_product
)

Resolve parameter product into a list of objects based on the original object.

Uses replace_in_obj().

param_search_kwargs property ¶

See Parameterized.find_params_in_obj.

parse_and_inject_params class method ¶

Parameterizer.parse_and_inject_params(
    flat_ann_args,
    eval_id=None
)

Parse Param instances from function annotations and inject them into flattened annotated arguments.

raise_no_results property ¶

Whether to raise NoResultsException if there are no results.

Otherwise, returns NoResult.

Has effect only if Parameterizer.filter_results is True. But regardless of this setting, gets passed to the merging function if the merging function is pre-configured.

random_replace property ¶

See combine_params().

random_sort property ¶

See combine_params().

random_subset property ¶

See combine_params().

return_meta property ¶

Whether to return all the metadata generated before running the function.

return_param_index property ¶

Whether to return the results along with the parameter index (as a tuple).

roll_param_config class method ¶

Parameterizer.roll_param_config(
    param_config,
    ann_args
)

Roll a parameter config.

run method ¶

Parameterizer.run(
    *args,
    param_configs=None,
    eval_id=None,
    **kwargs
)

Parameterize arguments and run the function.

seed property ¶

See combine_params().

select_comb class method ¶

Parameterizer.select_comb(
    param_configs,
    param_index,
    selection,
    single_comb=False,
    template_context=None,
    raise_no_results=True
)

Select a parameter combination from parameter configs and index.

selection property ¶

Parameter combination to select.

The selection can be one or more positions or labels from the parameter index. The selection value(s) can be wrapped with PosSel or LabelSel to instruct vectorbtpro what the value(s) should denote. Make sure that it's a sequence (for example, by wrapping it with a list) to attach the parameter index to the final result. It can be also NoResult to indicate that there's no result, or a template to yield any of the above.

skip_single_comb property ¶

Whether to execute the function directly if there's only one parameter combination.

template_context property ¶

Template context.

Any template in both execute_kwargs and merge_kwargs will be substituted. You can use the keys param_configs, param_index, all keys in template_context, and all arguments as found in the signature of the function. To substitute templates further down the pipeline, use substitution ids.

unroll_param_config class method ¶

Parameterizer.unroll_param_config(
    param_config,
    ann_args
)

Unroll a parameter config.

yield_tasks class method ¶

Parameterizer.yield_tasks(
    func,
    ann_args,
    param_configs,
    template_context=None
)

Yield functions and their arguments for execution.

params module¶

broadcast_params function¶

combine_params function¶

create_param_product function¶

flatten_param_tuples function¶

generate_param_combs function¶

get_param_grid_len function¶

is_single_param_value function¶

parameterized function¶

params_to_list function¶

pick_from_param_grid function¶

to_typed_list function¶

Itemable class¶

items method¶

Param class¶

condition class variable¶

context class variable¶

eval_id class variable¶

hide class variable¶

is_array_like class variable¶

is_tuple class variable¶

keys class variable¶

level class variable¶

map_template class variable¶

map_value method¶

mono_merge_func class variable¶

mono_merge_kwargs class variable¶

mono_reduce class variable¶

name class variable¶

random_subset class variable¶

value class variable¶

Paramable class¶

as_param method¶

Parameterizer class¶

build_grid property¶

build_mono_chunk_config method¶

clean_index_kwargs property¶

execute_kwargs property¶

filter_results property¶

find_params_in_obj class method¶

forward_kwargs_as property¶

func property¶

get_mono_chunk_indices class method¶

get_var_arg_names class method¶

grid_indices property¶

max_guesses property¶

max_misses property¶

merge_func property¶

merge_kwargs property¶

mono_chunk_len property¶

mono_chunk_meta property¶

mono_merge_func property¶

mono_merge_kwargs property¶

mono_min_size property¶

mono_n_chunks property¶

mono_reduce property¶

name_tuple_to_str property¶

param_product_to_objs class method¶

param_search_kwargs property¶

parse_and_inject_params class method¶

raise_no_results property¶

random_replace property¶

random_sort property¶

random_subset property¶

return_meta property¶

return_param_index property¶

roll_param_config class method¶

run method¶

seed property¶

select_comb class method¶

selection property¶

skip_single_comb property¶

template_context property¶

unroll_param_config class method¶

yield_tasks class method¶

params module ¶

broadcast_params function ¶

combine_params function ¶

create_param_product function ¶

flatten_param_tuples function ¶

generate_param_combs function ¶

get_param_grid_len function ¶

is_single_param_value function ¶

parameterized function ¶

params_to_list function ¶

pick_from_param_grid function ¶

to_typed_list function ¶

Itemable class ¶

items method ¶

Param class ¶

condition class variable ¶

context class variable ¶

eval_id class variable ¶

hide class variable ¶

is_array_like class variable ¶

is_tuple class variable ¶

keys class variable ¶

level class variable ¶

map_template class variable ¶

map_value method ¶

mono_merge_func class variable ¶

mono_merge_kwargs class variable ¶

mono_reduce class variable ¶

name class variable ¶

random_subset class variable ¶

value class variable ¶

Paramable class ¶

as_param method ¶

Parameterizer class ¶

build_grid property ¶

build_mono_chunk_config method ¶

clean_index_kwargs property ¶

execute_kwargs property ¶

filter_results property ¶

find_params_in_obj class method ¶

forward_kwargs_as property ¶

func property ¶

get_mono_chunk_indices class method ¶

get_var_arg_names class method ¶

grid_indices property ¶

max_guesses property ¶

max_misses property ¶

merge_func property ¶

merge_kwargs property ¶

mono_chunk_len property ¶

mono_chunk_meta property ¶

mono_merge_func property ¶

mono_merge_kwargs property ¶

mono_min_size property ¶

mono_n_chunks property ¶

mono_reduce property ¶

name_tuple_to_str property ¶

param_product_to_objs class method ¶

param_search_kwargs property ¶

parse_and_inject_params class method ¶

raise_no_results property ¶

random_replace property ¶

random_sort property ¶

random_subset property ¶

return_meta property ¶

return_param_index property ¶

roll_param_config class method ¶

run method ¶

seed property ¶

select_comb class method ¶

selection property ¶

skip_single_comb property ¶

template_context property ¶

unroll_param_config class method ¶

yield_tasks class method ¶