braindecode 1.8.0.dev1128__tar.gz → 1.8.0.dev168891348__tar.gz

{braindecode-1.8.0.dev1128/braindecode.egg-info → braindecode-1.8.0.dev168891348}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.8.0.dev1128
+Version: 1.8.0.dev168891348
 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>

{braindecode-1.8.0.dev1128 → braindecode-1.8.0.dev168891348}/braindecode/datasets/base.py

@@ -59,6 +59,7 @@ def _html_row(label, value):
 
 _METADATA_INTERNAL_COLS = {
     "i_window_in_trial",
+    "i_trial_in_dataset",
     "i_start_in_trial",
     "i_stop_in_trial",
     "target",
@@ -1374,6 +1375,20 @@ class BaseConcatDataset(ConcatDataset, HubDatasetMixin, Generic[T]):
                 "datasets are WindowsDataset."
             )
 
+        for ds in self.datasets:
+            if hasattr(ds, "_windows") and ds._windows is not None:
+                df = ds._windows.metadata
+            else:
+                df = ds.metadata
+            if (
+                "i_trial_in_dataset" in df.columns
+                and "i_trial_in_dataset" in ds.description
+            ):
+                raise ValueError(
+                    "Dataset descriptions cannot contain the reserved window "
+                    "metadata key 'i_trial_in_dataset'."
+                )
+
         all_dfs = list()
         for ds in self.datasets:
             if hasattr(ds, "_windows") and ds._windows is not None:

{braindecode-1.8.0.dev1128 → braindecode-1.8.0.dev168891348}/braindecode/models/atcnet.py

@@ -196,7 +196,7 @@ class ATCNet(EEGModuleMixin, nn.Module):
     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
+    att_drop_prob : float
         Dropout probability used in the attention block, denoted pa in table 1
         of the paper [1]_. Defaults to 0.5 as in [1]_.
     tcn_depth : int
@@ -206,7 +206,7 @@ class ATCNet(EEGModuleMixin, nn.Module):
     tcn_kernel_size : int
         Temporal kernel size used in TCN block, denoted Kt in table 1 of the
         paper [1]_. Defaults to 4 as in [1]_.
-    tcn_dropout : float
+    tcn_drop_prob : float
         Dropout probability used in the TCN block, denoted pt in table 1
         of the paper [1]_. Defaults to 0.3 as in [1]_.
     tcn_activation : torch.nn.Module

{braindecode-1.8.0.dev1128 → braindecode-1.8.0.dev168891348}/braindecode/models/attn_sleep.py

@@ -1,10 +1,36 @@
 # Authors: Divyesh Narayanan <divyesh.narayanan@gmail.com>
+#          Sarthak Tayal <sarthaktayal2@gmail.com>
 #
 # License: BSD (3-clause)
+#
+# This implementation derives from https://github.com/emadeldeen24/AttnSleep:
+#
+# MIT License
+#
+# Copyright (c) 2020 Emadeldeen Eldele
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
 
 import math
 import warnings
 from copy import deepcopy
+from numbers import Integral
 
 import torch
 import torch.nn.functional as F
@@ -33,7 +59,8 @@ class AttnSleep(EEGModuleMixin, nn.Module):
 
     Warning - This model was designed for signals of 30 seconds at 100Hz or 125Hz (in which case
     the reference architecture from [1]_ which was validated on SHHS dataset [2]_ will be used)
-    to use any other input is likely to make the model perform in unintended ways.
+    to use any other input is likely to make the model perform in unintended ways. Any other
+    window length also needs a ``d_model`` of its own, see the parameter below.
 
     Parameters
     ----------
@@ -44,7 +71,10 @@ class AttnSleep(EEGModuleMixin, nn.Module):
         Also the input dimension of the first FC layer in the feed forward
         and the output of the second FC layer in the same.
         Increase for higher sampling rate/signal length.
