braindecode 1.2.0.dev168908090__py3-none-any.whl → 1.2.0.dev175267687__py3-none-any.whl

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

@@ -157,7 +157,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/sccnet.py

@@ -17,13 +17,21 @@ from braindecode.modules import LogActivation
 class SCCNet(EEGModuleMixin, nn.Module):
     """SCCNet from Wei, C S (2019) [sccnet]_.
 
+    :bdg-success:`Convolution`
+
     Spatial component-wise convolutional network (SCCNet) for motor-imagery EEG
     classification.
 
     .. figure:: https://dt5vp8kor0orz.cloudfront.net/6e3ec5d729cd51fe8acc5a978db27d02a5df9e05/2-Figure1-1.png
        :align: center
        :alt:  Spatial component-wise convolutional network
+       :width: 680px
+
+    .. rubric:: Architectural Overview
 
+    SCCNet is a spatial-first convolutional layer that fixes temporal kernels in seconds
+    to make its filters correspond to neurophysiologically aligned windows. The model
+    comprises four stages:
 
     1. **Spatial Component Analysis**: Performs convolution spatial filtering
         across all EEG channels to extract spatial components, effectively
@@ -35,11 +43,81 @@ class SCCNet(EEGModuleMixin, nn.Module):
     4. **Classification**: Flattens the features and applies a fully connected
        layer.
 
+    .. rubric:: Macro Components
+
+    - `SCCNet.spatial_conv` **(spatial component analysis)**
+
+        - *Operations.*
+        - :class:`~torch.nn.Conv2d` with kernel `(n_chans, N_t)` and stride `(1, 1)` on an input reshaped to `(B, 1, n_chans, T)`; typical choice `N_t=1` yields a pure across-channel projection (montage-wide linear spatial filter).
+        - Zero padding to preserve time, :class:`~torch.nn.BatchNorm2d`; output has `N_u` component signals shaped `(B, 1, N_u, T)` after a permute step.
+
+    *Interpretability/robustness.* Mimics CSP-like spatial filtering: each learned filter is a channel-weighted component, easing inspection and reducing channel noise.
+
+    - `SCCNet.spatial_filt_conv` **(spatio-temporal filtering)**
+
+        - *Operations.*
+        - :class:`~torch.nn.Conv2d` with kernel `(N_u, 12)` over components and time (12 samples ~ 0.1 s at 125 Hz),
+        - :class:`~torch.nn.BatchNorm2d`;
+        - Nonlinearity is **power-like**: the original paper uses **square** like :class:`~braindecode.models.ShallowFBCSPNet` with the class :class:`~braindecode.modules.LogActivation` as default.
+        - :class:`~torch.nn.Dropout` with rate `p=0.5`.
+
+    - *Role.* Learns frequency-selective energy features and inter-component interactions within a 0.1 s context (beta/alpha cycle scale).
+
+    - `SCCNet.temporal_smoothing` **(aggregation + readout)**
+
+        - *Operations.*
+        - :class:`~torch.nn.AvgPool2d` with size `(1, 62)` (~ 0.5 s) for temporal smoothing and downsampling
+        - :class:`~torch.nn.Flatten`
+        - :class:`~torch.nn.Linear` to `n_outputs`.
+
+
+    .. rubric:: Convolutional Details
+
+    * **Temporal (where time-domain patterns are learned).**
+        The second block's kernel length is fixed to 12 samples (≈ 100 ms) and slides with
+        stride 1; average pooling `(1, 62)` (≈ 500 ms) integrates power over longer spans.
+        These choices bake in short-cycle detection followed by half-second trend smoothing.
+
+    * **Spatial (how electrodes are processed).**
+        The first block's kernel spans **all electrodes** `(n_chans, N_t)`. With `N_t=1`,
+        it reduces to a montage-wide linear projection, mapping channels → `N_u` components.
+        The second block mixes **across components** via kernel height `N_u`.
+
+    * **Spectral (how frequency information is captured).**
+        No explicit transform is used; learned **temporal kernels** serve as bandpass-like
+        filters, and the **square/log power** nonlinearity plus 0.5 s averaging approximate
+        band-power estimation (ERD/ERS-style features).
+
+    .. rubric:: Attention / Sequential Modules
+
+    This model contains **no attention** and **no recurrent units**.
+
+    .. rubric:: Additional Mechanisms
+
+    - :class:`~torch.nn.BatchNorm2d` and zero-padding are applied to both convolutions;
+      L2 weight decay was used in the original paper; dropout `p=0.5` combats overfitting.
+    - Contrasting with other compact neural network, in EEGNet performs a temporal depthwise conv
+      followed by a **depthwise spatial** conv (separable), learning temporal filters first.
+      SCCNet inverts this order: it performs a **full spatial projection first** (CSP-like),
+      then a short **spatio-temporal** conv with an explicit 0.1 s kernel, followed by
+      **power-like** nonlinearity and longer temporal averaging. EEGNet's ELU and
+      separable design favor parameter efficiency; SCCNet's second-scale kernels and
+      square/log emphasize interpretable **band-power** features.
+
+    .. rubric:: Usage and Configuration
+
+    * **Training from the original authors.**
+
+    * Match window length so that `T` is comfortably larger than pooling length
+        (e.g., > 1.5-2 s for MI).
+    * Start with standard MI augmentations (channel dropout/shuffle, time reverse)
+        and tune `n_spatial_filters` before deeper changes.
 
     Parameters
     ----------
     n_spatial_filters : int, optional
-        Number of spatial filters in the first convolutional layer. Default is 22.
+        Number of spatial filters in the first convolutional layer, variable `N_u` from the
+        original paper. Default is 22.
     n_spatial_filters_smooth : int, optional
         Number of spatial filters used as filter in the second convolutional
         layer. Default is 20.
@@ -49,13 +127,6 @@ class SCCNet(EEGModuleMixin, nn.Module):
         Activation function after the second convolutional layer. Default is
         logarithm activation.
 
-    Notes
-    -----
-    This implementation is not guaranteed to be correct, has not been checked
-    by original authors, only reimplemented from the paper description and
-    the source that have not been tested [sccnetcode]_.
-
-
     References
     ----------
     .. [sccnet] Wei, C. S., Koike-Akino, T., & Wang, Y. (2019, March). Spatial

braindecode/models/shallow_fbcsp.py

@@ -20,6 +20,8 @@ from braindecode.modules import (
 class ShallowFBCSPNet(EEGModuleMixin, nn.Sequential):
     """Shallow ConvNet model from Schirrmeister et al (2017) [Schirrmeister2017]_.
 
