Complete training-data provenance and Braindecode software citation

c613ad1 verified 6 days ago

7.99 kB

---
license: mit
library_name: braindecode
tags:
- braindecode
- pytorch
- safetensors
- meg
- megxl
- brain-to-text
- foundation-model
datasets:
- CamCAN
- MOUS
- on004078
- TUEG
---
# MEG-XL (pretrained, `meg-xl-med-v2`)

Weights of MEG-XL (Jayalath and Parker Jones, ICML 2026) for
[`braindecode.models.MEGXL`](https://braindecode.org/stable/generated/braindecode.models.MEGXL.html):
the released `meg-xl-med-v2.ckpt` (step 113000, the checkpoint the authors' model card
links) with its frozen BioCodec tokenizer, converted to braindecode's parameter names.
The class is added by [braindecode#1554](https://github.com/braindecode/braindecode/pull/1554)
(braindecode 2.1).

```python
from braindecode.models import MEGXL
model = MEGXL.from_pretrained(
    "braindecode/megxl-pretrained", chs_info=raw.info["chs"], n_outputs=2
)
```

The files hold no classification head: it is not pretrained and its shape depends on the
number of channels, so `from_pretrained` builds a new one (PyTorch's default init) for
your `chs_info`. Fine-tune or linear-probe before use.

<!-- braindecode:training-data -->
## Training data

The data that shaped these weights. The ids are the `datasets:` field of this card,
which braindecode reads into `model.card_data.datasets` when you call
`from_pretrained` (MOABB class names for MOABB datasets, OpenNeuro / NEMAR
accessions, Hub ids otherwise). `nm`/`on` ids are datasets on [NEMAR](https://nemar.org)
(`on` = NEMAR's copy of the OpenNeuro dataset with the same number). Rows marked
`private:` are data the authors did not release; they are not in `datasets:`.

| `datasets:` id | Dataset | Stage | Modality |
|---|---|---|---|
| `CamCAN` | [Cambridge Centre for Ageing and Neuroscience (Cam-CAN) MEG data, Shafto et al. 2014 / Taylor et al. 2017](https://cam-can.mrc-cbu.cam.ac.uk/dataset/) | pretraining | MEG |
| `MOUS` | [Mother Of Unification Studies (MOUS), Schoffelen et al. 2019, Donders Repository DSC_3011020.09_236](https://data.ru.nl/collections/di/dccn/DSC_3011020.09_236) | pretraining | MEG |
| [`on004078`](https://nemar.org/dataset/on004078) | [SMN4Lang: a synchronized multimodal neuroimaging dataset to study brain language processing (Wang et al. 2022)](https://openneuro.org/datasets/ds004078) | pretraining | MEG |
| `TUEG` | [Temple University Hospital EEG Corpus (TUH-EEG), minus the TUAB and TUEV subsets (BioCodec tokenizer only)](https://isip.piconepress.com/projects/nedc/html/tuh_eeg/) | pretraining | EEG |

- BioCodec single-channel EEG tokenizer (Avramidis et al. 2025), trained on TUH-EEG excluding TUAB and TUEV; frozen inside MEG-XL (encoder + RVQ codebooks kept in this repo)
- MEG-XL masked-token pretraining, ~300 h, 2.5-min windows: Cam-CAN rest + sensorimotor (smt) only, MOUS auditory/listening only, SMN4Lang all MEG; Armeni and Gwilliams (MEG-MASC) appear in the pretraining config only as validation_only sets
- The BioCodec tokenizer used here was trained on TUEG **with TUAB and TUEV excluded**, as stated in its source above. TUEG is the same collection as TUAB/TUEV and its other sub-corpora, but those two exclusions must not be confused with training on their evaluation recordings. Other sub-corpus overlap requires checking the authors’ preprocessing/split.
- Sources: arXiv:2602.02494 (HTML) Sec. 3 'Pre-training data'; https://github.com/neural-processing-lab/MEG-XL/blob/97da04171d22e8fe4822cfeb3047a57ecf86b318/README.md 'Supported Datasets'; arXiv:2510.09095 (BioCodec, HTML) Sec. 3.1; MEG-XL@97da0417 configs/train_criss_cross_multi_50hz_med.yaml.


## Intended input

- MEG only. `chs_info` must carry sensor positions and coil orientations (`loc`);
  magnetometers and gradiometers (planar or axial) get their own type embeddings. The
  `chs_info` in `config.json` (the 306 MEG channels of MNE's `test_raw.fif`, Neuromag) is
  only a default.
- 50 Hz, preprocessed as in the authors' code: 0.1-40 Hz band-pass, baseline correction
  and robust scaling per 3 s chunk, clipped to `[-5, 5]`.
- Pretrained on 150 s windows (`n_times=7500`); the stored RoPE table covers those 625
  token positions, longer windows rebuild it.

## Source

- Paper: D. Jayalath, O. Parker Jones. *MEG-XL: Data-Efficient Brain-to-Text via
  Long-Context Pre-Training.* ICML 2026. [arXiv:2602.02494](https://arxiv.org/abs/2602.02494)
- Code: [neural-processing-lab/MEG-XL @ `97da04171d22e8fe4822cfeb3047a57ecf86b318`](https://github.com/neural-processing-lab/MEG-XL/tree/97da04171d22e8fe4822cfeb3047a57ecf86b318) (MIT)
- Weights: [pnpl/MEG-XL](https://huggingface.co/pnpl/MEG-XL) at revision
  `79838987b0fea6bd55bb9b4cccbe1e6f59e97362`, file `meg-xl-med-v2.ckpt`,
  sha256 `a8be0f06416bebcbea896db8bfdc8027ec25072a64b7e2ab925908dd6edfe88c`
  (model card `license: mit`).
- The tokenizer inside the checkpoint equals the separate BioCodec release
  `biocodec_ckpt.pt` (sha256 `b8b5c864bd92242a2aa70c414ab1abe23231772dc2f2e39a8f509fdded728af1`,
  [klean2050/BioCodec-release @ `575bf6ea7ae14a34754b217d9b940597a16951bd`](https://github.com/klean2050/BioCodec-release/tree/575bf6ea7ae14a34754b217d9b940597a16951bd), MIT),
  max-abs difference 0.0.

## Conversion

`convert.py` (in this repository) was run with braindecode at
`bruAristimunha/braindecode@bf95a14d2ea2847013aead661646dcacf51d9aa3` (branch `feat/meg-megxl`, PR #1554):

```
python convert.py meg-xl-med-v2.ckpt <out_dir> test_raw.fif
```

It renames the checkpoint keys to braindecode's and writes `config.json` with
`save_pretrained`, then `model.safetensors` / `pytorch_model.bin` without the head. Tensor
values are copied unchanged, except the RoPE table, which the authors' loader recomputes
from `freqs` (`torch.polar`, 625 positions) and which is stored as `(cos, sin)` pairs.

Dropped (pretraining only or duplicated): the BioCodec decoder, the duplicated
`biocodec_embedding_*` codebooks, `mask_token`, the code-prediction `output_head`, the
complex RoPE cache and the Lightning/optimizer state.

| file | sha256 |
|---|---|
| `model.safetensors` | `0817547bc254bae86fd74c993a4c5ed941e2e2f35c16d2990046cf32916a99cf` |
| `pytorch_model.bin` | `cb8b1cb6642bd8ee8070d859b3158b979342a9878f18aee2e7e4dde06c15974e` |
| `config.json` | `ba072e1d8ccd8db88ed44160deedd8af1499d9ac6884c392732911512d61482c` |
| `convert.py` | `825bfa078974adb4dc54fc3e5d93f2fbece1f2b0530b9c58cd188e448d8b675b` |

## Verification

`MEGXL.from_pretrained` on these files (only `final_layer.*` missing, no unexpected key;
loaded tensors equal `convert.py` applied to the original checkpoint) against the
authors' code with the same weights and inputs, CPU float32, eval mode, 20 s: codes
identical, features and the gradients of all 119 parameters of one backward pass equal
with max-abs difference 0.0, for 306 Neuromag channels (batch 1 and 2) and 157 KIT
axial gradiometers. For that comparison the original's attention dropout is set to 0: the
released `SelfAttention` keeps dropout 0.1 active in eval mode, braindecode turns it off.

## License

MIT, as the original release: [MEG-XL licence](https://github.com/neural-processing-lab/MEG-XL/blob/main/LICENSE)
(code; the weights' model card on `pnpl/MEG-XL` says `license: mit`) and
[BioCodec licence](https://github.com/klean2050/BioCodec-release/blob/main/LICENSE).
Converted and re-hosted with attribution to the authors; for corrections or removal, open
an issue at https://github.com/braindecode/braindecode/issues.

## Citation

```bibtex
@inproceedings{jayalath2026megxl,
  title     = {{MEG-XL}: Data-Efficient Brain-to-Text via Long-Context Pre-Training},
  author    = {Jayalath, Dulhan and Parker Jones, Oiwi},
  booktitle = {Forty-third International Conference on Machine Learning (ICML)},
  year      = {2026},
  note      = {arXiv:2602.02494},
}
@article{aristimunha2025braindecode,
  title   = {Braindecode: a deep learning library for raw electrophysiological data},
  author  = {Aristimunha, Bruno and others},
  journal = {Zenodo},
  year    = {2025},
  doi     = {10.5281/zenodo.17699192},
}
```

	---
	license: mit
	library_name: braindecode
	tags:
	- braindecode
	- pytorch
	- safetensors
	- meg
	- megxl
	- brain-to-text
	- foundation-model
	datasets:
	- CamCAN
	- MOUS
	- on004078
	- TUEG
	---

	# MEG-XL (pretrained, `meg-xl-med-v2`)

	Weights of MEG-XL (Jayalath and Parker Jones, ICML 2026) for
	[`braindecode.models.MEGXL`](https://braindecode.org/stable/generated/braindecode.models.MEGXL.html):
	the released `meg-xl-med-v2.ckpt` (step 113000, the checkpoint the authors' model card
	links) with its frozen BioCodec tokenizer, converted to braindecode's parameter names.
	The class is added by [braindecode#1554](https://github.com/braindecode/braindecode/pull/1554)
	(braindecode 2.1).

	```python
	from braindecode.models import MEGXL

	model = MEGXL.from_pretrained(
	"braindecode/megxl-pretrained", chs_info=raw.info["chs"], n_outputs=2
	)
	```

	The files hold no classification head: it is not pretrained and its shape depends on the
	number of channels, so `from_pretrained` builds a new one (PyTorch's default init) for
	your `chs_info`. Fine-tune or linear-probe before use.

	<!-- braindecode:training-data -->
	## Training data

	The data that shaped these weights. The ids are the `datasets:` field of this card,
	which braindecode reads into `model.card_data.datasets` when you call
	`from_pretrained` (MOABB class names for MOABB datasets, OpenNeuro / NEMAR
	accessions, Hub ids otherwise). `nm`/`on` ids are datasets on [NEMAR](https://nemar.org)
	(`on` = NEMAR's copy of the OpenNeuro dataset with the same number). Rows marked
	`private:` are data the authors did not release; they are not in `datasets:`.

	\| `datasets:` id \| Dataset \| Stage \| Modality \|
	\|---\|---\|---\|---\|
	\| `CamCAN` \| [Cambridge Centre for Ageing and Neuroscience (Cam-CAN) MEG data, Shafto et al. 2014 / Taylor et al. 2017](https://cam-can.mrc-cbu.cam.ac.uk/dataset/) \| pretraining \| MEG \|
	\| `MOUS` \| [Mother Of Unification Studies (MOUS), Schoffelen et al. 2019, Donders Repository DSC_3011020.09_236](https://data.ru.nl/collections/di/dccn/DSC_3011020.09_236) \| pretraining \| MEG \|
	\| [`on004078`](https://nemar.org/dataset/on004078) \| [SMN4Lang: a synchronized multimodal neuroimaging dataset to study brain language processing (Wang et al. 2022)](https://openneuro.org/datasets/ds004078) \| pretraining \| MEG \|
	\| `TUEG` \| [Temple University Hospital EEG Corpus (TUH-EEG), minus the TUAB and TUEV subsets (BioCodec tokenizer only)](https://isip.piconepress.com/projects/nedc/html/tuh_eeg/) \| pretraining \| EEG \|

	- BioCodec single-channel EEG tokenizer (Avramidis et al. 2025), trained on TUH-EEG excluding TUAB and TUEV; frozen inside MEG-XL (encoder + RVQ codebooks kept in this repo)
	- MEG-XL masked-token pretraining, ~300 h, 2.5-min windows: Cam-CAN rest + sensorimotor (smt) only, MOUS auditory/listening only, SMN4Lang all MEG; Armeni and Gwilliams (MEG-MASC) appear in the pretraining config only as validation_only sets
	- The BioCodec tokenizer used here was trained on TUEG with TUAB and TUEV excluded, as stated in its source above. TUEG is the same collection as TUAB/TUEV and its other sub-corpora, but those two exclusions must not be confused with training on their evaluation recordings. Other sub-corpus overlap requires checking the authors’ preprocessing/split.
	- Sources: arXiv:2602.02494 (HTML) Sec. 3 'Pre-training data'; https://github.com/neural-processing-lab/MEG-XL/blob/97da04171d22e8fe4822cfeb3047a57ecf86b318/README.md 'Supported Datasets'; arXiv:2510.09095 (BioCodec, HTML) Sec. 3.1; MEG-XL@97da0417 configs/train_criss_cross_multi_50hz_med.yaml.


	## Intended input

	- MEG only. `chs_info` must carry sensor positions and coil orientations (`loc`);
	magnetometers and gradiometers (planar or axial) get their own type embeddings. The
	`chs_info` in `config.json` (the 306 MEG channels of MNE's `test_raw.fif`, Neuromag) is
	only a default.
	- 50 Hz, preprocessed as in the authors' code: 0.1-40 Hz band-pass, baseline correction
	and robust scaling per 3 s chunk, clipped to `[-5, 5]`.
	- Pretrained on 150 s windows (`n_times=7500`); the stored RoPE table covers those 625
	token positions, longer windows rebuild it.

	## Source

	- Paper: D. Jayalath, O. Parker Jones. *MEG-XL: Data-Efficient Brain-to-Text via
	Long-Context Pre-Training.* ICML 2026. [arXiv:2602.02494](https://arxiv.org/abs/2602.02494)
	- Code: [neural-processing-lab/MEG-XL @ `97da04171d22e8fe4822cfeb3047a57ecf86b318`](https://github.com/neural-processing-lab/MEG-XL/tree/97da04171d22e8fe4822cfeb3047a57ecf86b318) (MIT)
	- Weights: [pnpl/MEG-XL](https://huggingface.co/pnpl/MEG-XL) at revision
	`79838987b0fea6bd55bb9b4cccbe1e6f59e97362`, file `meg-xl-med-v2.ckpt`,
	sha256 `a8be0f06416bebcbea896db8bfdc8027ec25072a64b7e2ab925908dd6edfe88c`
	(model card `license: mit`).
	- The tokenizer inside the checkpoint equals the separate BioCodec release
	`biocodec_ckpt.pt` (sha256 `b8b5c864bd92242a2aa70c414ab1abe23231772dc2f2e39a8f509fdded728af1`,
	[klean2050/BioCodec-release @ `575bf6ea7ae14a34754b217d9b940597a16951bd`](https://github.com/klean2050/BioCodec-release/tree/575bf6ea7ae14a34754b217d9b940597a16951bd), MIT),
	max-abs difference 0.0.

	## Conversion

	`convert.py` (in this repository) was run with braindecode at
	`bruAristimunha/braindecode@bf95a14d2ea2847013aead661646dcacf51d9aa3` (branch `feat/meg-megxl`, PR #1554):

	```
	python convert.py meg-xl-med-v2.ckpt <out_dir> test_raw.fif
	```

	It renames the checkpoint keys to braindecode's and writes `config.json` with
	`save_pretrained`, then `model.safetensors` / `pytorch_model.bin` without the head. Tensor
	values are copied unchanged, except the RoPE table, which the authors' loader recomputes
	from `freqs` (`torch.polar`, 625 positions) and which is stored as `(cos, sin)` pairs.

	Dropped (pretraining only or duplicated): the BioCodec decoder, the duplicated
	`biocodec_embedding_*` codebooks, `mask_token`, the code-prediction `output_head`, the
	complex RoPE cache and the Lightning/optimizer state.

	\| file \| sha256 \|
	\|---\|---\|
	\| `model.safetensors` \| `0817547bc254bae86fd74c993a4c5ed941e2e2f35c16d2990046cf32916a99cf` \|
	\| `pytorch_model.bin` \| `cb8b1cb6642bd8ee8070d859b3158b979342a9878f18aee2e7e4dde06c15974e` \|
	\| `config.json` \| `ba072e1d8ccd8db88ed44160deedd8af1499d9ac6884c392732911512d61482c` \|
	\| `convert.py` \| `825bfa078974adb4dc54fc3e5d93f2fbece1f2b0530b9c58cd188e448d8b675b` \|

	## Verification

	`MEGXL.from_pretrained` on these files (only `final_layer.*` missing, no unexpected key;
	loaded tensors equal `convert.py` applied to the original checkpoint) against the
	authors' code with the same weights and inputs, CPU float32, eval mode, 20 s: codes
	identical, features and the gradients of all 119 parameters of one backward pass equal
	with max-abs difference 0.0, for 306 Neuromag channels (batch 1 and 2) and 157 KIT
	axial gradiometers. For that comparison the original's attention dropout is set to 0: the
	released `SelfAttention` keeps dropout 0.1 active in eval mode, braindecode turns it off.

	## License

	MIT, as the original release: [MEG-XL licence](https://github.com/neural-processing-lab/MEG-XL/blob/main/LICENSE)
	(code; the weights' model card on `pnpl/MEG-XL` says `license: mit`) and
	[BioCodec licence](https://github.com/klean2050/BioCodec-release/blob/main/LICENSE).
	Converted and re-hosted with attribution to the authors; for corrections or removal, open
	an issue at https://github.com/braindecode/braindecode/issues.

	## Citation

	```bibtex
	@inproceedings{jayalath2026megxl,
	title = {{MEG-XL}: Data-Efficient Brain-to-Text via Long-Context Pre-Training},
	author = {Jayalath, Dulhan and Parker Jones, Oiwi},
	booktitle = {Forty-third International Conference on Machine Learning (ICML)},
	year = {2026},
	note = {arXiv:2602.02494},
	}

	@article{aristimunha2025braindecode,
	title = {Braindecode: a deep learning library for raw electrophysiological data},
	author = {Aristimunha, Bruno and others},
	journal = {Zenodo},
	year = {2025},
	doi = {10.5281/zenodo.17699192},
	}
	```