MultiStimulus class

This class can present one or more stimuli during a trial. The class can handle Expyriment stimuli of any type - pictures, shapes, etc. You can easily configure the onset and offset time of each of the stimuli to present, so you can use this to present stimuli in RSVP.

The MultiStimulus object holds a set of preloaded stimuli that it can show, each with a string ID. On each trial, you define which of these stimuli to show. Thus, switching between stimuli is not time-consuming, and can be safely done in mid-trial. The only time-consuming operation is the initialization of stimuli, which would typically be done before the experiment starts.

A MultiStimulus is not by itself a stimulus (e.g., it does not have a present() method). The stimulus-like methods can be accessed via stimulus.

Using this class:

Configuring the stimuli

When working with the MultiStimulis class, you define stimuli twice:

  • available_stimuli is the set of all stimuli that can be presented. Typically, you’ll define this before the experiment starts, and preload all stimuli. Each picture is assigned a string ID.
  • shown_stimuli is the list of stimuli shown in a specific trial. Here, you don’t reload the stimuli - you just specify their string IDs.

Controlling the onset and offset times of each picture can be done via the events mechanism or by directly calling some methods of this class. This works just like the MultiTextBox class - please see there for details.

Methods and properties:

class trajtracker.stimuli.MultiStimulus(available_stimuli=None, shown_stimuli=None, position=None, onset_time=None, duration=None, last_stimulus_remains=False, onset_event=None, terminate_event=<trajtracker.events._Event.Event object>)
__init__(available_stimuli=None, shown_stimuli=None, position=None, onset_time=None, duration=None, last_stimulus_remains=False, onset_event=None, terminate_event=<trajtracker.events._Event.Event object>)

Called when creating a MultiStimulus object

Parameters:
add_stimulus(stim_id, stimulus)

Add a stimulus to the set of available stimuli.

Parameters:
  • stim_id (str) – A logical name of the stimulus
  • stimulus – an expyriment stimulus
available_stimuli

The pool of stimuli that can be presented.

Type:dict (key=string ID; value=an expyriment stimulus).
duration

The duration of showing each stimulus.

A stimulus disappears when the duration expired or when a terminate_event was dispatched.

Type:list/tuple of numbers
get_stimulus_desc(stimulus_num)

Get a description of one of the stimuli (e.g., the filename in case of a picture)

Parameters:stimulus_num – The stimulus index
Returns:str
init_for_trial()

Initialize when a trial starts.

Do not use this function if you are working with the events mechanism.

last_stimulus_remains

Whether the last stimulus presented in the sequence should remain on screen (True), or has a limited duration similarly to the previous stimuli (False)

log_level

Logging level of this object: trajtracker.log_none, log_error (default), log_warn, log_info, log_debug, log_trace

onset_event

The event which serves as a reference point for displaying stimul. All onset_time’s are indicated relatively to this event.

Note: This property is relevant only when working with events (with an EventManager)

onset_time

The onset time of each stimulus, relatively to the onset_event.

Type:list/tuple of numbers
position

The position of the stimuli to show (x,y). This can be either a single tuple or a list of tuples, one per shown value

register_onset_offset_callback_func(func)

Register a function that should be called when a stimulus is shown/hidden

Parameters:func –

The function, which gets 4 parameters:

  1. The MultiStimulus/MultiTextBox object
  2. The stimulus/text number (0=first)
  3. Whether the stimulus is presented (True) or hidden (False)
  4. The time when the corresponding present() function returned
shown_stimuli

The stimuli to show in the trial (a list of strings, each is the stimulus ID)

start_showing(time)

When working without events: this sets time=0 for the texts to show (i.e., the onset_time are relatively to this time point).

This function will also invoke update_display().

Do not use this function if you are working with the events mechanism.

Parameters:time – The time in the current session/trial. This must be synchronized with the “time” argument of update_display()
stim_visibility

Return an array of booleans, indicating whether each stimulus is presently visible or not. The array has as many elements as the number of stimuli (text/picture) presented.

stimulus

A single stimulus that represents all the stimuli in this MultiTextBox

Type:StimulusContainer
terminate_event

An event that terminates the display of stimuli, including the display of stimuli that are still scheduled to appear. Default: TRIAL_ENDED.

You can set to None to disable termination; however, note that in this case you might get strange behavior if the next trial starts while the stimuli are still being shown. To prevent this, you’ll have to take care yourself of cleaning up pending operations from the event manager.

Note: This property is relevant only when working with events (and with an EventManager)

trial_configured_event

An event indicating the time when the per-trial information was configured. By default, this is the TRIAL_INIITALIZED event.

Note:

  • This property is relevant only when working with events (and with an EventManager)
  • The property cannot be changed after the object was registered to an EventManager
unregister_onset_offset_callback_func(func)

Unegister a callback function previously registered with unregister_onset_offset_callback_func()

Parameters:func – The function
update_display(time)

Set relevant stimuli as visible/invisible.

Do not use this function if you are working with the events mechanism.

Parameters:time – The time in the current session/trial. This must be synchronized with the “time” argument of start_showing()