@synsci/cli-darwin-x64-baseline 1.1.76 → 1.1.78

package/bin/skills/neurokit2/references/epochs_events.md

@@ -0,0 +1,471 @@
+# Epochs and Event-Related Analysis
+
+## Overview
+
+Event-related analysis examines physiological responses time-locked to specific stimuli or events. NeuroKit2 provides tools for event detection, epoch creation, averaging, and event-related feature extraction across all signal types.
+
+## Event Detection
+
+### events_find()
+
+Automatically detect events/triggers in a signal based on threshold crossings or changes.
+
+```python
+events = nk.events_find(event_channel, threshold=0.5, threshold_keep='above',
+                        duration_min=1, inter_min=0)
+```
+
+**Parameters:**
+- `threshold`: Detection threshold value
+- `threshold_keep`: `'above'` or `'below'` threshold
+- `duration_min`: Minimum event duration (samples) to keep
+- `inter_min`: Minimum interval between events (samples)
+
+**Returns:**
+- Dictionary with:
+  - `'onset'`: Event onset indices
+  - `'offset'`: Event offset indices (if applicable)
+  - `'duration'`: Event durations
+  - `'label'`: Event labels (if multiple event types)
+
+**Common use cases:**
+
+**TTL triggers from experiments:**
+```python
+# Trigger channel: 0V baseline, 5V pulses during events
+events = nk.events_find(trigger_channel, threshold=2.5, threshold_keep='above')
+```
+
+**Button presses:**
+```python
+# Detect when button signal goes high
+button_events = nk.events_find(button_signal, threshold=0.5, threshold_keep='above',
+                               duration_min=10)  # Debounce
+```
+
+**State changes:**
+```python
+# Detect periods above/below threshold
+high_arousal = nk.events_find(eda_signal, threshold='auto', duration_min=100)
+```
+
+### events_plot()
+
+Visualize event timing relative to signals.
+
+```python
+nk.events_plot(events, signal)
+```
+
+**Displays:**
+- Signal trace
+- Event markers (vertical lines or shaded regions)
+- Event labels
+
+**Use case:**
+- Verify event detection accuracy
+- Inspect temporal distribution of events
+- Quality control before epoching
+
+## Epoch Creation
+
+### epochs_create()
+
+Create epochs (segments) of data around events for event-related analysis.
+
+```python
+epochs = nk.epochs_create(data, events, sampling_rate=1000,
+                          epochs_start=-0.5, epochs_end=2.0,
+                          event_labels=None, event_conditions=None,
+                          baseline_correction=False)
+```
+
+**Parameters:**
+- `data`: DataFrame with signals or single signal
+- `events`: Event indices or dictionary from `events_find()`
+- `sampling_rate`: Signal sampling rate (Hz)
+- `epochs_start`: Start time relative to event (seconds, negative = before)
+- `epochs_end`: End time relative to event (seconds, positive = after)
+- `event_labels`: List of labels for each event (optional)
+- `event_conditions`: List of condition names for each event (optional)
+- `baseline_correction`: If True, subtract baseline mean from each epoch
+
+**Returns:**
+- Dictionary of DataFrames, one per epoch
+- Each DataFrame contains signal data with time relative to event (Index=0 at event onset)
+- Includes `'Label'` and `'Condition'` columns if provided
+
+**Typical epoch windows:**
+- **Visual ERP**: -0.2 to 1.0 seconds (200 ms baseline, 1 s post-stimulus)
+- **Cardiac orienting**: -1.0 to 10 seconds (capture anticipation and response)
+- **EMG startle**: -0.1 to 0.5 seconds (brief response)
+- **EDA SCR**: -1.0 to 10 seconds (1-3 s latency, slow recovery)
+
+### Event Labels and Conditions
+
+Organize events by type and experimental conditions:
+
+```python
+# Example: Emotional picture experiment
+event_times = [1000, 2500, 4200, 5800]  # Event onsets in samples
+event_labels = ['trial1', 'trial2', 'trial3', 'trial4']
+event_conditions = ['positive', 'negative', 'positive', 'neutral']
+
+epochs = nk.epochs_create(signals, events=event_times, sampling_rate=1000,
+                          epochs_start=-1, epochs_end=5,
+                          event_labels=event_labels,
+                          event_conditions=event_conditions)
+```
+
+**Access epochs:**
+```python
+# Epoch by number
+epoch_1 = epochs['1']
+
+# Filter by condition
+positive_epochs = {k: v for k, v in epochs.items() if v['Condition'][0] == 'positive'}
+```
+
+### Baseline Correction
+
+Remove pre-stimulus baseline from epochs to isolate event-related changes:
+
+**Automatic (during epoch creation):**
+```python
+epochs = nk.epochs_create(data, events, sampling_rate=1000,
+                          epochs_start=-0.5, epochs_end=2.0,
+                          baseline_correction=True)  # Subtracts mean of entire baseline
+```
+
+**Manual (after epoch creation):**
+```python
+# Subtract baseline period mean
+baseline_start = -0.5  # seconds
+baseline_end = 0.0     # seconds
+
+for key, epoch in epochs.items():
+    baseline_mask = (epoch.index >= baseline_start) & (epoch.index < baseline_end)
+    baseline_mean = epoch[baseline_mask].mean()
+    epochs[key] = epoch - baseline_mean
+```
+
+**When to baseline correct:**
+- **ERPs**: Always (isolates event-related change)
+- **Cardiac/EDA**: Usually (removes inter-individual baseline differences)
+- **Absolute measures**: Sometimes not desired (e.g., analyzing absolute amplitude)
+
+## Epoch Analysis and Visualization
+
+### epochs_plot()
+
+Visualize individual or averaged epochs.
+
+```python
+nk.epochs_plot(epochs, column='ECG_Rate', condition=None, show=True)
+```
+
+**Parameters:**
+- `column`: Which signal column to plot
+- `condition`: Plot only specific condition (optional)
+
+**Displays:**
+- Individual epoch traces (semi-transparent)
+- Average across epochs (bold line)
+- Optional: Shaded error (SEM or SD)
+
+**Use cases:**
+- Visualize event-related responses
+- Compare conditions
+- Identify outlier epochs
+
+### epochs_average()
+
+Compute grand average across epochs with statistics.
+
+```python
+average_epochs = nk.epochs_average(epochs, output='dict')
+```
+
+**Parameters:**
+- `output`: `'dict'` (default) or `'df'` (DataFrame)
+
+**Returns:**
+- Dictionary or DataFrame with:
+  - `'Mean'`: Average across epochs at each time point
+  - `'SD'`: Standard deviation
+  - `'SE'`: Standard error of mean
+  - `'CI_lower'`, `'CI_upper'`: 95% confidence intervals
+
+**Use case:**
+- Compute event-related potentials (ERPs)
+- Grand average cardiac/EDA/EMG responses
+- Group-level analysis
+
+**Condition-specific averaging:**
+```python
+# Separate averages by condition
+positive_epochs = {k: v for k, v in epochs.items() if v['Condition'][0] == 'positive'}
+negative_epochs = {k: v for k, v in epochs.items() if v['Condition'][0] == 'negative'}
+
+avg_positive = nk.epochs_average(positive_epochs)
+avg_negative = nk.epochs_average(negative_epochs)
+```
+
+### epochs_to_df()
+
+Convert epochs dictionary to unified DataFrame.
+
+```python
+epochs_df = nk.epochs_to_df(epochs)
+```
+
+**Returns:**
+- Single DataFrame with all epochs stacked
+- Includes `'Epoch'`, `'Time'`, `'Label'`, `'Condition'` columns
+- Facilitates statistical analysis and plotting with pandas/seaborn
+
+**Use case:**
+- Prepare data for mixed-effects models
+- Plotting with seaborn/plotly
+- Export to R or statistical software
+
+### epochs_to_array()
+
+Convert epochs to 3D NumPy array.
+
+```python
+epochs_array = nk.epochs_to_array(epochs, column='ECG_Rate')
+```
+
+**Returns:**
+- 3D array: (n_epochs, n_timepoints, n_columns)
+
+**Use case:**
+- Machine learning input (epoched features)
+- Custom array-based analysis
+- Statistical tests on array data
+
+## Signal-Specific Event-Related Analysis
+
+NeuroKit2 provides specialized event-related analysis for each signal type:
+
+### ECG Event-Related
+```python
+ecg_epochs = nk.epochs_create(ecg_signals, events, sampling_rate=1000,
+                              epochs_start=-1, epochs_end=10)
+ecg_results = nk.ecg_eventrelated(ecg_epochs)
+```
+
+**Computed metrics:**
+- `ECG_Rate_Baseline`: Heart rate before event
+- `ECG_Rate_Min/Max`: Minimum/maximum rate during epoch
+- `ECG_Phase_*`: Cardiac phase at event onset
+- Rate dynamics across time windows
+
+### EDA Event-Related
+```python
+eda_epochs = nk.epochs_create(eda_signals, events, sampling_rate=100,
+                              epochs_start=-1, epochs_end=10)
+eda_results = nk.eda_eventrelated(eda_epochs)
+```
+
+**Computed metrics:**
+- `EDA_SCR`: Presence of SCR (binary)
+- `SCR_Amplitude`: Maximum SCR amplitude
+- `SCR_Latency`: Time to SCR onset
+- `SCR_RiseTime`, `SCR_RecoveryTime`
+- `EDA_Tonic`: Mean tonic level
+
+### RSP Event-Related
+```python
+rsp_epochs = nk.epochs_create(rsp_signals, events, sampling_rate=100,
+                              epochs_start=-0.5, epochs_end=5)
+rsp_results = nk.rsp_eventrelated(rsp_epochs)
+```
+
+**Computed metrics:**
+- `RSP_Rate_Mean`: Average breathing rate
+- `RSP_Amplitude_Mean`: Average breath depth
+- `RSP_Phase`: Respiratory phase at event
+- Rate/amplitude dynamics
+
+### EMG Event-Related
+```python
+emg_epochs = nk.epochs_create(emg_signals, events, sampling_rate=1000,
+                              epochs_start=-0.1, epochs_end=1.0)
+emg_results = nk.emg_eventrelated(emg_epochs)
+```
+
+**Computed metrics:**
+- `EMG_Activation`: Presence of activation
+- `EMG_Amplitude_Mean/Max`: Amplitude statistics
+- `EMG_Onset_Latency`: Time to activation onset
+- `EMG_Bursts`: Number of activation bursts
+
+### EOG Event-Related
+```python
+eog_epochs = nk.epochs_create(eog_signals, events, sampling_rate=500,
+                              epochs_start=-0.5, epochs_end=2.0)
+eog_results = nk.eog_eventrelated(eog_epochs)
+```
+
+**Computed metrics:**
+- `EOG_Blinks_N`: Number of blinks during epoch
+- `EOG_Rate_Mean`: Blink rate
+- Temporal blink distribution
+
+### PPG Event-Related
+```python
+ppg_epochs = nk.epochs_create(ppg_signals, events, sampling_rate=100,
+                              epochs_start=-1, epochs_end=10)
+ppg_results = nk.ppg_eventrelated(ppg_epochs)
+```
+
+**Computed metrics:**
+- Similar to ECG: rate dynamics, phase information
+
+## Practical Workflows
+
+### Complete Event-Related Analysis Pipeline
+
+```python
+import neurokit2 as nk
+
+# 1. Process physiological signals
+ecg_signals, ecg_info = nk.ecg_process(ecg, sampling_rate=1000)
+eda_signals, eda_info = nk.eda_process(eda, sampling_rate=100)
+
+# 2. Align sampling rates if needed
+eda_signals_resampled = nk.signal_resample(eda_signals, sampling_rate=100,
+                                           desired_sampling_rate=1000)
+
+# 3. Merge signals into single DataFrame
+signals = pd.concat([ecg_signals, eda_signals_resampled], axis=1)
+
+# 4. Detect events
+events = nk.events_find(trigger_channel, threshold=0.5)
+
+# 5. Add event labels and conditions
+event_labels = ['trial1', 'trial2', 'trial3', ...]
+event_conditions = ['condition_A', 'condition_B', 'condition_A', ...]
+
+# 6. Create epochs
+epochs = nk.epochs_create(signals, events, sampling_rate=1000,
+                          epochs_start=-1.0, epochs_end=5.0,
+                          event_labels=event_labels,
+                          event_conditions=event_conditions,
+                          baseline_correction=True)
+
+# 7. Signal-specific event-related analysis
+ecg_results = nk.ecg_eventrelated(epochs)
+eda_results = nk.eda_eventrelated(epochs)
+
+# 8. Merge results
+results = pd.merge(ecg_results, eda_results, left_index=True, right_index=True)
+
+# 9. Statistical analysis by condition
+results['Condition'] = event_conditions
+condition_comparison = results.groupby('Condition').mean()
+```
+
+### Handling Multiple Event Types
+
+```python
+# Different event types with different markers
+event_type1 = nk.events_find(trigger_ch1, threshold=0.5)
+event_type2 = nk.events_find(trigger_ch2, threshold=0.5)
+
+# Combine events with labels
+all_events = np.concatenate([event_type1['onset'], event_type2['onset']])
+event_labels = ['type1'] * len(event_type1['onset']) + ['type2'] * len(event_type2['onset'])
+
+# Sort by time
+sort_idx = np.argsort(all_events)
+all_events = all_events[sort_idx]
+event_labels = [event_labels[i] for i in sort_idx]
+
+# Create epochs
+epochs = nk.epochs_create(signals, all_events, sampling_rate=1000,
+                          epochs_start=-0.5, epochs_end=3.0,
+                          event_labels=event_labels)
+
+# Separate by type
+type1_epochs = {k: v for k, v in epochs.items() if v['Label'][0] == 'type1'}
+type2_epochs = {k: v for k, v in epochs.items() if v['Label'][0] == 'type2'}
+```
+
+### Quality Control and Artifact Rejection
+
+```python
+# Remove epochs with excessive noise or artifacts
+clean_epochs = {}
+for key, epoch in epochs.items():
+    # Example: reject if EDA amplitude too high (movement artifact)
+    if epoch['EDA_Phasic'].abs().max() < 5.0:  # Threshold
+        # Example: reject if heart rate change too large (invalid)
+        if epoch['ECG_Rate'].max() - epoch['ECG_Rate'].min() < 50:
+            clean_epochs[key] = epoch
+
+print(f"Kept {len(clean_epochs)}/{len(epochs)} epochs")
+
+# Analyze clean epochs
+results = nk.ecg_eventrelated(clean_epochs)
+```
+
+## Statistical Considerations
+
+### Sample Size
+- **ERP/averaging**: 20-30+ trials per condition minimum
+- **Individual trial analysis**: Mixed-effects models handle variable trial counts
+- **Group comparisons**: Pilot data for power analysis
+
+### Time Window Selection
+- **A priori hypotheses**: Pre-register time windows based on literature
+- **Exploratory**: Use full epoch, correct for multiple comparisons
+- **Avoid**: Selecting windows based on observed data (circular)
+
+### Baseline Period
+- Should be free of anticipatory effects
+- Sufficient duration for stable estimate (500-1000 ms typical)
+- Shorter for fast dynamics (e.g., startle: 100 ms sufficient)
+
+### Condition Comparison
+- Repeated measures ANOVA for within-subject designs
+- Mixed-effects models for unbalanced data
+- Permutation tests for non-parametric comparisons
+- Correct for multiple comparisons (time points/signals)
+
+## Common Applications
+
+**Cognitive psychology:**
+- P300 ERP analysis
+- Error-related negativity (ERN)
+- Attentional blink
+- Working memory load effects
+
+**Affective neuroscience:**
+- Emotional picture viewing (EDA, HR, facial EMG)
+- Fear conditioning (HR deceleration, SCR)
+- Valence/arousal dimensions
+
+**Clinical research:**
+- Startle response (orbicularis oculi EMG)
+- Orienting response (HR deceleration)
+- Anticipation and prediction error
+
+**Psychophysiology:**
+- Cardiac defense response
+- Orienting vs. defensive reflexes
+- Respiratory changes during emotion
+
+**Human-computer interaction:**
+- User engagement during events
+- Surprise/violation of expectation
+- Cognitive load during task events
+
+## References
+
+- Luck, S. J. (2014). An introduction to the event-related potential technique (2nd ed.). MIT press.
+- Bradley, M. M., & Lang, P. J. (2000). Measuring emotion: Behavior, feeling, and physiology. In R. D. Lane & L. Nadel (Eds.), Cognitive neuroscience of emotion (pp. 242-276). Oxford University Press.
+- Boucsein, W. (2012). Electrodermal activity (2nd ed.). Springer.
+- Gratton, G., Coles, M. G., & Donchin, E. (1983). A new method for off-line removal of ocular artifact. Electroencephalography and clinical neurophysiology, 55(4), 468-484.