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

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,83 @@ 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.
+
+    - Reference implementation: see [sccnetcode]_.
+
+    .. 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 +129,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/signal_jepa.py

@@ -5,7 +5,8 @@ from __future__ import annotations
 
 import math
 from copy import deepcopy
-from typing import Any, Sequence
+from pathlib import Path
+from typing import Any, Optional, Sequence
 
 import torch
 from einops.layers.torch import Rearrange
@@ -145,6 +146,8 @@ class _BaseSignalJEPA(EEGModuleMixin, nn.Module):
 class SignalJEPA(_BaseSignalJEPA):
     """Architecture introduced in signal-JEPA for self-supervised pre-training, Guetschel, P et al (2024) [1]_
 
+    :bdg-success:`Convolution` :bdg-dark-line:`Channel` :bdg-danger:`Large Brain Model`
+
     This model is not meant for classification but for SSL pre-training.
     Its output shape depends on the input shape.
     For classification purposes, three variants of this model are available:
@@ -231,6 +234,8 @@ class SignalJEPA(_BaseSignalJEPA):
 class SignalJEPA_Contextual(_BaseSignalJEPA):
     """Contextual downstream architecture introduced in signal-JEPA Guetschel, P et al (2024) [1]_.
 
+    :bdg-success:`Convolution` :bdg-dark-line:`Channel` :bdg-danger:`Large Brain Model`
+
     This architecture is one of the variants of :class:`SignalJEPA`
     that can be used for classification purposes.
 
@@ -319,25 +324,50 @@ class SignalJEPA_Contextual(_BaseSignalJEPA):
     @classmethod
     def from_pretrained(
         cls,
-        model: SignalJEPA,
-        n_outputs: int,
+        model: Optional[SignalJEPA | str | Path] = None,  # type: ignore
+        n_outputs: Optional[int] = None,  # type: ignore
         n_spat_filters: int = 4,
-        chs_info: list[dict[str, Any]] | None = None,
+        chs_info: Optional[list[dict[str, Any]]] = None,  # type: ignore
+        **kwargs,
     ):
-        """Instantiate a new model from a pre-trained :class:`SignalJEPA` model.
+        """Instantiate a new model from a pre-trained :class:`SignalJEPA` model or from Hub.
 
         Parameters
         ----------
-        model: SignalJEPA
-            Pre-trained model.
-        n_outputs: int
-            Number of classes for the new model.
+        model: SignalJEPA, str, Path, or None
+            Either a pre-trained :class:`SignalJEPA` model, a string/Path to a local directory
+            (for Hub-style loading), or None (for Hub loading via kwargs).
+        n_outputs: int or None
+            Number of classes for the new model. Required when loading from a SignalJEPA model,
+            optional when loading from Hub (will be read from config).
         n_spat_filters: int
             Number of spatial filters.
         chs_info: list of dict | None
             Information about each individual EEG channel. This should be filled with
             ``info["chs"]``. Refer to :class:`mne.Info` for more details.
+        **kwargs
+            Additional keyword arguments passed to the parent class for Hub loading.
         """
+        # Check if this is a Hub-style load (from a directory path)
+        if isinstance(model, (str, Path)) or (model is None and kwargs):
+            # This is a Hub load, delegate to parent class
+            if isinstance(model, (str, Path)):
+                # model is actually the repo_id or directory path
+                return super().from_pretrained(model, **kwargs)
+            else:
+                # model is None, treat as hub-style load
+                return super().from_pretrained(**kwargs)
+
+        # This is the original SignalJEPA transfer learning case
+        if not isinstance(model, SignalJEPA):
+            raise TypeError(
+                f"model must be a SignalJEPA instance, a path string, or Path object, got {type(model)}"
+            )
+        if n_outputs is None:
+            raise ValueError(
+                "n_outputs must be provided when loading from a SignalJEPA model"
+            )
+
         feature_encoder = model.feature_encoder
         pos_encoder = model.pos_encoder
         transformer = model.transformer
@@ -377,6 +407,8 @@ class SignalJEPA_Contextual(_BaseSignalJEPA):
 class SignalJEPA_PostLocal(_BaseSignalJEPA):
     """Post-local downstream architecture introduced in signal-JEPA Guetschel, P et al (2024) [1]_.
 