-        It should be divisible by n_attn_heads
+        It should be divisible by n_attn_heads. It must also equal the number
+        of time steps returned by the feature extractor: 80 for 30 seconds at
+        100 Hz and 100 for 30 seconds at 125 Hz. A construction error reports
+        the value needed for other window lengths.
     d_ff : int
         Output dimension of the first FC layer in the feed forward and the
         input dimension of the second FC layer in the same.
@@ -58,15 +88,12 @@ class AttnSleep(EEGModuleMixin, nn.Module):
         If True, return the features, i.e. the output of the feature extractor
         (before the final linear layer). If False, pass the features through
         the final linear layer.
-    n_classes : int
-        Alias for `n_outputs`.
-    input_size_s : float
-        Alias for `input_window_seconds`.
     activation : nn.Module, default=nn.ReLU
-        Activation function class to apply. Should be a PyTorch activation
+        Activation function class to apply in the AFR block and the TCE
+        feed-forward block. Should be a PyTorch activation
         module class like ``nn.ReLU`` or ``nn.ELU``. Default is ``nn.ReLU``.
-    activation_mrcnn : nn.Module, default=nn.ReLU
-        Activation function class to apply in the Mask R-CNN layer.
+    activation_mrcnn : nn.Module, default=nn.GELU
+        Activation function class to apply in the multi-resolution CNN layer.
         Should be a PyTorch activation module class like ``nn.ReLU`` or
         ``nn.GELU``. Default is ``nn.GELU``.
 
@@ -99,6 +126,14 @@ class AttnSleep(EEGModuleMixin, nn.Module):
         n_chans=None,
         n_times=None,
     ):
+        if (
+            sum(value is not None for value in (n_times, sfreq, input_window_seconds))
+            < 2
+        ):
+            raise ValueError(
+                "AttnSleep requires at least two of n_times, sfreq, and "
+                "input_window_seconds."
+            )
         super().__init__(
             n_outputs=n_outputs,
             n_chans=n_chans,
@@ -140,6 +175,14 @@ class AttnSleep(EEGModuleMixin, nn.Module):
             activation=activation_mrcnn,
             activation_se=activation,
         )
+        feature_length = self._feature_length(mrcnn, self.n_times)
+        if feature_length != d_model:
+            raise ValueError(
+                f"d_model is {d_model} but the feature extractor returns "
+                f"{feature_length} time steps for an input of {self.n_times} "
+                f"samples at {self.sfreq} Hz. Set d_model={feature_length}, with "
+                "an n_attn_heads that divides it."
+            )
         attn = _MultiHeadedAttention(n_attn_heads, d_model, after_reduced_cnn_size)
         ff = _PositionwiseFeedForward(d_model, d_ff, drop_prob, activation=activation)
         tce = _TCE(
@@ -150,23 +193,26 @@ class AttnSleep(EEGModuleMixin, nn.Module):
         )
 
         self.feature_extractor = nn.Sequential(mrcnn, tce)
-        self.len_last_layer = self._len_last_layer(self.n_times)
+        self.len_last_layer = feature_length * after_reduced_cnn_size
         self.return_feats = return_feats
 
         # TODO: Add new way to handle return features
         """if return_feats:
             raise ValueError("return_feat == True is not accepted anymore")"""
         if not return_feats:
-            self.final_layer = nn.Linear(
-                d_model * after_reduced_cnn_size, self.n_outputs
-            )
-
-    def _len_last_layer(self, input_size):
-        self.feature_extractor.eval()
-        with torch.no_grad():
-            out = self.feature_extractor(torch.Tensor(1, 1, input_size))
-        self.feature_extractor.train()
-        return len(out.flatten())
+            self.final_layer = nn.Linear(self.len_last_layer, self.n_outputs)
+
+    @staticmethod
+    def _feature_length(mrcnn, n_times):
+        training_states = [(module, module.training) for module in mrcnn.modules()]
+        mrcnn.eval()
+        try:
+            with torch.no_grad():
+                out = mrcnn(torch.zeros(1, 1, n_times))
+        finally:
+            for module, was_training in training_states:
+                module.training = was_training
+        return out.shape[-1]
 
     def forward(self, x: torch.Tensor) -> torch.Tensor:
         """
@@ -195,7 +241,7 @@ class _SELayer(nn.Module):
         self.avg_pool = nn.AdaptiveAvgPool1d(1)
         self.fc = nn.Sequential(
             nn.Linear(channel, channel // reduction, bias=False),
-            activation(inplace=True),
+            activation(),
             nn.Linear(channel // reduction, channel, bias=False),
             nn.Sigmoid(),
         )
@@ -236,10 +282,10 @@ class _SEBasicBlock(nn.Module):
         super(_SEBasicBlock, self).__init__()
         self.conv1 = nn.Conv1d(inplanes, planes, stride)
         self.bn1 = nn.BatchNorm1d(planes)
-        self.relu = activation(inplace=True)
+        self.relu = activation()
         self.conv2 = nn.Conv1d(planes, planes, 1)
         self.bn2 = nn.BatchNorm1d(planes)
-        self.se = _SELayer(planes, reduction)
+        self.se = _SELayer(planes, reduction, activation=activation)
         self.downsample = downsample
         self.stride = stride
         self.features = nn.Sequential(
@@ -320,11 +366,11 @@ class _MRCNN(nn.Module):
         self.dropout = nn.Dropout(drate)
         self.inplanes = 128
         self.AFR = self._make_layer(
-            _SEBasicBlock, after_reduced_cnn_size, 1, activate=activation_se
+            _SEBasicBlock, after_reduced_cnn_size, 1, activation=activation_se
         )
 
     def _make_layer(
-        self, block, planes, blocks, stride=1, activate: type[nn.Module] = nn.ReLU
+        self, block, planes, blocks, stride=1, activation: type[nn.Module] = nn.ReLU
     ):  # makes residual SE block
         downsample = None
         if stride != 1 or self.inplanes != planes * block.expansion:
@@ -340,10 +386,12 @@ class _MRCNN(nn.Module):
             )
 
         layers = []
-        layers.append(block(self.inplanes, planes, stride, downsample))
+        layers.append(
+            block(self.inplanes, planes, stride, downsample, activation=activation)
+        )
         self.inplanes = planes * block.expansion
         for i in range(1, blocks):
-            layers.append(block(self.inplanes, planes, activate=activate))
+            layers.append(block(self.inplanes, planes, activation=activation))
 
         return nn.Sequential(*layers)
 
@@ -375,9 +423,20 @@ class _MultiHeadedAttention(nn.Module):
     def __init__(self, h, d_model, after_reduced_cnn_size, dropout=0.1):
         """Take in model size and number of heads."""
         super().__init__()
-        assert d_model % h == 0
+        if (
+            isinstance(h, bool)
+            or not isinstance(h, Integral)
+            or h <= 0
+            or d_model % h != 0
+        ):
+            raise ValueError(
+                "n_attn_heads must be a positive integer that divides d_model, "
+                f"got n_attn_heads={h!r} and d_model={d_model}."
+            )
+        h = int(h)
         self.d_per_head = d_model // h
         self.h = h
+        self.attn = torch.empty(0)
 
         base_conv = CausalConv1d(
             in_channels=after_reduced_cnn_size,

{braindecode-1.8.0.dev1128 → braindecode-1.8.0.dev168891348}/braindecode/models/base.py

@@ -80,7 +80,7 @@ class _BraindecodeDocstringMeta(NumpyDocstringInheritanceInitMeta):
     unwrapped function and correctly inherits ``cls.__doc__``.
     """
 
-    def __init__(cls, class_name, class_bases, class_dict):
+    def __init__(cls, class_name, class_bases, class_dict, **kwargs):
         super().__init__(class_name, class_bases, class_dict)
         # Only wrap subclass __init__s, not EEGModuleMixin itself.
         # Wrapping the mixin would cause super().__init__() calls to
