README.md

---
license: other
library_name: pytorch
tags:
  - eeg
  - brain-signal
  - biosignal
  - time-series
  - classification
  - biomedical-signal-processing
  - epilepsy
  - interictal-epileptiform-discharge
  - neuroscience
  - eegpt
  - eeg-dino
  - braindecode
datasets:
  - vEpiSet
base_model:
  - braindecode/eegpt-pretrained
  - braindecode/eegdino-medium-pretrained
---

# SenuaLab EEG IED Detection

Five patient-independent binary IED checkpoints, aggregate benchmark artifacts,
and an app-ready model pack for
[SenuaLab EEG Annotation Tool](https://github.com/SenuaLab/EEGAnnotationTool).
Training and evaluation use only the public
[vEpiSet](https://doi.org/10.6084/m9.figshare.28069568) dataset.

> **Research use only.** These models are not medical devices and must not be
> used as the sole basis for diagnosis or treatment. Every candidate requires
> review by a qualified EEG professional against the original recording.

> **Privacy.** No private hospital recording, patient identifier, physician
> annotation, local path, or hospital-derived patient result is included. The
> model parameters, public configuration metadata, and aggregate vEpiSet
> results were reviewed before upload.

Source, methodology, and reproducibility documentation:
[github.com/SenuaLab/EEG-IED-Detection](https://github.com/SenuaLab/EEG-IED-Detection)

## Models

| Folder | Model | Params | Rate | Window | Test AUROC | Test AUPRC | Test F1 |
|---|---|---:|---:|---:|---:|---:|---:|
| `iednet_lite` | IEDNet-Lite | 0.25M | 250 Hz | 4 s | 0.8793 | 0.6848 | 0.6372 |
| `resnet_attention` | ResNet-Attention | 4.99M | 250 Hz | 4 s | 0.8998 | 0.7018 | 0.6667 |
| `eegpt` | EEGPT + temporal head | 25.59M | 250 Hz | 4 s | 0.8641 | 0.6532 | 0.6139 |
| `eegpt_linear_probe` | EEGPT linear probe | 25.32M | 250 Hz | 4 s | 0.7519 | 0.3722 | 0.3227 |
| `eegdino_medium` | EEG-DINO Medium | 34.45M | 200 Hz | 4 s | **0.9363** | **0.8020** | **0.7415** |

All test thresholds were selected on validation subjects and then frozen. The
test split contains 3,908 windows from 13 held-out vEpiSet subjects. Results are
single-dataset, four-second window metrics, not prospective clinical claims.

## Files

```text
models/<name>/
├── model.safetensors     # tensor-only weights (preferred)
└── config.json           # reviewed input/provenance/metric contract

pytorch/<name>/
├── model.pth             # sanitized checkpoint for the Python runner
└── config.json

eegannotationtool/senua_<name>/
├── model.py              # executable architecture adapter
├── preprocessing.py      # released preprocessing contract
├── model.pth             # app-compatible sanitized checkpoint
└── manifest.json

ensembles/                # validation-selected ensemble definitions
results/                  # aggregate benchmark table and figure
MANIFEST.json             # SHA-256 and byte size for every release file
```

PyTorch `.pth` is included because the current EEG Annotation Tool model
discovery contract supports `.pth/.pt/.ckpt`. Prefer `safetensors` elsewhere and
load executable/model files only from this official repository.

## Input contract

- 19 standard 10-20 channels in this order:
  `Fp1, Fp2, F3, F4, C3, C4, P3, P4, O1, O2, F7, F8, T3, T4, T5, T6, Fz, Cz, Pz`.
- Four-second full windows.
- Fourth-order zero-phase 1-45 Hz Butterworth band-pass.
- Common-average reference across the 19 channels.
- Resampling to the rate listed in the table.
- One global z-score over the complete channel-time window, clipped to `[-8,8]`.
- Binary output order: `[Non-IED, IED]`.

Legacy temporal aliases T7/T8/P7/P8 map to T3/T4/T5/T6.

## Download

```bash
hf download SenuaLab/EEG-IED-Detection \
  pytorch/iednet_lite/model.pth \
  --local-dir ./weights
```

Or from Python:

```python
from huggingface_hub import hf_hub_download

path = hf_hub_download(
    repo_id="SenuaLab/EEG-IED-Detection",
    filename="pytorch/iednet_lite/model.pth",
)
```

The source repository runner accepts model short names and handles the download:

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

EEGPT and EEG-DINO require `braindecode[hub]==1.6.1`.

## EEG Annotation Tool

Use the installer from the source repository:

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

IED Finder discovers the installed folders, validates channels and the declared
input contract, and uses the validation-selected threshold as its starting
point. Foundation-model adapters are included but need Braindecode in the
application's Python environment.

## Evaluation limitations

- One public dataset and one fixed internal held-out split.
- No prospective, external multi-center, or medical-device validation.
- Four-second window metrics do not equal continuous event-level sensitivity.
- Performance can shift with montage, hardware, preprocessing, age, disease
  mix, artifacts, prevalence, and annotation policy.
- Threshold changes require a prospectively defined validation protocol and
  must not use the final evaluation cohort.
- Automated output is a review candidate, never a diagnosis.

## Model and data provenance

- vEpiSet: Lin et al., Scientific Data 12, 229 (2025),
  https://doi.org/10.1038/s41597-025-04523-8, CC BY 4.0.
- EEGPT: NeurIPS 2024, upstream code
  [BINE022/EEGPT](https://github.com/BINE022/EEGPT), encoder checkpoint
  [braindecode/eegpt-pretrained](https://huggingface.co/braindecode/eegpt-pretrained).
- EEG-DINO: MICCAI 2025,
  [paper](https://papers.miccai.org/miccai-2025/paper/3347_paper.pdf), encoder
  checkpoint
  [braindecode/eegdino-medium-pretrained](https://huggingface.co/braindecode/eegdino-medium-pretrained)
  at revision `191f73eb50d68a184b4cabb623938df914235d3c`.

See `MODEL_LICENSE.md` for the per-artifact licensing boundary and upstream
conditions.