braindecode 1.2.0.dev169062562__py3-none-any.whl → 1.2.0.dev175337561__py3-none-any.whl

braindecode/models/atcnet.py

@@ -13,13 +13,154 @@ from braindecode.modules import CausalConv1d, Ensure4d, MaxNormLinear
 
 
 class ATCNet(EEGModuleMixin, nn.Module):
-    """ATCNet model from Altaheri et al. (2022) [1]_
+    """ATCNet from Altaheri et al. (2022) [1]_.
 
-    Pytorch implementation based on official tensorflow code [2]_.
+    :bdg-success:`Convolution` :bdg-info:`Small Attention`
 
     .. figure:: https://user-images.githubusercontent.com/25565236/185449791-e8539453-d4fa-41e1-865a-2cf7e91f60ef.png
-       :align: center
-       :alt: ATCNet Architecture
+        :align: center
+        :alt: ATCNet Architecture
+        :width: 650px
+
+    .. rubric:: Architectural Overview
+
+    ATCNet is a *convolution-first* architecture augmented with a *lightweight attention–TCN*
+    sequence module. The end-to-end flow is:
+
+    - (i) :class:`_ConvBlock` learns temporal filter-banks and spatial projections (EEGNet-style),
+      downsampling time to a compact feature map;
+
+    - (ii) Sliding Windows carve overlapping temporal windows from this map;
+
+    - (iii) for each window, :class:`_AttentionBlock` applies small multi-head self-attention
+      over time, followed by a :class:`_TCNResidualBlock` stack (causal, dilated);
+
+    - (iv) window-level features are aggregated (mean of window logits or concatenation)
+      and mapped via a max-norm–constrained linear layer.
+
+    Relative to ViT, ATCNet replaces linear patch projection with learned *temporal–spatial*
+    convolutions; it processes *parallel* window encoders (attention→TCN) instead of a deep
+    stack; and swaps the MLP head for a TCN suited to 1-D EEG sequences.
+
+    .. rubric:: Macro Components
+
+    - :class:`_ConvBlock` **(Shallow conv stem → feature map)**
+
+        - *Operations.*
+        - **Temporal conv** (:class:`torch.nn.Conv2d`) with kernel ``(L_t, 1)`` builds a
+            FIR-like filter bank (``F1`` maps).
+        - **Depthwise spatial conv** (:class:`torch.nn.Conv2d`, ``groups=F1``) with kernel
+          ``(1, n_chans)`` learns per-filter spatial projections (akin to EEGNet’s CSP-like step).
+        - **BN → ELU → AvgPool → Dropout** to stabilize and condense activations.
+        - **Refining temporal conv** (:class:`torch.nn.Conv2d`) with kernel ``(L_r, 1)`` +
+          **BN → ELU → AvgPool → Dropout**.
+
+    The output shape is ``(B, F2, T_c, 1)`` with ``F2 = F1·D`` and ``T_c = T/(P1·P2)``.
+    Temporal kernels behave as FIR filters; the depthwise-spatial conv yields frequency-specific
+    topographies. Pooling acts as a local integrator, reducing variance and imposing a
+    useful inductive bias on short EEG windows.
+
+    - **Sliding-Window Sequencer**
+
+      From the condensed time axis (length ``T_c``), ATCNet forms ``n`` overlapping windows
+      of width ``T_w = T_c - n + 1`` (one start per index). Each window produces a sequence
+      ``(B, F2, T_w)`` forwarded to its own attention–TCN branch. This creates *parallel*
+      encoders over shifted contexts and is key to robustness on nonstationary EEG.
+
+    - :class:`_AttentionBlock` **(small MHA on temporal positions)**
+
+        - *Operations.*
+        - Rearrange to ``(B, T_w, F2)``,
+        - Normalization :class:`torch.nn.LayerNorm`
+        - Custom MultiHeadAttention :class:`_MHA` (``num_heads=H``, per-head dim ``d_h``) + residual add,
+        - Dropout :class:`torch.nn.Dropout`
+        - Rearrange back to ``(B, F2, T_w)``.
+
+
+    **Note**: Attention is *local to a window* and purely temporal.
+
+    *Role.* Re-weights evidence across the window, letting the model emphasize informative
+    segments (onsets, bursts) before causal convolutions aggregate history.
+
+    - :class:`_TCNResidualBlock` **(causal dilated temporal CNN)**
+
+        - *Operations.*
+        - Two :class:`braindecode.modules.CausalConv1d` layers per block with dilation  ``1, 2, 4, …``
+        - Across blocks of `torch.nn.ELU` + `torch.nn.BatchNorm1d` + `torch.nn.Dropout`) +
+          a residual (identity or 1x1 mapping).
+        - The final feature used per window is the *last* causal step ``[..., -1]`` (forecast-style).
+
+    *Role.* Efficient long-range temporal integration with stable gradients; the dilated
+    receptive field complements attention’s soft selection.
+
+    - **Aggregation & Classifier**
+
+        - *Operations.*
+        - Either (a) map each window feature ``(B, F2)`` to logits via :class:`braindecode.modules.MaxNormLinear`
+        and **average** across windows (default, matching official code), or
+        - (b) **concatenate** all window features ``(B, n·F2)`` and apply a single :class:`MaxNormLinear`.
+        The max-norm constraint regularizes the readout.
+
+    .. rubric:: Convolutional Details
+
+    - **Temporal.** Temporal structure is learned in three places:
+        - (1) the stem’s wide ``(L_t, 1)`` conv (learned filter bank),
+        - (2) the refining ``(L_r, 1)`` conv after pooling (short-term dynamics), and
+        - (3) the TCN’s causal 1-D convolutions with exponentially increasing dilation
+          (long-range dependencies). The minimum sequence length required by the TCN stack is
+          ``(K_t - 1)·2^{L-1} + 1``; the implementation *auto-scales* kernels/pools/windows
+          when inputs are shorter to preserve feasibility.
+
+    - **Spatial.** A depthwise spatial conv spans the **full montage** (kernel ``(1, n_chans)``),
+        producing *per-temporal-filter* spatial projections (no cross-filter mixing at this step).
+        This mirrors EEGNet’s interpretability: each temporal filter has its own spatial pattern.
+
+
+    .. rubric:: Attention / Sequential Modules
+
+    - **Type.** Multi-head self-attention with ``H`` heads and per-head dim ``d_h`` implemented
+      in :class:`_MHA`, allowing ``embed_dim = H·d_h`` independent of input and output dims.
+    - **Shapes.** ``(B, F2, T_w) → (B, T_w, F2) → (B, F2, T_w)``. Attention operates along
+      the **temporal** axis within a window; channels/features stay in the embedding dim ``F2``.
+    - **Role.** Highlights salient temporal positions prior to causal convolution; small attention
+      keeps compute modest while improving context modeling over pooled features.
+
+    .. rubric:: Additional Mechanisms
+
+    - **Parallel encoders over shifted windows.** Improves montage/phase robustness by
+      ensembling nearby contexts rather than committing to a single segmentation.
+    - **Max-norm classifier.** Enforces weight norm constraints at the readout, a common
+      stabilization trick in EEG decoding.
+    - **ViT vs. ATCNet (design choices).** Convolutional *nonlinear* projection rather than
+      linear patchification; attention followed by **TCN** (not MLP); *parallel* window
+      encoders rather than stacked encoders.
+
+    .. rubric:: Usage and Configuration
+
+        - ``conv_block_n_filters (F1)``, ``conv_block_depth_mult (D)`` → capacity of the stem
+        (with ``F2 = F1·D`` feeding attention/TCN), dimensions aligned to ``F2``, like `EEGNetv4`.
+        - Pool sizes ``P1,P2`` trade temporal resolution for stability/compute; they set
+        ``T_c = T/(P1·P2)`` and thus window width ``T_w``.
+        - ``n_windows`` controls the ensemble over shifts (compute ∝ windows).
+        - ``att_num_heads``, ``att_head_dim`` set attention capacity; keep ``H·d_h ≈ F2``.
+        - ``tcn_depth``, ``tcn_kernel_size`` govern receptive field; larger values demand
+        longer inputs (see minimum length above). The implementation warns and *rescales*
+        kernels/pools/windows if inputs are too short.
+        - **Aggregation choice.** ``concat=False`` (default, average of per-window logits) matches
+        the official code; ``concat=True`` mirrors the paper’s concatenation variant.
+
+
+    Notes
+    -----
+    - Inputs substantially shorter than the implied minimum length trigger **automatic
+      downscaling** of kernels, pools, windows, and TCN kernel size to maintain validity.
+    - The attention–TCN sequence operates **per window**; the last causal step is used as the
+      window feature, aligning the temporal semantics across windows.
+
+    .. versionadded:: 1.1
+
+        - More detailed documentation of the model.
+
 
     Parameters
     ----------