+    :bdg-success:`Convolution`
+
     .. figure:: https://onlinelibrary.wiley.com/cms/asset/221ea375-6701-40d3-ab3f-e411aad62d9e/hbm23730-fig-0002-m.jpg
         :align: center
         :alt: ShallowNet Architecture

braindecode/models/sleep_stager_blanco_2020.py

@@ -11,6 +11,8 @@ from braindecode.models.base import EEGModuleMixin
 class SleepStagerBlanco2020(EEGModuleMixin, nn.Module):
     """Sleep staging architecture from Blanco et al. (2020) from [Blanco2020]_
 
+    :bdg-success:`Convolution`
+
     .. figure:: https://media.springernature.com/full/springer-static/image/art%3A10.1007%2Fs00500-019-04174-1/MediaObjects/500_2019_4174_Fig2_HTML.png
         :align: center
         :alt: SleepStagerBlanco2020 Architecture

braindecode/models/sleep_stager_chambon_2018.py

@@ -13,6 +13,8 @@ from braindecode.models.base import EEGModuleMixin
 class SleepStagerChambon2018(EEGModuleMixin, nn.Module):
     """Sleep staging architecture from Chambon et al. (2018) [Chambon2018]_.
 
+    :bdg-success:`Convolution`
+
     .. figure:: https://braindecode.org/dev/_static/model/SleepStagerChambon2018.jpg
         :align: center
         :alt: SleepStagerChambon2018 Architecture

braindecode/models/sparcnet.py

