Episode 2: Triggering Data

Explore how to generate, process, and visualize trigger events in your pipeline. This episode covers creating and visualizing event markers, synchronizing triggers with signal data, and using them to control data analysis.

Note

This page is still under development. Until we have the step-by-step instructions ready, please refer to the code example below.

File example_basic_trigger.py – View file on GitHub

  1"""
  2Basic Trigger Example - Event-Related Potential (ERP) Analysis
  3
  4This example demonstrates how to use the Trigger node to extract time-locked
  5signal segments around specific events. This is fundamental for analyzing
  6Event-Related Potentials (ERPs) in BCI applications, where brain responses
  7to stimuli or user actions are studied.
  8
  9What this example shows:
 10- Generating continuous EEG-like signals with background noise
 11- Capturing keyboard events as experimental triggers
 12- Extracting signal epochs around trigger events (time-locked segments)
 13- Dual visualization: continuous signal + triggered epochs
 14- Real-time ERP analysis capabilities
 15
 16Expected output:
 17When you run this example, you'll see two displays:
 181. Time Series Scope: Continuous signal with real-time updates
 192. Trigger Scope: Event-locked signal epochs overlaid for comparison
 20
 21Interactive behavior:
 22- Press ↑ (Up) or → (Right) arrow keys to trigger epoch extraction
 23- Each key press extracts a 0.9-second epoch (0.2s pre + 0.7s post event)
 24- Epochs are averaged in the Trigger Scope
 25- Continuous signal keeps running in the Time Series Scope
 26
 27Epoch configuration:
 28- Pre-trigger: 0.2 seconds (baseline period before event)
 29- Post-trigger: 0.7 seconds (response period after event)
 30- Target events: Up arrow (38) and Right arrow (39) key codes
 31- Total epoch length: 0.9 seconds per trigger
 32
 33Real-world applications:
 34- P300 speller analysis (visual stimulus responses)
 35- Auditory ERP studies (sound stimulus processing)
 36- Visual evoked potential analysis (image/pattern responses)
 37
 38ERP analysis concepts:
 39- Time-locking: Aligning signals to specific event times
 40- Baseline correction: Using pre-trigger period for normalization
 41- Epoch averaging: Overlaying multiple trials for pattern detection
 42- Event-related changes: Identifying stimulus-response relationships
 43
 44Technical details:
 45- Trigger node monitors event stream for target codes
 46- Automatic epoch extraction when target events detected
 47- Signal buffering ensures complete epoch capture
 48- Real-time display updates for immediate feedback
 49
 50Usage:
 51    python example_basic_trigger.py
 52    Press Up or Right arrow keys to generate triggered epochs
 53    Observe epoch overlays in the Trigger Scope window
 54
 55Note:
 56    This example forms the foundation for more advanced ERP analysis
 57    and BCI classification systems that rely on event-related signals.
 58"""
 59import gpype as gp
 60
 61fs = 250  # Sampling frequency in Hz
 62
 63if __name__ == "__main__":
 64    # Create the main application window
 65    app = gp.MainApp()
 66
 67    # Create processing pipeline
 68    p = gp.Pipeline()
 69
 70    # Generate continuous EEG-like signals with noise
 71    source = gp.Generator(
 72        sampling_rate=fs,
 73        channel_count=8,  # 8 EEG channels
 74        signal_frequency=10,  # 10 Hz alpha rhythm
 75        signal_amplitude=10,  # Signal strength
 76        signal_shape="sine",  # Clean sine waves
 77        noise_amplitude=10,
 78    )  # Background noise
 79
 80    # Capture keyboard input as trigger events
 81    keyboard = gp.Keyboard()  # Arrow keys -> trigger codes
 82
 83    # Trigger node for epoch extraction around events
 84    trigger = gp.Trigger(
 85        time_pre=0.2,  # 0.2s before trigger (baseline)
 86        time_post=0.7,  # 0.7s after trigger (response)
 87        target=[38, 39],
 88    )  # Up (38) and Right (39) keys
 89
 90    # Specialized scope for displaying triggered epochs
 91    ep_scope = gp.TriggerScope(amplitude_limit=30)  # Overlaid epoch display
 92
 93    # Standard scope for continuous signal monitoring
 94    ts_scope = gp.TimeSeriesScope(
 95        amplitude_limit=30, time_window=10  # Y-axis range
 96    )  # 10 seconds history
 97
 98    # Connect the trigger analysis pipeline
 99    p.connect(source, trigger[gp.Constants.Defaults.PORT_IN])
100    p.connect(keyboard, trigger[trigger.PORT_TRIGGER])
101    p.connect(trigger, ep_scope)
102
103    # Connect continuous monitoring pipeline
104    p.connect(source, ts_scope)  # Continuous signal -> Time Series Scope
105
106    # Add both visualization widgets to application
107    app.add_widget(ep_scope)  # Epoch overlay display
108    app.add_widget(ts_scope)  # Continuous signal display
109
110    # Start ERP analysis system
111    p.start()  # Begin processing (press Up/Right for epochs)
112    app.run()  # Show GUI and start main loop
113    p.stop()  # Clean shutdown when window closes