braindecode 1.3.0.dev180851780__py3-none-any.whl → 1.3.0.dev183667303__py3-none-any.whl

braindecode/datautil/serialization.py

@@ -19,8 +19,8 @@ from joblib import Parallel, delayed
 
 from ..datasets.base import (
     BaseConcatDataset,
-    BaseDataset,
     EEGWindowsDataset,
+    RawDataset,
     WindowsDataset,
 )
 
@@ -35,7 +35,7 @@ def save_concat_dataset(path, concat_dataset, overwrite=False):
 
 
 def _outdated_load_concat_dataset(path, preload, ids_to_load=None, target_name=None):
-    """Load a stored BaseConcatDataset of BaseDatasets or WindowsDatasets from
+    """Load a stored BaseConcatDataset from
     files.
 
     Parameters
@@ -52,7 +52,7 @@ def _outdated_load_concat_dataset(path, preload, ids_to_load=None, target_name=N
 
     Returns
     -------
-    concat_dataset: BaseConcatDataset of BaseDatasets or WindowsDatasets
+    concat_dataset: BaseConcatDataset
     """
     # assume we have a single concat dataset to load
     is_raw = (path / "0-raw.fif").is_file()
@@ -87,7 +87,7 @@ def _outdated_load_concat_dataset(path, preload, ids_to_load=None, target_name=N
         for i_signal, signal in enumerate(all_signals):
             if is_raw:
                 datasets.append(
-                    BaseDataset(
+                    RawDataset(
                         signal, description.iloc[i_signal], target_name=target_name
                     )
                 )
@@ -175,7 +175,7 @@ def _load_signals(fif_file, preload, is_raw):
 
 
 def load_concat_dataset(path, preload, ids_to_load=None, target_name=None, n_jobs=1):
-    """Load a stored BaseConcatDataset of BaseDatasets or WindowsDatasets from
+    """Load a stored BaseConcatDataset from
     files.
 
     Parameters
@@ -194,7 +194,7 @@ def load_concat_dataset(path, preload, ids_to_load=None, target_name=None, n_job
 
     Returns
     -------
-    concat_dataset: BaseConcatDataset of BaseDatasets or WindowsDatasets
+    concat_dataset: BaseConcatDataset
     """
     # Make sure we always work with a pathlib.Path
     path = Path(path)
@@ -266,7 +266,7 @@ def _load_parallel(path, i, preload, is_raw, has_stored_windows):
         target_name = json.load(open(target_file_path, "r"))["target_name"]
 
     if is_raw and (not has_stored_windows):
-        dataset = BaseDataset(signals, description, target_name)
+        dataset = RawDataset(signals, description, target_name)
     else:
         window_kwargs = _load_kwargs_json("window_kwargs", sub_dir)
         windows_ds_kwargs = [

braindecode/eegneuralnet.py

@@ -189,6 +189,8 @@ class _EEGNeuralNet(NeuralNet, abc.ABC):
                 "Skipping setting signal-related parameters from data."
             )
             return
+        if classes is None:
+            classes = getattr(self, "classes", None)
         # get kwargs from signal:
         signal_kwargs = dict()
         # Using shape to work both with torch.tensor and numpy.array:

braindecode/functional/functions.py

@@ -181,20 +181,24 @@ def plv_time(x, forward_fourier=True, epsilon: float = 1e-6):
     The Phase Locking Value (PLV) is a measure of the synchronization between
     different channels by evaluating the consistency of phase differences
     over time. It ranges from 0 (no synchronization) to 1 (perfect
-    synchronization) [1]_.
+    synchronization) [Lachaux1999]_.
 
     Parameters
     ----------
     x : torch.Tensor
         Input tensor containing the signal data.
+
         - If `forward_fourier` is `True`, the shape should be `(..., channels, time)`.
         - If `forward_fourier` is `False`, the shape should be `(..., channels, freqs, 2)`,
           where the last dimension represents the real and imaginary parts.
+
     forward_fourier : bool, optional
         Specifies the format of the input tensor `x`.
+
         - If `True`, `x` is assumed to be in the time domain.
         - If `False`, `x` is assumed to be in the Fourier domain with separate real and
           imaginary components.
+
         Default is `True`.
     epsilon : float, default 1e-6
         Small numerical value to ensure positivity constraint on the complex part
@@ -207,7 +211,7 @@ def plv_time(x, forward_fourier=True, epsilon: float = 1e-6):
 
     References
     ----------
