ETracker.record_event

ETracker.record_event(label)

Record timestamped experimental event during data collection.

Events are merged with gaze data based on timestamp proximity during save operations. Uses appropriate timing source for simulation vs. real eye tracker modes.

Parameters

Name Type Description Default
label str Descriptive label for the event (e.g., ‘trial_start’, ‘stimulus_onset’). required

Raises

Type Description
RuntimeWarning If called when recording is not active.

Details

Event-Gaze Synchronization

Events are stored separately and merged with gaze data when save_data() is called. Each event is aligned to the next closest gaze sample (at or after the event timestamp) using binary search. When multiple events occur within the same sampling interval, they are concatenated with semicolon delimiters in the Events column (e.g., ‘fixation_offset; stimulus_onset’). This ensures no event data is lost even when events occur in rapid succession.

Examples

Basic Usage

Recording single events

ET_controller.record_event('trial_1_start')
# ... present stimulus ...
ET_controller.record_event('stimulus_offset')

Common Patterns

Complete trial structure

ET_controller.record_event('trial_1_start')
ET_controller.record_event('fixation_onset')
core.wait(1.0)
ET_controller.record_event('fixation_offset')

ET_controller.record_event('stimulus_onset')
# ... show stimulus ...
ET_controller.record_event('stimulus_offset')

ET_controller.record_event('response_prompt')
# ... wait for response ...
ET_controller.record_event('response_recorded')
ET_controller.record_event('trial_1_end')

Multi-trial experiment

ET_controller.start_recording('experiment.h5')

for trial_num in range(10):
    ET_controller.record_event(f'trial_{trial_num}_start')
    # ... run trial ...
    ET_controller.record_event(f'trial_{trial_num}_end')

ET_controller.stop_recording()

Rapid successive events

# Events occurring within same sampling interval
ET_controller.record_event('fixation_offset')
ET_controller.record_event('stimulus_onset')

# In saved data, may appear as: "fixation_offset; stimulus_onset"
Back to top