# 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.