braindecode 1.6.0.dev1024__tar.gz → 1.6.1.dev1014__tar.gz

{braindecode-1.6.0.dev1024/braindecode.egg-info → braindecode-1.6.1.dev1014}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.6.0.dev1024
+Version: 1.6.1.dev1014
 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.0.dev1024 → braindecode-1.6.1.dev1014}/braindecode/datasets/bids/hub.py

@@ -327,6 +327,7 @@ class HubDatasetMixin:
 
         n_recordings = len(self.datasets)
         first_ds = self.datasets[0]
+        descriptions = [ds.description for ds in self.datasets]
 
         # Get dataset-specific info based on type using registry
         dataset_type = get_dataset_type(first_ds)
@@ -358,6 +359,9 @@ class HubDatasetMixin:
             raise TypeError(f"Unsupported dataset type: {dataset_type}")
 
         # Create README content and save
+        license_value, license_needs_update = _infer_license_from_descriptions(
+            descriptions
+        )
         readme_content = _generate_readme_content(
             format_info=format_info,
             n_recordings=n_recordings,
@@ -366,6 +370,8 @@ class HubDatasetMixin:
             data_type=data_type,
             n_windows=n_windows,
             total_duration=total_duration,
+            license=license_value,
+            license_needs_update=license_needs_update,
         )
 
         # Save README
@@ -466,6 +472,7 @@ class HubDatasetMixin:
         token: Optional[str] = None,
         cache_dir: Optional[Union[str, Path]] = None,
         force_download: bool = False,
+        revision: str | None = None,
         **kwargs,
     ):
         """
@@ -485,6 +492,9 @@ class HubDatasetMixin:
             cache directory (~/.cache/huggingface/datasets).
         force_download : bool, default=False
             Whether to force re-download even if cached.
+        revision : str | None, default=None
+            Specific branch, tag, or commit to download. If None, uses the
+            repository's default revision.
         **kwargs
             Additional arguments (currently unused).
 
@@ -526,6 +536,7 @@ class HubDatasetMixin:
                 token=token,
                 cache_dir=cache_dir,
                 force_download=force_download,
+                revision=revision,
             )
 
             # Load format info
@@ -962,6 +973,8 @@ def _generate_readme_content(
     n_windows: int,
     total_duration: float | None = None,
     format: str = "zarr",
+    license: str = "please-specify",
+    license_needs_update: bool = True,
 ):
     """Generate README.md content for a dataset uploaded to the Hub.
 
@@ -983,6 +996,10 @@ def _generate_readme_content(
         Total duration in seconds across all recordings.
     format : str
         Storage format (default: "zarr").
+    license : str
+        Dataset license string to write in YAML front matter.
+    license_needs_update : bool
+        Whether to append a reminder comment next to the license field.
 
     Returns
     -------
@@ -998,6 +1015,10 @@ def _generate_readme_content(
         str(timedelta(seconds=int(total_duration))) if total_duration else "N/A"
     )
 
+    license_line = f"license: {license}"
+    if license_needs_update:
+        license_line += "  # Please update this field to reflect your dataset's license"
+
     return f"""---
 tags:
 - braindecode
@@ -1005,7 +1026,7 @@ tags:
 - neuroscience
 - brain-computer-interface
 - deep-learning
-license: unknown
+{license_line}
 ---
 
 # EEG Dataset
@@ -1101,3 +1122,27 @@ if hasattr(dataset.datasets[0], "bids_channels"):
 
 *Created with [braindecode](https://braindecode.org)*
 """
+
+
+def _infer_license_from_descriptions(
+    descriptions: list[pd.Series | None],
+) -> tuple[str, bool]:
+    """Infer a single dataset license from descriptions.
+
+    Returns inferred license and whether a manual update reminder is needed.
+    """
+    licenses = set()
+    for description in descriptions:
+        if description is None:
+            continue
+        raw_license = description.get("license", None)
+        if raw_license is None:
+            continue
+        normalized = str(raw_license).strip()
+        if normalized and normalized.lower() != "nan":
+            licenses.add(normalized)
+
+    if len(licenses) == 1:
+        return next(iter(licenses)), False
+
+    return "please-specify", True

{braindecode-1.6.0.dev1024 → braindecode-1.6.1.dev1014}/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.0.dev1024 → braindecode-1.6.1.dev1014}/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.0.dev1024 → braindecode-1.6.1.dev1014}/braindecode/models/__init__.py

@@ -15,13 +15,14 @@ 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
+from .eegpt import EEGPT, InterpolatedEEGPT
 from .eegsimpleconv import EEGSimpleConv
 from .eegsym import EEGSym
 from .eegtcnet import EEGTCNet
@@ -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,13 +86,14 @@ __all__ = [
     "DeepSleepNet",
     "BrainModule",
     "EEGConformer",
+    "EEGDINO",
     "EEGPT",
+    "InterpolatedEEGPT",
     "EEGInceptionERP",
     "EEGInceptionMI",
     "EEGITNet",
     "EEGMiner",
     "EEGNet",
-    "EEGNetv4",
     "EEGNeX",
     "EEGSym",
     "EEGSimpleConv",
@@ -128,6 +131,7 @@ __all__ = [
     "SPARCNet",
     "SyncNet",
     "BDTCN",
+    "TCFormer",
     "TCN",
     "TIDNet",
     "TSception",

{braindecode-1.6.0.dev1024 → braindecode-1.6.1.dev1014}/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.0.dev1024 → braindecode-1.6.1.dev1014}/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

{braindecode-1.6.0.dev1024 → braindecode-1.6.1.dev1014}/braindecode/models/contrawr.py

@@ -5,6 +5,7 @@ import torch.nn as nn
 from mne.utils import warn
 
 from braindecode.models.base import EEGModuleMixin
+from braindecode.models.util import _disable_batch_norm_training_if_batch_size_one
 
 
 class ContraWR(EEGModuleMixin, nn.Module):
@@ -122,6 +123,7 @@ class ContraWR(EEGModuleMixin, nn.Module):
         self.activation_layer = activation()
         self.final_layer = nn.Linear(emb_size, self.n_outputs)
 
+    @_disable_batch_norm_training_if_batch_size_one
     def forward(self, X: torch.Tensor) -> torch.Tensor:
         """
         Forward pass.

{braindecode-1.6.0.dev1024 → braindecode-1.6.1.dev1014}/braindecode/models/deepsleepnet.py

@@ -7,6 +7,7 @@ import torch.nn as nn
 from einops.layers.torch import Rearrange
 
 from braindecode.models.base import EEGModuleMixin
+from braindecode.models.util import _disable_batch_norm_training_if_batch_size_one
 
 
 class DeepSleepNet(EEGModuleMixin, nn.Module):
@@ -289,6 +290,7 @@ class DeepSleepNet(EEGModuleMixin, nn.Module):
             else nn.Linear(fc_out_features, self.n_outputs)
         )
 
+    @_disable_batch_norm_training_if_batch_size_one
     def forward(self, x):
         if x.ndim == 3:
             x = x.unsqueeze(1)