braindecode 1.2.0.dev184328194__py3-none-any.whl → 1.3.0.dev171478045__py3-none-any.whl

braindecode/models/eegconformer.py

@@ -12,33 +12,129 @@ 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 +143,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/eeginception_erp.py

@@ -15,12 +15,84 @@ from braindecode.modules import DepthwiseConv2d, Ensure4d, InceptionBlock
 class EEGInceptionERP(EEGModuleMixin, nn.Sequential):
     """EEG Inception for ERP-based from Santamaria-Vazquez et al (2020) [santamaria2020]_.
 
+    :bdg-success:`Convolution`
+
     .. figure:: https://braindecode.org/dev/_static/model/eeginceptionerp.jpg
         :align: center
         :alt: EEGInceptionERP Architecture
 
-    The code for the paper and this model is also available at [santamaria2020]_
-    and an adaptation for PyTorch [2]_.
+        Figure: Overview of EEG-Inception architecture. 2D convolution blocks and depthwise 2D convolution blocks include batch normalization, activation and dropout regularization. The kernel size is displayed for convolutional and average pooling layers.
+
+    .. rubric:: Architectural Overview
+
+    A two-stage, multi-scale CNN tailored to ERP detection from short (0-1000 ms) single-trial epochs. Signals are mapped through
+    * (i) :class:`_InceptionModule1` multi-scale temporal feature extraction plus per-branch spatial mixing;
+    * (ii) :class:`_InceptionModule2` deeper multi-scale refinement at a reduced temporal resolution; and
+    * (iii) :class:`_OutputModule` compact aggregation and linear readout.
+
+    .. rubric:: Macro Components
+
+    - :class:`_InceptionModule1` **(multi-scale temporal + spatial mixing)**
+
+        - *Operations.*
+        - `EEGInceptionERP.c1`: :class:`torch.nn.Conv2d` ``k=(64,1)``, stride ``(1,1)``, *same* pad on input reshaped to ``(B,1,128,8)`` → BN → activation → dropout.
+        - `EEGInceptionERP.d1`: :class:`torch.nn.Conv2d` (depthwise) ``k=(1,8)``, *valid* pad over channels → BN → activation → dropout.
+        - `EEGInceptionERP.c2`: :class:`torch.nn.Conv2d` ``k=(32,1)`` → BN → activation → dropout; then `EEGInceptionERP.d2` depthwise ``k=(1,8)`` → BN → activation → dropout.
+        - `EEGInceptionERP.c3`: :class:`torch.nn.Conv2d` ``k=(16,1)`` → BN → activation → dropout; then `EEGInceptionERP.d3` depthwise ``k=(1,8)`` → BN → activation → dropout.
+        - `EEGInceptionERP.n1`: :class:`torch.nn.Concat` over branch features.
+        - `EEGInceptionERP.a1`: :class:`torch.nn.AvgPool2d` ``pool=(4,1)``, stride ``(4,1)`` for temporal downsampling.
+
+    *Interpretability/robustness.* Depthwise `1 x n_chans` layers act as learnable montage-wide spatial filters per temporal scale; pooling stabilizes against jitter.
+
+    - :class:`_InceptionModule2` **(refinement at coarser timebase)**
+
+        - *Operations.*
+        - `EEGInceptionERP.c4`: :class:`torch.nn.Conv2d` ``k=(16,1)`` → BN → activation → dropout.
+        - `EEGInceptionERP.c5`: :class:`torch.nn.Conv2d` ``k=(8,1)`` → BN → activation → dropout.
+        - `EEGInceptionERP.c6`: :class:`torch.nn.Conv2d` ``k=(4,1)`` → BN → activation → dropout.
+        - `EEGInceptionERP.n2`: :class:`torch.nn.Concat` (merge C4-C6 outputs).
+        - `EEGInceptionERP.a2`: :class:`torch.nn.AvgPool2d` ``pool=(2,1)``, stride ``(2,1)``.
+        - `EEGInceptionERP.c7`: :class:`torch.nn.Conv2d` ``k=(8,1)`` → BN → activation → dropout; then `EEGInceptionERP.a3`: :class:`torch.nn.AvgPool2d` ``pool=(2,1)``.
+        - `EEGInceptionERP.c8`: :class:`torch.nn.Conv2d` ``k=(4,1)`` → BN → activation → dropout; then `EEGInceptionERP.a4`: :class:`torch.nn.AvgPool2d` ``pool=(2,1)``.
+
+    *Role.* Adds higher-level, shorter-window evidence while progressively compressing temporal dimension.
+
+    - :class:`_OutputModule` **(aggregation + readout)**
+
+        - *Operations.*
+        - :class:`torch.nn.Flatten`
+        - :class:`torch.nn.Linear` ``(features → 2)``
+
+    .. rubric:: Convolutional Details
+
+    - **Temporal (where time-domain patterns are learned).**
+    First module uses 1D temporal kernels along the 128-sample axis: ``64``, ``32``, ``16``
+    (≈500, 250, 125 ms at 128 Hz). After ``pool=(4,1)``, the second module applies ``16``,
+    ``8``, ``4`` (≈125, 62.5, 31.25 ms at the pooled rate). All strides are ``1`` in convs;
+    temporal resolution changes only via average pooling.
+
+    - **Spatial (how electrodes are processed).**
+    Depthwise convs with ``k=(1,8)`` span all channels and are applied **per temporal branch**,
+    yielding scale-specific channel projections (no cross-branch mixing until concatenation).
+    There is no full 2D mixing kernel; spatial mixing is factorized and lightweight.
+
+    - **Spectral (how frequency information is captured).**
+    No explicit transform; multiple temporal kernels form a *learned filter bank* over
+    ERP-relevant bands. Successive pooling acts as low-pass integration to emphasize sustained
+    post-stimulus components.
+
+    .. rubric:: Additional Mechanisms
+
+    - Every conv/depthwise block includes **BatchNorm**, nonlinearity (paper used grid-searched activation), and **dropout**.
+    - Two Inception stages followed by short convs and pooling keep parameters small (≈15k reported) while preserving multi-scale evidence.
+    - Expected input: epochs of shape ``(B,1,128,8)`` (time x channels as a 2D map) or reshaped from ``(B,8,128)`` with an added singleton feature dimension.
+
+    .. rubric:: Usage and Configuration
+
+    - **Key knobs.** Number of filters per branch; kernel lengths in both Inception modules; depthwise kernel over channels (typically ``n_chans``); pooling lengths/strides; dropout rate; choice of activation.
+    - **Training tips.** Use 0-1000 ms windows at 128 Hz with CAR; tune activation and dropout (they strongly affect performance); early-stop on validation loss when overfitting emerges.
+
+    .. rubric:: Implementation Details
 
     The model is strongly based on the original InceptionNet for an image. The main goal is
     to extract features in parallel with different scales. The authors extracted three scales
@@ -33,12 +105,9 @@ class EEGInceptionERP(EEGModuleMixin, nn.Sequential):
     The winners of BEETL Competition/NeurIps 2021 used parts of the
     model [beetl]_.
 
-    The model is fully described in [santamaria2020]_.
+    The code for the paper and this model is also available at [santamaria2020]_
+    and an adaptation for PyTorch [2]_.
 
-    Notes
-    -----
-    This implementation is not guaranteed to be correct, has not been checked
-    by original authors, only reimplemented from the paper based on [2]_.
 
     Parameters
     ----------

braindecode/models/eeginception_mi.py

@@ -13,6 +13,8 @@ from braindecode.modules import Ensure4d
 class EEGInceptionMI(EEGModuleMixin, nn.Module):
     """EEG Inception for Motor Imagery, as proposed in Zhang et al. (2021) [1]_
 