-    [1] Lachaux, J. P., Rodriguez, E., Martinerie, J., & Varela, F. J. (1999).
+    .. [Lachaux1999] Lachaux, J. P., Rodriguez, E., Martinerie, J., & Varela, F. J. (1999).
         Measuring phase synchrony in brain signals. Human brain mapping,
         8(4), 194-208.
     """

braindecode/functional/initialization.py

@@ -5,9 +5,8 @@ from torch import nn
 
 def glorot_weight_zero_bias(model):
     """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.
+    glorot uniform/xavier initialization, and setting biases to zero. Weights from
+    batch norm layers are set to 1.
 
     Parameters
     ----------

braindecode/models/__init__.py

@@ -6,6 +6,7 @@ from .atcnet import ATCNet
 from .attentionbasenet import AttentionBaseNet
 from .attn_sleep import AttnSleep
 from .base import EEGModuleMixin
+from .bendr import BENDR
 from .biot import BIOT
 from .contrawr import ContraWR
 from .ctnet import CTNet
@@ -58,6 +59,7 @@ __all__ = [
     "AttentionBaseNet",
     "EEGModuleMixin",
     "BIOT",
+    "BENDR",
     "ContraWR",
     "CTNet",
     "Deep4Net",

braindecode/models/atcnet.py

@@ -50,7 +50,7 @@ class ATCNet(EEGModuleMixin, nn.Module):
         - **Temporal conv** (:class:`torch.nn.Conv2d`) with kernel ``(L_t, 1)`` builds a
             FIR-like filter bank (``F1`` maps).
         - **Depthwise spatial conv** (:class:`torch.nn.Conv2d`, ``groups=F1``) with kernel
-          ``(1, n_chans)`` learns per-filter spatial projections (akin to EEGNet’s CSP-like step).
+          ``(1, n_chans)`` learns per-filter spatial projections (akin to EEGNet's CSP-like step).
         - **BN → ELU → AvgPool → Dropout** to stabilize and condense activations.
         - **Refining temporal conv** (:class:`torch.nn.Conv2d`) with kernel ``(L_r, 1)`` +
           **BN → ELU → AvgPool → Dropout**.
@@ -62,13 +62,15 @@ class ATCNet(EEGModuleMixin, nn.Module):
 
     - **Sliding-Window Sequencer**
 
-      From the condensed time axis (length ``T_c``), ATCNet forms ``n`` overlapping windows
-      of width ``T_w = T_c - n + 1`` (one start per index). Each window produces a sequence
-      ``(B, F2, T_w)`` forwarded to its own attention–TCN branch. This creates *parallel*
-      encoders over shifted contexts and is key to robustness on nonstationary EEG.
+        From the condensed time axis (length ``T_c``), ATCNet forms ``n`` overlapping windows
+        of width ``T_w = T_c - n + 1`` (one start per index). Each window produces a sequence
+        ``(B, F2, T_w)`` forwarded to its own attention-TCN branch. This creates *parallel*
+        encoders over shifted contexts and is key to robustness on nonstationary EEG.
 
     - :class:`_AttentionBlock` **(small MHA on temporal positions)**
 
+        Attention here is *local to a window* and purely temporal.
+
         - *Operations.*
         - Rearrange to ``(B, T_w, F2)``,
         - Normalization :class:`torch.nn.LayerNorm`
@@ -76,11 +78,8 @@ class ATCNet(EEGModuleMixin, nn.Module):
         - Dropout :class:`torch.nn.Dropout`
         - Rearrange back to ``(B, F2, T_w)``.
 
-
-    **Note**: Attention is *local to a window* and purely temporal.
-
-    *Role.* Re-weights evidence across the window, letting the model emphasize informative
-    segments (onsets, bursts) before causal convolutions aggregate history.
+        *Role.* Re-weights evidence across the window, letting the model emphasize informative
+        segments (onsets, bursts) before causal convolutions aggregate history.
 
     - :class:`_TCNResidualBlock` **(causal dilated temporal CNN)**
 
@@ -90,8 +89,8 @@ class ATCNet(EEGModuleMixin, nn.Module):
           a residual (identity or 1x1 mapping).
         - The final feature used per window is the *last* causal step ``[..., -1]`` (forecast-style).
 
-    *Role.* Efficient long-range temporal integration with stable gradients; the dilated
-    receptive field complements attention’s soft selection.
+        *Role.* Efficient long-range temporal integration with stable gradients; the dilated
+        receptive field complements attention's soft selection.
 
     - **Aggregation & Classifier**
 
@@ -104,16 +103,16 @@ class ATCNet(EEGModuleMixin, nn.Module):
     .. rubric:: Convolutional Details
 
     - **Temporal.** Temporal structure is learned in three places:
-        - (1) the stem’s wide ``(L_t, 1)`` conv (learned filter bank),
+        - (1) the stem's wide ``(L_t, 1)`` conv (learned filter bank),
         - (2) the refining ``(L_r, 1)`` conv after pooling (short-term dynamics), and
-        - (3) the TCN’s causal 1-D convolutions with exponentially increasing dilation
+        - (3) the TCN's causal 1-D convolutions with exponentially increasing dilation
           (long-range dependencies). The minimum sequence length required by the TCN stack is
           ``(K_t - 1)·2^{L-1} + 1``; the implementation *auto-scales* kernels/pools/windows
           when inputs are shorter to preserve feasibility.
 
     - **Spatial.** A depthwise spatial conv spans the **full montage** (kernel ``(1, n_chans)``),
         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.
+        This mirrors EEGNet's interpretability: each temporal filter has its own spatial pattern.
 
 
     .. rubric:: Attention / Sequential Modules
@@ -137,17 +136,17 @@ class ATCNet(EEGModuleMixin, nn.Module):
 
     .. rubric:: Usage and Configuration
 
-        - ``conv_block_n_filters (F1)``, ``conv_block_depth_mult (D)`` → capacity of the stem
-        (with ``F2 = F1·D`` feeding attention/TCN), dimensions aligned to ``F2``, like :class:`EEGNet`.
-        - 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).
-        - ``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.
+    - ``conv_block_n_filters (F1)``, ``conv_block_depth_mult (D)`` → capacity of the stem
+      (with ``F2 = F1·D`` feeding attention/TCN), dimensions aligned to ``F2``, like :class:`EEGNet`.
+    - 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).
+    - ``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