@@ -214,6 +214,8 @@ class EEGModuleMixin(_BaseHubMixin, metaclass=_BraindecodeDocstringMeta):
     __jit_unused_properties__ = ["chs_info"]
 
     def __init_subclass__(cls, **kwargs):
+        license = kwargs.pop("license", "bsd-3-clause")
+
         # TorchScript only honours ``__jit_ignored_attributes__`` for
         # properties defined directly on the concrete class: it collects them
         # with ``vars(type(module))``, which skips inherited ones. Rebinding
@@ -253,8 +255,6 @@ class EEGModuleMixin(_BaseHubMixin, metaclass=_BraindecodeDocstringMeta):
         )
         repo_url = kwargs.pop("repo_url", "https://braindecode.org")
         library_name = kwargs.pop("library_name", "braindecode")
-        license = kwargs.pop("license", "bsd-3-clause")
-
         # Register a coder so that type[nn.Module] parameters
         # (e.g. activation=nn.ELU) are serialized as importable
         # strings in config.json and decoded back on load.

{braindecode-1.8.0.dev1128 → braindecode-1.8.0.dev168891348}/braindecode/models/ctnet.py

@@ -59,16 +59,19 @@ class CTNet(EEGModuleMixin, nn.Module):
 
     Parameters
     ----------
-    activation : nn.Module, default=nn.GELU
-        Activation function to use in the network.
+    activation_patch : nn.Module, default=nn.ELU
+        Activation function to use in the convolutional patch embedding.
+    activation_transformer : nn.Module, default=nn.GELU
+        Activation function to use in the Transformer encoder.
     num_heads : int, default=4
         Number of attention heads in the Transformer encoder.
-    embed_dim : int or None, default=None
+    embed_dim : int or None, default=40
         Embedding size (dimensionality) for the Transformer encoder.
     num_layers : int, default=6
         Number of encoder layers in the Transformer.
-    n_filters_time : int, default=20
-        Number of temporal filters in the first convolutional layer.
+    n_filters_time : int or None, default=None
+        Number of temporal filters in the first convolutional layer. Inferred
+        from ``embed_dim`` and ``depth_multiplier`` when left at ``None``.
     kernel_size : int, default=64
         Kernel size for the temporal convolutional layer.
     depth_multiplier : int, default=2
@@ -77,7 +80,7 @@ class CTNet(EEGModuleMixin, nn.Module):
         Pooling size for the first average pooling layer.
     pool_size_2 : int, default=8
         Pooling size for the second average pooling layer.
-        cnn_drop_prob: float, default=0.3
+    cnn_drop_prob : float, default=0.3
         Dropout probability after convolutional layers.
     att_positional_drop_prob : float, default=0.1
         Dropout probability for the positional encoding in the Transformer.

{braindecode-1.8.0.dev1128 → braindecode-1.8.0.dev168891348}/braindecode/models/eegsimpleconv.py

@@ -71,17 +71,19 @@ class EEGSimpleConv(EEGModuleMixin, torch.nn.Module):
 
     Parameters
     ----------
-    feature_maps: int
+    feature_maps : int
         Number of Feature Maps at the first Convolution, width of the model.
-    n_convs: int
+    n_convs : int
         Number of blocks of convolutions (2 convolutions per block), depth of the model.
-    resampling: int
+    resampling_freq : int
         Resampling Frequency.
-    kernel_size: int
+    kernel_size : int
         Size of the convolutions kernels.
-    activation: nn.Module, default=nn.ELU
+    return_feature : bool, default=False
+        If True, return the features before the final linear layer.
+    activation : nn.Module, default=nn.ReLU
         Activation function class to apply. Should be a PyTorch activation
-        module class like ``nn.ReLU`` or ``nn.ELU``. Default is ``nn.ELU``.
+        module class like ``nn.ReLU`` or ``nn.ELU``. Default is ``nn.ReLU``.
 
     References
     ----------

{braindecode-1.8.0.dev1128 → braindecode-1.8.0.dev168891348}/braindecode/models/ifnet.py

@@ -71,21 +71,24 @@ class IFNet(EEGModuleMixin, nn.Module):
 
     Parameters
     ----------
-    bands : list[tuple[int, int]] or int or None, default=[[4, 16], (16, 40)]
+    bands : list[tuple[float, float]] or int or None, default=[(4, 16), (16, 40)]
         Frequency bands for filtering.
-    out_planes : int, default=64
+    n_filters_spat : int, default=64
         Number of output feature dimensions.
     kernel_sizes : tuple of int, default=(63, 31)
         List of kernel sizes for temporal convolutions.
-    patch_size : int, default=125
-        Size of the patches for temporal segmentation.
+    stride_factor : int, default=8
+        Number of temporal segments the padded signal is split into before
+        variance pooling.
     drop_prob : float, default=0.5
         Dropout probability.
+    linear_max_norm : float, default=0.5
+        Maximum norm constraint on the weights of the final linear layer.
     activation : nn.Module, default=nn.GELU
         Activation function after the InterFrequency Layer.
     verbose : bool, default=False
         Verbose to control the filtering layer
-    filter_parameters : dict, default={}
+    filter_parameters : dict or None, default=None
         Additional parameters for the filter bank layer.
 
     References

{braindecode-1.8.0.dev1128 → braindecode-1.8.0.dev168891348}/braindecode/models/sleep_stager_blanco_2020.py

@@ -26,10 +26,12 @@ class SleepStagerBlanco2020(EEGModuleMixin, nn.Module):
     ----------
     n_conv_chans : int
         Number of convolutional channels. Set to 20 in [Blanco2020]_.
+    max_pool_size : int, default=2
+        Kernel and stride of the max pooling layers.
     n_groups : int
         Number of groups for the convolution. Set to 2 in [Blanco2020]_ for 2 Channel EEG.
-        controls the connections between inputs and outputs. n_channels and n_conv_chans must be
-        divisible by n_groups.
+        Controls the connections between inputs and outputs. ``n_chans`` and
+        ``n_conv_chans`` must be divisible by ``n_groups``.
     drop_prob : float
         Dropout rate before the output dense layer.
     apply_batch_norm : bool
@@ -39,13 +41,7 @@ class SleepStagerBlanco2020(EEGModuleMixin, nn.Module):
         If True, return the features, i.e. the output of the feature extractor
         (before the final linear layer). If False, pass the features through
         the final linear layer.
-    n_channels : int
-        Alias for `n_chans`.
-    n_classes : int
-        Alias for `n_outputs`.
-    input_size_s : float
-        Alias for `input_window_seconds`.
-    activation: nn.Module, default=nn.ReLU
+    activation : nn.Module, default=nn.ReLU
         Activation function class to apply. Should be a PyTorch activation
         module class like ``nn.ReLU`` or ``nn.ELU``. Default is ``nn.ReLU``.
 

{braindecode-1.8.0.dev1128 → braindecode-1.8.0.dev168891348}/braindecode/models/sleep_stager_chambon_2018.py

@@ -43,13 +43,7 @@ class SleepStagerChambon2018(EEGModuleMixin, nn.Module):
         If True, return the features, i.e. the output of the feature extractor
         (before the final linear layer). If False, pass the features through
         the final linear layer.
-    n_channels : int
-        Alias for `n_chans`.
-    input_size_s:
-        Alias for `input_window_seconds`.
-    n_classes:
-        Alias for `n_outputs`.
-    activation: nn.Module, default=nn.ReLU
+    activation : nn.Module, default=nn.ReLU
         Activation function class to apply. Should be a PyTorch activation
         module class like ``nn.ReLU`` or ``nn.ELU``. Default is ``nn.ReLU``.
 

{braindecode-1.8.0.dev1128 → braindecode-1.8.0.dev168891348}/braindecode/models/sparcnet.py

