braindecode.models.DANCE#

class braindecode.models.DANCE(n_outputs=None, n_chans=None, chs_info=None, n_times=None, input_window_seconds=None, sfreq=None, *, n_queries=100, use_channel_merger=True, n_virtual_channels=270, fourier_emb_dim=2048, merger_drop_prob=0.2, embed_dim=128, conv_hidden=512, conv_depth=10, conv_kernel_size=9, conv_dilation_growth=2.5, conv_initial_linear=256, conv_initial_depth=1, conv_drop_prob=0.2, num_latents=256, perceiver_depth=6, cross_attn_heads=2, latent_attn_heads=2, cross_dim_head=64, latent_dim_head=64, max_freq=10.0, num_freq_bands=6, decoder_dim=256, decoder_depth=4, decoder_heads=4, activation=<class 'torch.nn.modules.activation.GELU'>, drop_prob=0.1)[source]#

DANCE from Lévy et al (2026) [dance].

Convolution Attention/Transformer Channel

DANCE frames EEG decoding as event set prediction: a long, unaligned window is mapped to a set of events (t_start, t_end, class) with normalized [0, 1] spans – DETR [detr2020] for 1-D EEG.

Architecture Overview

ChannelMerger (spatial Fourier attention over electrode positions, from [defossez2023]) -> SimpleConv (dilated conv stack) -> Perceiver [perceiver2021] (cross-attention to a fixed 256-latent grid) -> a dense head (forward output) and a DETR cross-attention decoder (detect output).

Macro Components

DANCE.conv.merger (Spatial ChannelMerger)

Operations. ChannelMerger Fourier-embeds each electrode’s (x, y) position (FourierEmb) and computes n_virtual_channels softmax-attention combinations of the input channels, mapping (B, n_chans, T) -> (B, n_virtual_channels, T). Nested inside self.conv (matching upstream); disabled (None) when chs_info has no usable locations. Controlled by merger_drop_prob. Role. Makes the model montage-agnostic by projecting any electrode layout onto a fixed virtual-channel basis.

DANCE.conv (SimpleConv dilated front-end)

Operations. SimpleConv runs the nested merger, a 1x1 initial_linear projection, then conv_depth residual dilated Conv1d blocks (nn.ReLU, dilation accumulating as int(dilation * conv_dilation_growth) per block, same-padding preserves T), mapping -> (B, embed_dim, T). Role. Builds the temporal feature representation (Défossez lineage).

DANCE.perceiver (Perceiver bottleneck)

Operations. Perceiver Fourier-encodes the time axis, then cross-attends a fixed num_latents-token learnable grid to the conv features over perceiver_depth blocks, mapping (B, T, embed_dim) -> (B, num_latents, embed_dim). Role. Makes the model length-agnostic (any T -> num_latents tokens) and forms the detection time-grid (num_latents / duration tokens/s).

DANCE.decoder (DETR cross-attention decoder)

Operations. DanceDetrDecoder projects the latents to decoder_dim, then decoder_depth self-/cross-attention layers update n_queries learnable event queries; per-query heads emit class logits and sigmoid start/end spans. Used only by detect() (not forward()). Role. Produces the event-set prediction {class, start, end}.

DANCE.final_layer (dense per-token head)

Operations. nn.Linear(embed_dim, n_outputs) applied to every latent token, mapping (B, num_latents, embed_dim) -> (B, num_latents, n_outputs). Role. The forward() output (dense per-token class logits) and the dense term consumed by the consistency loss.

Temporal, Spatial, and Spectral Encoding

Temporal context comes from the dilated conv stack; spatial structure from the Fourier-position channel merge; the Perceiver fourier-encodes the time axis before cross-attention.

Additional Mechanisms

The DETR decoder uses learnable event queries and emits per-query class logits plus sigmoid start/end spans. The dense head provides per-token class logits used as forward’s output and for the consistency loss.

Added in version 1.6.1.

