Update README.md
Browse files
README.md
CHANGED
|
@@ -3,22 +3,86 @@ pipeline_tag: feature-extraction
|
|
| 3 |
tags:
|
| 4 |
- eeg
|
| 5 |
- brain-computer-interface
|
| 6 |
-
-
|
| 7 |
- mamba
|
|
|
|
| 8 |
---
|
| 9 |
|
| 10 |
# SAMBA-100s
|
| 11 |
|
| 12 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 13 |
|
| 14 |
-
[
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 15 |
|
| 16 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 17 |
|
| 18 |
```python
|
|
|
|
| 19 |
from huggingface_hub import snapshot_download
|
| 20 |
from samba_eeg import SambaModel
|
| 21 |
|
| 22 |
-
folder = snapshot_download(
|
|
|
|
|
|
|
|
|
|
| 23 |
model = SambaModel.from_pretrained(folder).cuda().eval()
|
| 24 |
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3 |
tags:
|
| 4 |
- eeg
|
| 5 |
- brain-computer-interface
|
| 6 |
+
- self-supervised-learning
|
| 7 |
- mamba
|
| 8 |
+
- pytorch
|
| 9 |
---
|
| 10 |
|
| 11 |
# SAMBA-100s
|
| 12 |
|
| 13 |
+
[Project website](https://samba.dcode.ai/) · [Code](https://github.com/Jiazhen-Hong/SAMBA) · [Paper](https://arxiv.org/abs/2511.18571) · [SAMBA-2s](https://huggingface.co/Dcode-AI/SAMBA-2s)
|
| 14 |
+
|
| 15 |
+
SAMBA-100s was pretrained on 100-second windows from the Temple University Hospital Abnormal EEG Corpus (TUAB), using 12,800 samples at 128 Hz and 16 bipolar channels. Retraining followed the original method with a rebuilt TUAB pipeline and validation split. The encoder supports other window lengths and electrode layouts.
|
| 16 |
+
|
| 17 |
+
## Download
|
| 18 |
|
| 19 |
+
[Download config](https://huggingface.co/Dcode-AI/SAMBA-100s/resolve/main/config.json?download=true) · [Download weights](https://huggingface.co/Dcode-AI/SAMBA-100s/resolve/main/model.safetensors?download=true)
|
| 20 |
+
|
| 21 |
+
Keep both files in the same directory. To download them together from a terminal:
|
| 22 |
+
|
| 23 |
+
```bash
|
| 24 |
+
pip install -U huggingface_hub
|
| 25 |
+
hf download Dcode-AI/SAMBA-100s config.json model.safetensors --local-dir ./SAMBA-100s
|
| 26 |
+
```
|
| 27 |
|
| 28 |
+
## Usage
|
| 29 |
+
|
| 30 |
+
Install SAMBA in a CUDA environment:
|
| 31 |
+
|
| 32 |
+
```bash
|
| 33 |
+
git clone https://github.com/Jiazhen-Hong/SAMBA.git
|
| 34 |
+
cd SAMBA
|
| 35 |
+
pip install -e '.[mamba,hub]'
|
| 36 |
+
```
|
| 37 |
+
|
| 38 |
+
Load the downloaded directory. If you skipped the download step, the following example fetches both files automatically:
|
| 39 |
|
| 40 |
```python
|
| 41 |
+
import torch
|
| 42 |
from huggingface_hub import snapshot_download
|
| 43 |
from samba_eeg import SambaModel
|
| 44 |
|
| 45 |
+
folder = snapshot_download(
|
| 46 |
+
"Dcode-AI/SAMBA-100s",
|
| 47 |
+
allow_patterns=["config.json", "model.safetensors"],
|
| 48 |
+
)
|
| 49 |
model = SambaModel.from_pretrained(folder).cuda().eval()
|
| 50 |
```
|
| 51 |
+
|
| 52 |
+
For files you already downloaded, pass their local directory to `SambaModel.from_pretrained` in place of `folder`.
|
| 53 |
+
|
| 54 |
+
Prepare EEG at 128 Hz. Use `signals` shaped `[batch, channels, samples]` and electrode `positions` shaped `[channels, 3]` or `[batch, channels, 3]`. Match the signal channel order and use the same coordinate frame and units as the target positions in `config.json`. TUAB pretraining used a 0.5–45 Hz bandpass. The decoder reconstructs EEG on a fixed 16-channel bipolar montage.
|
| 55 |
+
|
| 56 |
+
```python
|
| 57 |
+
signals = signals.to(device="cuda", dtype=torch.float32)
|
| 58 |
+
positions = positions.to(device="cuda", dtype=torch.float32)
|
| 59 |
+
|
| 60 |
+
# Skip these two lines if the signals are already normalized this way.
|
| 61 |
+
scale = torch.quantile(signals.abs(), 0.95, dim=-1, keepdim=True)
|
| 62 |
+
signals = signals / scale.clamp_min(1e-8)
|
| 63 |
+
|
| 64 |
+
with torch.inference_mode():
|
| 65 |
+
features = model.encode(signals, positions)
|
| 66 |
+
pooled_features = features.mean(dim=1)
|
| 67 |
+
```
|
| 68 |
+
|
| 69 |
+
`features` has shape `[batch, floor(samples / 8), 128]`. Use `pooled_features` for linear probing.
|
| 70 |
+
|
| 71 |
+
## Learned EEG spatial weights
|
| 72 |
+
|
| 73 |
+
SAMBA uses electrode coordinates to learn how to combine EEG channels. These maps show how the spatial weights change during training.
|
| 74 |
+
|
| 75 |
+
| Eyes open vs. closed | Driver distraction | Motor imagery |
|
| 76 |
+
|:---:|:---:|:---:|
|
| 77 |
+
| <img src="https://raw.githubusercontent.com/Jiazhen-Hong/SAMBA/main/Figures/Topo_gif/EyesState_GIF.gif" width="250" alt="Eyes open vs. closed"> | <img src="https://raw.githubusercontent.com/Jiazhen-Hong/SAMBA/main/Figures/Topo_gif/DriverDistraction_GIF.gif" width="250" alt="Driver distraction"> | <img src="https://raw.githubusercontent.com/Jiazhen-Hong/SAMBA/main/Figures/Topo_gif/MI_GIF.gif" width="250" alt="Motor imagery"> |
|
| 78 |
+
|
| 79 |
+
## Citation
|
| 80 |
+
|
| 81 |
+
```bibtex
|
| 82 |
+
@article{hong2026samba,
|
| 83 |
+
title={SAMBA: Toward an EEG Foundation Model via Differential Mamba and Coordinate-Driven Spatial Embedding},
|
| 84 |
+
author={Hong, Jiazhen and Mackellar, Geoffrey and Ghane, Soheila},
|
| 85 |
+
journal={arXiv preprint arXiv:2511.18571},
|
| 86 |
+
year={2026}
|
| 87 |
+
}
|
| 88 |
+
```
|