| --- |
| license: mit |
| library_name: braindecode |
| tags: |
| - eeg |
| - event-detection |
| - dance |
| - p300 |
| datasets: |
| - nm000244 |
| --- |
| |
| # 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. |
|
|
| <!-- braindecode:training-data --> |
| ## Training data |
|
|
| The data that shaped these weights. The ids are the `datasets:` field of this card, |
| which braindecode reads into `model.card_data.datasets` when you call |
| `from_pretrained` (MOABB class names for MOABB datasets, OpenNeuro / NEMAR |
| accessions, Hub ids otherwise). `nm`/`on` ids are datasets on [NEMAR](https://nemar.org) |
| (`on` = NEMAR's copy of the OpenNeuro dataset with the same number). Rows marked |
| `private:` are data the authors did not release; they are not in `datasets:`. |
|
|
| | `datasets:` id | Dataset | Stage | Modality | |
| |---|---|---|---| |
| | [`nm000244`](https://nemar.org/dataset/nm000244) | [Brain Invaders 2014a P300 dataset (MOABB BI2014a)](https://moabb.neurotechx.com/docs/generated/moabb.datasets.BI2014a.html) | training | EEG | |
|
|
| - Supervised DANCE event detection, cross-subject. Gradient updates on BI2014a subjects 1, 2, 4, 5, 6, 7, 8, 9 (all their sessions as loaded by MOABBDataset); subject 3 is the held-out subject but its F1-event is used to keep the best epoch (torch.save on improvement), so subject 3 selected the checkpoint. 32 s windows at 128 Hz, 120 epochs per card (script default 100). |
| - Sources: https://huggingface.co/braindecode/plot_dance_event_detection/resolve/main/train_checkpoint.py; W/cards-orig/plot_dance_event_detection.md; W/bd/examples/applied_examples/plot_dance_event_detection.py. |
| |
| |
| |
| ## Cite Braindecode |
| |
| If you use this braindecode port in scientific work, cite the software on Zenodo, |
| [doi:10.5281/zenodo.17699192](https://doi.org/10.5281/zenodo.17699192), |
| and the original model and datasets cited above. |
| |
| ```bibtex |
| @software{braindecode, |
| author = {Aristimunha, Bruno and |
| Guetschel, Pierre and |
| Wimpff, Martin and |
| Gemein, Lukas and |
| Rommel, Cedric and |
| Banville, Hubert and |
| Sliwowski, Maciej and |
| Wilson, Daniel and |
| Brandt, Simon and |
| Gnassounou, Théo and |
| Paillard, Joseph and |
| {Junqueira Lopes}, Bruna and |
| Sedlar, Sara and |
| Moreau, Thomas and |
| Chevallier, Sylvain and |
| Gramfort, Alexandre and |
| Schirrmeister, Robin Tibor}, |
| title = {Braindecode: toolbox for decoding raw electrophysiological brain data |
| with deep learning models}, |
| url = {https://github.com/braindecode/braindecode}, |
| doi = {10.5281/zenodo.17699192}, |
| publisher = {Zenodo}, |
| license = {BSD-3-Clause}, |
| } |
| ``` |
| |
