Create README.md
Browse files
README.md
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
library_name: samba-eeg
|
| 3 |
+
pipeline_tag: feature-extraction
|
| 4 |
+
tags:
|
| 5 |
+
- eeg
|
| 6 |
+
- brain-computer-interface
|
| 7 |
+
- self-supervised-learning
|
| 8 |
+
- mamba
|
| 9 |
+
- pytorch
|
| 10 |
+
---
|
| 11 |
+
|
| 12 |
+
# SAMBA
|
| 13 |
+
|
| 14 |
+
EEG representation models. [Code](https://github.com/Jiazhen-Hong/SAMBA) · [Paper](https://arxiv.org/abs/2511.18571)
|
| 15 |
+
|
| 16 |
+
SAMBA was developed during my 2025 internship at Emotiv. The original checkpoints are no longer available, so we retrained both models. SAMBA-100s follows the original training method with a rebuilt TUAB pipeline and validation split. SAMBA-2s adds HBN, Muse, and DICE to the Emotiv data for greater electrode-layout diversity.
|
| 17 |
+
|
| 18 |
+
## Checkpoints
|
| 19 |
+
|
| 20 |
+
Both models use 128 Hz EEG. The names indicate the pretraining window; the encoders support other input lengths and channel layouts.
|
| 21 |
+
|
| 22 |
+
| | [SAMBA-2s](SAMBA-2s) | [SAMBA-100s](SAMBA-100s) |
|
| 23 |
+
|---|---|---|
|
| 24 |
+
| Window | 2 s, 256 samples | 100 s, 12,800 samples |
|
| 25 |
+
| Data | Emotiv¹, HBN, Muse, DICE | TUAB |
|
| 26 |
+
| Pretraining channels | 4, 14, 19, 129 | 16 bipolar |
|
| 27 |
+
| Parameters | 1.06M | 1.06M |
|
| 28 |
+
|
| 29 |
+
¹ Alpha, Attention, Crowdsource, DriverDistraction, and STEW.
|
| 30 |
+
|
| 31 |
+
## Usage
|
| 32 |
+
|
| 33 |
+
Requires a compatible CUDA system.
|
| 34 |
+
|
| 35 |
+
```bash
|
| 36 |
+
git clone https://github.com/Jiazhen-Hong/SAMBA.git
|
| 37 |
+
cd SAMBA
|
| 38 |
+
pip install -e '.[mamba,hub]'
|
| 39 |
+
```
|
| 40 |
+
|
| 41 |
+
```python
|
| 42 |
+
from pathlib import Path
|
| 43 |
+
import torch
|
| 44 |
+
from huggingface_hub import snapshot_download
|
| 45 |
+
from samba_eeg import SambaModel
|
| 46 |
+
|
| 47 |
+
variant = "SAMBA-2s" # or "SAMBA-100s"
|
| 48 |
+
folder = snapshot_download(
|
| 49 |
+
"Jay1208/SAMBA",
|
| 50 |
+
allow_patterns=[f"{variant}/*"],
|
| 51 |
+
)
|
| 52 |
+
model = SambaModel.from_pretrained(Path(folder) / variant).cuda().eval()
|
| 53 |
+
```
|
| 54 |
+
|
| 55 |
+
Prepare EEG at 128 Hz:
|
| 56 |
+
- `signals`: `[batch, channels, samples]`.
|
| 57 |
+
- `positions`: `[channels, 3]` or `[batch, channels, 3]`, matching the channel order and the coordinate units and frame in `config.json`.
|
| 58 |
+
- Normalize each channel in each window by its absolute 95th percentile. TUAB pretraining uses a 0.5–45 Hz bandpass.
|
| 59 |
+
|
| 60 |
+
```python
|
| 61 |
+
signals = signals.to(device="cuda", dtype=torch.float32)
|
| 62 |
+
positions = positions.to(device="cuda", dtype=torch.float32)
|
| 63 |
+
|
| 64 |
+
# Skip if already normalized.
|
| 65 |
+
scale = torch.quantile(signals.abs(), 0.95, dim=-1, keepdim=True)
|
| 66 |
+
signals = signals / scale.clamp_min(1e-8)
|
| 67 |
+
|
| 68 |
+
with torch.inference_mode():
|
| 69 |
+
features = model.encode(signals, positions)
|
| 70 |
+
pooled_features = features.mean(dim=1)
|
| 71 |
+
```
|
| 72 |
+
|
| 73 |
+
`features` has shape `[batch, floor(samples / 8), 128]`. Use the pooled features for linear probing, or fine-tune the encoder.
|
| 74 |
+
|
| 75 |
+
## Citation
|
| 76 |
+
|
| 77 |
+
```bibtex
|
| 78 |
+
@article{hong2026samba,
|
| 79 |
+
title={SAMBA: Toward an EEG Foundation Model via Differential Mamba and Coordinate-Driven Spatial Embedding},
|
| 80 |
+
author={Hong, Jiazhen and Mackellar, Geoffrey and Ghane, Soheila},
|
| 81 |
+
journal={arXiv preprint arXiv:2511.18571},
|
| 82 |
+
year={2026}
|
| 83 |
+
}
|
| 84 |
+
```
|