Feature Extraction
Safetensors
braindecode
eeg
foundation-model
bruAristimunha commited on
Commit
daf5ccc
·
verified ·
1 Parent(s): 10cd774

Re-host ZUNA1.1 encoder in braindecode parameter names (the ZUNA1 file did not load into braindecode.models.ZUNA)

Browse files

Source: Zyphra/ZUNA1.1 @ 10b9d6c8 (sha256 295fcddb...). Previous revision 10cd7745 held the raw ZUNA1 file, whose keys matched no parameter of the class. Strict load: only the head missing; parity vs original Zyphra encoder float64 9.1e-13.

Files changed (4) hide show
  1. README.md +123 -21
  2. config.json +28 -24
  3. convert_zuna11.py +176 -0
  4. model.safetensors +2 -2
README.md CHANGED
@@ -6,46 +6,148 @@ tags:
6
  - foundation-model
7
  - braindecode
8
  pipeline_tag: feature-extraction
 
 
 
9
  ---
10
 
11
  # ZUNA (braindecode re-host)
12
 
13
- Faithful re-host of the **ZUNA** EEG foundation-model encoder weights for use with
14
- [braindecode](https://github.com/braindecode/braindecode).
 
15
 
16
- - **Original model:** [`Zyphra/ZUNA`](https://huggingface.co/Zyphra/ZUNA)
17
- - **Original code:** https://github.com/Zyphra/zuna
18
- - **Paper:** Warner, C., Mago, J., Huml, J.R., Osman, M. and Millidge, B. (2026).
19
- *ZUNA: Flexible EEG Superresolution with Position-Aware Diffusion Autoencoders.*
20
- arXiv:2602.18478
 
 
 
 
 
 
 
21
  - **Original authors (Zyphra):** Chris Warner, Jonas Mago, Jon Huml, et al.
22
  - **License:** Apache-2.0 (inherited from the upstream release)
23
 
24
  ## Why this re-host
25
 
26
  The braindecode `ZUNA` port loads these weights through
27
- `ZUNA.from_pretrained(...)`. Re-hosting under the `braindecode` org gives a
28
- stable, permanent location that the library can point to by default, so the
29
- integration does not depend on the upstream repository staying unchanged. The
30
- weights file is **bit-identical** to the upstream checkpoint (same SHA-256);
31
- only the filename is normalised to the standard `model.safetensors`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
32
 
33
  ## What is (and is not) pretrained
34
 
35
- These are the pretrained **encoder** weights (a position-aware diffusion
36
- autoencoder trained for EEG superresolution). The braindecode wrapper adds a
37
- **classification head that is randomly initialised** and must be fine-tuned on
38
- your downstream task — loading these weights alone does not give a trained
39
- classifier.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
40
 
41
  ## Usage
42
 
43
  ```python
44
  from braindecode.models import ZUNA
45
 
46
- # Defaults to this repo (braindecode/ZUNA); n_chans / n_outputs are montage-
47
- # and task-dependent and must be supplied.
48
- model = ZUNA.from_pretrained(n_chans=19, n_outputs=4)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
49
 
50
- # Inputs are 5 s EEG windows sampled at 256 Hz (n_times = 1280).
 
 
 
 
 
51
  ```
 
6
  - foundation-model
7
  - braindecode
8
  pipeline_tag: feature-extraction
9
+ datasets:
10
+ - TUEG
11
+ base_model: Zyphra/ZUNA1.1
12
  ---
13
 
14
  # ZUNA (braindecode re-host)
15
 
16
+ Re-host of the **ZUNA1.1** EEG foundation-model encoder weights for use with
17
+ [braindecode](https://github.com/braindecode/braindecode), converted to the
18
+ parameter names of braindecode's `ZUNA` class.
19
 
20
+ - **Original model:** [`Zyphra/ZUNA1.1`](https://huggingface.co/Zyphra/ZUNA1.1)
21
+ at commit [`10b9d6c8`](https://huggingface.co/Zyphra/ZUNA1.1/tree/10b9d6c8285ab808685f079f586bdafe3ad2c9a3)
22
+ (`model-00001-of-00001.safetensors`, sha256 `295fcddb42ab4623dc1346fba12176798d97ab95389c666907e32cbce23f7f33`)
23
+ - **Original code:** https://github.com/Zyphra/zuna (checked against commit
24
+ [`c7b0195`](https://github.com/Zyphra/zuna/tree/c7b0195252e197bf0d1f9a0cebbb602ed0b69284))
25
+ - **Papers:**
26
+ - Warner, C., Mago, J., Huml, J.R. and Millidge, B. (2026).
27
+ *ZUNA1.1: A More Flexible EEG Foundation Model for Denoising and
28
+ Super-Resolution.* arXiv:2607.27308
29
+ - Warner, C., Mago, J., Huml, J.R., Osman, M. and Millidge, B. (2026).
30
+ *ZUNA: Flexible EEG Superresolution with Position-Aware Diffusion
31
+ Autoencoders.* arXiv:2602.18478
32
  - **Original authors (Zyphra):** Chris Warner, Jonas Mago, Jon Huml, et al.
33
  - **License:** Apache-2.0 (inherited from the upstream release)
34
 
35
  ## Why this re-host
36
 
37
  The braindecode `ZUNA` port loads these weights through
38
+ `ZUNA.from_pretrained("braindecode/ZUNA", ...)`. Re-hosting under the
39
+ `braindecode` org gives a stable, permanent location that the library can point
40
+ to, so the integration does not depend on the upstream repository staying
41
+ unchanged.
42
+
43
+ The upstream file holds the full ZUNA1.1 pretraining model (encoder and
44
+ rectified-flow decoder, 639 tensors). `model.safetensors` here holds its 213
45
+ encoder tensors, unchanged in value (float32, bit-identical), renamed to the
46
+ braindecode class's parameter names; the 426 decoder tensors are not included.
47
+ [`convert_zuna11.py`](convert_zuna11.py) in this repository produces the file
48
+ from the upstream checkpoint: it downloads the pinned revision, checks its
49
+ sha256, renames the keys, loads them into `ZUNA` with every non-head key
50
+ required (the only missing keys are the classification head) and saves the
51
+ encoder with `save_pretrained`.
52
+
53
+ `config.json` records ZUNA1.1's settings: the class defaults, `sfreq` 256, and
54
+ `pos_bins` 100. ZUNA1.1 buckets each electrode coordinate into 100 bins over
55
+ ±0.12 m (arXiv:2607.27308, Table II; ZUNA1 used 50). The input geometry
56
+ (channels, window length, number of outputs) is left to you.
57
+
58
+ ## Parity with the original code
59
+
60
+ On identical random inputs (19 standard 10-05 channels and the 32-channel
61
+ BioSemi montage, 256 Hz, 5 s and 10 s windows, several seeds), braindecode's
62
+ encoder was compared with the encoder of the original Zyphra code
63
+ (`EncoderTransformer`, eval mode, same weights):
64
+
65
+ - the patch tokens and the discretized electrode positions are identical;
66
+ - float64 against float64: per-token latents differ by at most 9.1e-13, the
67
+ per-channel features by at most 2.8e-14 (the original code's float32 casts
68
+ redirected to float64 for this check);
69
+ - float32 against float32: per-token latents (values up to ~10) differ by at
70
+ most 3.0e-4, the per-channel features used by the classification head by at
71
+ most 8.3e-6. Reordering the tokens in the original code alone (its own
72
+ time-major against channel-major layout) changes its float32 output by up to
73
+ 2.9e-4, so the float32 gap is rounding.
74
+
75
+ `ZUNA.from_pretrained` on this repository loads all 213 encoder tensors; its
76
+ features are bit-identical to the converted model's.
77
 
78
  ## What is (and is not) pretrained
79
 
80
+ These are the pretrained **encoder** weights of ZUNA1.1 (a masked diffusion
81
+ autoencoder trained to reconstruct, denoise and upsample EEG). The braindecode
82
+ wrapper adds a **classification head that is randomly initialised** and must be
83
+ fine-tuned on your downstream task — loading these weights alone does not give
84
+ a trained classifier. The diffusion decoder and the reconstruction sampler are
85
+ not part of the braindecode class; use the upstream `zuna` package for
86
+ reconstruction.
87
+
88
+ <!-- braindecode:training-data -->
89
+ ## Training data
90
+
91
+ | `datasets:` id | Dataset | Stage | Modality |
92
+ |---|---|---|---|
93
+ | `TUEG` | [Temple University Hospital EEG Corpus (TUH EEG)](https://isip.piconepress.com/projects/nedc/html/tuh_eeg/) | pretraining | EEG |
94
+
95
+ - ZUNA1.1 was pretrained on approximately 3.5M channel-hours of public EEG, the
96
+ ZUNA1 corpus (about 2M channel-hours from the TUH EEG Corpus and OpenNeuro,
97
+ 208 datasets) grown through quality-aware loading of partially noisy channels
98
+ and pre-epoched datasets.
99
+ - `TUEG` (the TUH EEG Corpus) contains the recordings of its sub-corpora TUAB,
100
+ TUEV, TUSZ, TUAR, TUSL and TUEP; an evaluation on one of those is not held out
101
+ from these weights unless the authors removed it.
102
+ - **Incomplete list.** The corpus also includes OpenNeuro datasets that the
103
+ papers, the upstream model cards and the upstream code do not list, so they
104
+ are not in `datasets:`. A dataset missing here is therefore not proof that
105
+ these weights never saw it.
106
 
107
  ## Usage
108
 
109
  ```python
110
  from braindecode.models import ZUNA
111
 
112
+ # Channel locations come from chs_info (metres, MNE head frame); a channel
113
+ # without a location takes the standard 10-05 position of its name.
114
+ model = ZUNA.from_pretrained(
115
+ "braindecode/ZUNA",
116
+ chs_info=raw.info["chs"], # your montage
117
+ n_times=1280, # e.g. 5 s at 256 Hz; ZUNA1.1 saw 0.5 s to 30 s
118
+ n_outputs=4, # your task; this head is new and untrained
119
+ )
120
+ ```
121
+
122
+ Inputs are EEG sampled at 256 Hz. braindecode does not resample, filter or
123
+ normalise; the upstream inference pipeline high-pass filters at 0.5 Hz,
124
+ average-references each segment and z-scores each channel before the encoder.
125
+
126
+ ## Revisions
127
+
128
+ - Earlier revision
129
+ [`10cd7745`](https://huggingface.co/braindecode/ZUNA/tree/10cd774556f36aa26a28ec40c1fd9707313c517f)
130
+ (2026-08-01) held the raw **ZUNA1** file of
131
+ [`Zyphra/ZUNA`](https://huggingface.co/Zyphra/ZUNA) (sha256 `31e68d14…`,
132
+ upstream key names `model.*`). Its keys did not match the braindecode class,
133
+ so `ZUNA.from_pretrained` on it loaded no tensor and left the encoder randomly
134
+ initialised (without an error). The current revision holds the ZUNA1.1
135
+ encoder in the class's own parameter names.
136
+
137
+ ## Citation
138
+
139
+ ```bibtex
140
+ @article{warner2026zuna11,
141
+ title = {{ZUNA1.1}: A More Flexible {EEG} Foundation Model for Denoising and Super-Resolution},
142
+ author = {Warner, Christopher and Mago, Jonas and Huml, JR and Millidge, Beren},
143
+ journal = {arXiv preprint arXiv:2607.27308},
144
+ year = {2026}
145
+ }
146
 
147
+ @article{warner2026zuna,
148
+ title = {{ZUNA}: Flexible {EEG} Superresolution with Position-Aware Diffusion Autoencoders},
149
+ author = {Warner, Christopher and Mago, Jonas and Huml, JR and Osman, Mohamed and Millidge, Beren},
150
+ journal = {arXiv preprint arXiv:2602.18478},
151
+ year = {2026}
152
+ }
153
  ```
config.json CHANGED
@@ -1,25 +1,29 @@
1
  {
2
- "model": {
3
- "dim": 1024,
4
- "n_layers": 16,
5
- "head_dim": 64,
6
- "seqlen_t": false,
7
- "huber_c": null,
8
- "input_dim": 32,
9
- "encoder_input_dim": 32,
10
- "encoder_output_dim": 32,
11
- "encoder_latent_downsample_factor": 1,
12
- "encoder_sliding_window": 65536,
13
- "sliding_window": 65536,
14
- "xattn_sliding_window": 65536,
15
- "max_seqlen": 50,
16
- "adaptive_loss_weighting": true,
17
- "num_fine_time_pts": 32,
18
- "rope_dim": 4,
19
- "rope_theta": 10000.0,
20
- "tok_idx_type": "{x,y,z,tc}",
21
- "dont_noise_chan_xyz": false,
22
- "stft_global_sigma": 0.1,
23
- "dropout_type": "zeros"
24
- }
25
- }
 
 
 
 
 
1
  {
2
+ "n_outputs": null,
3
+ "n_chans": null,
4
+ "chs_info": null,
5
+ "n_times": null,
6
+ "input_window_seconds": null,
7
+ "sfreq": 256,
8
+ "dim": 1024,
9
+ "n_layers": 16,
10
+ "n_heads": 8,
11
+ "head_dim": 64,
12
+ "fine_time_pts": 32,
13
+ "latent_dim": 32,
14
+ "max_seqlen": 256,
15
+ "rope_theta": 10000.0,
16
+ "pos_bins": 100,
17
+ "pos_half_range": 0.12,
18
+ "norm_eps": 1e-05,
19
+ "multiple_of": 256,
20
+ "ffn_dim_multiplier": null,
21
+ "sandwich_norm": true,
22
+ "qk_norm": true,
23
+ "activation": "torch.nn.modules.activation.SiLU",
24
+ "on_non_divisible": "pad",
25
+ "registers": true,
26
+ "channel_strategy": "native",
27
+ "channel_strategy_kwargs": null,
28
+ "braindecode_version": "2.1.0dev0"
29
+ }
convert_zuna11.py ADDED
@@ -0,0 +1,176 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Convert the Zyphra/ZUNA1.1 checkpoint to braindecode's ZUNA class.
2
+
3
+ The upstream file holds the full ZUNA1.1 pretraining model (encoder and
4
+ rectified-flow decoder, 639 tensors named ``model.*``). Braindecode's
5
+ :class:`braindecode.models.ZUNA` is the ZUNA1.1 encoder followed by a
6
+ classification head, so this script
7
+
8
+ 1. downloads ``model-00001-of-00001.safetensors`` from Zyphra/ZUNA1.1 at a
9
+ pinned revision and checks its sha256;
10
+ 2. keeps the 213 encoder tensors, renamed to the class's parameter names
11
+ (``model.encoder.X`` -> ``encoder.X``; the upstream RMSNorm wraps a
12
+ ``torch.nn.RMSNorm`` as ``.norm``, so ``*.norm.weight`` -> ``*.weight``),
13
+ and drops the 426 decoder tensors;
14
+ 3. loads them into ``ZUNA`` with ``strict=False`` and requires that the only
15
+ missing keys are the classification head and nothing is unexpected, and
16
+ that every loaded tensor equals its source bit for bit;
17
+ 4. saves the encoder (no head) with ``save_pretrained``, with a config.json
18
+ that leaves the input geometry (channels, window, outputs) to the user.
19
+
20
+ Usage::
21
+
22
+ python convert_zuna11.py --out ./export [--weights local.safetensors]
23
+
24
+ Then::
25
+
26
+ from braindecode.models import ZUNA
27
+ model = ZUNA.from_pretrained("braindecode/ZUNA", chs_info=raw.info["chs"],
28
+ n_times=1280, n_outputs=4)
29
+
30
+ Upstream code: github.com/Zyphra/zuna @ c7b0195252e197bf0d1f9a0cebbb602ed0b69284
31
+ (``EncoderTransformer`` in
32
+ ``src/zuna/inference/AY2l/lingua/apps/AY2latent_bci/transformer.py``).
33
+ """
34
+
35
+ from __future__ import annotations
36
+
37
+ import argparse
38
+ import hashlib
39
+ import json
40
+ from pathlib import Path
41
+
42
+ import torch
43
+
44
+ REPO_ID = "Zyphra/ZUNA1.1"
45
+ REVISION = "10b9d6c8285ab808685f079f586bdafe3ad2c9a3"
46
+ FILENAME = "model-00001-of-00001.safetensors"
47
+ SHA256 = "295fcddb42ab4623dc1346fba12176798d97ab95389c666907e32cbce23f7f33"
48
+
49
+ # ZUNA1.1 buckets each scalp coordinate into 100 bins over +/-0.12 m
50
+ # (upstream configs/config_bci.yaml and config_infer_fif.yaml:
51
+ # num_bins_discretize_xyz_chan_pos: 100, chan_pos_xyz_extremes_type: "twelves").
52
+ # ZUNA1 used 50 bins. All other ZUNA1.1 hyperparameters are the class defaults.
53
+ RELEASE_KWARGS = dict(pos_bins=100)
54
+ SFREQ = 256
55
+ HEAD_KEYS = {"final_layer.1.weight", "final_layer.1.bias"}
56
+ GEOMETRY_KEYS = ("n_outputs", "n_chans", "chs_info", "n_times", "input_window_seconds")
57
+
58
+
59
+ def sha256sum(path, chunk=1 << 24):
60
+ digest = hashlib.sha256()
61
+ with open(path, "rb") as f:
62
+ for block in iter(lambda: f.read(chunk), b""):
63
+ digest.update(block)
64
+ return digest.hexdigest()
65
+
66
+
67
+ def convert_key(key: str) -> str | None:
68
+ """Upstream key -> braindecode ZUNA key; None for tensors not in the class."""
69
+ if not key.startswith("model.encoder."):
70
+ return None # decoder
71
+ key = key[len("model.") :]
72
+ if key.endswith(".norm.weight"): # upstream RMSNorm(...).norm = nn.RMSNorm
73
+ key = key[: -len(".norm.weight")] + ".weight"
74
+ return key
75
+
76
+
77
+ def convert_state_dict(upstream: dict) -> dict:
78
+ converted, dropped = {}, []
79
+ for key, value in upstream.items():
80
+ new = convert_key(key)
81
+ if new is None:
82
+ dropped.append(key)
83
+ continue
84
+ if new in converted:
85
+ raise ValueError(f"two upstream tensors map to {new}")
86
+ converted[new] = value.to(torch.float32)
87
+ if not all(k.startswith("model.decoder.") for k in dropped):
88
+ raise ValueError(f"unexpected upstream tensors: {dropped}")
89
+ return converted
90
+
91
+
92
+ def standard_chs_info(names=None, montage="standard_1005"):
93
+ import mne
94
+
95
+ names = names or (
96
+ "Fp1 Fp2 F7 F3 Fz F4 F8 T7 C3 Cz C4 T8 P7 P3 Pz P4 P8 O1 O2".split()
97
+ )
98
+ info = mne.create_info(names, SFREQ, "eeg")
99
+ info.set_montage(montage)
100
+ return info["chs"]
101
+
102
+
103
+ def build_model(converted: dict, chs_info=None, n_times=1280, n_outputs=4):
104
+ """ZUNA with the converted encoder; strict on every non-head key."""
105
+ from braindecode.models import ZUNA
106
+
107
+ model = ZUNA(
108
+ n_outputs=n_outputs,
109
+ chs_info=chs_info if chs_info is not None else standard_chs_info(),
110
+ n_times=n_times,
111
+ sfreq=SFREQ,
112
+ **RELEASE_KWARGS,
113
+ )
114
+ result = model.load_state_dict(converted, strict=False)
115
+ if set(result.missing_keys) != HEAD_KEYS or result.unexpected_keys:
116
+ raise RuntimeError(
117
+ f"strict load failed: missing={result.missing_keys} "
118
+ f"unexpected={result.unexpected_keys}"
119
+ )
120
+ own = model.state_dict()
121
+ for key, value in converted.items():
122
+ if not torch.equal(own[key], value):
123
+ raise RuntimeError(f"{key} differs after loading")
124
+ return model.eval()
125
+
126
+
127
+ def load_upstream(weights=None, cache_dir=None):
128
+ from safetensors.torch import load_file
129
+
130
+ if weights is None:
131
+ from huggingface_hub import hf_hub_download
132
+
133
+ weights = hf_hub_download(
134
+ REPO_ID, FILENAME, revision=REVISION, cache_dir=cache_dir
135
+ )
136
+ digest = sha256sum(weights)
137
+ if digest != SHA256:
138
+ raise ValueError(f"{weights}: sha256 {digest}, expected {SHA256}")
139
+ return load_file(weights)
140
+
141
+
142
+ def export(converted: dict, out: Path):
143
+ """``save_pretrained`` of the encoder (no head) with a geometry-free config."""
144
+ model = build_model(converted)
145
+ model.final_layer = torch.nn.Identity() # the head is task-specific: not saved
146
+ out.mkdir(parents=True, exist_ok=True)
147
+ model.save_pretrained(out)
148
+ config_path = out / "config.json"
149
+ config = json.loads(config_path.read_text())
150
+ for key in GEOMETRY_KEYS:
151
+ config[key] = None
152
+ config["sfreq"] = SFREQ
153
+ config_path.write_text(json.dumps(config, indent=2) + "\n")
154
+ for extra in ("pytorch_model.bin", "README.md"): # safetensors + config only
155
+ (out / extra).unlink(missing_ok=True)
156
+ return {p.name: sha256sum(p) for p in sorted(out.iterdir()) if p.is_file()}
157
+
158
+
159
+ def main():
160
+ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
161
+ parser.add_argument("--out", type=Path, required=True)
162
+ parser.add_argument("--weights", help="local copy of the upstream file")
163
+ parser.add_argument("--cache-dir")
164
+ args = parser.parse_args()
165
+ upstream = load_upstream(args.weights, args.cache_dir)
166
+ converted = convert_state_dict(upstream)
167
+ print(
168
+ f"upstream tensors {len(upstream)}: encoder {len(converted)} kept, "
169
+ f"decoder {len(upstream) - len(converted)} dropped"
170
+ )
171
+ for name, digest in export(converted, args.out).items():
172
+ print(f"{digest} {name}")
173
+
174
+
175
+ if __name__ == "__main__":
176
+ main()
model.safetensors CHANGED
@@ -1,3 +1,3 @@
1
  version https://git-lfs.github.com/spec/v1
2
- oid sha256:31e68d142c142f1c99fe05125ee01a00e075835b8ec3fc0c983e29c929011a28
3
- size 1528134925
 
1
  version https://git-lfs.github.com/spec/v1
2
+ oid sha256:132da54c120d212148b27d0e9c73ec3816cf95027f75d5ae3e74905a3b514ed5
3
+ size 688430168