braindecode.models.LUNA#
- class braindecode.models.LUNA(n_outputs=None, n_chans=None, n_times=None, sfreq=None, chs_info=None, input_window_seconds=None, patch_size=40, num_queries=4, embed_dim=64, depth=8, num_heads=2, mlp_ratio=4.0, norm_layer=<class 'torch.nn.modules.normalization.LayerNorm'>, drop_path=0.0, drop_prob_chan=0.0, attn_drop=0.0, activation=<class 'torch.nn.modules.activation.GELU'>)[source]#
LUNA from Döner et al [LUNA].
Convolution Foundation Model Channel
LUNA is a topology-invariant EEG model that processes signals from varying numbers of channels using a channel-unification mechanism with learned queries.
The architecture consists of: 1. Patch Feature Extraction (temporal CNN + FFT-based features) 2. Channel-Unification Module (cross-attention with learned queries) 3. Patch-wise Temporal Encoder (RoPE-based transformer) 4. Decoder Heads (classification or reconstruction)
Important
Pre-trained Weights Available
This model has pre-trained weights available on the Hugging Face Hub at PulpBio/LUNA.
Available model variants:
LUNA_base.safetensors - Base model (embed_dim=64, num_queries=4, depth=8)
LUNA_large.safetensors - Large model (embed_dim=96, num_queries=6, depth=10)
LUNA_huge.safetensors - Huge model (embed_dim=128, num_queries=8, depth=24)
Example loading for fine-tuning:
from braindecode.models import LUNA # Load pre-trained base model from Hugging Face Hub model = LUNA.from_pretrained( "PulpBio/LUNA", filename="LUNA_base.safetensors", n_outputs=2, n_chans=22, n_times=1000, embed_dim=64, num_queries=4, depth=8, )
To push your own trained model to the Hub:
# After training your model model.push_to_hub( repo_id="username/my-luna-model", commit_message="Upload trained LUNA model" )
Requires installing
braindecode[hug]for Hub integration.- Parameters:
n_outputs (
Optional[int]) – Number of outputs of the model. This is the number of classes in the case of classification.n_times (
Optional[int]) – Number of time samples of the input window.sfreq (
Optional[float]) – Sampling frequency of the EEG recordings.chs_info (
Optional[Any]) – Information about each individual EEG channel. This should be filled withinfo["chs"]. Refer tomne.Infofor more details.input_window_seconds (
Optional[float]) – Length of the input window in seconds.patch_size (
int) – Number of time samples per patch. Default: 40.num_queries (
int) – Number of learned queries for channel unification. Paper uses: 4 (Base), 6 (Large), 8 (Huge). Default: 4.embed_dim (
int) – Embedding dimension for patch features. Paper uses: 64 (Base), 96 (Large), 128 (Huge). Default: 64.depth (
int) – Number of transformer encoder blocks. Paper uses: 8 (Base), 10 (Large), 24 (Huge). Default: 8.num_heads (
int) – Number of attention heads in channel unification. Default: 2.mlp_ratio (
float) – Ratio of MLP hidden dimension to embedding dimension. Default: 4.0.norm_layer (
Type[Module]) – Normalization layer class. Default: nn.LayerNorm.drop_path (
float) – Stochastic depth rate. Default: 0.0.drop_prob_chan (
float) – The description is missing.attn_drop (
float) – The description is missing.
- Raises:
ValueError – If some input signal-related parameters are not specified: and can not be inferred.
Notes
If some input signal-related parameters are not specified, there will be an attempt to infer them from the other parameters.
References
[LUNA]Döner, B., Ingolfsson, T. M., Benini, L., & Li, Y. (2025). LUNA: Efficient and Topology-Agnostic Foundation Model for EEG Signal Analysis. The Thirty-Ninth Annual Conference on Neural Information Processing Systems - NeurIPS. Retrieved from https://openreview.net/forum?id=uazfjnFL0G
Hugging Face Hub integration
When the optional
huggingface_hubpackage is installed, all models automatically gain the ability to be pushed to and loaded from the Hugging Face Hub. Install with:pip install braindecode[hub]
Pushing a model to the Hub:
from braindecode.models import LUNA # Train your model model = LUNA(n_chans=22, n_outputs=4, n_times=1000) # ... training code ... # Push to the Hub model.push_to_hub( repo_id="username/my-luna-model", commit_message="Initial model upload", )
Loading a model from the Hub:
from braindecode.models import LUNA # Load pretrained model model = LUNA.from_pretrained("username/my-luna-model") # Load with a different number of outputs (head is rebuilt automatically) model = LUNA.from_pretrained("username/my-luna-model", n_outputs=4)
Extracting features and replacing the head:
import torch x = torch.randn(1, model.n_chans, model.n_times) # Extract encoder features (consistent dict across all models) out = model(x, return_features=True) features = out["features"] # Replace the classification head model.reset_head(n_outputs=10)
Saving and restoring full configuration:
import json config = model.get_config() # all __init__ params with open("config.json", "w") as f: json.dump(config, f) model2 = LUNA.from_config(config) # reconstruct (no weights)
All model parameters (both EEG-specific and model-specific such as dropout rates, activation functions, number of filters) are automatically saved to the Hub and restored when loading.
See Loading and Adapting Pretrained Foundation Models for a complete tutorial.
Methods
- build_channel_location_template(num_channels)[source]#
Build channel location template for the model.
Attempts to extract channel locations from chs_info. Falls back to a default linear spacing along the x-axis if real locations are unavailable.