+    :bdg-success:`Convolution` :bdg-dark-line:`Channel` :bdg-danger:`Large Brain Model`
+
     This architecture is one of the variants of :class:`SignalJEPA`
     that can be used for classification purposes.
 
@@ -463,22 +495,47 @@ class SignalJEPA_PostLocal(_BaseSignalJEPA):
 
     @classmethod
     def from_pretrained(
-        cls, model: SignalJEPA, n_outputs: int, n_spat_filters: int = 4
+        cls,
+        model: SignalJEPA | str | Path = None,  # type: ignore
+        n_outputs: int = None,  # type: ignore
+        n_spat_filters: int = 4,
+        **kwargs,
     ):
-        """Instantiate a new model from a pre-trained :class:`SignalJEPA` model.
+        """Instantiate a new model from a pre-trained :class:`SignalJEPA` model or from Hub.
 
         Parameters
         ----------
-        model: SignalJEPA
-            Pre-trained model.
-        n_outputs: int
-            Number of classes for the new model.
+        model: SignalJEPA, str, Path, or None
+            Either a pre-trained :class:`SignalJEPA` model, a string/Path to a local directory
+            (for Hub-style loading), or None (for Hub loading via kwargs).
+        n_outputs: int or None
+            Number of classes for the new model. Required when loading from a SignalJEPA model,
+            optional when loading from Hub (will be read from config).
         n_spat_filters: int
             Number of spatial filters.
-        chs_info: list of dict | None
-            Information about each individual EEG channel. This should be filled with
-            ``info["chs"]``. Refer to :class:`mne.Info` for more details.
+        **kwargs
+            Additional keyword arguments passed to the parent class for Hub loading.
         """
+        # Check if this is a Hub-style load (from a directory path)
+        if isinstance(model, (str, Path)) or (model is None and kwargs):
+            # This is a Hub load, delegate to parent class
+            if isinstance(model, (str, Path)):
+                # model is actually the repo_id or directory path
+                return super().from_pretrained(model, **kwargs)
+            else:
+                # model is None, treat as hub-style load
+                return super().from_pretrained(**kwargs)
+
+        # This is the original SignalJEPA transfer learning case
+        if not isinstance(model, SignalJEPA):
+            raise TypeError(
+                f"model must be a SignalJEPA instance, a path string, or Path object, got {type(model)}"
+            )
+        if n_outputs is None:
+            raise ValueError(
+                "n_outputs must be provided when loading from a SignalJEPA model"
+            )
+
         feature_encoder = model.feature_encoder
         assert feature_encoder is not None
         new_model = cls(
@@ -501,6 +558,8 @@ class SignalJEPA_PostLocal(_BaseSignalJEPA):
 class SignalJEPA_PreLocal(_BaseSignalJEPA):
     """Pre-local downstream architecture introduced in signal-JEPA Guetschel, P et al (2024) [1]_.
 
+    :bdg-success:`Convolution` :bdg-dark-line:`Channel` :bdg-danger:`Large Brain Model`
+
     This architecture is one of the variants of :class:`SignalJEPA`
     that can be used for classification purposes.
 
@@ -597,22 +656,47 @@ class SignalJEPA_PreLocal(_BaseSignalJEPA):
 
     @classmethod
     def from_pretrained(
-        cls, model: SignalJEPA, n_outputs: int, n_spat_filters: int = 4
+        cls,
+        model: SignalJEPA | str | Path = None,  # type: ignore
+        n_outputs: int = None,  # type: ignore
+        n_spat_filters: int = 4,
+        **kwargs,
     ):
