Channel strategies#
A pretrained model expects the channels it was trained on. To run it on your recording,
give it your montage and a channel_strategy:
from braindecode.models import EEGPT
model = EEGPT.from_pretrained(
"braindecode/eegpt-pretrained",
chs_info=raw.info["chs"], # your montage
channel_strategy="spline", # how to map it
)
y = model(x) # x: (batch, len(chs_info), n_times)
y = model(x_other, chs_info=other_chs) # another montage, per call
Any strategy other than "native" puts a ChannelLayer
in front of the backbone. The layer maps the montage of chs_info, or the one given
to the call, onto the channels of the backbone. BENDR,
BIOT, CodeBrain,
EEGDINO, EEGPT,
Labram, MIRepNet and the
SignalJEPA models build their backbone on their
pre-training montage. The other models build it on the montage given at construction.
"native" is the default. It adds no layer, so the released checkpoints give the same
outputs (max-abs difference 0.0) with the same state_dict. The config saves
channel_strategy, channel_strategy_kwargs and the input montage, so
from_config rebuilds the same model.
Note
When to attach an external strategy vs. keep “native”. Across five pretrained
EEG foundation models and five downstream tasks, Kokate et al.[1]
report a regime-dependent trade-off: rigid-montage models (such as
BENDR) require an external adapter on mismatched caps,
whereas montage-flexible models (such as EEGPT and
CBraMod) benefit from external interpolation under
frozen-encoder linear probing but match or exceed it under "native" during full
fine-tuning.
The strategies#
Input channels that match a target channel are copied (see How the layer maps a montage). The strategy fills the targets that are left.
Strategy |
How a missing target channel is filled |
What it needs |
Trainable |
|---|---|---|---|
|
No layer. The model reads its input as it is. |
The model’s own channels |
no |
|
Not filled. A missing target that has a position raises a |
Nothing |
no |
|
Zeros. |
Nothing |
no |
|
Copy of the nearest input electrode. |
One input channel with a position |
no |
|
Mean of the inputs, weighted by inverse distance ( |
One input channel with a position |
no |
|
MNE spherical spline ( |
4+ positions four input channels with a position |
no |
|
MNE field mapping ( |
4+ positions four input channels with a position |
no |
|
Minimum-norm inverse on a template sphere head ( |
4+ positions four input channels with a position; scalp EEG only no intracranial channels |
optional |
|
Mean of the inputs within |
Two input channels with a position |
no |
|
Linear minimum mean square error estimate from a spatial covariance fitted on
dense recordings ( |
fit() first |
fitted the covariance is saved in the |
|
Learned cross-attention, as in POYO. The position of each missing target queries the positions and signal statistics of the inputs. |
One input channel with a position |
trainable attention weights |
Options go in channel_strategy_kwargs, for example {"reg": 1e-2} for
"spline".
Models that read only their own input#
The models below have released weights but no channel layer, at least for some of their
inputs. Those that take no channel_strategy raise a TypeError that says so. The
others take it and raise a ValueError that names the input the layer cannot map.
Model |
Its input |
With a |
|---|---|---|
MEG sensors |
TypeError not a parameter |
|
MEG source parcels |
TypeError not a parameter |
|
fNIRS channels placed by their optode positions |
TypeError not a parameter |
|
fNIRS HbO/HbR pairs with their optode positions |
TypeError not a parameter |
|
fNIRS channel patches |
TypeError not a parameter |
|
sEMG channel slots |
TypeError not a parameter |
|
sEMG, for hand-pose regression |
TypeError not a parameter |
|
iEEG, with a second per-channel input, |
TypeError not a parameter |
|
EEG. It is not a foundation model. |
TypeError not a parameter |
|
Polysomnography grouped by modality (EEG, EOG, ECG, EMG, respiration) |
ValueError for every strategy but |
|
EEG and MEG |
ValueError when |
|
EEG, or the modality set by |
ValueError when |
|
iEEG; spectrograms with |
ValueError with |
How the layer maps a montage#
Positions and copies#
The layer is one matrix per montage, built the first time it sees that montage. A target
channel found in the input is copied. An input channel matches by name, ignoring case,
or by a legacy name (T3 is T7, T5 is P7). An input channel whose name
MNE does not know matches a target within 15 mm. Positions come from loc, else from
standard_1005 by name. A target without a position, such as the SCALE channel of
BENDR, is zero unless the input has it. A map whose row gain exceeds 2 warns, because it
amplifies noise.
Derived channels#
A channel named A-B is V(A) - V(B). A target that is a combination of measured
channels is computed exactly under every strategy, "exact" included. For example,
F3-C3 comes from C3-F3 (weight -1), F3-P3 from F3-C3 and C3-P3, and
F3-C3 from F3 and C3 or from F3-REF and C3-REF. No reference is
guessed. F3-C3 is not exact from F3-R1 and C3-R2, and F3 is not exact
from bipolar channels alone. The same algebra is in
braindecode.functional.derivation_matrix() and
exact_derivation().
Other channel types#
The layer maps EEG, sEEG, ECoG and DBS electrodes. Any other channel raises a
ValueError, unless channel_strategy_kwargs={"drop_non_eeg": True} makes the
layer ignore it. "source" uses a scalp-EEG head and also refuses intracranial
channels.
One montage per sample#
The layer also maps a batch with one montage per sample. Pass chs_info as a list of
montages, x padded to the largest one, and ch_mask (by keyword) for the real
channels. This works for the strategies without trained state, so not for "latent"
or trainable=True. Batches of pad_channels_collate(),
with pos and ch_mask, work as they are. The layer reads the montage of each
sample from its positions.
Saved state and TorchScript#
For "wiener", model.channel_layer.fit(X, chs_info_dense) takes X of shape
(n_samples, n_dense_channels). Each montage is matched to the dense one by position,
within 15 mm. An unfitted map raises. The state of the layer (the latent attention, the
parcel mixing, the fitted covariance) lives under channel_layer.*, so a backbone
checkpoint without these keys still loads. The layer runs in eager mode, and TorchScript
works under "native" only.
Reconstruct a bad channel#
To reconstruct a bad EEG channel, keep the full montage as the target. Select the good EEG channels before extracting the signal and its input montage:
>>> import mne
>>> import numpy as np
>>> import torch
>>> from braindecode.modules import ChannelLayer
>>> info = mne.create_info(["C3", "Cz", "C4"], sfreq=100, ch_types="eeg")
>>> signals = np.array([[1.0, 2.0], [9.0, 9.0], [3.0, 4.0]]) * 1e-6
>>> raw = mne.io.RawArray(signals, info, verbose=False)
>>> raw.info["bads"] = ["Cz"]
>>> good = raw.copy().pick("eeg", exclude="bads")
>>> layer = ChannelLayer(raw.info["chs"], "nearest", good.info["chs"])
>>> x = torch.tensor(good.get_data(), dtype=torch.float32).unsqueeze(0)
>>> mapped, observed = layer(x)
>>> observed.tolist()
[True, False, True]
>>> torch.equal(mapped[:, observed], x)
True
observed marks the targets that are measured or exactly derived. Here Cz takes
the signal of its nearest good electrode, and C3 and C4 are copied as they are.
See it in a tutorial#
Runs BENDR on a synthetic 32-channel recording that lacks three of its channels, and plots what each strategy reconstructs.
Trains one model on recordings with different channels. Each window carries
its electrode positions, and pad_channels_collate pads every batch.
Loads foundation models from the Hugging Face Hub, adapts them to a new task and saves them with their configuration.
Examples that use the channel layer
Running a Pretrained Model on Any Channel Set with the Channel Layer
References