SenuaLab EEG IED Detection

Patient-independent detection of interictal epileptiform discharges (IEDs) in scalp EEG. We release the complete leakage-safe training and evaluation pipeline, aggregate experiment artifacts, reproducibility metadata, five supported checkpoints, and an installation path for our EEG Annotation Tool.

Warning

This is research software, not a medical device. It must not be used as the sole basis for diagnosis or treatment. Every automated candidate requires review by a qualified EEG professional against the original recording.

Important

No private hospital recording, patient identifier, physician annotation, or patient-level hospital result is included in this repository or in the model release. The reported benchmark uses only the public vEpiSet dataset.

فارسی: راهنمای کامل فارسی

What we release

• A subject-level train/validation/test pipeline that prevents windows from the same person from crossing split boundaries.
• IEDNet-Lite and ResNet-Attention baselines trained from scratch.
• EEGPT and EEG-DINO Medium transfer-learning models, plus an EEGPT linear probe retained as an experimental baseline.
• Validation-selected operating thresholds, calibration results, bootstrap confidence intervals, training histories, confusion matrices, and aggregate held-out test metrics.
• safetensors weights and sanitized PyTorch checkpoints on Hugging Face.
• A model pack matching EEG Annotation Tool's IED Finder discovery contract.

Legacy window-split experiments are documented as development history, but their checkpoints are not presented as supported release models because a window-level split does not measure generalization to unseen subjects.

Held-out benchmark

All thresholds were selected on the validation split and then frozen. The test set contains 3,908 four-second windows from 13 held-out subjects. These are window-classification results on vEpiSet; they are not prospective clinical performance claims.

Model	AUROC	AUPRC	F1	Sensitivity	Specificity
IEDNet-Lite	0.8793	0.6848	0.6372	0.6313	0.9562
ResNet-Attention	0.8998	0.7018	0.6667	0.6083	0.9729
EEGPT	0.8641	0.6532	0.6139	0.5714	0.9637
EEG-DINO Medium	0.9363	0.8020	0.7415	0.7765	0.9603
Four-model ensemble	0.9201	0.7888	0.7624	0.7465	0.9735

The full table, thresholds, confusion counts, and limitations are in Results. Machine-readable artifacts are in results/.

Quick start

Create a Python 3.10-3.12 environment and install the project:

git clone https://github.com/SenuaLab/EEG-IED-Detection.git
cd EEG-IED-Detection
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

For EEGPT and EEG-DINO, install the optional foundation-model dependency:

python -m pip install -e ".[foundation]"

Download a released model by its short name and run inference on BrainVision recordings:

python -m eeg_ied_detector.robust_predict \
  --data-dir /path/to/recordings \
  --model-paths iednet_lite resnet_attention \
  --output-dir ./predictions \
  --no-label-comparison

Short names are resolved from SenuaLab/EEG-IED-Detection and cached by huggingface_hub. Local .pth checkpoint paths are also accepted. The input directory can be a single BrainVision session or a recursive folder tree. Required 10-20 channels are validated before inference.

Dataset

We train and evaluate on vEpiSet, a CC BY 4.0 public EEG dataset containing recordings from 84 subjects. The source publication reports 2,516 IED and 22,933 non-IED epochs. Our reproducible conversion yielded 25,384 usable four-second windows for the released split.

We do not duplicate the 16.9 GB upstream archive in Git. Download and verify it directly from its authoritative Figshare record:

python scripts/download_vepiset.py --output-dir ./Dataset

See Dataset and attribution for the file contract, checksum, class mapping, and preprocessing steps.

Reproduce training

Train the two from-scratch baselines:

python -m eeg_ied_detector.robust_train \
  --data-dir ./Dataset \
  --output-dir ./outputs/robust_patient_split \
  --models iednet_lite resnet_attention \
  --seed 2026

Continue with EEGPT and EEG-DINO after the common split/cache has been created:

python -m eeg_ied_detector.eegpt_train \
  --output-root ./outputs/robust_patient_split \
  --seed 2026

python -m eeg_ied_detector.eegdino_train \
  --output-root ./outputs/robust_patient_split \
  --data-dir ./Dataset \
  --seed 2026

Exact methodology and provenance are documented in Methodology and Reproducibility.

EEG Annotation Tool

The released Hugging Face repository contains an eegannotationtool/ model pack. Install it into EEG Annotation Tool's model directory with:

python scripts/install_eeg_annotation_models.py \
  --models iednet_lite resnet_attention

IED Finder will discover the folders and read the declared channel order, sampling rate, four-second input window, preprocessing contract, and validation-selected threshold. EEGPT and EEG-DINO adapters are also available when the application's Python environment includes braindecode==1.6.1.

See EEG Annotation Tool integration for Windows paths, verification, and the exact review workflow.

Privacy and responsible use

The publication was built from an explicit allowlist. Raw hospital recordings, local result directories, physician label files, private subject names, absolute local paths, and per-patient hospital metrics are excluded by design. The repository includes a privacy audit script and CI gate:

python scripts/privacy_audit.py .

The full boundary and contributor rules are in Privacy. Do not open an issue containing clinical EEG, patient identifiers, private annotations, or screenshots with identifying metadata.

Documentation

• Methodology
• Results and interpretation
• Dataset and attribution
• Reproducibility
• Development history
• Privacy boundary
• EEG Annotation Tool integration
• Third-party software and model terms

Citation

Use CITATION.cff for this release and cite the upstream dataset/foundation model corresponding to the model you use. Complete BibTeX entries are provided in Reproducibility.

License

SenuaLab source code and documentation are released under the MIT License. Dataset and model artifacts retain the attribution and upstream conditions described in THIRD_PARTY.md and on the Hugging Face model card.