@@ -85,15 +226,13 @@ class ATCNet(EEGModuleMixin, nn.Module):
         Maximum L2-norm constraint imposed on weights of the last
         fully-connected layer. Defaults to 0.25.
 
-
     References
     ----------
-    .. [1] H. Altaheri, G. Muhammad and M. Alsulaiman,
-        Physics-informed attention temporal convolutional network for EEG-based
-        motor imagery classification in IEEE Transactions on Industrial Informatics,
-        2022, doi: 10.1109/TII.2022.3197419.
-    .. [2] EEE-ATCNet implementation.
-       https://github.com/Altaheri/EEG-ATCNet/blob/main/models.py
+    .. [1] H. Altaheri, G. Muhammad, M. Alsulaiman (2022).
+        *Physics-informed attention temporal convolutional network for EEG-based motor imagery classification.*
+        IEEE Transactions on Industrial Informatics. doi:10.1109/TII.2022.3197419.
+    .. [2] Official EEG-ATCNet implementation (TensorFlow):
+        https://github.com/Altaheri/EEG-ATCNet/blob/main/models.py
     """
 
     def __init__(
@@ -556,7 +695,8 @@ class _TCNResidualBlock(nn.Module):
         # Reshape the input for the residual connection when necessary
         if in_channels != n_filters:
             self.reshaping_conv = nn.Conv1d(
-                n_filters,
+                in_channels=in_channels,
+                out_channels=n_filters,
                 kernel_size=1,
                 padding="same",
             )

braindecode/models/attentionbasenet.py

@@ -24,26 +24,148 @@ from braindecode.modules.attention import (
 
 
 class AttentionBaseNet(EEGModuleMixin, nn.Module):
-    """AttentionBaseNet from Wimpff M et al. (2023) [Martin2023]_.
+    """
+
+    :bdg-success:`Convolution` :bdg-info:`Small Attention`
 
     .. figure:: https://content.cld.iop.org/journals/1741-2552/21/3/036020/revision2/jnead48b9f2_hr.jpg
-       :align: center
-       :alt: Attention Base Net
-
-    Neural Network from the paper: EEG motor imagery decoding:
-    A framework for comparative analysis with channel attention
-    mechanisms
-
-    The paper and original code with more details about the methodological
-    choices are available at the [Martin2023]_ and [MartinCode]_.
-
-    The AttentionBaseNet architecture is composed of four modules:
-    - Input Block that performs a temporal convolution and a spatial
-    convolution.
-    - Channel Expansion that modifies the number of channels.
-    - An attention block that performs channel attention with several
-    options
-    - ClassificationHead
+        :align: center
+        :alt: AttentionBaseNet Architecture
+        :width: 640px
+
+
+    .. rubric:: Architectural Overview
+
+    AttentionBaseNet is a *convolution-first* network with a *channel-attention* stage.
+    The end-to-end flow is:
+
+    - (i) :class:`_FeatureExtractor` learns a temporal filter bank and per-filter spatial
+      projections (depthwise across electrodes), then condenses time by pooling;
+    - (ii) **Channel Expansion** uses a ``1x1`` convolution to set the feature width;
+    - (iii) :class:`_ChannelAttentionBlock` refines features via depthwise–pointwise temporal
+      convs and an optional channel-attention module (SE/CBAM/ECA/…);
+    - (iv) **Classifier** flattens the sequence and applies a linear readout.
+
+    This design mirrors shallow CNN pipelines (EEGNet-style stem) but inserts a pluggable
+    attention unit that *re-weights channels* (and optionally temporal positions) before
+    classification.
+
+
+    .. rubric:: Macro Components
+
+    - :class:`_FeatureExtractor` **(Shallow conv stem → condensed feature map)**
+
+        - *Operations.*
+        - **Temporal conv** (:class:`torch.nn.Conv2d`) with kernel ``(1, L_t)`` creates a learned
+        FIR-like filter bank with ``n_temporal_filters`` maps.
+        - **Depthwise spatial conv** (:class:`torch.nn.Conv2d`, ``groups=n_temporal_filters``)
+        with kernel ``(n_chans, 1)`` learns per-filter spatial projections over the full montage.
+        - **BatchNorm → ELU → AvgPool → Dropout** stabilize and downsample time.
+        - Output shape: ``(B, F2, 1, T₁)`` with ``F2 = n_temporal_filters x spatial_expansion``.
+
+    *Interpretability/robustness.* Temporal kernels behave as analyzable FIR filters; the
+    depthwise spatial step yields rhythm-specific topographies. Pooling acts as a local
+    integrator that reduces variance on short EEG windows.
+
+    - **Channel Expansion**
+
+        - *Operations.*
+        - A ``1x1`` conv → BN → activation maps ``F2 → ch_dim`` without changing
+        the temporal length ``T₁`` (shape: ``(B, ch_dim, 1, T₁)``).
+        This sets the embedding width for the attention block.
+
+    - :class:`_ChannelAttentionBlock` **(temporal refinement + channel attention)**
+
+        - *Operations.*
+        - **Depthwise temporal conv** ``(1, L_a)`` (groups=``ch_dim``) + **pointwise ``1x1``**,
+          BN and activation → preserves shape ``(B, ch_dim, 1, T₁)`` while refining timing.
+        - **Optional attention module** (see *Additional Mechanisms*) applies channel reweighting
+          (some variants also apply temporal gating).
+        - **AvgPool (1, P₂)** with stride ``(1, S₂)`` and **Dropout** → outputs
+          ``(B, ch_dim, 1, T₂)``.
+
+    *Role.* Emphasizes informative channels (and, in certain modes, salient time steps)
+    before the classifier; complements the convolutional priors with adaptive re-weighting.
+
+    - **Classifier (aggregation + readout)**
+
+    *Operations.* :class:`torch.nn.Flatten` → :class:`torch.nn.Linear` from
+    ``(B, ch_dim·T₂)`` to classes.
+
+
+    .. rubric:: Convolutional Details
+
+    - **Temporal (where time-domain patterns are learned).**
+        Wide kernels in the stem (``(1, L_t)``) act as a learned filter bank for oscillatory
+        bands/transients; the attention block’s depthwise temporal conv (``(1, L_a)``) sharpens
+        short-term dynamics after downsampling. Pool sizes/strides (``P₁,S₁`` then ``P₂,S₂``)
+        set the token rate and effective temporal resolution.
+
+    - **Spatial (how electrodes are processed).**
+        A depthwise spatial conv with kernel ``(n_chans, 1)`` spans the full montage to
+        learn *per-temporal-filter* spatial projections (no cross-filter mixing at this step),
+        mirroring the interpretable spatial stage in shallow CNNs.
+
+    - **Spectral (how frequency content is captured).**
+        No explicit Fourier/wavelet transform is used in the stem—spectral selectivity
+        emerges from learned temporal kernels. When ``attention_mode="fca"``, a frequency
+        channel attention (DCT-based) summarizes frequencies to drive channel weights.
+
+
+    .. rubric:: Attention / Sequential Modules
+
+    - **Type.** Channel attention chosen by ``attention_mode`` (SE, ECA, CBAM, CAT, GSoP,
+        EncNet, GE, GCT, SRM, CATLite). Most operate purely on channels; CBAM/CAT additionally
+        include temporal attention.
+    - **Shapes.** Input/Output around attention: ``(B, ch_dim, 1, T₁)``. Re-arrangements
+        (if any) are internal to the module; the block returns the same shape before pooling.
+    - **Role.** Re-weights channels (and optionally time) to highlight informative sources
+        and suppress distractors, improving SNR ahead of the linear head.
+
+
+    .. rubric:: Additional Mechanisms
+
+        - **Attention variants at a glance.**
+        - ``"se"``: Squeeze-and-Excitation (global pooling → bottleneck → gates).
+        - ``"gsop"``: Global second-order pooling (covariance-aware channel weights).
+        - ``"fca"``: Frequency Channel Attention (DCT summary; uses ``seq_len`` and ``freq_idx``).
+        - ``"encnet"``: EncNet with learned codewords (uses ``n_codewords``).
+        - ``"eca"``: Efficient Channel Attention (local 1-D conv over channel descriptor; uses ``kernel_size``).
+        - ``"ge"``: Gather–Excite (context pooling with optional MLP; can use ``extra_params``).
+        - ``"gct"``: Gated Channel Transformation (global context normalization + gating).
+        - ``"srm"``: Style-based recalibration (mean–std descriptors; optional MLP).
+        - ``"cbam"``: Channel then temporal attention (uses ``kernel_size``).
+        - ``"cat"`` / ``"catlite"``: Collaborative (channel ± temporal) attention; *lite* omits temporal.
+        - **Auto-compatibility on short inputs.**
+
+    If the input duration is too short for the configured kernels/pools, the implementation
+    **automatically rescales** temporal lengths/strides downward (with a warning) to keep
+    shapes valid and preserve the pipeline semantics.
+
+
+    .. rubric:: Usage and Configuration
+
+    - ``n_temporal_filters``, ``temporal_filter_length`` and ``spatial_expansion``:
+        control the capacity and the number of spatial projections in the stem.
+    - ``pool_length_inp``, ``pool_stride_inp`` then ``pool_length``, ``pool_stride``:
+        trade temporal resolution for compute; they determine the final sequence length ``T₂``.
+    - ``ch_dim``: width after the ``1x1`` expansion and the effective embedding size for attention.
+    - ``attention_mode`` + its specific hyperparameters (``reduction_rate``,
+        ``kernel_size``, ``seq_len``, ``freq_idx``, ``n_codewords``, ``use_mlp``):
+        select and tune the reweighting mechanism.
+    - ``drop_prob_inp`` and ``drop_prob_attn``: regularize stem and attention stages.
+    - **Training tips.**
+
+    Start with moderate pooling (e.g., ``P₁=75,S₁=15``) and ELU activations; enable attention
+    only after the stem learns stable filters. For small datasets, prefer simpler modes
+    (``"se"``, ``"eca"``) before heavier ones (``"gsop"``, ``"encnet"``).
+
+    Notes
+    -----
+    - Sequence length after each stage is computed internally; the final classifier expects
+    a flattened ``ch_dim x T₂`` vector.
+    - Attention operates on *channel* dimension by design; temporal gating exists only in
+    specific variants (CBAM/CAT).
 
     .. versionadded:: 0.9
 

braindecode/models/eegconformer.py

@@ -12,33 +12,126 @@ from braindecode.modules import FeedForwardBlock, MultiHeadAttention
 
 
 class EEGConformer(EEGModuleMixin, nn.Module):
-    """EEG Conformer from Song et al. (2022) from [song2022]_.
+    """EEG Conformer from Song et al. (2022) [song2022]_.
 
-     .. figure:: https://raw.githubusercontent.com/eeyhsong/EEG-Conformer/refs/heads/main/visualization/Fig1.png
+    :bdg-success:`Convolution` :bdg-info:`Small Attention`
+
+    .. figure:: https://raw.githubusercontent.com/eeyhsong/EEG-Conformer/refs/heads/main/visualization/Fig1.png
         :align: center
         :alt: EEGConformer Architecture
+        :width: 600px
+
+
+    .. rubric:: Architectural Overview
+
+    EEG-Conformer is a *convolution-first* model augmented with a *lightweight transformer
+    encoder*. The end-to-end flow is:
+
+    - (i) :class:`_PatchEmbedding` converts the continuous EEG into a compact sequence of tokens via a :class:`ShallowFBCSPNet` temporal–spatial conv stem and temporal pooling;
+    - (ii) :class:`_TransformerEncoder applies small multi-head self-attention to integrate longer-range temporal context across tokens;
+    - (iii) :class:`_ClassificationHead` aggregates the sequence and performs a linear readout.
+        This preserves the strong inductive biases of shallow CNN filter banks while adding
+        just enough attention to capture dependencies beyond the pooling horizon [song2022]_.
+
+    .. rubric:: Macro Components
+
+    - :class:`_PatchEmbedding` **(Shallow conv stem → tokens)**
+
+    - *Operations.*
+        - A temporal convolution (`:class:`torch.nn.Conv2d`) ``(1 x L_t)`` forms a data-driven "filter bank";
+        - A spatial convolution (`:class:`torch.nn.Conv2d`) (n_chans x 1)`` projects across electrodes, collapsing the channel axis into a virtual channel.
+        - **Normalization function** `:class:torch.nn.BatchNorm`
+        - **Activation function** `:class:torch.nn.ELU`
+        - **Average Pooling** `:class:torch.nn.AvgPool` along time (kernel ``(1, P)`` with stride ``(1, S)``)
+        -  final ``1x1`` :class:`torch.nn.Linear` projection.
+
+    The result is rearranged to a token sequence ``(B, S_tokens, D)``, where ``D = n_filters_time``.
+
+    *Interpretability/robustness.* Temporal kernels can be inspected as FIR filters;
+    the spatial conv yields channel projections analogous to :class:`ShallowFBCSPNet`’s learned
+    spatial filters. Temporal pooling stabilizes statistics and reduces sequence length.
+
+    - :class:`_TransformerEncoder` **(context over temporal tokens)**
+
+    - *Operations.*
+        - A stack of ``att_depth`` encoder blocks. :class:`_TransformerEncoderBlock`
+        - Each block applies LayerNorm :class:`torch.nn.LayerNorm`
+        - Multi-Head Self-Attention (``att_heads``) with dropout + residual :class:`MultiHeadAttention` (:class:`torch.nn.Dropout`)
+        - LayerNorm :class:`torch.nn.LayerNorm`
+        - 2-layer feed-forward (≈4x expansion, :class:`torch.nn.GELU`) with dropout + residual.
+
+    Shapes remain ``(B, S_tokens, D)`` throughout.
 
-    Convolutional Transformer for EEG decoding.
+    *Role.* Small attention focuses on interactions among *temporal patches* (not channels),
+    extending effective receptive fields at modest cost.
 
-    The paper and original code with more details about the methodological
-    choices are available at the [song2022]_ and [ConformerCode]_.
+    - :class:`ClassificationHead` **(aggregation + readout)**
 
-    This neural network architecture receives a traditional braindecode input.
-    The input shape should be three-dimensional matrix representing the EEG
-    signals.
+    - *Operations*.
+        - Flatten, :class:`torch.nn.Flatten` the sequence ``(B, S_tokens·D)`` -
+        - MLP (:class:`torch.nn.Linear` → activation (default: :class:`torch.nn.ELU`) → :class:`torch.nn.Dropout` → :class:`torch.nn.Linear`)
+        - final Linear to classes.
 
-         `(batch_size, n_channels, n_timesteps)`.
+    With ``return_features=True``, features before the last Linear can be exported for
+    linear probing or downstream tasks.
 
-    The EEG Conformer architecture is composed of three modules:
-        - PatchEmbedding
-        - TransformerEncoder
-        - ClassificationHead
+    .. rubric:: Convolutional Details
+
+    - **Temporal (where time-domain patterns are learned).**
+        The initial ``(1 x L_t)`` conv per channel acts as a *learned filter bank* for oscillatory
+        bands and transients. Subsequent **AvgPool** along time performs local integration,
+        converting activations into “patches” (tokens). Pool length/stride control the
+        token rate and set the lower bound on temporal context within each token.
+
+    - **Spatial (how electrodes are processed).**
+        A single conv with kernel ``(n_chans x 1)`` spans the full montage to learn spatial
+        projections for each temporal feature map, collapsing the channel axis into a
+        virtual channel before tokenization. This mirrors the shallow spatial step in
+        :class:`ShallowFBCSPNet` (temporal filters → spatial projection → temporal condensation).
+
+    - **Spectral (how frequency content is captured).**
+        No explicit Fourier/wavelet stage is used. Spectral selectivity emerges implicitly
+        from the learned temporal kernels; pooling further smooths high-frequency noise.
+        The effective spectral resolution is thus governed by ``L_t`` and the pooling
+        configuration.
+
+    .. rubric:: Attention / Sequential Modules
+
+    - **Type.** Standard multi-head self-attention (MHA) with ``att_heads`` heads over the token sequence.
+    - **Shapes.** Input/Output: ``(B, S_tokens, D)``; attention operates along the ``S_tokens`` axis.
+    - **Role.** Re-weights and integrates evidence across pooled windows, capturing dependencies
+      longer than any single token while leaving channel relationships to the convolutional stem.
+      The design is intentionally *small*—attention refines rather than replaces convolutional feature extraction.
+
+    .. rubric:: Additional Mechanisms
+
+    - **Parallel with ShallowFBCSPNet.** Both begin with a learned temporal filter bank,
+        spatial projection across electrodes, and early temporal condensation.
+        :class:`ShallowFBCSPNet` then computes band-power (via squaring/log-variance), whereas
+        EEG-Conformer applies BN/ELU and **continues with attention** over tokens to
+        refine temporal context before classification.
+
+    - **Tokenization knob.** ``pool_time_length`` and especially ``pool_time_stride`` set
+        the number of tokens ``S_tokens``. Smaller strides → more tokens and higher attention
+        capacity (but higher compute); larger strides → fewer tokens and stronger inductive bias.
+
+    - **Embedding dimension = filters.** ``n_filters_time`` serves double duty as both the
+        number of temporal filters in the stem and the transformer’s embedding size ``D``,
+        simplifying dimensional alignment.
+
+    .. rubric:: Usage and Configuration
+
+    - **Instantiation.** Choose ``n_filters_time`` (embedding size ``D``) and
+        ``filter_time_length`` to match the rhythms of interest. Tune
+        ``pool_time_length/stride`` to trade temporal resolution for sequence length.
+        Keep ``att_depth`` modest (e.g., 4–6) and set ``att_heads`` to divide ``D``.
+        ``final_fc_length="auto"`` infers the flattened size from PatchEmbedding.
 
     Notes
     -----
     The authors recommend using data augmentation before using Conformer,
     e.g. segmentation and recombination,
-    Please refer to the original paper and code for more details.
+    Please refer to the original paper and code for more details [ConformerCode]_.
 
     The model was initially tuned on 4 seconds of 250 Hz data.
     Please adjust the scale of the temporal convolutional layer,
@@ -47,7 +140,10 @@ class EEGConformer(EEGModuleMixin, nn.Module):
     .. versionadded:: 0.8
 
     We aggregate the parameters based on the parts of the models, or
-    when the parameters were used first, e.g. n_filters_time.
+    when the parameters were used first, e.g. ``n_filters_time``.
+
+    .. versionadded:: 1.1
+
 
     Parameters
     ----------

braindecode/models/eegnet.py

@@ -20,13 +20,60 @@ from braindecode.modules import (
 
 
 class EEGNetv4(EEGModuleMixin, nn.Sequential):
-    """EEGNet v4 model from Lawhern et al. (2018) [EEGNet4]_.
+    """EEGNet v4 model from Lawhern et al. (2018) [Lawhern2018]_.
+
+    :bdg-success:`Convolution` :bdg-secondary:`Depthwise–Separable`
 
     .. figure:: https://content.cld.iop.org/journals/1741-2552/15/5/056013/revision2/jneaace8cf01_hr.jpg
        :align: center
-       :alt: EEGNet4 Architecture
+       :alt: EEGNetv4 Architecture
+       :width: 600px
+
+    .. rubric:: Architectural Overview
+
+    EEGNetv4 is a compact convolutional network designed for EEG decoding with a
+    pipeline that mirrors classical EEG processing:
+    - (i) learn temporal frequency-selective filters,
+    - (ii) learn spatial filters for those frequencies, and
+    - (iii) condense features with depthwise–separable convolutions before a lightweight classifier.
+
+    The architecture is deliberately small (temporal convolutional and spatial patterns) [Lawhern2018]_.
+
+    .. rubric:: Macro Components
+
+    - **Temporal convolution**
+      Temporal convolution applied per channel; learns ``F1`` kernels that act as data-driven band-pass filters.
+    - **Depthwise Spatial Filtering.**
+      Depthwise convolution spanning the channel dimension with ``groups = F1``,
+      yielding ``D`` spatial filters for each temporal filter (no cross-filter mixing).
+    - **Norm–Nonlinearity–Pooling (+ dropout).**
+      Batch normalization → ELU → temporal pooling, with dropout.
+    - **Depthwise–Separable Convolution Block.**
+      (a) depthwise temporal conv to refine temporal structure;
+      (b) pointwise 1x1 conv to mix feature maps into ``F2`` combinations.
+    - **Classifier Head.**
+      Lightweight 1x1 conv or dense layer (often with max-norm constraint).
 
-    See details in [EEGNet4]_.
+    .. rubric:: Convolutional Details
+
+    **Temporal.** The initial temporal convs serve as a *learned filter bank*:
+    long 1-D kernels (implemented as 2-D with singleton spatial extent) emphasize oscillatory bands and transients.
+    Because this stage is linear prior to BN/ELU, kernels can be analyzed as FIR filters to reveal each feature’s spectrum [Lawhern2018]_.
+
+    **Spatial.** The depthwise spatial conv spans the full channel axis (kernel height = #electrodes; temporal size = 1).
+    With ``groups = F1``, each temporal filter learns its own set of ``D`` spatial projections—akin to CSP, learned end-to-end and
+    typically regularized with max-norm.
+
+    **Spectral.** No explicit Fourier/wavelet transform is used. Frequency structure
+    is captured implicitly by the temporal filter bank; later depthwise temporal kernels act as short-time integrators/refiners.
+
+    .. rubric:: Additional Comments
+
+    - **Filter-bank structure:** Parallel temporal kernels (``F1``) emulate classical filter banks; pairing them with frequency-specific spatial filters
+      yields features mappable to rhythms and topographies.
+    - **Depthwise & separable convs:** Parameter-efficient decomposition (depthwise + pointwise) retains power while limiting overfitting
+      [Chollet2017]_ and keeps temporal vs. mixing steps interpretable.
+    - **Regularization:** Batch norm, dropout, pooling, and optional max-norm on spatial kernels aid stability on small EEG datasets.
 
     Parameters
     ----------
@@ -68,10 +115,13 @@ class EEGNetv4(EEGModuleMixin, nn.Sequential):
 
     References
     ----------
-    .. [EEGNet4] Lawhern, V. J., Solon, A. J., Waytowich, N. R., Gordon, S. M.,
+    .. [Lawhern2018] Lawhern, V. J., Solon, A. J., Waytowich, N. R., Gordon, S. M.,
         Hung, C. P., & Lance, B. J. (2018). EEGNet: a compact convolutional
         neural network for EEG-based brain–computer interfaces. Journal of
         neural engineering, 15(5), 056013.
+    .. [Chollet2017] Chollet, F., *Xception: Deep Learning with Depthwise Separable
+        Convolutions*, CVPR, 2017.
+
     """
 
     def __init__(

braindecode/modules/attention.py

@@ -157,7 +157,8 @@ class FCA(nn.Module):
     ):
         super(FCA, self).__init__()
         mapper_y = [freq_idx]
