Jay1208 commited on
Commit
0965a1f
路
verified 路
1 Parent(s): 4cef6ba

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +69 -5
README.md CHANGED
@@ -3,22 +3,86 @@ pipeline_tag: feature-extraction
3
  tags:
4
  - eeg
5
  - brain-computer-interface
6
- - pytorch
7
  - mamba
 
8
  ---
9
 
10
  # SAMBA-2s
11
 
12
- SAMBA EEG encoder pretrained on 2-second windows at 128 Hz using Emotiv, HBN, Muse, and DICE. The encoder supports other input lengths and electrode layouts.
 
 
 
 
13
 
14
- [Project](https://samba.dcode.ai/) 路 [Code](https://github.com/Jiazhen-Hong/SAMBA) 路 [Paper](https://arxiv.org/abs/2511.18571) 路 [Shared usage guide](https://huggingface.co/Dcode-AI/SAMBA) 路 [SAMBA-100s](https://huggingface.co/Dcode-AI/SAMBA-100s)
 
 
 
 
 
 
 
15
 
16
- Install SAMBA from the code repository with `pip install -e '.[mamba,hub]'`. Inference requires CUDA.
 
 
 
 
 
 
 
 
 
 
17
 
18
  ```python
 
19
  from huggingface_hub import snapshot_download
20
  from samba_eeg import SambaModel
21
 
22
- folder = snapshot_download("Dcode-AI/SAMBA-2s", allow_patterns=["config.json", "model.safetensors"])
 
 
 
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-2s
12
 
13
+ [Project website](https://samba.dcode.ai/) 路 [Code](https://github.com/Jiazhen-Hong/SAMBA) 路 [Paper](https://arxiv.org/abs/2511.18571) 路 [SAMBA-100s](https://huggingface.co/Dcode-AI/SAMBA-100s)
14
+
15
+ SAMBA-2s was pretrained on 2-second EEG windows from Emotiv (Alpha, Attention, Crowdsource, DriverDistraction, and STEW), HBN resting state, Muse sleep onset, and DICE eyes closed. Pretraining used 256 samples per window at 128 Hz and 4, 14, 19, and 129 EEG channels. The encoder supports other window lengths and electrode layouts.
16
+
17
+ ## Download
18
 
19
+ [Download config](https://huggingface.co/Dcode-AI/SAMBA-2s/resolve/main/config.json?download=true) 路 [Download weights](https://huggingface.co/Dcode-AI/SAMBA-2s/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-2s config.json model.safetensors --local-dir ./SAMBA-2s
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-2s",
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`. The decoder reconstructs EEG at the input electrode coordinates.
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
+ ```