+    :bdg-success:`Convolution`
+
     .. figure:: https://content.cld.iop.org/journals/1741-2552/18/4/046014/revision3/jneabed81f1_hr.jpg
         :align: center
         :alt: EEGInceptionMI Architecture

braindecode/models/eegnet.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 from typing import Dict, Optional
 
 from einops.layers.torch import Rearrange
-from mne.utils import warn
+from mne.utils import deprecated, warn
 from torch import nn
 
 from braindecode.functional import glorot_weight_zero_bias
@@ -19,14 +19,62 @@ from braindecode.modules import (
 )
 
 
-class EEGNetv4(EEGModuleMixin, nn.Sequential):
-    """EEGNet v4 model from Lawhern et al. (2018) [EEGNet4]_.
+class EEGNet(EEGModuleMixin, nn.Sequential):
+    """EEGNet model from Lawhern et al. (2018) [Lawhern2018]_.
+
+    :bdg-success:`Convolution`
 
     .. figure:: https://content.cld.iop.org/journals/1741-2552/15/5/056013/revision2/jneaace8cf01_hr.jpg
-       :align: center
-       :alt: EEGNet4 Architecture
+        :align: center
+        :alt: EEGNet Architecture
+        :width: 600px
+
+    .. rubric:: Architectural Overview
+
+    EEGNet 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).
+
+    .. 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.
+    - The v4 means the version 4 at the arxiv paper [Lawhern2018]_.
 
