braindecode 1.6.1.dev1041__tar.gz → 1.6.1.dev1044__tar.gz

{braindecode-1.6.1.dev1041/braindecode.egg-info → braindecode-1.6.1.dev1044}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.6.1.dev1041
+Version: 1.6.1.dev1044
 Summary: Deep learning software to decode EEG, ECG or MEG signals
 Author-email: Robin Tibor Schirrmeister <robintibor@gmail.com>, Bruno Aristimunha Pinto <b.aristimunha@gmail.com>, Alexandre Gramfort <agramfort@meta.com>
 Maintainer-email: Alexandre Gramfort <agramfort@meta.com>, Bruno Aristimunha Pinto <b.aristimunha@gmail.com>, Robin Tibor Schirrmeister <robintibor@gmail.com>
@@ -46,7 +46,7 @@ Requires-Dist: zarr>=3.0; extra == "hub"
 Provides-Extra: viz
 Requires-Dist: captum>=0.7.0; extra == "viz"
 Provides-Extra: tests
-Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest<9.1; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
 Requires-Dist: codecov; extra == "tests"
 Requires-Dist: pytest_cases; extra == "tests"

{braindecode-1.6.1.dev1041 → braindecode-1.6.1.dev1044}/braindecode/datasets/moabb.py

@@ -15,7 +15,6 @@ from typing import Any
 
 import mne
 import pandas as pd
-from mne.utils import deprecated
 
 from braindecode.util import _update_moabb_docstring
 
@@ -208,12 +207,3 @@ class HGD(MOABBDataset):
 
     def __init__(self, subject_ids):
         super().__init__("Schirrmeister2017", subject_ids=subject_ids)
-
-
-@deprecated(
-    "`BNCI2014001` was renamed to `BNCI2014_001` in v1.13; this alias will be removed in v1.14."
-)
-class BNCI2014001(BNCI2014_001):
-    """Deprecated alias for BNCI2014001."""
-
-    pass

{braindecode-1.6.1.dev1041 → braindecode-1.6.1.dev1044}/braindecode/eegneuralnet.py

@@ -7,6 +7,7 @@
 import abc
 import inspect
 import logging
+import warnings
 from typing import Literal
 
 import mne
@@ -41,6 +42,7 @@ def _get_model(model: str):
 
 class _EEGNeuralNet(NeuralNet, abc.ABC):
     signal_args_set_ = False
+    _warned_drop_last_ = False
 
     @property
     def log(self):
@@ -267,6 +269,44 @@ class _EEGNeuralNet(NeuralNet, abc.ABC):
             X = X.get_data(units="uV")
         return super().get_dataset(X, y)
 
+    def get_iterator(self, dataset, training=False):
+        iterator = super().get_iterator(dataset, training=training)
+        # Warn (once per fit) if drop_last would discard every training batch,
+        # e.g. a training set smaller than batch_size. This silently skips
+        # training without raising any error, which is hard to diagnose.
+        if training and not self._warned_drop_last_:
+            self._warn_if_training_batches_dropped(iterator)
+        return iterator
+
+    def _warn_if_training_batches_dropped(self, loader):
+        """Warn if ``drop_last`` discards all training batches.
+
+        With ``iterator_train__drop_last=True`` (the braindecode default), a
+        training set smaller than ``batch_size`` yields zero batches, so no
+        forward/backward pass runs and the model is left untrained without any
+        error. We inspect the resolved training ``DataLoader`` (after
+        ``train_split`` has been applied), so the count reflects the actual
+        number of training examples.
+        """
+        self._warned_drop_last_ = True
+        if not getattr(loader, "drop_last", False):
+            return
+        batch_size = getattr(loader, "batch_size", None)
+        try:
+            n_train = len(loader.dataset)
+        except TypeError:
+            return  # e.g. an IterableDataset whose length is unknown
+        if not batch_size or n_train == 0 or n_train >= batch_size:
+            return
+        warnings.warn(
+            f"The training set has {n_train} example(s), which is smaller than "
+            f"batch_size={batch_size}. With iterator_train__drop_last=True "
+            f"(the braindecode default), all training batches are dropped and "
+            f"the model is not trained. Reduce batch_size to at most {n_train}, "
+            f"or pass iterator_train__drop_last=False.",
+            UserWarning,
+        )
+
     def partial_fit(self, X, y=None, classes=None, **fit_params):
         """Fit the module.
 
@@ -366,6 +406,7 @@ class _EEGNeuralNet(NeuralNet, abc.ABC):
           the module and to the ``self.train_split`` call.
         """
         # this needs to be executed before the net is initialized:
+        self._warned_drop_last_ = False  # re-check on every fresh fit
         if not self.signal_args_set_:
             self._set_signal_args(X, y, classes=None)
             self.signal_args_set_ = True

{braindecode-1.6.1.dev1041 → braindecode-1.6.1.dev1044}/braindecode/models/__init__.py

@@ -15,11 +15,12 @@ from .deep4 import Deep4Net
 from .deepsleepnet import DeepSleepNet
 from .dgcnn import DGCNN
 from .eegconformer import EEGConformer
+from .eegdino import EEGDINO
 from .eeginception_erp import EEGInceptionERP
 from .eeginception_mi import EEGInceptionMI
 from .eegitnet import EEGITNet
 from .eegminer import EEGMiner
-from .eegnet import EEGNet, EEGNetv4
+from .eegnet import EEGNet
 from .eegnex import EEGNeX
 from .eegpt import EEGPT, InterpolatedEEGPT
 from .eegsimpleconv import EEGSimpleConv
@@ -54,6 +55,7 @@ from .sleep_stager_chambon_2018 import SleepStagerChambon2018
 from .sparcnet import SPARCNet
 from .sstdpn import SSTDPN
 from .syncnet import SyncNet
+from .tcformer import TCFormer
 from .tcn import BDTCN, TCN
 from .tidnet import TIDNet
 from .tsinception import TSception
@@ -84,6 +86,7 @@ __all__ = [
     "DeepSleepNet",
     "BrainModule",
     "EEGConformer",
+    "EEGDINO",
     "EEGPT",
     "InterpolatedEEGPT",
     "EEGInceptionERP",
@@ -91,7 +94,6 @@ __all__ = [
     "EEGITNet",
     "EEGMiner",
     "EEGNet",
-    "EEGNetv4",
     "EEGNeX",
     "EEGSym",
     "EEGSimpleConv",
@@ -129,6 +131,7 @@ __all__ = [
     "SPARCNet",
     "SyncNet",
     "BDTCN",
+    "TCFormer",
     "TCN",
     "TIDNet",
     "TSception",

{braindecode-1.6.1.dev1041 → braindecode-1.6.1.dev1044}/braindecode/models/atcnet.py

@@ -2,14 +2,21 @@
 #
 # License: BSD (3-clause)
 import math
+from typing import Optional
 
 import torch
 from einops.layers.torch import Rearrange
 from mne.utils import warn
 from torch import nn
+from torch.nn.utils.parametrize import is_parametrized, register_parametrization
 
 from braindecode.models.base import EEGModuleMixin
-from braindecode.modules import CausalConv1d, Ensure4d, MaxNormLinear
+from braindecode.modules import (
+    CausalConv1d,
+    Ensure4d,
+    MaxNormLinear,
+    MaxNormParametrize,
+)
 
 
 class ATCNet(EEGModuleMixin, nn.Module):
@@ -213,6 +220,16 @@ class ATCNet(EEGModuleMixin, nn.Module):
     max_norm_const : float
         Maximum L2-norm constraint imposed on weights of the last
         fully-connected layer. Defaults to 0.25.
+    conv_max_norm_const : float | None
+        If not ``None``, applies a max-norm constraint (via a weight
+        parametrization) to the convolution kernels of :class:`_ConvBlock` and
+        :class:`_TCNResidualBlock`, matching the official implementation which
+        uses ``0.6``. When ``None`` (default), no constraint is applied to those
+        layers, preserving the previous behavior. The complementary ``L2``
+        weight decay of the official code can be obtained from
+        :meth:`source_optimizer_param_groups`.
+
+        .. versionadded:: 1.6.1
 
     Notes
     -----
@@ -257,6 +274,7 @@ class ATCNet(EEGModuleMixin, nn.Module):
         tcn_activation: type[nn.Module] = nn.ELU,
         concat=False,
         max_norm_const=0.25,
+        conv_max_norm_const: Optional[float] = None,
         chs_info=None,
         n_times=None,
     ):
@@ -325,6 +343,7 @@ class ATCNet(EEGModuleMixin, nn.Module):
         self.tcn_activation = tcn_activation
         self.concat = concat
         self.max_norm_const = max_norm_const
+        self.conv_max_norm_const = conv_max_norm_const
         self.tcn_n_filters = int(self.conv_block_depth_mult * self.conv_block_n_filters)
         map = dict()
         for w in range(self.n_windows):
@@ -346,6 +365,7 @@ class ATCNet(EEGModuleMixin, nn.Module):
             pool_size_2=conv_block_pool_size_2,
             depth_mult=conv_block_depth_mult,
             dropout=conv_block_dropout,
+            conv_max_norm=self.conv_max_norm_const,
         )
 
         self.F2 = int(conv_block_depth_mult * conv_block_n_filters)
@@ -375,6 +395,7 @@ class ATCNet(EEGModuleMixin, nn.Module):
                             dropout=self.tcn_dropout,
                             activation=self.tcn_activation,
                             dilation=2**i,
+                            conv_max_norm=self.conv_max_norm_const,
                         )
                         for i in range(self.tcn_depth)
                     ]
@@ -458,6 +479,93 @@ class ATCNet(EEGModuleMixin, nn.Module):
 
         return self.out_fun(sw_concat_agg)
 
+    def source_optimizer_param_groups(
+        self,
+        conv_weight_decay: float = 0.009,
+        dense_weight_decay: float = 0.5,
+    ) -> list[dict]:
+        r"""Source-faithful optimizer parameter groups for ATCNet.
+
+        The official Keras implementation applies ``L2`` weight decay only to the
+        convolution / TCN kernels (``conv_weightDecay = 0.009``) and to the final
+        dense layer (``dense_weightDecay = 0.5``); biases, BatchNorm and attention
+        weights are left undecayed. This reproduces the Keras ``L2`` kernel penalty
+        only for optimizers that implement ``weight_decay`` as a coupled L2 term,
+        e.g. :class:`torch.optim.SGD` or :class:`torch.optim.Adam` (as used by the
+        official code). For decoupled-weight-decay optimizers such as
+        :class:`torch.optim.AdamW`, ``weight_decay`` is *not* equivalent to a Keras
+        ``L2`` penalty.
+
+        Parameters
+        ----------
+        conv_weight_decay : float
+            Weight decay applied to the convolution and TCN kernels. Defaults to
+            ``0.009`` as in the official code.
+        dense_weight_decay : float
+            Weight decay applied to the final (dense) layer weights. Defaults to
+            ``0.5`` as in the official code.
+
+        Returns
+        -------
+        list of dict
+            Parameter groups ready to be passed to a ``torch.optim`` optimizer:
+            convolution/TCN kernels, final dense weights, and everything else
+            (no decay).
+
+        Examples
+        --------
+        >>> model = ATCNet(n_chans=22, n_outputs=4, n_times=1125)  # doctest: +SKIP
+        >>> opt = torch.optim.Adam(model.source_optimizer_param_groups())  # doctest: +SKIP
+        """
+
+        def weight_leaf(module):
+            # Return the leaf weight Parameter, accounting for a registered
+            # max-norm parametrization (``conv_max_norm_const`` / MaxNormLinear).
+            if is_parametrized(module, "weight"):
+                return module.parametrizations.weight.original
+            return module.weight
+
+        conv_weights: list[nn.Parameter] = []
+        dense_weights: list[nn.Parameter] = []
+        decayed_ids: set[int] = set()
+
+        # Convolution / TCN kernels (Keras L2 = 0.009).
+        for parent in (self.conv_block, self.temporal_conv_nets):
+            for module in parent.modules():
+                if isinstance(module, (nn.Conv1d, nn.Conv2d)):
+                    weight = weight_leaf(module)
+                    conv_weights.append(weight)
+                    decayed_ids.add(id(weight))
+
+        # Final dense / readout weights (Keras L2 = 0.5).
+        for module in self.final_layer.modules():
+            if isinstance(module, nn.Linear):
+                weight = weight_leaf(module)
+                dense_weights.append(weight)
+                decayed_ids.add(id(weight))
+
+        # Everything else (biases, BatchNorm, attention) is left undecayed.
+        other = [p for p in self.parameters() if id(p) not in decayed_ids]
+
+        return [
+            {"params": conv_weights, "weight_decay": conv_weight_decay},
+            {"params": dense_weights, "weight_decay": dense_weight_decay},
+            {"params": other, "weight_decay": 0.0},
+        ]
+
+
+def _register_max_norm(max_norm, *convs):
+    """Register a max-norm weight parametrization on each given convolution.
+
+    No-op when ``max_norm`` is ``None`` or a passed layer is not a convolution
+    (e.g. an ``nn.Identity`` residual shortcut).
+    """
+    if max_norm is None:
+        return
+    for conv in convs:
+        if isinstance(conv, (nn.Conv1d, nn.Conv2d)):
+            register_parametrization(conv, "weight", MaxNormParametrize(max_norm))
+
 
 class _ConvBlock(nn.Module):
     r"""Convolutional block proposed in ATCNet [1]_, inspired by the EEGNet.
@@ -487,6 +595,7 @@ class _ConvBlock(nn.Module):
         pool_size_2=7,
         depth_mult=2,
         dropout=0.3,
+        conv_max_norm: Optional[float] = None,
     ):
         super().__init__()
 
@@ -534,6 +643,9 @@ class _ConvBlock(nn.Module):
 
         self.drop3 = nn.Dropout2d(dropout)
 
+        # Optional source-faithful max-norm constraint on the conv kernels.
+        _register_max_norm(conv_max_norm, self.conv1, self.conv2, self.conv3)
+
     def forward(self, X):
         # ----- Temporal convolution -----
         # Dimension: (batch_size, 1, T, C)
@@ -662,6 +774,7 @@ class _TCNResidualBlock(nn.Module):
         dropout=0.3,
         activation: type[nn.Module] = nn.ELU,
         dilation=1,
+        conv_max_norm: Optional[float] = None,
     ):
         super().__init__()
         self.activation = activation()
@@ -706,6 +819,10 @@ class _TCNResidualBlock(nn.Module):
         else:
             self.reshaping_conv = nn.Identity()
 
+        # Optional source-faithful max-norm constraint on the conv kernels
+        # (reshaping_conv may be nn.Identity, which the helper skips).
+        _register_max_norm(conv_max_norm, self.conv1, self.conv2, self.reshaping_conv)
+
     def forward(self, X):
         # Dimension: (batch_size, F2, Tw)
         # ----- Double dilated convolutions -----

{braindecode-1.6.1.dev1041 → braindecode-1.6.1.dev1044}/braindecode/models/attn_sleep.py

@@ -8,7 +8,6 @@ from copy import deepcopy
 
 import torch
 import torch.nn.functional as F
-from mne.utils import deprecated
 from torch import nn
 
 from braindecode.models.base import EEGModuleMixin
@@ -538,12 +537,3 @@ class _PositionwiseFeedForward(nn.Module):
     def forward(self, x: torch.Tensor) -> torch.Tensor:
         """Implements FFN equation."""
         return self.w_2(self.dropout(self.activate(self.w_1(x))))
-
-
-@deprecated(
-    "`SleepStagerEldele2021` was renamed to `AttnSleep` in v1.12 to follow original author's name; this alias will be removed in v1.14."
-)
-class SleepStagerEldele2021(AttnSleep):
-    r"""Deprecated alias for SleepStagerEldele2021."""
-
-    pass