Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,70 @@
+---
+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.