-        """Instantiate a new model from a pre-trained :class:`SignalJEPA` model.
+        """Instantiate a new model from a pre-trained :class:`SignalJEPA` model or from Hub.
 
         Parameters
         ----------
-        model: SignalJEPA
-            Pre-trained model.
-        n_outputs: int
-            Number of classes for the new model.
+        model: SignalJEPA, str, Path, or None
+            Either a pre-trained :class:`SignalJEPA` model, a string/Path to a local directory
+            (for Hub-style loading), or None (for Hub loading via kwargs).
+        n_outputs: int or None
+            Number of classes for the new model. Required when loading from a SignalJEPA model,
+            optional when loading from Hub (will be read from config).
         n_spat_filters: int
             Number of spatial filters.
-        chs_info: list of dict | None
-            Information about each individual EEG channel. This should be filled with
-            ``info["chs"]``. Refer to :class:`mne.Info` for more details.
+        **kwargs
+            Additional keyword arguments passed to the parent class for Hub loading.
         """
+        # Check if this is a Hub-style load (from a directory path)
+        if isinstance(model, (str, Path)) or (model is None and kwargs):
+            # This is a Hub load, delegate to parent class
+            if isinstance(model, (str, Path)):
+                # model is actually the repo_id or directory path
+                return super().from_pretrained(model, **kwargs)
+            else:
+                # model is None, treat as hub-style load
+                return super().from_pretrained(**kwargs)
+
+        # This is the original SignalJEPA transfer learning case
+        if not isinstance(model, SignalJEPA):
+            raise TypeError(
+                f"model must be a SignalJEPA instance, a path string, or Path object, got {type(model)}"
+            )
+        if n_outputs is None:
+            raise ValueError(
+                "n_outputs must be provided when loading from a SignalJEPA model"
+            )
+
         feature_encoder = model.feature_encoder
         assert feature_encoder is not None
         new_model = cls(

braindecode/models/sinc_shallow.py

@@ -12,6 +12,8 @@ from braindecode.models.base import EEGModuleMixin
 class SincShallowNet(EEGModuleMixin, nn.Module):
     """Sinc-ShallowNet from Borra, D et al (2020) [borra2020]_.
 
+    :bdg-success:`Convolution` :bdg-warning:`Interpretability`
+
     .. figure:: https://ars.els-cdn.com/content/image/1-s2.0-S0893608020302021-gr2_lrg.jpg
         :align: center
         :alt: SincShallowNet Architecture
@@ -19,23 +21,24 @@ class SincShallowNet(EEGModuleMixin, nn.Module):
     The Sinc-ShallowNet architecture has these fundamental blocks:
 
     1. **Block 1: Spectral and Spatial Feature Extraction**
-        - *Temporal Sinc-Convolutional Layer*:
-            Uses parametrized sinc functions to learn band-pass filters,
-            significantly reducing the number of trainable parameters by only
-            learning the lower and upper cutoff frequencies for each filter.
-       - *Spatial Depthwise Convolutional Layer*:
-            Applies depthwise convolutions to learn spatial filters for
-            each temporal feature map independently, further reducing
-            parameters and enhancing interpretability.
-       - *Batch Normalization*
+
+        - *Temporal Sinc-Convolutional Layer*: Uses parametrized sinc functions to learn band-pass filters,
+          significantly reducing the number of trainable parameters by only
+          learning the lower and upper cutoff frequencies for each filter.
+        - *Spatial Depthwise Convolutional Layer*: Applies depthwise convolutions to learn spatial filters for
+          each temporal feature map independently, further reducing
+          parameters and enhancing interpretability.
+        - *Batch Normalization*
 
     2. **Block 2: Temporal Aggregation**
+
         - *Activation Function*: ELU
         - *Average Pooling Layer*: Aggregation by averaging spatial dim
         - *Dropout Layer*
         - *Flatten Layer*
 
     3. **Block 3: Classification**
+
         - *Fully Connected Layer*: Maps the feature vector to n_outputs.
 
     **Implementation Notes:**

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.