@@ -13,6 +13,8 @@ from braindecode.models.base import EEGModuleMixin
 class SPARCNet(EEGModuleMixin, nn.Module):
     """Seizures, Periodic and Rhythmic pattern Continuum Neural Network (SPaRCNet) from Jing et al. (2023) [jing2023]_.
 
+    :bdg-success:`Convolution`
+
     This is a temporal CNN model for biosignal classification based on the DenseNet
     architecture.
 

braindecode/models/summary.csv

@@ -1,41 +1,39 @@
-Model,Paradigm,Type,Freq(Hz),Hyperparameters,#Parameters,get_#Parameters
-ATCNet,General,Classification,250,"n_chans, n_outputs, n_times",113732,"ATCNet(n_chans=22, n_outputs=4, n_times=1000)"
-AttentionBaseNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times",3692,"AttentionBaseNet(n_chans=22, n_outputs=4, n_times=1000)"
-BDTCN,Normal/Abnormal,Classification,100,"n_chans, n_outputs, n_times",456502,"BDTCN(n_chans=21, n_outputs=2, n_times=6000, n_blocks=5, n_filters=55, kernel_size=16)"
-BIOT,"Sleep Staging, Epilepsy",Classification,200,"n_chans, n_outputs",3183879,"BIOT(n_chans=2,  n_outputs=5,  n_times=6000)"
-ContraWR,Sleep Staging,"Classification, Embedding",125,"n_chans, n_outputs, sfreq",1160165,"ContraWR(n_chans=2, n_outputs=5, n_times=3750, emb_size=256, sfreq=125)"
-CTNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times",26900,"CTNet(n_chans=22, n_outputs=4, n_times=1000, n_filters_time=8, kernel_size=16, heads=2, emb_size=16)"
-Deep4Net,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times",282879,"Deep4Net(n_chans=22, n_outputs=4, n_times=1000)"
-DeepSleepNet,Sleep Staging,Classification,256,"n_chans, n_outputs",24744837,"DeepSleepNet(n_chans=1, n_outputs=5, n_times=7680, sfreq=256)"
-EEGConformer,General,Classification,250,"n_chans, n_outputs, n_times",789572,"EEGConformer(n_chans=22, n_outputs=4, n_times=1000)."
-EEGInceptionERP,"ERP, SSVEP",Classification,128,"n_chans, n_outputs",14926,"EEGInceptionERP(n_chans=8, n_outputs=2, n_times=128, sfreq=128)"
-EEGInceptionMI,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times",558028,"EEGInceptionMI(n_chans=22, n_outputs=4, n_times=1000, n_convs=5, n_filters=12)"
-EEGITNet,Motor Imagery,Classification,125,"n_chans, n_outputs, n_times",5212,"EEGITNet(n_chans=22,  n_outputs=4,  n_times=500)"
-EEGNetv1,General,Classification,128,"n_chans, n_outputs, n_times",3052,"EEGNetv1(n_chans=22,  n_outputs=4,  n_times=512)"
-EEGNetv4,General,Classification,128,"n_chans, n_outputs, n_times",2484,"EEGNetv4(n_chans=22,  n_outputs=4,  n_times=512)"
-EEGNeX,Motor Imagery,Classification,125,"n_chans, n_outputs, n_times",55940,"EEGNeX(n_chans=22,  n_outputs=4,  n_times=500)"
-EEGMiner,Emotion Recognition,Classification,128,"n_chans, n_outputs, n_times, sfreq",7572,"EEGMiner(n_chans=62, n_outputs=2, n_times=2560, sfreq=128)"
-EEGResNet,General,Classification,250,"n_chans, n_outputs, n_times",247484,"EEGResNet(n_chans=22,  n_outputs=4,  n_times=1000)"
-EEGSimpleConv,Motor Imagery,Classification,80,"n_chans, n_outputs, sfreq",730404,"EEGSimpleConv(n_chans=22,  n_outputs=4,  n_times=320, sfreq=80)"
-EEGTCNet,Motor Imagery,Classification,250,"n_chans, n_outputs",4516,"EEGTCNet(n_chans=22,  n_outputs=4,  n_times=1000, kern_length=32)"
-Labram,General,"Classification, Embedding",200,"n_chans, n_outputs, n_times",5866180,"Labram(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)"
-MSVTNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times",75494," MSVTNet(n_chans=22,  n_outputs=4,  n_times=1000)"
-SCCNet,Motor Imagery,Classification,125,"n_chans, n_outputs, n_times, sfreq",12070,"SCCNet(n_chans=22,  n_outputs=4,  n_times=1000, sfreq=125)"
-SignalJEPA,"Motor Imagery, ERP, SSVEP",Embedding,128,"n_times, chs_info",3456882,"SignalJEPA(n_times=512, chs_info=Lee2019_MI().get_data(subjects=[1])[1]['0']['1train'].info[""chs""][:62])"
-SignalJEPA_Contextual,"Motor Imagery, ERP, SSVEP",Classification,128,"n_outputs, n_times, chs_info",3459184,"SignalJEPA_Contextual(n_outputs=2, input_window_seconds=4.19, sfreq=128, chs_info=Lee2019_MI().get_data(subjects=[1])[1]['0']['1train'].info[""chs""][:62])"
-SignalJEPA_PostLocal,"Motor Imagery, ERP, SSVEP",Classification,128,"n_chans, n_outputs, n_times",16142,"SignalJEPA_PostLocal(n_chans=62, n_outputs=2, input_window_seconds=4.19, sfreq=128)"
-SignalJEPA_PreLocal,"Motor Imagery, ERP, SSVEP",Classification,128,"n_outputs, n_times, chs_info",16142,"SignalJEPA_PreLocal(n_chans=62, n_outputs=2, input_window_seconds=4.19, sfreq=128)"
-SincShallowNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",21892,"SincShallowNet(n_chans=22,  n_outputs=4,  n_times=1000, sfreq=250)"
-ShallowFBCSPNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times",46084,"ShallowFBCSPNet(n_chans=22,  n_outputs=4,  n_times=1000, sfreq=250)"
-SleepStagerBlanco2020,Sleep Staging,Classification,100,"n_chans, n_outputs, n_times",2845,"SleepStagerBlanco2020(n_chans=2, n_outputs=5, n_times=3000, sfreq=100)"
-SleepStagerChambon2018,Sleep Staging,Classification,128,"n_chans, n_outputs, n_times, sfreq",5835,"SleepStagerChambon2018(n_chans=2, n_outputs=5, n_times=3840, sfreq=128)"
-SleepStagerEldele2021,Sleep Staging,Classification,100,"n_chans, n_outputs, n_times, sfreq",719925,"SleepStagerEldele2021(n_chans=2, n_outputs=5, n_times=3000, sfreq=100)"
-SPARCNet,Epilepsy,Classification,200,"n_chans, n_outputs, n_times",1141921,"SPARCNet(n_chans=16, n_outputs=6, n_times=2000, sfreq=200)"
-SyncNet,"Emotion Recognition, Alcoholism",Classification,256,"n_chans, n_outputs, n_times",554,"SyncNet(n_chans=62, n_outputs=3, n_times=5120, sfreq=256)"
-TSceptionV1,Emotion Recognition,Classification,256,"n_chans, n_outputs, n_times, sfreq",2187206,"TSceptionV1(n_chans=62, n_outputs=3, n_times=5120, sfreq=256)"
-TIDNet,General,Classification,250,"n_chans, n_outputs, n_times",240404,"TIDNet(n_chans=22,  n_outputs=4,  n_times=1000)"
-USleep,Sleep Staging,Classification,128,"n_chans, n_outputs, n_times, sfreq",2482011,"USleep(n_chans=2, n_outputs=5, n_times=3000, sfreq=100)"
-FBCNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",11812,"FCNet(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)"
-FBMSNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",16231,"FBMSNet(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)"
-FBLightConvNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",6596,"FBLightConvNet(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)"
-IFNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",9860,"IFNet(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)"
+Model,Application,Type,Sampling Frequency (Hz),Hyperparameters,#Parameters,get_#Parameters,Categorization
+ATCNet,General,Classification,250,"n_chans, n_outputs, n_times",113732,"ATCNet(n_chans=22, n_outputs=4, n_times=1000)","Convolution,Recurrent,Small Attention"
+AttentionBaseNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times",3692,"AttentionBaseNet(n_chans=22, n_outputs=4, n_times=1000)","Convolution,Small Attention"
+BDTCN,Normal Abnormal,Classification,100,"n_chans, n_outputs, n_times",456502,"BDTCN(n_chans=21, n_outputs=2, n_times=6000, n_blocks=5, n_filters=55, kernel_size=16)","Convolution,Recurrent"
+BIOT,"Sleep Staging, Epilepsy",Classification,200,"n_chans, n_outputs",3183879,"BIOT(n_chans=2,  n_outputs=5,  n_times=6000)","Large Language Model"
+ContraWR,Sleep Staging,"Classification, Embedding",125,"n_chans, n_outputs, sfreq",1160165,"ContraWR(n_chans=2, n_outputs=5, n_times=3750, emb_size=256, sfreq=125)",Convolution
+CTNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times",26900,"CTNet(n_chans=22, n_outputs=4, n_times=1000, n_filters_time=8, kernel_size=16, heads=2, emb_size=16)","Convolution,Small Attention"
+Deep4Net,General,Classification,250,"n_chans, n_outputs, n_times",282879,"Deep4Net(n_chans=22, n_outputs=4, n_times=1000)","Convolution"
+DeepSleepNet,Sleep Staging,Classification,256,"n_chans, n_outputs",24744837,"DeepSleepNet(n_chans=1, n_outputs=5, n_times=7680, sfreq=256)","Convolution,Recurrent"
+EEGConformer,General,Classification,250,"n_chans, n_outputs, n_times",789572,"EEGConformer(n_chans=22, n_outputs=4, n_times=1000)","Convolution,Small Attention"
+EEGInceptionERP,"ERP, SSVEP",Classification,128,"n_chans, n_outputs",14926,"EEGInceptionERP(n_chans=8, n_outputs=2, n_times=128, sfreq=128)","Convolution"
+EEGInceptionMI,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times",558028,"EEGInceptionMI(n_chans=22, n_outputs=4, n_times=1000, n_convs=5, n_filters=12)","Convolution"
+EEGITNet,Motor Imagery,Classification,125,"n_chans, n_outputs, n_times",5212,"EEGITNet(n_chans=22,  n_outputs=4,  n_times=500)","Convolution,Recurrent"
+EEGNet,General,Classification,128,"n_chans, n_outputs, n_times",2484,"EEGNet(n_chans=22,  n_outputs=4,  n_times=512)","Convolution"
+EEGNeX,Motor Imagery,Classification,125,"n_chans, n_outputs, n_times",55940,"EEGNeX(n_chans=22,  n_outputs=4,  n_times=500)","Convolution"
+EEGMiner,Emotion Recognition,Classification,128,"n_chans, n_outputs, n_times, sfreq",7572,"EEGMiner(n_chans=62, n_outputs=2, n_times=2560, sfreq=128)","Convolution,Interpretability"
+EEGSimpleConv,Motor Imagery,Classification,80,"n_chans, n_outputs, sfreq",730404,"EEGSimpleConv(n_chans=22,  n_outputs=4,  n_times=320, sfreq=80)","Convolution"
+EEGTCNet,Motor Imagery,Classification,250,"n_chans, n_outputs",4516,"EEGTCNet(n_chans=22,  n_outputs=4,  n_times=1000, kern_length=32)","Convolution,Recurrent"
+Labram,General,"Classification, Embedding",200,"n_chans, n_outputs, n_times",5866180,"Labram(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)","Convolution,Large Language Model"
+MSVTNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times",75494," MSVTNet(n_chans=22,  n_outputs=4,  n_times=1000)","Convolution,Recurrent,Small Attention"
+SCCNet,Motor Imagery,Classification,125,"n_chans, n_outputs, n_times, sfreq",12070,"SCCNet(n_chans=22,  n_outputs=4,  n_times=1000, sfreq=125)","Convolution"
+SignalJEPA,"Motor Imagery, ERP, SSVEP",Embedding,128,"n_times, chs_info",3456882,"SignalJEPA(n_times=512, chs_info=Lee2019_MI().get_data(subjects=[1])[1]['0']['1train'].info[""chs""][:62])","Convolution,Channel,Large Language Model"
+SignalJEPA_Contextual,"Motor Imagery, ERP, SSVEP",Classification,128,"n_outputs, n_times, chs_info",3459184,"SignalJEPA_Contextual(n_outputs=2, input_window_seconds=4.19, sfreq=128, chs_info=Lee2019_MI().get_data(subjects=[1])[1]['0']['1train'].info[""chs""][:62])","Convolution,Channel,Large Language Model"
+SignalJEPA_PostLocal,"Motor Imagery, ERP, SSVEP",Classification,128,"n_chans, n_outputs, n_times",16142,"SignalJEPA_PostLocal(n_chans=62, n_outputs=2, input_window_seconds=4.19, sfreq=128)","Convolution,Channel,Large Language Model"
+SignalJEPA_PreLocal,"Motor Imagery, ERP, SSVEP",Classification,128,"n_outputs, n_times, chs_info",16142,"SignalJEPA_PreLocal(n_chans=62, n_outputs=2, input_window_seconds=4.19, sfreq=128)","Convolution,Channel,Large Language Model"
+SincShallowNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",21892,"SincShallowNet(n_chans=22,  n_outputs=4,  n_times=1000, sfreq=250)","Convolution,Interpretability"
+ShallowFBCSPNet,General,Classification,250,"n_chans, n_outputs, n_times",46084,"ShallowFBCSPNet(n_chans=22,  n_outputs=4,  n_times=1000, sfreq=250)","Convolution"
+SleepStagerBlanco2020,Sleep Staging,Classification,100,"n_chans, n_outputs, n_times",2845,"SleepStagerBlanco2020(n_chans=2, n_outputs=5, n_times=3000, sfreq=100)","Convolution"
+SleepStagerChambon2018,Sleep Staging,Classification,128,"n_chans, n_outputs, n_times, sfreq",5835,"SleepStagerChambon2018(n_chans=2, n_outputs=5, n_times=3840, sfreq=128)","Convolution"
+AttnSleep,Sleep Staging,Classification,100,"n_chans, n_outputs, n_times, sfreq",719925,"AttnSleep(n_chans=2, n_outputs=5, n_times=3000, sfreq=100)","Convolution, Small Attention"
+SPARCNet,Epilepsy,Classification,200,"n_chans, n_outputs, n_times",1141921,"SPARCNet(n_chans=16, n_outputs=6, n_times=2000, sfreq=200)","Convolution"
+SyncNet,"Emotion Recognition, Alcoholism",Classification,256,"n_chans, n_outputs, n_times",554,"SyncNet(n_chans=62, n_outputs=3, n_times=5120, sfreq=256)","Interpretability"
+TSception,Emotion Recognition,Classification,256,"n_chans, n_outputs, n_times, sfreq",2187206,"TSception(n_chans=62, n_outputs=3, n_times=5120, sfreq=256)","Convolution"
+TIDNet,General,Classification,250,"n_chans, n_outputs, n_times",240404,"TIDNet(n_chans=22,  n_outputs=4,  n_times=1000)","Convolution"
+USleep,Sleep Staging,Classification,128,"n_chans, n_outputs, n_times, sfreq",2482011,"USleep(n_chans=2, n_outputs=5, n_times=3000, sfreq=100)","Convolution"
+FBCNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",11812,"FCNet(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)","Convolution,FilterBank"
+FBMSNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",16231,"FBMSNet(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)","Convolution,FilterBank"
+FBLightConvNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",6596,"FBLightConvNet(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)","Convolution,FilterBank"
+IFNet,Motor Imagery,Classification,250,"n_chans, n_outputs, n_times, sfreq",9860,"IFNet(n_chans=22, n_outputs=4, n_times=1000, sfreq=250)","Convolution,FilterBank"

braindecode/models/tidnet.py

@@ -13,6 +13,8 @@ from braindecode.modules import Ensure4d
 class TIDNet(EEGModuleMixin, nn.Module):
     """Thinker Invariance DenseNet model from Kostas et al. (2020) [TIDNet]_.
 