-        assert in_channels % len(mapper_y) == 0
+        if in_channels % len(mapper_y) != 0:
+            raise ValueError("in_channels must be divisible by number of DCT filters")
 
         self.weight = nn.Parameter(
             self.get_dct_filter(seq_len, mapper_y, in_channels), requires_grad=False
@@ -295,7 +296,8 @@ class ECA(nn.Module):
     def __init__(self, in_channels: int, kernel_size: int):
         super(ECA, self).__init__()
         self.gap = nn.AdaptiveAvgPool2d(1)
-        assert kernel_size % 2 == 1, "kernel size must be odd for same padding"
+        if kernel_size % 2 != 1:
+            raise ValueError("kernel size must be odd for same padding")
         self.conv = nn.Conv1d(
             1, 1, kernel_size=kernel_size, padding=kernel_size // 2, bias=False
         )
@@ -530,7 +532,8 @@ class CBAM(nn.Module):
             nn.ReLU(),
             nn.Conv2d(in_channels // reduction_rate, in_channels, 1, bias=False),
         )
-        assert kernel_size % 2 == 1, "kernel size must be odd for same padding"
+        if kernel_size % 2 != 1:
+            raise ValueError("kernel size must be odd for same padding")
         self.conv = nn.Conv2d(2, 1, (1, kernel_size), padding=(0, kernel_size // 2))
 
     def forward(self, x):

braindecode/modules/convolution.py

@@ -136,7 +136,8 @@ class CombinedConv(nn.Module):
         # Calculate bias terms
         if self.bias_time:
             time_bias = self.conv_time.bias
-            assert time_bias is not None
+            if time_bias is None:
+                raise RuntimeError("conv_time.bias is None despite bias_time=True")
             calculated_bias = (
                 self.conv_spat.weight.squeeze()
                 .sum(-1)
@@ -145,7 +146,8 @@ class CombinedConv(nn.Module):
             )
         if self.bias_spat:
             spat_bias = self.conv_spat.bias
-            assert spat_bias is not None
+            if spat_bias is None:
+                raise RuntimeError("conv_spat.bias is None despite bias_spat=True")
             if calculated_bias is None:
                 calculated_bias = spat_bias
             else:
@@ -190,11 +192,12 @@ class CausalConv1d(nn.Conv1d):
         dilation=1,
         **kwargs,
     ):
-        assert "padding" not in kwargs, (
-            "The padding parameter is controlled internally by "
-            f"{type(self).__name__} class. You should not try to override this"
-            " parameter."
-        )
+        if "padding" in kwargs:
+            raise ValueError(
+                "The padding parameter is controlled internally by "
+                f"{type(self).__name__} class. You should not try to override this"
+                " parameter."
+            )
 
         super().__init__(
             in_channels=in_channels,

braindecode/modules/filter.py

@@ -452,12 +452,14 @@ class GeneralizedGaussianFilter(nn.Module):
         self.inverse_fourier = inverse_fourier
         self.affine_group_delay = affine_group_delay
         self.clamp_f_mean = clamp_f_mean
-        assert out_channels % in_channels == 0, (
-            "out_channels has to be multiple of in_channels"
-        )
-        assert len(f_mean) * in_channels == out_channels
-        assert len(bandwidth) * in_channels == out_channels
-        assert len(shape) * in_channels == out_channels
+        if out_channels % in_channels != 0:
+            raise ValueError("out_channels has to be multiple of in_channels")
+        if len(f_mean) * in_channels != out_channels:
+            raise ValueError("len(f_mean) * in_channels must equal out_channels")
+        if len(bandwidth) * in_channels != out_channels:
+            raise ValueError("len(bandwidth) * in_channels must equal out_channels")
+        if len(shape) * in_channels != out_channels:
+            raise ValueError("len(shape) * in_channels must equal out_channels")
 
         # Range from 0 to half sample rate, normalized
         self.n_range = nn.Parameter(

braindecode/training/scoring.py

@@ -11,7 +11,6 @@ from contextlib import contextmanager
 
 import numpy as np
 import torch
-from mne.utils.check import check_version
 from skorch.callbacks.scoring import EpochScoring
 from skorch.dataset import unpack_data
 from skorch.utils import to_numpy
@@ -370,13 +369,8 @@ class PostEpochTrainScoring(EpochScoring):
             y_preds = []
             y_test = []
             for batch in iterator:
-                batch_X, batch_y = unpack_data(batch)
-                # TODO: remove after skorch 0.10 release
-                if not check_version("skorch", min_version="0.10.1"):
-                    yp = net.evaluation_step(batch_X, training=False)
-                # X, y unpacking has been pushed downstream in skorch 0.10
-                else:
-                    yp = net.evaluation_step(batch, training=False)
+                _, batch_y = unpack_data(batch)
+                yp = net.evaluation_step(batch, training=False)
                 yp = yp.to(device="cpu")
                 y_test.append(self.target_extractor(batch_y))
                 y_preds.append(yp)

braindecode/version.py

@@ -1 +1 @@
-__version__ = "1.2.0.dev169062562"
+__version__ = "1.2.0.dev175337561"

braindecode/visualization/gradients.py

@@ -6,8 +6,13 @@ import numpy as np
 import torch
 from skorch.utils import to_numpy, to_tensor
 
+from braindecode.util import set_random_seeds
 
-def compute_amplitude_gradients(model, dataset, batch_size):
+
+def compute_amplitude_gradients(model, dataset, batch_size, seed=20240205):
+    """Compute amplitude gradients after seeding for reproducibility."""
+    cuda = next(model.parameters()).is_cuda
+    set_random_seeds(seed=seed, cuda=cuda)
     loader = torch.utils.data.DataLoader(
         dataset, batch_size=batch_size, drop_last=False, shuffle=False
     )

{braindecode-1.2.0.dev169062562.dist-info → braindecode-1.2.0.dev175337561.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.2.0.dev169062562
+Version: 1.2.0.dev175337561
 Summary: Deep learning software to decode EEG, ECG or MEG signals
 Author-email: Robin Tibor Schirrmeister <robintibor@gmail.com>
 Maintainer-email: Alexandre Gramfort <agramfort@meta.com>, Bruno Aristimunha Pinto <b.aristimunha@gmail.com>, Robin Tibor Schirrmeister <robintibor@gmail.com>

{braindecode-1.2.0.dev169062562.dist-info → braindecode-1.2.0.dev175337561.dist-info}/RECORD

@@ -3,7 +3,7 @@ braindecode/classifier.py,sha256=k9vSCtfQbld0YVleDi5rrrmk6k_k5JYEPPBYcNxYjZ8,980
 braindecode/eegneuralnet.py,sha256=dz8k_-2jV7WqkaX4bQG-dmr-vRT7ZtOwJqomXyC9PTw,15287
 braindecode/regressor.py,sha256=VLfrpiXklwI4onkwue3QmzlBWcvspu0tlrLo9RT1Oiw,9375
 braindecode/util.py,sha256=J-tBcDJNlMTIFW2mfOy6Ko0nsgdP4obRoEVDeg2rFH0,12686
-braindecode/version.py,sha256=peEUr8wSaU7Geu5W6LeP3IamWD3aza4xEKMC4rdjQl4,35
+braindecode/version.py,sha256=3Qa8hXZGNQHDb0ML-Uc2XpGnkUoLzPs7R6mgvIjDB60,35
 braindecode/augmentation/__init__.py,sha256=LG7ONqCufYAF9NZt8POIp10lYXb8iSueYkF-CWGK2Ls,1001
 braindecode/augmentation/base.py,sha256=gg7wYsVfa9jfqBddtE03B5ZrPHFFmPl2sa3LOrRnGfo,7325
 braindecode/augmentation/functional.py,sha256=ygkMNEFHaUdRQfk7meMML19FnM406Uf34h-ztKXdJwM,37978
@@ -27,20 +27,20 @@ braindecode/functional/__init__.py,sha256=JPUDFeKtfogEzfrwPaZRBmxexPjBw7AglYMlIm
 braindecode/functional/functions.py,sha256=CoEweM6YLhigx0tNmmz6yAc8iQ078sTFY2GeCjK5fFs,8622
 braindecode/functional/initialization.py,sha256=BUSC7y2TMsfShpMYBVwm3xg3ODFqWp-STH7yD4sn8zk,1388
 braindecode/models/__init__.py,sha256=xv1QPELZxocPgbc_mz-eYM5w08ZDNOsDV4pOnIFhUww,2551
-braindecode/models/atcnet.py,sha256=PhDJl6nBChButabjsmLz_heRcGFCCMKoeUt7k7neNzs,24483
-braindecode/models/attentionbasenet.py,sha256=1uwrtsdEGiBwokkO8A_2SR5zapOTQUBZd4q7hIpR0cw,23359
+braindecode/models/atcnet.py,sha256=Pn5KzQjv7YxSNDr_CY6O_Yg9K4m9XJ7btCIqyzkcPxc,32102
+braindecode/models/attentionbasenet.py,sha256=ZThyvhiSikSjv7mv3C5QuIF4df1QxEojzhJskmXcviU,30120
 braindecode/models/base.py,sha256=9icrWNZBGbh_VLyB9m8g_K1QyK7s3mh8X-hJ29gEbWs,10802
 braindecode/models/biot.py,sha256=T4PymX3penMJcrdfb5Nq6B3P-jyP2laAIu_R9o3uCXo,17512
 braindecode/models/contrawr.py,sha256=eeR_ik4gNZ3rJLM6Mw9gJ2gTMkZ8CU8C4rN_GQMQTAE,10044
 braindecode/models/ctnet.py,sha256=-J9QtUM8kcntz_xinfuBBvwDMECHiMPMcr2MS4GDPEY,17308
 braindecode/models/deep4.py,sha256=YJQUw-0EuFUi4qjm8caJGB8wRM_aeJa5X_d8jrGaQAI,14588
 braindecode/models/deepsleepnet.py,sha256=RrciuVJtZ-fhiUl-yLPfK2FP-G29V5Wor6pPlrMHQWQ,9218
-braindecode/models/eegconformer.py,sha256=_Y0SXprBD74zD8nKPcS9HQ6PoWzfpu-VCY7Tj6R7Xrs,11612
+braindecode/models/eegconformer.py,sha256=6scz0Axm97JV7-4u5yd6HGE7PldAMR39x5qSNzjSqxQ,17404
 braindecode/models/eeginception_erp.py,sha256=mwh3rGSHAJVvnbOlYTuWWkKxlmFAdAXBNCrq4IPgOS4,11408
 braindecode/models/eeginception_mi.py,sha256=aKJRFuYrpbcRbmmT2xVghKbK8pnl7fzu5hrV0ybRKso,12424
 braindecode/models/eegitnet.py,sha256=feXFmPCd-Ejxt7jgWPen1Ag0-oSclDVQai0Atwu9d_A,9827
 braindecode/models/eegminer.py,sha256=ouKZah9Q7_sxT7DJJMcPObwVxNQE87sEljJg6QwiQNw,9847
-braindecode/models/eegnet.py,sha256=1ZAG0KLDedkodDfqgnGGsoZj6iuU55kGmBlyQo1b47w,16284
+braindecode/models/eegnet.py,sha256=YeBCmU6Al9FDS4MZQTOLd0MCUfPbM6tmVlGWpb59Qzg,19256
 braindecode/models/eegnex.py,sha256=KNJIh8pFNhY087Bey2OPzDD4Uqw9pS6UkwMjnOngBzg,8497
 braindecode/models/eegresnet.py,sha256=cqWOSGqfJN_dNYUU9l8nYd_S3T1N-UX5-encKQzfBlg,12057
 braindecode/models/eegsimpleconv.py,sha256=sHpK-7ZGOCMuXsdkSVuarFTd1T0jMJUP_xwXP3gxQwc,7268
@@ -69,10 +69,10 @@ braindecode/models/usleep.py,sha256=dFh3KiZITu13gMxcbPGoK4hq2ySDWzVSCQXkj1006w0,
 braindecode/models/util.py,sha256=VrhwG1YBGwKohCej6TmhrNAIoleQHRu3YdiBPuHFY_E,5302
 braindecode/modules/__init__.py,sha256=PD2LpeSHWW_MgEef7-G8ief5gheGObzsIoacchxWuyA,1756
 braindecode/modules/activation.py,sha256=lTO2IjZWBDeXZ4ZVDgLmTDmxHdqyAny3Fsy07HY9tmQ,1466
-braindecode/modules/attention.py,sha256=fsjruzqMdtPbcS6jbU5ux8xtHl0BVrKt4agyf2yNe_E,23966
+braindecode/modules/attention.py,sha256=ISE11jXAvMqKpawZilg8i7lDX5mkuvpEplrh_CtGEkk,24102
 braindecode/modules/blocks.py,sha256=QE34HBg7kmEj0z-8dQZ1jJErLRPcniGIorMTeIArpv4,3621
-braindecode/modules/convolution.py,sha256=VAqJXj1Xfb7qlnjRAhH_fJT8qPcaAqy5FHu_sNEbkWw,8291
-braindecode/modules/filter.py,sha256=tj3zFQf40kt605yKE3bGpmnxtf91FTY7cWqxwAIIGPc,25050
+braindecode/modules/convolution.py,sha256=gZMMOa-2gy1nfduA_j2ezgdIdq5Bi2PtonNomWA4D8k,8481
+braindecode/modules/filter.py,sha256=iCz0HiGKrBS09m3aGiNnZEt8jpYOOrmn6SpPCUcuHfU,25291
 braindecode/modules/layers.py,sha256=w_tAGcm8BDFiyMdAYM4DNLx46zIUted8B6my8_jtpps,3724
 braindecode/modules/linear.py,sha256=pNhSUU0u-IGEUCjAfEDq_TJWnIJMWuOk7Y5L-7I8Meg,1702
 braindecode/modules/parametrization.py,sha256=sTvV21-sdpqpiY2PzwDebi7SeEvkFw8yDgA6OqJDo34,1310
@@ -89,13 +89,13 @@ braindecode/samplers/ssl.py,sha256=C-FKopnbncN_-spQPCrgljY5Qds4fgTLr2TG3s_-QqU,9
 braindecode/training/__init__.py,sha256=sxtfI6MgxX3aP03EFc0wJYA37uULoL9SQyUao1Oxyn0,523
 braindecode/training/callbacks.py,sha256=LqXqzJd6s3w0pvAKy9TEVTxWwVRyWNEu2uyWVsvb9RQ,839
 braindecode/training/losses.py,sha256=EyVVZE_028G6WwrAtzLbrRfDLgsoKwLLhqIkOYBXNL4,3551
-braindecode/training/scoring.py,sha256=tG7uCojIG3KIQZq3AymrdwlIJLlzbgsS0nBLUXQ-A8s,19062
+braindecode/training/scoring.py,sha256=WRkwqbitA3m_dzRnGp2ZIZPge5Nhx9gAEQhIHzeH4eU,18716
 braindecode/visualization/__init__.py,sha256=4EER_xHqZIDzEvmgUEm7K1bgNKpyZAIClR9ZCkMuY4M,240
 braindecode/visualization/confusion_matrices.py,sha256=qIWMLEHow5CJ7PhGggD8mnD55Le6xhma9HSzt4R33fc,9509
-braindecode/visualization/gradients.py,sha256=qAtXmuXkCDsWs8RMxvE6T9dz3uv_BhwTqhzkFFsEUDI,1948
-braindecode-1.2.0.dev169062562.dist-info/licenses/LICENSE.txt,sha256=7rg7k6hyj8m9whQ7dpKbqnCssoOEx_Mbtqb4uSOjljE,1525
-braindecode-1.2.0.dev169062562.dist-info/licenses/NOTICE.txt,sha256=sOxuTbalPxTM8H6VqtvGbXCt_BoOF7JevEYG_knqbm4,620
-braindecode-1.2.0.dev169062562.dist-info/METADATA,sha256=-76DvxesVFpEyLE_1OeR6BFkmbyz5Hij3w-epsTsM3w,6883
-braindecode-1.2.0.dev169062562.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-braindecode-1.2.0.dev169062562.dist-info/top_level.txt,sha256=pHsWQmSy0uhIez62-HA9j0iaXKvSbUL39ifFRkFnChA,12
-braindecode-1.2.0.dev169062562.dist-info/RECORD,,
+braindecode/visualization/gradients.py,sha256=KZo-GA0uwiwty2_94j2IjmCR2SKcfPb1Bi3sQq7vpTk,2170
+braindecode-1.2.0.dev175337561.dist-info/licenses/LICENSE.txt,sha256=7rg7k6hyj8m9whQ7dpKbqnCssoOEx_Mbtqb4uSOjljE,1525
+braindecode-1.2.0.dev175337561.dist-info/licenses/NOTICE.txt,sha256=sOxuTbalPxTM8H6VqtvGbXCt_BoOF7JevEYG_knqbm4,620
+braindecode-1.2.0.dev175337561.dist-info/METADATA,sha256=KaA8oZvJ4p7v61Sc1ZGTouHhzfOXZI9Yed7BhfHS0eo,6883
+braindecode-1.2.0.dev175337561.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+braindecode-1.2.0.dev175337561.dist-info/top_level.txt,sha256=pHsWQmSy0uhIez62-HA9j0iaXKvSbUL39ifFRkFnChA,12
+braindecode-1.2.0.dev175337561.dist-info/RECORD,,