braindecode/models/attentionbasenet.py

@@ -97,7 +97,7 @@ class AttentionBaseNet(EEGModuleMixin, nn.Module):
 
     - **Temporal (where time-domain patterns are learned).**
         Wide kernels in the stem (``(1, L_t)``) act as a learned filter bank for oscillatory
-        bands/transients; the attention block’s depthwise temporal conv (``(1, L_a)``) sharpens
+        bands/transients; the attention block's depthwise temporal conv (``(1, L_a)``) sharpens
         short-term dynamics after downsampling. Pool sizes/strides (``P₁,S₁`` then ``P₂,S₂``)
         set the token rate and effective temporal resolution.
 
@@ -127,23 +127,24 @@ class AttentionBaseNet(EEGModuleMixin, nn.Module):
 
     .. rubric:: Additional Mechanisms
 
-        - **Attention variants at a glance.**
-        - ``"se"``: Squeeze-and-Excitation (global pooling → bottleneck → gates).
-        - ``"gsop"``: Global second-order pooling (covariance-aware channel weights).
-        - ``"fca"``: Frequency Channel Attention (DCT summary; uses ``seq_len`` and ``freq_idx``).
-        - ``"encnet"``: EncNet with learned codewords (uses ``n_codewords``).
-        - ``"eca"``: Efficient Channel Attention (local 1-D conv over channel descriptor; uses ``kernel_size``).
-        - ``"ge"``: Gather–Excite (context pooling with optional MLP; can use ``extra_params``).
-        - ``"gct"``: Gated Channel Transformation (global context normalization + gating).
-        - ``"srm"``: Style-based recalibration (mean–std descriptors; optional MLP).
-        - ``"cbam"``: Channel then temporal attention (uses ``kernel_size``).
-        - ``"cat"`` / ``"catlite"``: Collaborative (channel ± temporal) attention; *lite* omits temporal.
-        - **Auto-compatibility on short inputs.**
+    **Attention variants at a glance:**
 
-    If the input duration is too short for the configured kernels/pools, the implementation
-    **automatically rescales** temporal lengths/strides downward (with a warning) to keep
-    shapes valid and preserve the pipeline semantics.
+    - ``"se"``: Squeeze-and-Excitation (global pooling → bottleneck → gates).
+    - ``"gsop"``: Global second-order pooling (covariance-aware channel weights).
+    - ``"fca"``: Frequency Channel Attention (DCT summary; uses ``seq_len`` and ``freq_idx``).
+    - ``"encnet"``: EncNet with learned codewords (uses ``n_codewords``).
+    - ``"eca"``: Efficient Channel Attention (local 1-D conv over channel descriptor; uses ``kernel_size``).
+    - ``"ge"``: Gather–Excite (context pooling with optional MLP; can use ``extra_params``).
+    - ``"gct"``: Gated Channel Transformation (global context normalization + gating).
+    - ``"srm"``: Style-based recalibration (mean–std descriptors; optional MLP).
+    - ``"cbam"``: Channel then temporal attention (uses ``kernel_size``).
+    - ``"cat"`` / ``"catlite"``: Collaborative (channel ± temporal) attention; *lite* omits temporal.
 