+    :bdg-success:`Convolution`
+
     .. figure:: https://content.cld.iop.org/journals/1741-2552/17/5/056008/revision3/jneabb7a7f1_hr.jpg
         :align: center
         :alt: TIDNet Architecture

braindecode/models/tsinception.py

@@ -7,19 +7,21 @@ from __future__ import annotations
 import torch
 import torch.nn as nn
 from einops.layers.torch import Rearrange
-from mne.utils import warn
+from mne.utils import deprecated, warn
 
 from braindecode.models.base import EEGModuleMixin
 
 
-class TSceptionV1(EEGModuleMixin, nn.Module):
+class TSception(EEGModuleMixin, nn.Module):
     """TSception model from Ding et al. (2020) from [ding2020]_.
 
+    :bdg-success:`Convolution`
+
     TSception: A deep learning framework for emotion detection using EEG.
 
     .. figure:: https://user-images.githubusercontent.com/58539144/74716976-80415e00-526a-11ea-9433-02ab2b753f6b.PNG
         :align: center
-        :alt: TSceptionV1 Architecture
+        :alt: TSception Architecture
 
     The model consists of temporal and spatial convolutional layers
     (Tception and Sception) designed to learn temporal and spatial features
@@ -281,3 +283,13 @@ class TSceptionV1(EEGModuleMixin, nn.Module):
             activation(),
             nn.AvgPool2d(kernel_size=(1, pool_size), stride=(1, pool_size)),
         )
+
+
+@deprecated(
+    "`TSceptionV1` was renamed to `TSception` in v1.12; "
+    "this alias will be removed in v1.14."
+)
+class TSceptionV1(TSception):
+    """Deprecated alias for TSception."""
+
+    pass

braindecode/models/usleep.py

@@ -15,22 +15,116 @@ class USleep(EEGModuleMixin, nn.Module):
     """
     Sleep staging architecture from Perslev et al. (2021) [1]_.
 