@@ -33,7 +33,7 @@ class SPARCNet(EEGModuleMixin, nn.Module):
         Number of layers per dense block. Default is 4.
     growth_rate : int, optional
         Growth rate of the DenseNet. Default is 16.
-    bn_size : int, optional
+    bottleneck_size : int, optional
         Bottleneck size. Default is 16.
     drop_prob : float, optional
         Dropout rate. Default is 0.5.
@@ -41,7 +41,7 @@ class SPARCNet(EEGModuleMixin, nn.Module):
         Whether to use bias in convolutional layers. Default is True.
     batch_norm : bool, optional
         Whether to use batch normalization. Default is True.
-    activation: nn.Module, default=nn.ELU
+    activation : nn.Module, default=nn.ELU
         Activation function class to apply. Should be a PyTorch activation
         module class like ``nn.ReLU`` or ``nn.ELU``. Default is ``nn.ELU``.
 

{braindecode-1.8.0.dev1128 → braindecode-1.8.0.dev168891348}/braindecode/models/summary.csv

@@ -31,7 +31,7 @@ SincShallowNet,Motor Imagery,Prediction,250,"n_chans, n_outputs, n_times, sfreq"
 ShallowFBCSPNet,General,Prediction,250,"n_chans, n_outputs, n_times",46084,"ShallowFBCSPNet(n_chans=22,  n_outputs=4,  n_times=1000, sfreq=250)","Convolution",EEG
 SleepStagerBlanco2020,Sleep Staging,Prediction,100,"n_chans, n_outputs, n_times",2845,"SleepStagerBlanco2020(n_chans=2, n_outputs=5, n_times=3000, sfreq=100)","Convolution",EEG
 SleepStagerChambon2018,Sleep Staging,Prediction,128,"n_chans, n_outputs, n_times, sfreq",5835,"SleepStagerChambon2018(n_chans=2, n_outputs=5, n_times=3840, sfreq=128)","Convolution",EEG
-AttnSleep,Sleep Staging,Prediction,100,"n_chans, n_outputs, n_times, sfreq",719925,"AttnSleep(n_chans=2, n_outputs=5, n_times=3000, sfreq=100)","Convolution, Attention/Transformer",EEG
+AttnSleep,Sleep Staging,Prediction,100,"n_chans, n_outputs, n_times, sfreq",522805,"AttnSleep(n_chans=1, n_outputs=5, n_times=3000, sfreq=100)","Convolution, Attention/Transformer",EEG
 SPARCNet,Epilepsy,Prediction,200,"n_chans, n_outputs, n_times",1141921,"SPARCNet(n_chans=16, n_outputs=6, n_times=2000, sfreq=200)","Convolution",EEG
 SyncNet,"Emotion Recognition, Alcoholism",Prediction,256,"n_chans, n_outputs, n_times",554,"SyncNet(n_chans=62, n_outputs=3, n_times=5120, sfreq=256)","Interpretability",EEG
 TSception,Emotion Recognition,Prediction,256,"n_chans, n_outputs, n_times, sfreq",2187206,"TSception(n_chans=62, n_outputs=3, n_times=5120, sfreq=256)","Convolution",EEG

{braindecode-1.8.0.dev1128 → braindecode-1.8.0.dev168891348}/braindecode/models/tidnet.py

@@ -45,13 +45,7 @@ class TIDNet(EEGModuleMixin, nn.Module):
     summary : int
         Output size of AdaptiveAvgPool1D layer. If set to -1, value will be calculated
         automatically (n_times // pooling).
-    in_chans :
-        Alias for n_chans.
-    n_classes:
-        Alias for n_outputs.
-    input_window_samples :
-        Alias for n_times.
-    activation: nn.Module, default=nn.LeakyReLU
+    activation : nn.Module, default=nn.LeakyReLU
         Activation function class to apply. Should be a PyTorch activation
         module class like ``nn.ReLU`` or ``nn.ELU``. Default is ``nn.LeakyReLU``.