README.md

---
license: mit
library_name: braindecode
tags:
  - eeg
  - event-detection
  - dance
  - p300
datasets:
  - BI2014a
---

# DANCE — BI2014a P300 event-detection checkpoint

Pretrained weights for the [`braindecode.models.DANCE`](https://braindecode.org/stable/generated/braindecode.models.DANCE.html)
model, used by the tutorial *"From window labels to events: asynchronous EEG
decoding with DANCE"*.

DANCE detects a *set* of `(start, end, class)` events directly from long,
unaligned EEG windows, without being told where an event starts. This
checkpoint was trained on the Brain Invaders **BI2014a** P300 dataset (flash
detection: class `1` = non-target, class `2` = target, class `0` = background).

## Results

Cross-subject, held-out subject 3 (never seen in training):

| Metric | Value |
|---|---|
| F1-event (IoU > 0.5 + class match) | **0.495** |
| F1-sample (per-token macro) | 0.372 |

On the first held-out window the model predicts 51 events (ground truth: 53),
mean duration ≈ 1.1 s, with confidences 0.75–0.99 — i.e. sharp, correctly
localized P300 flashes.

## How to load

The architecture must be built exactly as in the tutorial (the state dict is
saved with these hyper-parameters):

```python
import torch
from huggingface_hub import hf_hub_download
from braindecode.models import DANCE

model = DANCE(
    n_outputs=3,
    n_chans=len(chs_info),   # 16 for BI2014a
    chs_info=chs_info,
    n_times=4096,            # 32 s @ 128 Hz
    sfreq=128.0,
    input_window_seconds=32.0,
)
model.load_state_dict(
    torch.load(hf_hub_download("braindecode/plot_dance_event_detection", "model.pt"))
)
```

## Training

- Data: BI2014a, subjects 1, 2, 4–9 for training; subject 3 held out.
- Preprocessing (paper recipe): pick EEG, band-pass 0.1–100 Hz, resample to
  128 Hz, per-channel robust scaling clamped to `[-16, 16]`.
- Windows: 32 s fixed length, up to 150 events/window, `num_latents = 256`.
- Optimiser: Adam, constant lr `5e-4`, batch size 16, 120 epochs,
  best-by-held-out-F1-event checkpoint.
- Loss: `braindecode.training.DanceLoss` (matched-only IoU normalization).

Reproduce with `train_checkpoint.py` in this repository.