braindecode/popt-pretrained

PopulationTransformer (PopT) — braindecode weights

braindecode-native re-host of the official PopulationTransformer (PopT) popt_brainbert_stft checkpoint, remapped so it loads directly with braindecode.models.PopulationTransformer.

PopT is a self-supervised population model for intracranial recordings (iEEG/sEEG). It does not encode a raw time signal: each electrode is represented by a feature vector — typically the frozen embedding of a per-channel foundation model such as BrainBERT (stft features, 768-d) — and PopT aggregates across the electrode population. Each electrode feature is linearly projected and given a fixed sinusoidal spatial position encoding built from its integer anatomical coordinates; a CLS token is prepended, a stack of Transformer encoder layers mixes the population, and the CLS output is the pooled representation used downstream.

Provenance

Original code	https://github.com/czlwang/PopulationTransformer
Original weights	https://huggingface.co/PopulationTransformer/popt_brainbert_stft
Paper	Chau et al. (2024), Population Transformer: Learning Population-level Representations of Neural Activity, arXiv:2406.03044

These weights are a format conversion only of the authors' released checkpoint — no re-training. The input embedding, the spatial positional encoding and the 6-layer Transformer encoder are carried over bit-for-bit (verified: all 82 mapped tensors are identical to the source, and the ported encoder reproduces the upstream PtModelCustom output to < 1e-5). The upstream masked-modelling heads (cls_head, token_cls_head) are not carried; the braindecode classification head (final_layer, a single linear layer on the CLS token, as upstream's PtDownstreamModel.linear_out) is randomly initialised and must be trained/fine-tuned for your task.

Configuration

param	value
hidden_dim	512
ffn_dim	2048
n_layers	6
n_heads	8
n_times (feature dim)	768
max_len (coord table)	5000
activation	GELU
parameters (encoder + spec head)	~20.0M

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 (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
nm000253	Brain Treebank: large-scale intracranial recordings from naturalistic language stimuli (Wang et al., NeurIPS 2024 D&B; 10 subjects, 26 movie sessions, ~43.5 h sEEG)	pretraining, pretraining	iEEG

• frozen per-channel front end: BrainBERT stft_large_pretrained (itself pretrained on Brain Treebank)
• PopT self-supervised pretraining on BrainBERT features; 19 of 26 movies (same 10 subjects), 7 held out for downstream
• Sources: https://huggingface.co/PopulationTransformer/popt_brainbert_stft README; arXiv:2406.03044 (ICLR 2025) p.5, Section 4; https://github.com/czlwang/PopulationTransformer README.

Usage

import torch
from braindecode.models import PopulationTransformer

# n_chans = number of electrodes; n_outputs = your task's classes.
model = PopulationTransformer.from_pretrained(
    "braindecode/popt-pretrained", n_outputs=2
)

# input = per-electrode features (e.g. frozen BrainBERT stft embeddings),
# shape (batch, n_electrodes, 768). Electrode coordinates are read from
# chs_info when available, otherwise fall back to sequential indices.
x = torch.randn(4, 64, 768)
logits = model(x)                       # (4, n_outputs)
cls = model(x, return_features=True)    # {"features": ..., "cls_token": ...}

The classification head is task-specific: pass your own n_outputs (the head is re-initialised) and fine-tune. Electrode positions can be provided through chs_info (their loc, in metres by default, coord_units="m"), or as integer coords to forward. They are rounded to absolute integer indices, as upstream feeds them, and match the pretrained spatial encoding only when they are in the upstream Brain Treebank (left, inferior, posterior) space; MNE head-frame positions (e.g. a standard montage) are not that space.

Revisions

Revision 50b02d6 stored the untrained head as final_layer.norm.* / final_layer.fc.* (LayerNorm + Linear). This revision was re-exported with the fixed port (braindecode PR #1105): the head is stored as final_layer.weight / final_layer.bias (the same fc values; the LayerNorm was exactly identity), and config.json adds coord_units and shift_coords. The backbone tensors are unchanged. PopulationTransformer loads both revisions strictly.

Licensing

The upstream PopulationTransformer repository ships no explicit license file, so the license of these weights is marked unknown. They are re-hosted here for research use with attribution; if you use them, cite the original work and respect any terms the authors may later publish. The braindecode code is BSD-3-Clause.

Citation

@article{chau2024population,
  title={Population Transformer: Learning Population-level Representations of Neural Activity},
  author={Chau, Geeling and Wang, Christopher and Talukder, Sabera and Subramaniam, Vighnesh and Soedarmadji, Saraswati and Yue, Yisong and Katz, Boris and Barbu, Andrei},
  journal={arXiv preprint arXiv:2406.03044},
  year={2024}
}

Cite Braindecode

If you use this braindecode port in scientific work, cite the software on Zenodo, doi:10.5281/zenodo.17699192, and the original model and datasets cited above.

@software{braindecode,
  author = {Aristimunha, Bruno and
            Guetschel, Pierre and
            Wimpff, Martin and
            Gemein, Lukas and
            Rommel, Cedric and
            Banville, Hubert and
            Sliwowski, Maciej and
            Wilson, Daniel and
            Brandt, Simon and
            Gnassounou, Théo and
            Paillard, Joseph and
            {Junqueira Lopes}, Bruna and
            Sedlar, Sara and
            Moreau, Thomas and
            Chevallier, Sylvain and
            Gramfort, Alexandre and
            Schirrmeister, Robin Tibor},
  title = {Braindecode: toolbox for decoding raw electrophysiological brain data
           with deep learning models},
  url = {https://github.com/braindecode/braindecode},
  doi = {10.5281/zenodo.17699192},
  publisher = {Zenodo},
  license = {BSD-3-Clause},
}