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

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).

braindecode/models/eegsimpleconv.py

@@ -21,6 +21,8 @@ from braindecode.models.base import EEGModuleMixin
 class EEGSimpleConv(EEGModuleMixin, torch.nn.Module):
     """EEGSimpleConv from Ouahidi, YE et al. (2023) [Yassine2023]_.
 
+    :bdg-success:`Convolution`
+
     .. figure:: https://raw.githubusercontent.com/elouayas/EEGSimpleConv/refs/heads/main/architecture.png
         :align: center
         :alt: EEGSimpleConv Architecture

braindecode/models/eegtcnet.py

@@ -15,6 +15,8 @@ from braindecode.modules import Chomp1d, MaxNormLinear
 class EEGTCNet(EEGModuleMixin, nn.Module):
     """EEGTCNet model from Ingolfsson et al. (2020) [ingolfsson2020]_.
 
+    :bdg-success:`Convolution` :bdg-secondary:`Recurrent`
+
     .. figure:: https://braindecode.org/dev/_static/model/eegtcnet.jpg
         :align: center
         :alt: EEGTCNet Architecture
@@ -157,7 +159,7 @@ class EEGTCNet(EEGModuleMixin, nn.Module):
 class _EEGNetTC(nn.Module):
     """EEGNet Temporal Convolutional Network (TCN) block.
 
-    The main difference from our EEGNetV4 (braindecode) implementation is the
+    The main difference from our :class:`EEGNet` (braindecode) implementation is the
     kernel and dimensional order. Because of this, we decided to keep this
     implementation in a future issue; we will re-evaluate if it is necessary
     to maintain this separate implementation.

braindecode/models/fbcnet.py

@@ -31,6 +31,8 @@ _valid_layers = {
 class FBCNet(EEGModuleMixin, nn.Module):
     """FBCNet from Mane, R et al (2021) [fbcnet2021]_.
 
+    :bdg-success:`Convolution` :bdg-primary:`Filterbank`
+
     .. figure:: https://raw.githubusercontent.com/ravikiran-mane/FBCNet/refs/heads/master/FBCNet-V2.png
         :align: center
         :alt: FBCNet Architecture
@@ -67,7 +69,9 @@ class FBCNet(EEGModuleMixin, nn.Module):
     linear_max_norm : float, default=0.5
         Maximum norm for the final linear layer.
     filter_parameters: dict, default None
-        Parameters for the FilterBankLayer
+        Dictionary of parameters to use for the FilterBankLayer.
+        If None, a default Chebyshev Type II filter with transition bandwidth of
+        2 Hz and stop-band ripple of 30 dB will be used.
 
     References
     ----------

braindecode/models/fblightconvnet.py

@@ -18,6 +18,8 @@ from braindecode.modules import (
 class FBLightConvNet(EEGModuleMixin, nn.Module):
     """LightConvNet from Ma, X et al (2023) [lightconvnet]_.
 
+    :bdg-success:`Convolution` :bdg-primary:`Filterbank`
+
     .. figure:: https://raw.githubusercontent.com/Ma-Xinzhi/LightConvNet/refs/heads/main/network_architecture.png
         :align: center
         :alt: LightConvNet Neural Network

braindecode/models/fbmsnet.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Optional, Sequence
+from typing import Any, Sequence
 
 import torch
 from einops.layers.torch import Rearrange
@@ -19,6 +19,8 @@ from braindecode.modules import (
 class FBMSNet(EEGModuleMixin, nn.Module):
     """FBMSNet from Liu et al (2022) [fbmsnet]_.
 
+    :bdg-success:`Convolution` :bdg-primary:`Filterbank`
+
     .. figure:: https://raw.githubusercontent.com/Want2Vanish/FBMSNet/refs/heads/main/FBMSNet.png
         :align: center
         :alt: FBMSNet Architecture
@@ -55,16 +57,28 @@ class FBMSNet(EEGModuleMixin, nn.Module):
     ----------
     n_bands : int, default=9
         Number of input channels (e.g., number of frequency bands).
-    stride_factor : int, default=4
-        Stride factor for temporal segmentation.
-    temporal_layer : str, default='LogVarLayer'
-        Temporal aggregation layer to use.
     n_filters_spat : int, default=36
         Number of output channels from the MixedConv2d layer.
+    temporal_layer : str, default='LogVarLayer'
+        Temporal aggregation layer to use.
+    n_dim: int, default=3
+        Dimension of the temporal reduction layer.
+    stride_factor : int, default=4
+        Stride factor for temporal segmentation.
     dilatability : int, default=8
         Expansion factor for the spatial convolution block.
     activation : nn.Module, default=nn.SiLU
         Activation function class to apply.
+    kernels_weights : Sequence[int], default=(15, 31, 63, 125)
+        Kernel sizes for the MixedConv2d layer.
+    cnn_max_norm : float, default=2
+        Maximum norm constraint for the convolutional layers.
+    linear_max_norm : float, default=0.5
+        Maximum norm constraint for the linear layers.
+    filter_parameters : dict, default=None
+        Dictionary of parameters to use for the FilterBankLayer.
+        If None, a default Chebyshev Type II filter with transition bandwidth of
+        2 Hz and stop-band ripple of 30 dB will be used.
     verbose: bool, default False
         Verbose parameter to create the filter using mne.
 
@@ -101,7 +115,7 @@ class FBMSNet(EEGModuleMixin, nn.Module):
         cnn_max_norm: float = 2,
         linear_max_norm: float = 0.5,
         verbose: bool = False,
-        filter_parameters: Optional[dict] = None,
+        filter_parameters: dict[Any, Any] | None = None,
     ):
         super().__init__(
             n_chans=n_chans,

braindecode/models/ifnet.py

@@ -31,6 +31,8 @@ from braindecode.modules import (
 class IFNet(EEGModuleMixin, nn.Module):
     """IFNetV2 from Wang J et al (2023) [ifnet]_.
 
+    :bdg-success:`Convolution` :bdg-primary:`Filterbank`
+
     .. figure:: https://raw.githubusercontent.com/Jiaheng-Wang/IFNet/main/IFNet.png
         :align: center
         :alt: IFNetV2 Architecture