Skip to content
New: Star-import, signal unraveling, Python 3.12 support, and more

# params module

Utilities for working with parameters.

## broadcast_params function

    broadcast_params(
        param_list,
        to_n=None
    )

Broadcast parameters in `param_list`.

## 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,
        index_stack_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 `index_stack_kwargs` are passed to stack_indexes().

## create_param_product function

    create_param_product(
        param_list
    )

Make Cartesian product out of all params in `param_list`.

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

## 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,
        index_stack_kwargs=None,
        name_tuple_to_str=None,
        merge_func=None,
        merge_kwargs=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,
        return_meta=None,
        return_param_index=None,
        execute_kwargs=None,
        **kwargs
    )

Decorator that parameterizes the 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` are passed directly to execute().

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(
        params,
        is_tuple,
        is_array_like
    )

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.

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

## Param class

    Param(
        value=vectorbtpro.utils.params._DEF,
        is_tuple=False,
        is_array_like=False,
        map_template=None,
        random_subset=None,
        level=None,
        condition=None,
        context=None,
        keys=None,
        hide=False,
        name=None,
        mono_reduce=False,
        mono_merge_func=None,
        mono_merge_kwargs=None
    )

Class that represents a parameter.

Method generated by attrs for class Param.

Superclasses

- Annotatable

### check_value method

    Param.check_value()

Check whether value is missing.

### condition class variable

Keep a parameter combination only if the condition is met.

Condition should be an expression where `x` denotes this parameter and any other variable denotes the name of other parameter(s).

### context class variable

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

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

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

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

## 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,
        index_stack_kwargs=None,
        name_tuple_to_str=None,
        merge_func=None,
        merge_kwargs=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,
        return_meta=None,
        return_param_index=None,
        execute_kwargs=None,
        **kwargs
    )

Class responsible for parameterizing and running a function.

Superclasses

- Cacheable
- Chainable
- Comparable
- Configured
- HasSettings
- Pickleable
- Prettified

Inherited members

- Cacheable.get_ca_setup()
- Chainable.pipe()
- Configured.config
- Configured.copy()
- Configured.equals()
- Configured.get_writeable_attrs()
- Configured.prettify()
- Configured.rec_state
- Configured.replace()
- Configured.resolve_merge_kwargs()
- Configured.update_config()
- HasSettings.get_path_setting()
- HasSettings.get_path_settings()
- HasSettings.get_setting()
- HasSettings.get_settings()
- HasSettings.has_path_setting()
- HasSettings.has_path_settings()
- HasSettings.has_setting()
- HasSettings.has_settings()
- HasSettings.reset_settings()
- HasSettings.resolve_setting()
- HasSettings.resolve_settings_paths()
- HasSettings.set_settings()
- Pickleable.decode_config()
- Pickleable.decode_config_node()
- Pickleable.dumps()
- Pickleable.encode_config()
- Pickleable.encode_config_node()
- Pickleable.file_exists()
- Pickleable.getsize()
- Pickleable.load()
- Pickleable.loads()
- Pickleable.modify_state()
- Pickleable.resolve_file_path()
- Pickleable.save()

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

### execute_kwargs property

Keyword arguments passed to execute().

### find_params_in_obj class method

    Parameterizer.find_params_in_obj(
        obj,
        **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.

### grid_indices property

See combine_params().

### index_stack_kwargs property

See combine_params().

### max_guesses property

See combine_params().

### max_misses property

See combine_params().

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

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

### 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,
        **kwargs
    )

Parameterize arguments and run the function.

Does the following:

1. Searches for values wrapped with the class Param in any nested dicts and tuples using Parameterizer.find_params_in_obj()
2. Uses combine_params() to build parameter combinations
3. Maps parameter combinations to configs using Parameterizer.param_product_to_objs()
4. 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.
5. 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.
6. Builds mono-chunks if `mono_n_chunks`, `mono_chunk_len`, or `mono_chunk_meta` is not None
7. Extracts arguments and keyword arguments from each parameter config and substitutes any templates (lazily)
8. Passes each set of the function and its arguments to execute() for execution
9. 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.

### seed property

See combine_params().

### select_comb class method

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

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_funcs_args class method

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

Yield functions and their arguments for execution.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings