braindecode 1.1.1.dev183425073__tar.gz → 1.2.0.dev182094932__tar.gz

{braindecode-1.1.1.dev183425073/braindecode.egg-info → braindecode-1.2.0.dev182094932}/PKG-INFO

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

{braindecode-1.1.1.dev183425073 → braindecode-1.2.0.dev182094932}/braindecode/models/eegnet.py

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

{braindecode-1.1.1.dev183425073 → braindecode-1.2.0.dev182094932}/braindecode/modules/attention.py

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

{braindecode-1.1.1.dev183425073 → braindecode-1.2.0.dev182094932}/braindecode/modules/convolution.py

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

{braindecode-1.1.1.dev183425073 → braindecode-1.2.0.dev182094932}/braindecode/modules/filter.py

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

{braindecode-1.1.1.dev183425073 → braindecode-1.2.0.dev182094932}/braindecode/training/scoring.py

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

braindecode-1.2.0.dev182094932/braindecode/version.py

@@ -0,0 +1 @@
+__version__ = "1.2.0.dev182094932"

{braindecode-1.1.1.dev183425073 → braindecode-1.2.0.dev182094932}/braindecode/visualization/gradients.py

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

{braindecode-1.1.1.dev183425073 → braindecode-1.2.0.dev182094932/braindecode.egg-info}/PKG-INFO

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

{braindecode-1.1.1.dev183425073 → braindecode-1.2.0.dev182094932}/docs/conf.py

@@ -166,6 +166,9 @@ templates_path = ["_templates"]
 # source_suffix = ['.rst', '.md']
 source_suffix = ".rst"
 
+rst_prolog = """
+.. role:: tag(bdg-success)
+"""
 # The master toctree document.
 master_doc = "index"
 

{braindecode-1.1.1.dev183425073 → braindecode-1.2.0.dev182094932}/docs/whats_new.rst

@@ -22,6 +22,11 @@ Current 1.2 (dev)
 
 Enhancements
 ~~~~~~~~~~~~
+- Improving the docstring for :class:`braindecode.models.EEGNetv4`  (:gh:`768` by `Bruno Aristimunha`_)
+
+
+API changes
+~~~~~~~~~~~
 
 Bugs
 ~~~~

braindecode-1.1.1.dev183425073/braindecode/version.py

@@ -1 +0,0 @@
-__version__ = "1.1.1.dev183425073"