Parameters:
  • n_outputs (int) – Number of outputs of the model. This is the number of classes in the case of classification.

  • n_chans (int) – Number of EEG channels.

  • chs_info (list of dict) – Information about each individual EEG channel. This should be filled with info["chs"]. Refer to mne.Info for more details.

  • n_times (int) – Number of time samples of the input window.

  • input_window_seconds (float) – Length of the input window in seconds.

  • sfreq (float) – Sampling frequency of the EEG recordings.

  • n_queries (int) – Number of learnable event queries. The default is 100.

  • use_channel_merger (bool) – Enable the spatial Fourier ChannelMerger. Auto-disabled if chs_info has no usable electrode locations. The default is True.

  • n_virtual_channels (int) – Merger output channels. The default is 270.

  • fourier_emb_dim (int) – Fourier position embedding dim. The default is 2048.

  • merger_drop_prob (float) – Spatial dropout of the ChannelMerger ONLY (self.conv.merger); bans whole channels within a random radius during training. The default is 0.2.

  • embed_dim (int) – Conv/Perceiver feature dim. The default is 128.

  • conv_hidden (int) – SimpleConv hidden width. The default is 512.

  • conv_depth (int) – Number of dilated conv blocks. The default is 10.

  • conv_kernel_size (int) – Conv kernel size. The default is 9.

  • conv_dilation_growth (float) – Per-block dilation growth. The default is 2.5.

  • conv_initial_linear (int) – 1x1 projection width. The default is 256.

  • conv_initial_depth (int) – Number of 1x1 projections. The default is 1.

  • conv_drop_prob (float) – Conv-block dropout knob, exposed for API symmetry. NOTE: the verified DANCE config has NO conv dropout, so this maps to no upstream weights and does not affect parity; kept for forward-compatibility. The default is 0.2 (the paper value).

  • num_latents (int) – Perceiver latent count (detection token grid). The default is 256.

  • perceiver_depth (int) – Perceiver cross-attn blocks. The default is 6.

  • cross_attn_heads (int) – Perceiver cross-attn heads. The default is 2.

  • latent_attn_heads (int) – Perceiver self-attn heads. The default is 2.

  • cross_dim_head (int) – Perceiver cross-attn head dim. The default is 64.

  • latent_dim_head (int) – Perceiver self-attn head dim. The default is 64.

  • max_freq (float) – Perceiver fourier max frequency. The default is 10.0.

  • num_freq_bands (int) – Perceiver fourier bands. The default is 6.

  • decoder_dim (int) – DETR decoder dim. The default is 256.

  • decoder_depth (int) – DETR decoder layers. The default is 4.

  • decoder_heads (int) – DETR decoder heads. The default is 4.

  • activation (type[Module]) – Accepted for interface symmetry but currently INERT: it is forwarded to self.decoder yet the decoder feed-forward hardwires GEGLU (_FeedForward), and the SimpleConv front-end hardcodes nn.ReLU to match upstream. No submodule reads it today. The default is nn.GELU.

  • drop_prob (float) – Dropout applied to the raw input (self.input_drop) and inside the DETR decoder (self.decoder). Does NOT touch the merger (use merger_drop_prob) or the conv stack (no conv dropout upstream). The default is 0.1.

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

[dance]

Lévy, Banville, Rapin, King, Moreau, d’Ascoli (2026). DANCE: Detect and Classify Events in EEG. arXiv:2605.10688.

[defossez2023]

Défossez et al. (2023). Decoding speech from non-invasive brain recordings.

[perceiver2021]

Jaegle et al. (2021). Perceiver: General perception with iterative attention.

[detr2020]

Carion et al. (2020). End-to-end object detection with transformers.

Hugging Face Hub integration

When the optional huggingface_hub package 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 DANCE

# Train your model
model = DANCE(n_chans=22, n_outputs=4, n_times=1000)
# ... training code ...

# Push to the Hub; ``datasets`` and ``base_model`` go to the card
model.push_to_hub(
    repo_id="username/my-dance-model",
    commit_message="Initial model upload",
    model_card_kwargs={"datasets": ["BNCI2014_001"]},
)

Loading a model from the Hub:

from braindecode.models import DANCE

# Load pretrained model
model = DANCE.from_pretrained("username/my-dance-model")
# Data the weights were trained on, from the Hub model card
print(model.card_data.datasets if model.card_data else None)

# Load with a different number of outputs (head is rebuilt automatically)
model = DANCE.from_pretrained("username/my-dance-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 = DANCE.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

detect(x)[source]#
Return type:

dict

forward(x)[source]#

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Parameters:

x (Tensor) – The description is missing.

Return type:

Tensor

reset_head(n_outputs)[source]#

Replace the dense head and the DETR class head for a new n_outputs.

Parameters:

n_outputs (int) – New number of output classes.

Return type:

None

Examples

>>> from braindecode.models import BENDR
>>> model = BENDR(n_chans=22, n_times=1000, n_outputs=4)
>>> model.reset_head(10)
>>> model.n_outputs
10

Added in version 1.4.

Examples using braindecode.models.DANCE#

From window labels to events: asynchronous EEG decoding with DANCE

From window labels to events: asynchronous EEG decoding with DANCE