braindecode 0.8__py3-none-any.whl → 1.0.0__py3-none-any.whl

braindecode/models/util.py

@@ -0,0 +1,133 @@
+# Authors: Robin Schirrmeister <robintibor@gmail.com>
+#          Hubert Banville <hubert.jbanville@gmail.com>
+#
+# License: BSD (3-clause)
+import inspect
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import torch
+from scipy.special import log_softmax
+from sklearn.utils import deprecated
+
+import braindecode.models as models
+
+models_dict = {}
+
+# For the models inside the init model, go through all the models
+# check those have the EEGMixin class inherited. If they are, add them to the
+# list.
+
+
+def _init_models_dict():
+    for m in inspect.getmembers(models, inspect.isclass):
+        if (
+            issubclass(m[1], models.base.EEGModuleMixin)
+            and m[1] != models.base.EEGModuleMixin
+        ):
+            models_dict[m[0]] = m[1]
+
+
+################################################################
+# Test cases for models
+#
+# This list should be updated whenever a new model is added to
+# braindecode (otherwise `test_completeness__models_test_cases`
+# will fail).
+# Each element in the list should be a tuple with structure
+# (model_class, required_params, signal_params), such that:
+#
+# model_name: str
+#   The name of the class of the model to be tested.
+# required_params: list[str]
+#   The signal-related parameters that are needed to initialize
+#   the model.
+# signal_params: dict | None
+#   The characteristics of the signal that should be passed to
+#   the model tested in case the default_signal_params are not
+#   compatible with this model.
+#   The keys of this dictionary can only be among those of
+#   default_signal_params.
+################################################################
+models_mandatory_parameters = [
+    ("ATCNet", ["n_chans", "n_outputs", "n_times"], None),
+    ("BDTCN", ["n_chans", "n_outputs"], None),
+    ("Deep4Net", ["n_chans", "n_outputs", "n_times"], None),
+    ("DeepSleepNet", ["n_outputs"], None),
+    ("EEGConformer", ["n_chans", "n_outputs", "n_times"], None),
+    ("EEGInceptionERP", ["n_chans", "n_outputs", "n_times", "sfreq"], None),
+    ("EEGInceptionMI", ["n_chans", "n_outputs", "n_times", "sfreq"], None),
+    ("EEGITNet", ["n_chans", "n_outputs", "n_times"], None),
+    ("EEGNetv1", ["n_chans", "n_outputs", "n_times"], None),
+    ("EEGNetv4", ["n_chans", "n_outputs", "n_times"], None),
+    ("EEGResNet", ["n_chans", "n_outputs", "n_times"], None),
+    ("ShallowFBCSPNet", ["n_chans", "n_outputs", "n_times"], None),
+    (
+        "SleepStagerBlanco2020",
+        ["n_chans", "n_outputs", "n_times"],
+        dict(n_chans=4),  # n_chans dividable by n_groups=2
+    ),
+    ("SleepStagerChambon2018", ["n_chans", "n_outputs", "n_times", "sfreq"], None),
+    (
+        "SleepStagerEldele2021",
+        ["n_outputs", "n_times", "sfreq"],
+        dict(sfreq=100.0, n_times=3000, chs_info=[dict(ch_name="C1", kind="eeg")]),
+    ),  # 1 channel
+    ("TIDNet", ["n_chans", "n_outputs", "n_times"], None),
+    ("USleep", ["n_chans", "n_outputs", "n_times", "sfreq"], dict(sfreq=128.0)),
+    ("BIOT", ["n_chans", "n_outputs", "sfreq"], None),
+    ("AttentionBaseNet", ["n_chans", "n_outputs", "n_times"], None),
+    ("Labram", ["n_chans", "n_outputs", "n_times"], None),
+    ("EEGSimpleConv", ["n_chans", "n_outputs", "sfreq"], None),
+    ("SPARCNet", ["n_chans", "n_outputs", "n_times"], None),
+    ("ContraWR", ["n_chans", "n_outputs", "sfreq"], dict(sfreq=200.0)),
+    ("EEGNeX", ["n_chans", "n_outputs", "n_times"], None),
+    ("TSceptionV1", ["n_chans", "n_outputs", "n_times", "sfreq"], dict(sfreq=200.0)),
+    ("EEGTCNet", ["n_chans", "n_outputs", "n_times"], None),
+    ("SyncNet", ["n_chans", "n_outputs", "n_times"], None),
+    ("MSVTNet", ["n_chans", "n_outputs", "n_times"], None),
+    ("EEGMiner", ["n_chans", "n_outputs", "n_times", "sfreq"], dict(sfreq=200.0)),
+    ("CTNet", ["n_chans", "n_outputs", "n_times"], None),
+    ("SincShallowNet", ["n_chans", "n_outputs", "n_times", "sfreq"], dict(sfreq=250.0)),
+    ("SCCNet", ["n_chans", "n_outputs", "n_times", "sfreq"], dict(sfreq=200.0)),
+    ("SignalJEPA", ["chs_info"], None),
+    ("SignalJEPA_Contextual", ["chs_info", "n_times", "n_outputs"], None),
+    ("SignalJEPA_PostLocal", ["n_chans", "n_times", "n_outputs"], None),
+    ("SignalJEPA_PreLocal", ["n_chans", "n_times", "n_outputs"], None),
+    ("FBCNet", ["n_chans", "n_outputs", "n_times", "sfreq"], dict(sfreq=200.0)),
+    ("FBMSNet", ["n_chans", "n_outputs", "n_times", "sfreq"], dict(sfreq=200.0)),
+    ("FBLightConvNet", ["n_chans", "n_outputs", "n_times", "sfreq"], dict(sfreq=200.0)),
+    ("IFNet", ["n_chans", "n_outputs", "n_times", "sfreq"], dict(sfreq=200.0)),
+]
+
+################################################################
+# List of models that are not meant for classification
+#
+# Their output shape may difer from the expected output shape
+# for classification models.
+################################################################
+non_classification_models = [
+    "SignalJEPA",
+]
+
+
+################################################################
+def get_summary_table(dir_name=None):
+    if dir_name is None:
+        dir_path = Path(__file__).parent
+    else:
+        dir_path = Path(dir_name) if not isinstance(dir_name, Path) else dir_name
+
+    path = dir_path / "summary.csv"
+
+    df = pd.read_csv(
+        path,
+        header=0,
+        index_col="Model",
+        skipinitialspace=True,
+    )
+    return df
+
+
+_summary_table = get_summary_table()