+    :bdg-success:`Convolution`
+
     .. figure:: https://media.springernature.com/full/springer-static/image/art%3A10.1038%2Fs41746-021-00440-5/MediaObjects/41746_2021_440_Fig2_HTML.png
         :align: center
         :alt: USleep Architecture
 
-    U-Net (autoencoder with skip connections) feature-extractor for sleep
-    staging described in [1]_.
+        Figure: U-Sleep consists of an encoder (left) which encodes the input signals into dense feature representations, a decoder (middle) which projects
+        the learned features into the input space to generate a dense sleep stage representation, and finally a specially designed segment
+        classifier (right) which generates sleep stages at a chosen temporal resolution.
+
+    .. rubric:: Architectural Overview
+
+    U-Sleep is a **fully convolutional**, feed-forward encoder-decoder with a *segment classifier* head for
+    time-series **segmentation** (sleep staging). It maps multi-channel PSG (EEG+EOG) to a *dense, high-frequency*
+    per-sample representation, then aggregates it into fixed-length stage labels (e.g., 30 s). The network
+    processes arbitrarily long inputs in **one forward pass** (resampling to 128 Hz), allowing whole-night
+    hypnograms in seconds.
+
+    - (i). :class:`_EncoderBlock` extracts progressively deeper temporal features at lower resolution;
+    - (ii). :class:`_Decoder` upsamples and fuses encoder features via U-Net-style skips to recover a per-sample stage map;
+    - (iii). Segment Classifier mean-pools over the target epoch length and applies two pointwise convs to yield
+      per-epoch probabilities. Integrates into the USleep class.
+
+    .. rubric:: Macro Components
+
+    - Encoder :class:`_EncoderBlock` **(multi-scale temporal feature extractor; downsampling x2 per block)**
+
+        - *Operations.*
+        - **Conv1d** (:class:`torch.nn.Conv1d`) with kernel ``9`` (stride ``1``, no dilation)
+        - **ELU** (:class:`torch.nn.ELU`)
+        - **Batch Norm** (:class:`torch.nn.BatchNorm1d`)
+        - **Max Pool 1d**, :class:`torch.nn.MaxPool1d` (``kernel=2, stride=2``).
+
+        Filters grow with depth by a factor of ``sqrt(2)`` (start ``c_1=5``); each block exposes a **skip**
+        (pre-pooling activation) to the matching decoder block.
+        *Role.* Slow, uniform downsampling preserves early information while expanding the effective temporal
+        context over minutes—foundational for robust cross-cohort staging.
+
+    The number of filters grows with depth (capacity scaling); each block also exposes a **skip** (pre-pool)
+    to the matching decoder block.
+
+    **Rationale.**
+        - Slow, uniform downsampling (x2 each level) preserves information in early layers while expanding the temporal receptive field over the minutes.
+
+    - Decoder :class:`_DecoderBlock`  **(progressive upsampling + skip fusion to high-frequency map, 12 blocks; upsampling x2 per block)**
+
+        - *Operations.*
+        - **Nearest-neighbor upsample**, :class:`nn.Upsample` (x2)
+        - **Convolution2d** (k=2), :class:`torch.nn.Conv2d`
+        - ELU, :class:`torch.nn.ELU`
+        - Batch Norm, :class:`torch.nn.BatchNorm2d`
+        - **Concatenate** with the encoder skip at the same temporal scale, :function:`torch.cat`
+        - **Convolution**, :class:`torch.nn.Conv2d`
+        - ELU, :class:`torch.nn.ELU`
+        - Batch Norm, :class:`torch.nn.BatchNorm2d`.
+
+    **Output**: A multi-class, **high-frequency** per-sample representation aligned to the input rate (128 Hz).
+
+    - **Segment Classifier incorporate into :class:`braindecode.models.USleep` (aggregation to fixed epochs)**
+
+        - *Operations.*
+        - **Mean-pool**, :class:`torch.nn.AvgPool2d` per class with kernel = epoch length *i* and stride *i*
+        - **1x1 conv**, :class:`torch.nn.Conv2d`
+        - ELU, :class:`torch.nn.ELU`
+        - **1x1 conv**, :class:`torch.nn.Conv2d` with ``(T, K)`` (epochs x stages).
+
+    **Role**: Learns a **non-linear** weighted combination over each 30-s window (unlike U-Time's linear combiner).
+
+    .. rubric:: Convolutional Details
+
+    - **Temporal (where time-domain patterns are learned).**
+    All convolutions are **1-D along time**; depth (12 levels) plus pooling yields an extensive receptive field
+    (reported sensitivity to ±6.75 min around each epoch; theoretical field ≈ 9.6 min at the deepest layer).
+    The decoder restores sample-level resolution before epoch aggregation.
+
+    - **Spatial (how channels are processed).**
+    Convolutions mix across the *channel* dimension jointly with time (no separate spatial operator). The system
+    is **montage-agnostic** (any reasonable EEG/EOG pair) and was trained across diverse cohorts/protocols,
+    supporting robustness to channel placement and hardware differences.
+
+    - **Spectral (how frequency content is captured).**
+    No explicit Fourier/wavelet transform is used; the **stack of temporal convolutions** acts as a learned
+    filter bank whose effective bandwidth grows with depth. The high-frequency decoder output (128 Hz)
+    retains fine temporal detail for the segment classifier.
+
+
+    .. rubric:: Attention / Sequential Modules
+
+    U-Sleep contains **no attention or recurrent units**; it is a *pure* feed-forward, fully convolutional
+    segmentation network inspired by U-Net/U-Time, favoring training stability and cross-dataset portability.
+
+
+    .. rubric:: Additional Mechanisms
+
+    - **U-Net lineage with task-specific head.** U-Sleep extends U-Time by being **deeper** (12 vs. 4 levels),
+      switching ReLU→**ELU**, using uniform pooling (2) at all depths, and replacing the linear combiner with a
+      **two-layer** pointwise head—improving capacity and resilience across datasets.
+    - **Arbitrary-length inference.** Thanks to full convolutionality and tiling-free design, entire nights can be
+      staged in a single pass on commodity hardware. Inputs shorter than ≈ 17.5 min may reduce performance by
+      limiting long-range context.
+    - **Complexity scaling (alpha).** Filter counts can be adjusted by a global **complexity factor** to trade accuracy
+      and memory (as described in the paper's topology table).
+
 
-    For the encoder ('down'):
-        - the temporal dimension shrinks (via maxpooling in the time-domain)
-        - the spatial dimension expands (via more conv1d filters in the time-domain)
+    .. rubric:: Usage and Configuration
 
-    For the decoder ('up'):
-        - the temporal dimension expands (via upsampling in the time-domain)
-        - the spatial dimension shrinks (via fewer conv1d filters in the time-domain)
+    - **Practice.** Resample PSG to **128 Hz** and provide at least two channels (one EEG, one EOG). Choose epoch
+      length *i* (often 30 s); ensure windows long enough to exploit the model's receptive field (e.g., training on
+      ≥ 17.5 min chunks).
 
-    Both do so at exponential rates.
 
     Parameters
     ----------

braindecode/models/util.py

@@ -22,6 +22,8 @@ def _init_models_dict():
             issubclass(m[1], models.base.EEGModuleMixin)
             and m[1] != models.base.EEGModuleMixin
         ):
