poulet_py.tools.generators module

generate_stimulus_sequence(n, *, stimuli_options, mode='random')

Generate a list of trials with specified stimuli distribution.

Parameters:

• n (int) – Number of trials to generate. Must be divisible by the number of stimuli options when mode is ‘random’ or when multiple stimuli are provided in ‘fixed’ mode.

• stimuli_options (List[Any]) – List of possible stimulus values. For a single stimulus, all trials will use it. For multiple stimuli, distribution depends on mode.

• mode ({'random', 'fixed'}, optional) – Distribution mode: - ‘random’: Shuffled trials with equal representation of each stimulus - ‘fixed’: Trials use stimuli in sequence (or single stimulus repeated) (default: ‘random’)

Returns:

Generated list of stimuli for each trial

Return type:

List[Any]

Raises:

ValueError – If n is not divisible by number of stimuli options (for relevant modes), or if mode is invalid.

Notes

• For ‘random’ mode with multiple stimuli, each appears exactly

  n//len(stimuli_options) times.

• For ‘fixed’ mode with multiple stimuli, stimuli are repeated in sequence

  until n is reached.

• For ‘fixed’ mode with single stimulus, that stimulus is repeated n times.

Examples

>>> generate_trials(4, stimuli_options=[1, 2], mode="random")
[2, 1, 2, 1]  # Random order with equal representation

>>> generate_trials(3, stimuli_options=[5], mode="fixed")
[5, 5, 5]