-    See details in [EEGNet4]_.
 
     Parameters
     ----------
@@ -68,10 +116,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__(
@@ -299,174 +350,10 @@ class EEGNetv4(EEGModuleMixin, nn.Sequential):
         glorot_weight_zero_bias(self)
 
 
-class EEGNetv1(EEGModuleMixin, nn.Sequential):
-    """EEGNet model from Lawhern et al. 2016 from [EEGNet]_.
-
-    See details in [EEGNet]_.
-
-    Parameters
-    ----------
-    in_chans :
-        Alias for n_chans.
-    n_classes:
-        Alias for n_outputs.
-    input_window_samples :
-        Alias for n_times.
-    activation: nn.Module, default=nn.ELU
-        Activation function class to apply. Should be a PyTorch activation
-        module class like ``nn.ReLU`` or ``nn.ELU``. Default is ``nn.ELU``.
-
-    Notes
-    -----
-    This implementation is not guaranteed to be correct, has not been checked
-    by original authors, only reimplemented from the paper description.
-
-    References
-    ----------
-    .. [EEGNet] Lawhern, V. J., Solon, A. J., Waytowich, N. R., Gordon,
-       S. M., Hung, C. P., & Lance, B. J. (2016).
-       EEGNet: A Compact Convolutional Network for EEG-based
-       Brain-Computer Interfaces.
-       arXiv preprint arXiv:1611.08024.
-    """
-
-    def __init__(
-        self,
-        n_chans=None,
-        n_outputs=None,
-        n_times=None,
-        final_conv_length="auto",
-        pool_mode="max",
-        second_kernel_size=(2, 32),
-        third_kernel_size=(8, 4),
-        drop_prob=0.25,
-        activation: nn.Module = nn.ELU,
-        chs_info=None,
-        input_window_seconds=None,
-        sfreq=None,
-    ):
-        super().__init__(
-            n_outputs=n_outputs,
-            n_chans=n_chans,
-            chs_info=chs_info,
-            n_times=n_times,
-            input_window_seconds=input_window_seconds,
-            sfreq=sfreq,
-        )
-        del n_outputs, n_chans, chs_info, n_times, input_window_seconds, sfreq
-        warn(
-            "The class EEGNetv1 is deprecated and will be removed in the "
-            "release 1.0 of braindecode. Please use "
-            "braindecode.models.EEGNetv4 instead in the future.",
-            DeprecationWarning,
-        )
-        if final_conv_length == "auto":
-            assert self.n_times is not None
-        self.final_conv_length = final_conv_length
-        self.pool_mode = pool_mode
-        self.second_kernel_size = second_kernel_size
-        self.third_kernel_size = third_kernel_size
-        self.drop_prob = drop_prob
-        # For the load_state_dict
-        # When padronize all layers,
-        # add the old's parameters here
-        self.mapping = {
-            "conv_classifier.weight": "final_layer.conv_classifier.weight",
-            "conv_classifier.bias": "final_layer.conv_classifier.bias",
-        }
-
-        pool_class = dict(max=nn.MaxPool2d, mean=nn.AvgPool2d)[self.pool_mode]
-        self.add_module("ensuredims", Ensure4d())
-        n_filters_1 = 16
-        self.add_module(
-            "conv_1",
-            nn.Conv2d(self.n_chans, n_filters_1, (1, 1), stride=1, bias=True),
-        )
-        self.add_module(
-            "bnorm_1",
-            nn.BatchNorm2d(n_filters_1, momentum=0.01, affine=True, eps=1e-3),
-        )
-        self.add_module("elu_1", activation())
-        # transpose to examples x 1 x (virtual, not EEG) channels x time
-        self.add_module("permute_1", Rearrange("batch x y z -> batch z x y"))
-
-        self.add_module("drop_1", nn.Dropout(p=self.drop_prob))
-
-        n_filters_2 = 4
-        # keras pads unequal padding more in front, so padding
-        # too large should be ok.
-        # Not padding in time so that cropped training makes sense
-        # https://stackoverflow.com/questions/43994604/padding-with-even-kernel-size-in-a-convolutional-layer-in-keras-theano
-
-        self.add_module(
-            "conv_2",
-            nn.Conv2d(
-                1,
-                n_filters_2,
-                self.second_kernel_size,
-                stride=1,
-                padding=(self.second_kernel_size[0] // 2, 0),
-                bias=True,
-            ),
-        )
-        self.add_module(
-            "bnorm_2",
-            nn.BatchNorm2d(n_filters_2, momentum=0.01, affine=True, eps=1e-3),
-        )
-        self.add_module("elu_2", activation())
-        self.add_module("pool_2", pool_class(kernel_size=(2, 4), stride=(2, 4)))
-        self.add_module("drop_2", nn.Dropout(p=self.drop_prob))
-
-        n_filters_3 = 4
-        self.add_module(
-            "conv_3",
-            nn.Conv2d(
-                n_filters_2,
-                n_filters_3,
-                self.third_kernel_size,
-                stride=1,
-                padding=(self.third_kernel_size[0] // 2, 0),
-                bias=True,
-            ),
-        )
-        self.add_module(
-            "bnorm_3",
-            nn.BatchNorm2d(n_filters_3, momentum=0.01, affine=True, eps=1e-3),
-        )
-        self.add_module("elu_3", activation())
-        self.add_module("pool_3", pool_class(kernel_size=(2, 4), stride=(2, 4)))
-        self.add_module("drop_3", nn.Dropout(p=self.drop_prob))
-
-        output_shape = self.get_output_shape()
-        n_out_virtual_chans = output_shape[2]
-
-        if self.final_conv_length == "auto":
-            n_out_time = output_shape[3]
-            self.final_conv_length = n_out_time
-
-        # Incorporating classification module and subsequent ones in one final layer
-        module = nn.Sequential()
-
-        module.add_module(
-            "conv_classifier",
-            nn.Conv2d(
-                n_filters_3,
-                self.n_outputs,
-                (n_out_virtual_chans, self.final_conv_length),
-                bias=True,
-            ),
-        )
-
-        # Transpose back to the logic of braindecode,
-
-        # so time in third dimension (axis=2)
-        module.add_module(
-            "permute_2",
-            Rearrange("batch x y z -> batch x z y"),
-        )
-
-        module.add_module("squeeze", SqueezeFinalOutput())
-
-        self.add_module("final_layer", module)
+@deprecated(
+    "`EEGNetv4` was renamed to `EEGNet` in v1.12; this alias will be removed in v1.14."
+)
+class EEGNetv4(EEGNet):
+    """Deprecated alias for EEGNet."""
 
-        glorot_weight_zero_bias(self)
+    pass

braindecode/models/eegnex.py

@@ -16,9 +16,122 @@ from braindecode.modules import Conv2dWithConstraint, LinearWithConstraint
 class EEGNeX(EEGModuleMixin, nn.Module):
     """EEGNeX model from Chen et al. (2024) [eegnex]_.
 
+    :bdg-success:`Convolution`
+
     .. figure:: https://braindecode.org/dev/_static/model/eegnex.jpg
         :align: center
         :alt: EEGNeX Architecture
+        :width: 620px
+
+    .. rubric:: Architectural Overview
+
+    EEGNeX is a **purely convolutional** architecture that refines the EEGNet-style stem
+    and deepens the temporal stack with **dilated temporal convolutions**. The end-to-end
+    flow is:
+
+    - (i) **Block-1/2**: two temporal convolutions ``(1 x L)`` with BN refine a
+      learned FIR-like *temporal filter bank* (no pooling yet);
+    - (ii) **Block-3**: depthwise **spatial** convolution across electrodes
+      ``(n_chans x 1)`` with max-norm constraint, followed by ELU → AvgPool (time) → Dropout;
+    - (iii) **Block-4/5**: two additional **temporal** convolutions with increasing **dilation**
+      to expand the receptive field; the last block applies ELU → AvgPool → Dropout → Flatten;
+    - (iv) **Classifier**: a max-norm–constrained linear layer.
+
+    The published work positions EEGNeX as a compact, conv-only alternative that consistently
+    outperforms prior baselines across MOABB-style benchmarks, with the popular
+    “EEGNeX-8,32” shorthand denoting *8 temporal filters* and *kernel length 32*.
+
+
+    .. rubric:: Macro Components
+
+    - **Block-1 / Block-2 — Temporal filter (learned).**
+
+       - *Operations.*
+       - :class:`torch.nn.Conv2d` with kernels ``(1, L)``
+       - :class:`torch.nn.BatchNorm2d` (no nonlinearity until Block-3, mirroring a linear FIR analysis stage).
+         These layers set up frequency-selective detectors before spatial mixing.
+
+       - *Interpretability.* Kernels can be inspected as FIR filters; two stacked temporal
+         convs allow longer effective kernels without parameter blow-up.
+
+    - **Block-3 — Spatial projection + condensation.**
+
+        - *Operations.*
+        - :class:`braindecode.modules.Conv2dWithConstraint` with kernel``(n_chans, 1)``
+          and ``groups = filter_2`` (depthwise across filters)
+        - :class:`torch.nn.BatchNorm2d`
+        - :class:`torch.nn.ELU`
+        - :class:`torch.nn.AvgPool2d` (time)
+        - :class:`torch.nn.Dropout`.
+
+    **Role**: Learns per-filter spatial patterns over the **full montage** while temporal
+      pooling stabilizes and compresses features; max-norm encourages well-behaved spatial
+      weights similar to EEGNet practice.
+
+    - **Block-4 / Block-5 — Dilated temporal integration.**
+
+        - *Operations.*
+        - :class:`torch.nn.Conv2d` with kernels ``(1, k)`` and **dilations**
+          (e.g., 2 then 4);
+        - :class:`torch.nn.BatchNorm2d`
+        - :class:`torch.nn.ELU`
+        - :class:`torch.nn.AvgPool2d` (time)
+        - :class:`torch.nn.Dropout`
+        - :class:`torch.nn.Flatten`.
+
+    **Role**: Expands the temporal receptive field efficiently to capture rhythms and
+    long-range context after condensation.
+
+    - **Final Classifier — Max-norm linear.**
+
+        - *Operations.*
+        - :class:`braindecode.modules.LinearWithConstraint` maps the flattened
+          vector to the target classes; the max-norm constraint regularizes the readout.
+
+
+    .. rubric:: Convolutional Details
+
+    - **Temporal (where time-domain patterns are learned).**
+      Blocks 1-2 learn the primary filter bank (oscillations/transients), while Blocks 4-5
+      use **dilation** to integrate over longer horizons without extra pooling. The final
+      AvgPool in Block-5 sets the output token rate and helps noise suppression.
+
+    - **Spatial (how electrodes are processed).**
+      A *single* depthwise spatial conv (Block-3) spans the entire electrode set
+      (kernel ``(n_chans, 1)``), producing per-temporal-filter topographies; no cross-filter
+      mixing occurs at this stage, aiding interpretability.
+
+    - **Spectral (how frequency content is captured).**
+      Frequency selectivity emerges from the learned temporal kernels; dilation broadens effective
+      bandwidth coverage by composing multiple scales.
+
+    .. rubric:: Additional Mechanisms
+
+    - **EEGNeX-8,32 naming.** “8,32” indicates *8 temporal filters* and *kernel length 32*,
+      reflecting the paper's ablation path from EEGNet-8,2 toward thicker temporal kernels
+      and a deeper conv stack.
+    - **Max-norm constraints.** Spatial (Block-3) and final linear layers use max-norm
+      regularization—standard in EEG CNNs—to reduce overfitting and encourage stable spatial
+      patterns.
+
+    .. rubric:: Usage and Configuration
+
+    - **Kernel schedule.** Start with the canonical **EEGNeX-8,32** (``filter_1=8``,
+      ``kernel_block_1_2=32``) and keep **Block-3** depth multiplier modest (e.g., 2) to match
+      the paper's “pure conv” profile.
+    - **Pooling vs. dilation.** Use pooling in Blocks 3 and 5 to control compute and variance;
+      increase dilations (Blocks 4-5) to widen temporal context when windows are short.
+    - **Regularization.** Combine dropout (Blocks 3 & 5) with max-norm on spatial and
+      classifier layers; prefer ELU activations for stable training on small EEG datasets.
+
+
+    - The braindecode implementation follows the paper's conv-only design with five blocks
+      and reproduces the depthwise spatial step and dilated temporal stack. See the class
+      reference for exact kernel sizes, dilations, and pooling defaults. You can check the
+      original implementation at [EEGNexCode]_.
+
+    .. versionadded:: 1.1
+
 
     Parameters
     ----------
@@ -45,12 +158,6 @@ class EEGNeX(EEGModuleMixin, nn.Module):
     avg_pool_block5 : tuple[int, int], optional
         Pooling size for block 5. Default is (1, 8).
 
-    Notes
-    -----
-    This implementation is not guaranteed to be correct, has not been checked
-    by original authors, only reimplemented from the paper description and
-    source code in tensorflow [EEGNexCode]_.
-
     References
     ----------
     .. [eegnex] Chen, X., Teng, X., Chen, H., Pan, Y., & Geyer, P. (2024).