Episode 2: Triggering Data

In this episode, you learn how to work with triggering data in g.Pype.

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