braindecode/modules/__init__.py

@@ -0,0 +1,38 @@
+from .activation import LogActivation, SafeLog
+from .attention import (
+    CAT,
+    CBAM,
+    ECA,
+    FCA,
+    GCT,
+    SRM,
+    CATLite,
+    EncNet,
+    GatherExcite,
+    GSoP,
+    MultiHeadAttention,
+    SqueezeAndExcitation,
+)
+from .blocks import MLP, FeedForwardBlock, InceptionBlock
+from .convolution import (
+    AvgPool2dWithConv,
+    CausalConv1d,
+    CombinedConv,
+    Conv2dWithConstraint,
+    DepthwiseConv2d,
+)
+from .filter import FilterBankLayer, GeneralizedGaussianFilter
+from .layers import Chomp1d, DropPath, Ensure4d, SqueezeFinalOutput, TimeDistributed
+from .linear import LinearWithConstraint, MaxNormLinear
+from .parametrization import MaxNorm, MaxNormParametrize
+from .stats import (
+    LogPowerLayer,
+    LogVarLayer,
+    MaxLayer,
+    MeanLayer,
+    StatLayer,
+    StdLayer,
+    VarLayer,
+)
+from .util import aggregate_probas
+from .wrapper import Expression, IntermediateOutputWrapper

braindecode/modules/activation.py

@@ -0,0 +1,60 @@
+import torch
+from torch import Tensor, nn
+
+import braindecode.functional as F
+
+
+class SafeLog(nn.Module):
+    r"""
+    Safe logarithm activation function module.
+
+    :math:\text{SafeLog}(x) = \log\left(\max(x, \epsilon)\right)
+
+    Parameters
+    ----------
+    eps : float, optional
+        A small value to clamp the input tensor to prevent computing log(0) or log of negative numbers.
+        Default is 1e-6.
+
+    """
+
+    def __init__(self, epsilon: float = 1e-6):
+        super().__init__()
+        self.epsilon = epsilon
+
+    def forward(self, x) -> Tensor:
+        """
+        Forward pass of the SafeLog module.
+
+        Parameters
+        ----------
+        x : torch.Tensor
+            Input tensor.
+
+        Returns
+        -------
+        torch.Tensor
+            Output tensor after applying safe logarithm.
+        """
+        return F.safe_log(x=x, eps=self.epsilon)
+
+    def extra_repr(self) -> str:
+        eps_str = f"eps={self.epsilon}"
+        return eps_str
+
+
+class LogActivation(nn.Module):
+    """Logarithm activation function."""
+
+    def __init__(self, epsilon: float = 1e-6, *args, **kwargs):
+        """
+        Parameters
+        ----------
+        epsilon : float
+            Small float to adjust the activation.
+        """
+        super().__init__(*args, **kwargs)
+        self.epsilon = epsilon
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return torch.log(x + self.epsilon)  # Adding epsilon to prevent log(0)