create_stimspace_stimuli

create_stimspace_stimuli#

stimupy.utils.create_stimspace_stimuli(stimulus_function, permutations_dicts, title_params=None)#

Generate stimuli for all parameter combinations in a stimspace.

Given a callable stimulus_function and a list of parameter combinations (as produced by [utils.permutate_params](utils.permutate_params)), this function generates and returns all corresponding stimulus images. Optionally, specific parameters can be included in the stimulus names for easier identification in plots or debugging.

Parameters:

  • stimulus_function (callable) – A stimulus-generating function that accepts keyword arguments matching the keys in permutations_dicts.

  • permutations_dicts (list of dict) – A list of parameter dictionaries, each representing one combination of stimulus parameters to be passed to stimulus_function. Typically obtained from [utils.permutate_params](utils.permutate_params).

  • title_params (str or list of str, optional) – Name(s) of parameters to display in the dictionary keys for the output. - If a string, it is interpreted as a single parameter name. - If a list, multiple parameter values will be included in the name. - If None (default), keys will be simple integer indices.

Returns:

Dictionary mapping descriptive keys to the generated stimulus outputs. Keys are either: - String representations of selected title_params and their values. - Sequential integer strings if title_params is None.

Return type:

dict

Raises:

ValueError – If stimulus_function is not callable.

Examples

>>> from stimupy.stimuli.gabors import gabor
>>> from stimupy.utils import permutate_params, create_stimspace_stimuli
>>> params = {
...     "visual_size": [1.],
...     "ppd": [50],
...     "sigma": [0.1, 0.2],
...     "frequency": [2, 4]
... }
>>> permuted = permutate_params(params)
>>> stimspace = create_stimspace_stimuli(
...     stimulus_function=gabor,
...     permutations_dicts=permuted,
...     title_params=["sigma", "frequency"]
... )
>>> list(stimspace.keys())
['sigma=0.1 frequency=2 ', 'sigma=0.1 frequency=4 ',
 'sigma=0.2 frequency=2 ', 'sigma=0.2 frequency=4 ']
Contents