+    **Auto-compatibility on short inputs:**
+
+        If the input duration is too short for the configured kernels/pools, the implementation
+        **automatically rescales** temporal lengths/strides downward (with a warning) to keep
+        shapes valid and preserve the pipeline semantics.
 
     .. rubric:: Usage and Configuration
 
@@ -158,9 +159,9 @@ class AttentionBaseNet(EEGModuleMixin, nn.Module):
     - ``drop_prob_inp`` and ``drop_prob_attn``: regularize stem and attention stages.
     - **Training tips.**
 
-    Start with moderate pooling (e.g., ``P₁=75,S₁=15``) and ELU activations; enable attention
-    only after the stem learns stable filters. For small datasets, prefer simpler modes
-    (``"se"``, ``"eca"``) before heavier ones (``"gsop"``, ``"encnet"``).
+        Start with moderate pooling (e.g., ``P₁=75,S₁=15``) and ELU activations; enable attention
+        only after the stem learns stable filters. For small datasets, prefer simpler modes
+        (``"se"``, ``"eca"``) before heavier ones (``"gsop"``, ``"encnet"``).
 
     Notes
     -----
@@ -170,6 +171,7 @@ class AttentionBaseNet(EEGModuleMixin, nn.Module):
       specific variants (CBAM/CAT).
     - The paper and original code with more details about the methodological
       choices are available at the [Martin2023]_ and [MartinCode]_.
+
     .. versionadded:: 0.9
 
     Parameters
@@ -198,19 +200,21 @@ class AttentionBaseNet(EEGModuleMixin, nn.Module):
         the depth of the network after the initial layer. Default is 16.
     attention_mode : str, optional
         The type of attention mechanism to apply. If `None`, no attention is applied.
-            - "se" for Squeeze-and-excitation network
-            - "gsop" for Global Second-Order Pooling
-            - "fca" for Frequency Channel Attention Network
-            - "encnet" for context encoding module
-            - "eca" for Efficient channel attention for deep convolutional neural networks
-            - "ge" for Gather-Excite
-            - "gct" for Gated Channel Transformation
-            - "srm" for Style-based Recalibration Module
-            - "cbam" for Convolutional Block Attention Module
-            - "cat" for Learning to collaborate channel and temporal attention
-            from multi-information fusion
-            - "catlite" for Learning to collaborate channel attention
-        from multi-information fusion (lite version, cat w/o temporal attention)
+
+        - "se" for Squeeze-and-excitation network
+        - "gsop" for Global Second-Order Pooling
+        - "fca" for Frequency Channel Attention Network
+        - "encnet" for context encoding module
+        - "eca" for Efficient channel attention for deep convolutional neural networks
+        - "ge" for Gather-Excite
+        - "gct" for Gated Channel Transformation
+        - "srm" for Style-based Recalibration Module
+        - "cbam" for Convolutional Block Attention Module
+        - "cat" for Learning to collaborate channel and temporal attention
+          from multi-information fusion
+        - "catlite" for Learning to collaborate channel attention
+          from multi-information fusion (lite version, cat w/o temporal attention)
+
     pool_length : int, default=8
         The length of the window for the average pooling operation.
     pool_stride : int, default=8
@@ -381,6 +385,8 @@ class AttentionBaseNet(EEGModuleMixin, nn.Module):
         for k, pl, ps in zip(kernel_lengths, pool_lengths, pool_strides):
             out = math.floor(out + 2 * (k // 2) - k + 1)
             out = math.floor((out - pl) / ps + 1)
+            # Ensure output is at least 1 to avoid zero-sized tensors
+            out = max(1, out)
             seq_lengths.append(int(out))
         return seq_lengths
 
@@ -497,6 +503,7 @@ class _ChannelAttentionBlock(nn.Module):
     ----------
     attention_mode : str, optional
         The type of attention mechanism to apply. If `None`, no attention is applied.
+
         - "se" for Squeeze-and-excitation network
         - "gsop" for Global Second-Order Pooling
         - "fca" for Frequency Channel Attention Network