Jay1208 commited on
Commit
da66cd2
·
verified ·
1 Parent(s): 371b4f3

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-100s
11
 
12
- SAMBA EEG encoder pretrained on 100-second windows at 128 Hz using TUAB. 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-2s](https://huggingface.co/Dcode-AI/SAMBA-2s)
 
 
 
 
 
 
 
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-100s", 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-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
+ ```