+            if m[1].__name__ == "EEGNetv4":
+                continue
             models_dict[m[0]] = m[1]
 
 
@@ -55,9 +57,7 @@ models_mandatory_parameters = [
     ("EEGInceptionERP", ["n_chans", "n_outputs", "n_times", "sfreq"], None),
     ("EEGInceptionMI", ["n_chans", "n_outputs", "n_times", "sfreq"], None),
     ("EEGITNet", ["n_chans", "n_outputs", "n_times"], None),
-    ("EEGNetv1", ["n_chans", "n_outputs", "n_times"], None),
-    ("EEGNetv4", ["n_chans", "n_outputs", "n_times"], None),
-    ("EEGResNet", ["n_chans", "n_outputs", "n_times"], None),
+    ("EEGNet", ["n_chans", "n_outputs", "n_times"], None),
     ("ShallowFBCSPNet", ["n_chans", "n_outputs", "n_times"], None),
     (
         "SleepStagerBlanco2020",
@@ -66,7 +66,7 @@ models_mandatory_parameters = [
     ),
     ("SleepStagerChambon2018", ["n_chans", "n_outputs", "n_times", "sfreq"], None),
     (
-        "SleepStagerEldele2021",
+        "AttnSleep",
         ["n_outputs", "n_times", "sfreq"],
         dict(sfreq=100.0, n_times=3000, chs_info=[dict(ch_name="C1", kind="eeg")]),
     ),  # 1 channel
@@ -79,7 +79,7 @@ models_mandatory_parameters = [
     ("SPARCNet", ["n_chans", "n_outputs", "n_times"], None),
     ("ContraWR", ["n_chans", "n_outputs", "sfreq", "n_times"], dict(sfreq=200.0)),
     ("EEGNeX", ["n_chans", "n_outputs", "n_times"], None),
-    ("TSceptionV1", ["n_chans", "n_outputs", "n_times", "sfreq"], dict(sfreq=200.0)),
+    ("TSception", ["n_chans", "n_outputs", "n_times", "sfreq"], dict(sfreq=200.0)),
     ("EEGTCNet", ["n_chans", "n_outputs", "n_times"], None),
     ("SyncNet", ["n_chans", "n_outputs", "n_times"], None),
     ("MSVTNet", ["n_chans", "n_outputs", "n_times"], None),

braindecode/version.py

@@ -1 +1 @@
-__version__ = "1.2.0.dev168908090"
+__version__ = "1.2.0.dev175267687"