braindecode 1.3.0.dev177069446__py3-none-any.whl → 1.3.0.dev177628147__py3-none-any.whl

braindecode/datautil/util.py

@@ -2,19 +2,6 @@
 #
 # License: BSD (3-clause)
 
-import logging
-from typing import Any, Literal
-
-import mne
-import numpy as np
-from skorch.helper import SliceDataset
-from skorch.utils import is_dataset
-
-from braindecode.datasets.base import BaseConcatDataset, WindowsDataset
-from braindecode.models.util import SigArgName
-
-log = logging.getLogger(__name__)
-
 
 def ms_to_samples(ms, fs):
     """
@@ -22,15 +9,16 @@ def ms_to_samples(ms, fs):
 
     Parameters
     ----------
-    ms : number
+    ms: number
         Milliseconds
-    fs : number
+    fs: number
         Sampling rate
 
     Returns
     -------
-    n_samples : int
+    n_samples: int
         Number of samples
+
     """
     return ms * fs / 1000.0
 
@@ -41,114 +29,13 @@ def samples_to_ms(n_samples, fs):
 
     Parameters
     ----------
-    n_samples : number
+    n_samples: number
         Number of samples
-    fs : number
+    fs: number
         Sampling rate
 
     Returns
     -------
-    milliseconds : int
+    milliseconds: int
     """
     return n_samples * 1000.0 / fs
-
-
-def _get_n_outputs(y, classes, mode):
-    if mode == "classification":
-        classes_y = np.unique(y)
-        if classes is not None:
-            assert set(classes_y) <= set(classes)
-        else:
-            classes = classes_y
-        return len(classes)
-    elif mode == "regression":
-        if y is None:
-            return None
-        if y.ndim == 1:
-            return 1
-        else:
-            return y.shape[-1]
-    else:
-        raise ValueError(f"Unknown mode {mode}")
-
-
-def infer_signal_properties(
-    X,
-    y=None,
-    mode: Literal["classification", "regression"] = "classification",
-    classes: list | None = None,
-) -> dict[SigArgName, Any]:
-    """Infers signal properties from the data.
-
-    The extracted signal properties are:
-
-    + n_chans: number of channels
-    + n_times: number of time points
-    + n_outputs: number of outputs
-    + chs_info: channel information
-    + sfreq: sampling frequency
-
-    The returned dictionary can serve as kwargs for model initialization.
-
-    Depending on the type of input passed, not all properties can be inferred.
-
-    Parameters
-    ----------
-    X : array-like or mne.BaseEpochs or Dataset
-        Input data
-    y : array-like or None
-        Targets
-    mode : "classification" or "regression"
-        Mode of the task
-    classes : list or None
-        List of classes for classification
-
-    Returns
-    -------
-    signal_kwargs : dict
-        Dictionary with signal-properties. Can serve as kwargs for model
-        initialization.
-    """
-    signal_kwargs: dict[SigArgName, Any] = {}
-    # Using shape to work both with torch.tensor and numpy.array:
-    if (
-        isinstance(X, mne.BaseEpochs)
-        or (hasattr(X, "shape") and len(X.shape) >= 2)
-        or isinstance(X, SliceDataset)
-    ):
-        if y is None:
-            raise ValueError("y must be specified if X is array-like.")
-        signal_kwargs["n_outputs"] = _get_n_outputs(y, classes, mode)
-        if isinstance(X, mne.BaseEpochs):
-            log.info("Using mne.Epochs to find signal-related parameters.")
-            signal_kwargs["n_times"] = len(X.times)
-            signal_kwargs["sfreq"] = X.info["sfreq"]
-            signal_kwargs["chs_info"] = X.info["chs"]
-        elif isinstance(X, SliceDataset):
-            log.info("Using SliceDataset to find signal-related parameters.")
-            Xshape = X[0].shape
-            signal_kwargs["n_times"] = Xshape[-1]
-            signal_kwargs["n_chans"] = Xshape[-2]
-        else:
-            log.info("Using array-like to find signal-related parameters.")
-            signal_kwargs["n_times"] = X.shape[-1]
-            signal_kwargs["n_chans"] = X.shape[-2]
-    elif is_dataset(X):
-        log.info(f"Using Dataset {X!r} to find signal-related parameters.")
-        X0 = X[0][0]
-        Xshape = X0.shape
-        signal_kwargs["n_times"] = Xshape[-1]
-        signal_kwargs["n_chans"] = Xshape[-2]
-        if isinstance(X, BaseConcatDataset) and all(
-            ds.targets_from == "metadata" for ds in X.datasets
-        ):
-            y_target = X.get_metadata().target
-            signal_kwargs["n_outputs"] = _get_n_outputs(y_target, classes, mode)
-        elif isinstance(X, WindowsDataset) and X.targets_from == "metadata":
-            y_target = X.windows.metadata.target
-            signal_kwargs["n_outputs"] = _get_n_outputs(y_target, classes, mode)
-    else:
-        log.warning(
-            f"Can only infer signal shape of array-like and Datasets, got {type(X)!r}."
-        )
-    return signal_kwargs

braindecode/eegneuralnet.py

@@ -7,7 +7,6 @@
 import abc
 import inspect
 import logging
-from typing import Literal
 
 import mne
 import numpy as np
@@ -15,10 +14,10 @@ import torch
 from sklearn.metrics import get_scorer
 from skorch import NeuralNet
 from skorch.callbacks import BatchScoring, EpochScoring, EpochTimer, PrintLog
-from skorch.utils import noop, to_numpy, train_loss_score, valid_loss_score
-
-from braindecode.datautil import infer_signal_properties
+from skorch.helper import SliceDataset
+from skorch.utils import is_dataset, noop, to_numpy, train_loss_score, valid_loss_score
 
+from .datasets.base import BaseConcatDataset, WindowsDataset
 from .models.util import models_dict
 from .training.scoring import (
     CroppedTimeSeriesEpochScoring,
@@ -53,6 +52,7 @@ class _EEGNeuralNet(NeuralNet, abc.ABC):
 
         If the module is already initialized and no parameter was changed, it
         will be left as is.
+
         """
         kwargs = self.get_params_for("module")
         module = _get_model(self.module)
@@ -174,9 +174,8 @@ class _EEGNeuralNet(NeuralNet, abc.ABC):
             ("print_log", PrintLog()),
         ]
 
-    @property
     @abc.abstractmethod
-    def mode(self) -> Literal["classification", "regression"]:
+    def _get_n_outputs(self, y, classes):
         pass
 
     def _set_signal_args(self, X, y, classes):
@@ -192,8 +191,50 @@ class _EEGNeuralNet(NeuralNet, abc.ABC):
             return
         if classes is None:
             classes = getattr(self, "classes", None)
-        signal_kwargs = infer_signal_properties(X, y, mode=self.mode, classes=classes)
-        if not signal_kwargs:
+        # get kwargs from signal:
+        signal_kwargs = dict()
+        # Using shape to work both with torch.tensor and numpy.array:
+        if (
+            isinstance(X, mne.BaseEpochs)
+            or (hasattr(X, "shape") and len(X.shape) >= 2)
+            or isinstance(X, SliceDataset)
+        ):
+            if y is None:
+                raise ValueError("y must be specified if X is array-like.")
+            signal_kwargs["n_outputs"] = self._get_n_outputs(y, classes)
+            if isinstance(X, mne.BaseEpochs):
+                self.log.info("Using mne.Epochs to find signal-related parameters.")
+                signal_kwargs["n_times"] = len(X.times)
+                signal_kwargs["sfreq"] = X.info["sfreq"]
+                signal_kwargs["chs_info"] = X.info["chs"]
+            elif isinstance(X, SliceDataset):
+                self.log.info("Using SliceDataset to find signal-related parameters.")
+                Xshape = X[0].shape
+                signal_kwargs["n_times"] = Xshape[-1]
+                signal_kwargs["n_chans"] = Xshape[-2]
+            else:
+                self.log.info("Using array-like to find signal-related parameters.")
+                signal_kwargs["n_times"] = X.shape[-1]
+                signal_kwargs["n_chans"] = X.shape[-2]
+        elif is_dataset(X):
+            self.log.info(f"Using Dataset {X!r} to find signal-related parameters.")
+            X0 = X[0][0]
+            Xshape = X0.shape
+            signal_kwargs["n_times"] = Xshape[-1]
+            signal_kwargs["n_chans"] = Xshape[-2]
+            if isinstance(X, BaseConcatDataset) and all(
+                ds.targets_from == "metadata" for ds in X.datasets
+            ):
+                y_target = X.get_metadata().target
+                signal_kwargs["n_outputs"] = self._get_n_outputs(y_target, classes)
+            elif isinstance(X, WindowsDataset) and X.targets_from == "metadata":
+                y_target = X.windows.metadata.target
+                signal_kwargs["n_outputs"] = self._get_n_outputs(y_target, classes)
+        else:
+            self.log.warning(
+                "Can only infer signal shape of array-like and Datasets, "
+                f"got {type(X)!r}."
+            )
             return
 
         # kick out missing kwargs:
@@ -208,18 +249,6 @@ class _EEGNeuralNet(NeuralNet, abc.ABC):
             else:
                 self.log.warning(f"Module {self.module!r} is missing parameter {k!r}.")
 
-        # kick out inferred signal kwargs if user specifies kwargs:
-        user_specified_kwargs = self.get_params_for("module").items()
-        if len(user_specified_kwargs) > 0:
-            self.log.info(
-                f"Overriding inferred parameters with user "
-                f"specified parameters{user_specified_kwargs!r}."
-            )
-            for k, v in self.get_params_for("module").items():
-                if k in module_kwargs:
-                    module_kwargs.pop(k)
-                    module_kwargs[k] = v
-
         # save kwargs to self:
         self.log.info(
             f"Passing additional parameters {module_kwargs!r} "
@@ -229,8 +258,7 @@ class _EEGNeuralNet(NeuralNet, abc.ABC):
         self.set_params(**module_kwargs)
 
     def get_dataset(self, X, y=None):
-        """Get a dataset that contains the input data and is passed to.
-
+        """Get a dataset that contains the input data and is passed to
         the iterator.
 
         Override this if you want to initialize your dataset
@@ -262,6 +290,7 @@ class _EEGNeuralNet(NeuralNet, abc.ABC):
         -------
         dataset
           The initialized dataset.
+
         """
         if isinstance(X, mne.BaseEpochs):
             X = X.get_data(units="uV")
@@ -314,6 +343,7 @@ class _EEGNeuralNet(NeuralNet, abc.ABC):
         **fit_params : dict
           Additional parameters passed to the ``forward`` method of
           the module and to the ``self.train_split`` call.
+
         """
         # this needs to be executed before the net is initialized:
         if not self.signal_args_set_:

braindecode/functional/functions.py

@@ -24,13 +24,14 @@ def drop_path(
 ):
     """Drop paths (Stochastic Depth) per sample.
 
+
     Notes: This implementation is taken from timm library.
 
     All credit goes to Ross Wightman.
 
     Parameters
     ----------
-    x : torch.Tensor
+    x: torch.Tensor
         input tensor
     drop_prob : float, optional
         survival rate (i.e. probability of being kept), by default 0.0
@@ -50,10 +51,11 @@ def drop_path(
     etc. networks, however,
     the original name is misleading as 'Drop Connect' is a different form
     of dropout in a separate paper...
-    See discussion : https://github.com/tensorflow/tpu/issues/494#issuecomment-532968956
+    See discussion: https://github.com/tensorflow/tpu/issues/494#issuecomment-532968956
     ... I've opted for changing the layer and argument names to 'drop path'
     rather than mix DropConnect as a layer name and use
     'survival rate' as the argument.
+
     """
     if drop_prob == 0.0 or not training:
         return x
@@ -69,8 +71,7 @@ def drop_path(
 
 def _get_gaussian_kernel1d(kernel_size: int, sigma: float) -> torch.Tensor:
     """
-    Generates a 1-dimensional Gaussian kernel based on the specified kernel.
-
+    Generates a 1-dimensional Gaussian kernel based on the specified kernel
     size and standard deviation (sigma).
     This kernel is useful for Gaussian smoothing or filtering operations in
     image processing. The function calculates a range limit to ensure the kernel
@@ -79,14 +80,15 @@ def _get_gaussian_kernel1d(kernel_size: int, sigma: float) -> torch.Tensor:
     Gaussian curve, normalized using a softmax function
     to ensure all weights sum to 1.
 
+
     Parameters
     ----------
-    kernel_size : int
-    sigma : float
+    kernel_size: int
+    sigma: float
 
     Returns
     -------
-    kernel1d : torch.Tensor
+    kernel1d: torch.Tensor
 
     Notes
     -----
@@ -95,6 +97,7 @@ def _get_gaussian_kernel1d(kernel_size: int, sigma: float) -> torch.Tensor:
     All rights reserved.
 
     LICENSE in https://github.com/pytorch/vision/blob/main/LICENSE
+
     """
     ksize_half = (kernel_size - 1) * 0.5
     x = torch.linspace(-ksize_half, ksize_half, steps=kernel_size)

braindecode/functional/initialization.py

@@ -4,14 +4,13 @@ from torch import nn
 
 
 def glorot_weight_zero_bias(model):
-    """Initialize parameters of all modules by initializing weights with.
-
+    """Initialize parameters of all modules by initializing weights with
     glorot uniform/xavier initialization, and setting biases to zero. Weights from
     batch norm layers are set to 1.
 
     Parameters
     ----------
-    model : Module
+    model: Module
     """
     for module in model.modules():
         if hasattr(module, "weight"):

braindecode/models/__init__.py

@@ -1,4 +1,6 @@
-"""Some predefined network architectures for EEG decoding."""
+"""
+Some predefined network architectures for EEG decoding.
+"""
 
 from .atcnet import ATCNet
 from .attentionbasenet import AttentionBaseNet
@@ -6,7 +8,6 @@ from .attn_sleep import AttnSleep
 from .base import EEGModuleMixin
 from .bendr import BENDR
 from .biot import BIOT
-from .brainmodule import BrainModule
 from .contrawr import ContraWR
 from .ctnet import CTNet
 from .deep4 import Deep4Net
@@ -31,7 +32,6 @@ from .luna import LUNA
 from .medformer import MEDFormer
 from .msvtnet import MSVTNet
 from .patchedtransformer import PBT
-from .reve import REVE
 from .sccnet import SCCNet
 from .shallow_fbcsp import ShallowFBCSPNet
 from .signal_jepa import (
@@ -71,7 +71,6 @@ __all__ = [
     "CTNet",
     "Deep4Net",
     "DeepSleepNet",
-    "BrainModule",
     "EEGConformer",
     "EEGInceptionERP",
     "EEGInceptionMI",
@@ -94,7 +93,6 @@ __all__ = [
     "MEDFormer",
     "MSVTNet",
     "PBT",
-    "REVE",
     "SCCNet",
     "ShallowFBCSPNet",
     "SignalJEPA",

braindecode/models/atcnet.py

@@ -13,9 +13,9 @@ from braindecode.modules import CausalConv1d, Ensure4d, MaxNormLinear
 
 
 class ATCNet(EEGModuleMixin, nn.Module):
-    r"""ATCNet from Altaheri et al   (2022) [1]_.
+    """ATCNet from Altaheri et al. (2022) [1]_.
 
-    :bdg-success:`Convolution` :bdg-secondary:`Recurrent` :bdg-info:`Attention/Transformer`
+    :bdg-success:`Convolution` :bdg-secondary:`Recurrent` :bdg-info:`Small Attention`
 
     .. figure:: https://user-images.githubusercontent.com/25565236/185449791-e8539453-d4fa-41e1-865a-2cf7e91f60ef.png
         :align: center
@@ -83,8 +83,7 @@ class ATCNet(EEGModuleMixin, nn.Module):
 
     - :class:`_TCNResidualBlock` **(causal dilated temporal CNN)**
 
-        *Operations:*
-
+        - *Operations.*
         - Two :class:`braindecode.modules.CausalConv1d` layers per block with dilation  ``1, 2, 4, …``
         - Across blocks of `torch.nn.ELU` + `torch.nn.BatchNorm1d` + `torch.nn.Dropout`) +
           a residual (identity or 1x1 mapping).
@@ -95,12 +94,10 @@ class ATCNet(EEGModuleMixin, nn.Module):
 
     - **Aggregation & Classifier**
 
-        *Operations:*
-
+        - *Operations.*
         - Either (a) map each window feature ``(B, F2)`` to logits via :class:`braindecode.modules.MaxNormLinear`
-          and **average** across windows (default, matching official code), or
+        and **average** across windows (default, matching official code), or
         - (b) **concatenate** all window features ``(B, n·F2)`` and apply a single :class:`MaxNormLinear`.
-
         The max-norm constraint regularizes the readout.
 
     .. rubric:: Convolutional Details
@@ -117,6 +114,7 @@ class ATCNet(EEGModuleMixin, nn.Module):
         producing *per-temporal-filter* spatial projections (no cross-filter mixing at this step).
         This mirrors EEGNet's interpretability: each temporal filter has its own spatial pattern.
 
+
     .. rubric:: Attention / Sequential Modules
 
     - **Type.** Multi-head self-attention with ``H`` heads and per-head dim ``d_h`` implemented
@@ -143,13 +141,26 @@ class ATCNet(EEGModuleMixin, nn.Module):
     - Pool sizes ``P1,P2`` trade temporal resolution for stability/compute; they set
       ``T_c = T/(P1·P2)`` and thus window width ``T_w``.
     - ``n_windows`` controls the ensemble over shifts (compute ∝ windows).
-    - ``num_heads``, ``head_dim`` set attention capacity; keep ``H·d_h ≈ F2``.
+    - ``att_num_heads``, ``att_head_dim`` set attention capacity; keep ``H·d_h ≈ F2``.
     - ``tcn_depth``, ``tcn_kernel_size`` govern receptive field; larger values demand
       longer inputs (see minimum length above). The implementation warns and *rescales*
       kernels/pools/windows if inputs are too short.
     - **Aggregation choice.** ``concat=False`` (default, average of per-window logits) matches
       the official code; ``concat=True`` mirrors the paper's concatenation variant.
 
+
+    Notes
+    -----
+    - Inputs substantially shorter than the implied minimum length trigger **automatic
+      downscaling** of kernels, pools, windows, and TCN kernel size to maintain validity.
+    - The attention–TCN sequence operates **per window**; the last causal step is used as the
+      window feature, aligning the temporal semantics across windows.
+
+    .. versionadded:: 1.1
+
+        - More detailed documentation of the model.
+
+
     Parameters
     ----------
     input_window_seconds : float, optional
@@ -183,10 +194,10 @@ class ATCNet(EEGModuleMixin, nn.Module):
         table 1 of the paper [1]_. Defaults to 0.3 as in [1]_.
     n_windows : int
         Number of sliding windows, denoted n in [1]_. Defaults to 5 as in [1]_.
-    head_dim : int
+    att_head_dim : int
         Embedding dimension used in each self-attention head, denoted dh in
         table 1 of the paper [1]_. Defaults to 8 as in [1]_.
-    num_heads : int
+    att_num_heads : int
         Number of attention heads, denoted H in table 1 of the paper [1]_.
         Defaults to 2 as in [1]_.
     att_dropout : float
@@ -214,17 +225,6 @@ class ATCNet(EEGModuleMixin, nn.Module):
         Maximum L2-norm constraint imposed on weights of the last
         fully-connected layer. Defaults to 0.25.
 
-    Notes
-    -----
-    - Inputs substantially shorter than the implied minimum length trigger **automatic
-      downscaling** of kernels, pools, windows, and TCN kernel size to maintain validity.
-    - The attention–TCN sequence operates **per window**; the last causal step is used as the
-      window feature, aligning the temporal semantics across windows.
-
-    .. versionadded:: 1.1
-
-        - More detailed documentation of the model.
-
     References
     ----------
     .. [1] H. Altaheri, G. Muhammad, M. Alsulaiman (2022).
@@ -248,13 +248,13 @@ class ATCNet(EEGModuleMixin, nn.Module):
         conv_block_depth_mult=2,
         conv_block_dropout=0.3,
         n_windows=5,
-        head_dim=8,
-        num_heads=2,
+        att_head_dim=8,
+        att_num_heads=2,
         att_drop_prob=0.5,
         tcn_depth=2,
         tcn_kernel_size=4,
         tcn_drop_prob=0.3,
-        tcn_activation: type[nn.Module] = nn.ELU,
+        tcn_activation: nn.Module = nn.ELU,
         concat=False,
         max_norm_const=0.25,
         chs_info=None,
@@ -316,8 +316,8 @@ class ATCNet(EEGModuleMixin, nn.Module):
         self.conv_block_depth_mult = conv_block_depth_mult
         self.conv_block_dropout = conv_block_dropout
         self.n_windows = n_windows
-        self.head_dim = head_dim
-        self.num_heads = num_heads
+        self.att_head_dim = att_head_dim
+        self.att_num_heads = att_num_heads
         self.att_dropout = att_drop_prob
         self.tcn_depth = tcn_depth
         self.tcn_kernel_size = tcn_kernel_size
@@ -356,8 +356,8 @@ class ATCNet(EEGModuleMixin, nn.Module):
             [
                 _AttentionBlock(
                     in_shape=self.F2,
-                    head_dim=self.head_dim,
-                    num_heads=num_heads,
+                    head_dim=self.att_head_dim,
+                    num_heads=att_num_heads,
                     dropout=att_drop_prob,
                 )
                 for _ in range(self.n_windows)
@@ -460,8 +460,7 @@ class ATCNet(EEGModuleMixin, nn.Module):
 
 
 class _ConvBlock(nn.Module):
-    r"""Convolutional block proposed in ATCNet [1]_, inspired by the EEGNet.
-
+    """Convolutional block proposed in ATCNet [1]_, inspired by the EEGNet
     architecture [2]_.
 
     References
@@ -563,8 +562,7 @@ class _ConvBlock(nn.Module):
 
 
 class _AttentionBlock(nn.Module):
-    r"""Multi Head self Attention (MHA) block used in ATCNet [1]_, inspired from.
-
+    """Multi Head self Attention (MHA) block used in ATCNet [1]_, inspired from
     [2]_.
 
     References
@@ -638,9 +636,7 @@ class _AttentionBlock(nn.Module):
 
 
 class _TCNResidualBlock(nn.Module):
-    r"""Modified TCN Residual block as proposed in [1]_.
-
-    Inspired from
+    """Modified TCN Residual block as proposed in [1]_. Inspired from
     Temporal Convolutional Networks (TCN) [2]_.
 
     References
@@ -660,7 +656,7 @@ class _TCNResidualBlock(nn.Module):
         kernel_size=4,
         n_filters=32,
         dropout=0.3,
-        activation: type[nn.Module] = nn.ELU,
+        activation: nn.Module = nn.ELU,
         dilation=1,
     ):
         super().__init__()
@@ -736,7 +732,7 @@ class _MHA(nn.Module):
         num_heads: int,
         dropout: float = 0.0,
     ):
-        """Multi-head Attention.
+        """Multi-head Attention
 
         The difference between this module and torch.nn.MultiheadAttention is
         that this module supports embedding dimensions different then input
@@ -779,20 +775,20 @@ class _MHA(nn.Module):
     def forward(
         self, Q: torch.Tensor, K: torch.Tensor, V: torch.Tensor
     ) -> torch.Tensor:
-        """Compute MHA(Q, K, V).
+        """Compute MHA(Q, K, V)
 
         Parameters
         ----------
-        Q : torch.Tensor of size (batch_size, seq_len, input_dim)
+        Q: torch.Tensor of size (batch_size, seq_len, input_dim)
             Input query (Q) sequence.
-        K : torch.Tensor of size (batch_size, seq_len, input_dim)
+        K: torch.Tensor of size (batch_size, seq_len, input_dim)
             Input key (K) sequence.
-        V : torch.Tensor of size (batch_size, seq_len, input_dim)
+        V: torch.Tensor of size (batch_size, seq_len, input_dim)
             Input value (V) sequence.
 
         Returns
         -------
-        O : torch.Tensor of size (batch_size, seq_len, output_dim)
+        O: torch.Tensor of size (batch_size, seq_len, output_dim)
             Output MHA(Q, K, V)
         """
         assert Q.shape[-1] == K.shape[-1] == V.shape[-1] == self.input_dim