PeakFlow

PeakFlow: Peak-Guided Coarse-to-Refined Modeling for EEG-Based Dynamic Affective Trajectory Prediction

This repository provides a clean PyTorch implementation of PeakFlow for EEG-based dynamic affective intensity trajectory prediction.

PeakFlow contains three stages:

1. Stage I: Feature-Level EEG Temporal Tokenization
   Learns discrete EEG temporal-state tokens with a VQ-VAE style tokenizer.

2. Stage II: Masked Dynamic Affective-Flow Modeling
   Trains a masked Transformer to predict a coarse affective trajectory while using VQ code prediction as auxiliary supervision.

3. Stage III: Peak-Guided Bounded Residual Calibration
   Refines the coarse trajectory using peak-probability-guided bounded residual correction.

---

Installation

conda create -n peakflow python=3.9 -y
conda activate peakflow
pip install -r requirements.txt

---

Data Format

The main input file should be a .npz file containing:

X         float32, shape [N, T, D]       EEG feature sequence
y         float32, shape [N, T]          normalized intensity trajectory in [0, 1]
mask      float32/int, shape [N, T]      valid temporal mask
subjects  int, shape [N]                subject id for LOSO split

Optional keys: video_ids, emotion_ids, emotion_id_names, trial_ids.

---

Quick Start

Run all LOSO folds:

python scripts/run_loso.py \
  --data /path/to/seedvii_arousal_dynamic_seq.npz \
  --out-root runs/seedvii_peakflow \
  --num-subjects 20 \
  --device cuda

Run one subject fold:

python scripts/run_loso.py \
  --data /path/to/seedvii_arousal_dynamic_seq.npz \
  --out-root runs/seedvii_peakflow \
  --test-subject 1 \
  --device cuda

Aggregate results:

python scripts/aggregate_loso_results.py \
  --run-root runs/seedvii_peakflow \
  --out runs/seedvii_peakflow/summary.csv

Plot peak-position distribution:

python scripts/plot_peak_position_distribution.py \
  --run-root runs/seedvii_peakflow \
  --out-dir runs/seedvii_peakflow/figures

---

Metrics

Global metrics: MSE, MAE, PCC, R².
Peak-centered metrics: normalized peak-time error, peak-value error, and false-terminal peak rate.
The terminal region is defined as the last r_term = 10% of valid temporal windows.

---

---

License

MIT License.