EventManager class

An object that takes care of events in the experiment. See (TBD) for overview of the events mechanism.

When working with event manager, you should:

Some operations are triggered to run with temporal delay after the event. The event manager takes care of this timing. However, note that the event manager never takes the system time: it fully relies on the time you provide it (both dispatch_event() and on_frame() receive a time_in_session argument). For best precision, time_in_session should be synchronized with the display - i.e., set its value right aftet calling stimulus.present()

Methods and properties:

class trajtracker.events.EventManager
__init__()
cancel_pending_operations()

Cancel all pending operation - i.e., operations that were registered to run in a delay from an event that has already occurred.

In standard mode, there will be no need to call this function. You can call it, however, in case you want to reset everything and make sure you don’t have any leftovers.

dispatch_event(event, time_in_trial, time_in_session)

Inform the event manager that an event has occurred. This method will:

  • If an operation was registered to run on this event (with offset=0), invoke it
  • If an operation was registered to run some time after the event (offset > 0), remember it for later. It will be invoked by on_frame()
Parameters:
  • event – an Event object
  • time_in_trial – The time (in seconds) from the beginning of the present trial
  • time_in_session – The time (in seconds) from the beginning of the session. This parameter is very important, as the timing of operations is based on it. It must be syncronized with the time_in_session parameter sent to on_frame()
log_level

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

on_frame(time_in_trial, time_in_session)

This method must be called repeatedly - preferably on each frame. It takes care of invoking delayed operations - i.e., operations that should run somewhen after an already-dispatched event.

Parameters:
  • time_in_trial – The time (in seconds) from the beginning of the current trial
  • time_in_session – The time (in seconds) from the beginning of the session. This parameter is very important, as the timing of operations is based on it. It must be syncronized with the time_in_session parameter sent to dispatch_event()
Returns:

The number of operations invoked.
register(es_obj)

Register an event-sensitive object: an object that needs to run things based on the occurrence of events.

Under the hood: Technically, the only thing this method does is to call es_obj.on_registered(), and that method should take care of all the rest.

Parameters:es_obj – Must have an “on_registered” method, which will be called at the time of registration with the event manager as a single argument.
register_operation(event, operation, recurring=False, cancel_pending_operation_on=(), description=None)

Register a specific operation to run at some time.

This method is intended for internal use of the trajtracker package. Generally, you should not use this method but register().

Parameters:
  • event – Determines when the operation should be invoked
  • operation – A function that gets two arguments - time_in_trial and time_in_session. The function will be called at the time of the requested event. (you can provide any python object that behaves like a function, i.e., supports the () operator).
  • recurring – If True, the operation will be re-invoked every time the event occurs again. If False, the operation will be invoked once and then forgotten.
  • cancel_pending_operation_on (either Event or a list of events) – This is relevant for operations that were registered to run some time after an event X occurred. If, between the time of event X and the operation’s due time, a second event Y occurs (and cancel_pending_operation_on=Y), the operation will be discarded and not invoked.
Returns:

a unique identifier of this operation. You can use it later to unregister the operation via unregister_operation().
unregister_operation(operation_ids, warn_if_op_missing=True)

Unregister a previously-registered operation.

This method is intended for internal use of the trajtracker package. Generally, you should not use this method but register().

Parameters:
  • operation_ids – The ID returned from register_operation().
  • warn_if_op_missing – Print a warning to log if an operation ID is not registered in the event manager