Braindecode 1.3.2.dev168583761__tar.gz → 1.3.2.dev169626090__tar.gz

{braindecode-1.3.2.dev168583761/braindecode.egg-info → braindecode-1.3.2.dev169626090}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.3.2.dev168583761
+Version: 1.3.2.dev169626090
 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.3.2.dev168583761 → braindecode-1.3.2.dev169626090}/braindecode/datasets/bids/hub.py

@@ -103,7 +103,7 @@ class HubDatasetMixin:
         compression: str = "blosc",
         compression_level: int = 5,
         pipeline_name: str = "braindecode",
-        chunk_size: int = 5_000_000,
+        chunk_size: int = 10000,
         local_cache_dir: str | Path | None = None,
         **kwargs,
     ) -> str:
@@ -129,13 +129,10 @@ class HubDatasetMixin:
             Compression level (0-9). Level 5 provides optimal balance.
         pipeline_name : str, default="braindecode"
             Name of the processing pipeline for BIDS sourcedata.
-        chunk_size : int, default=5_000_000
-            Number of samples per chunk in Zarr along the time/window dimension.
-            Larger chunk sizes create fewer but larger chunks/files. This parameter
-            is used for both continuous data (e.g., RawDataset, EEGWindowsDataset)
-            and pre-cut windows (WindowsDataset). For WindowsDataset, multiple
-            windows may be stored in a single chunk depending on their duration
-            and the chosen ``chunk_size``.
+        chunk_size : int, default=10000
+            Number of samples per chunk in Zarr. Larger chunk size will create fewer
+            but larger files. Only used for RawDataset and EEGWindowsDataset (continuous data).
+            With WindowsDataset (pre-cut epochs), each window is saved as a separate chunk.
         local_cache_dir : str | Path | None
             Local directory to use for temporary files during upload. If None, uses
             the system temp directory and cleans it up after upload. If provided,
@@ -660,7 +657,7 @@ class HubDatasetMixin:
         output_path: Path,
         compression: str,
         compression_level: int,
-        chunk_size: int = 5_000_000,
+        chunk_size: int = 10000,
     ) -> None:
         """Convert dataset to Zarr format (inline implementation)."""
 
@@ -726,14 +723,7 @@ class HubDatasetMixin:
 
                 # Save using inlined function
                 _save_windows_to_zarr(
-                    grp,
-                    data,
-                    metadata,
-                    description,
-                    info_dict,
-                    compressor,
-                    target_name,
-                    chunk_size,
+                    grp, data, metadata, description, info_dict, compressor, target_name
                 )
 
             elif dataset_type == "EEGWindowsDataset":

{braindecode-1.3.2.dev168583761 → braindecode-1.3.2.dev169626090}/braindecode/datasets/bids/hub_io.py

@@ -45,25 +45,16 @@ def _restore_nan_from_json(obj):
 
 
 def _save_windows_to_zarr(
-    grp, data, metadata, description, info, compressor, target_name, chunk_size
+    grp, data, metadata, description, info, compressor, target_name
 ):
     """Save windowed data to Zarr group (low-level function)."""
     data_array = data.astype(np.float32)
     compressors_list = [compressor] if compressor is not None else None
 
-    max_windows_per_chunk = max(
-        1, chunk_size // (data_array.shape[1] * data_array.shape[2])
-    )
-    n_windows_per_chunk = min(data_array.shape[0], max_windows_per_chunk)
-
     grp.create_array(
         "data",
         data=data_array,
-        chunks=(
-            n_windows_per_chunk,
-            data_array.shape[1],
-            data_array.shape[2],
-        ),
+        chunks=(1, data_array.shape[1], data_array.shape[2]),
         compressors=compressors_list,
     )
 
@@ -94,13 +85,10 @@ def _save_eegwindows_to_zarr(
     continuous_float = continuous_data.astype(np.float32)
     compressors_list = [compressor] if compressor is not None else None
 
-    max_samples_per_chunk = max(1, chunk_size // continuous_float.shape[0])
-    n_samples_per_chunk = min(continuous_float.shape[1], max_samples_per_chunk)
-
     grp.create_array(
         "data",
         data=continuous_float,
-        chunks=(continuous_float.shape[0], n_samples_per_chunk),
+        chunks=(continuous_float.shape[0], min(chunk_size, continuous_float.shape[1])),
         compressors=compressors_list,
     )
 
@@ -169,13 +157,10 @@ def _save_raw_to_zarr(grp, raw, description, info, target_name, compressor, chun
     continuous_float = continuous_data.astype(np.float32)
     compressors_list = [compressor] if compressor is not None else None
 
-    max_samples_per_chunk = max(1, chunk_size // continuous_float.shape[0])
-    n_samples_per_chunk = min(continuous_float.shape[1], max_samples_per_chunk)
-
     grp.create_array(
         "data",
         data=continuous_float,
-        chunks=(continuous_float.shape[0], n_samples_per_chunk),
+        chunks=(continuous_float.shape[0], min(chunk_size, continuous_float.shape[1])),
         compressors=compressors_list,
     )
 

{braindecode-1.3.2.dev168583761 → braindecode-1.3.2.dev169626090}/braindecode/datautil/hub_formats.py

@@ -36,7 +36,7 @@ def convert_to_zarr(
     output_path: Union[str, Path],
     compression: str = "blosc",
     compression_level: int = 5,
-    chunk_size: int = 5_000_000,
+    chunk_size: int = 10000,
     overwrite: bool = False,
 ) -> Path:
     """Convert BaseConcatDataset to Zarr format.
@@ -59,13 +59,10 @@ def convert_to_zarr(
         blosc uses zstd codec by default, providing best balance of speed and compression.
     compression_level : int, default=5
         Compression level (0-9). Level 5 provides optimal balance based on benchmarks.
-    chunk_size : int, default=5_000_000
-        Target chunk size for Zarr storage.
-        For continuous data (e.g., RawDataset, EEGWindowsDataset), this is interpreted
-        as the approximate number of samples per chunk; larger values create fewer but
-        larger chunks on disk.
-        For pre-cut windowed data (WindowsDataset), this controls how many windows are
-        grouped together in each chunk (i.e., multiple windows can be stored per chunk).
+    chunk_size : int, default=10000
+        Number of samples per chunk in Zarr. Larger chunk size will create fewer
+        but larger files. Only used for RawDataset and EEGWindowsDataset (continuous data).
+        With WindowsDataset (pre-cut epochs), each window is saved as a separate chunk.
     overwrite : bool, default=False
         Whether to overwrite existing directory.
 
@@ -77,11 +74,8 @@ def convert_to_zarr(
     Notes
     -----
     The chunking strategy is optimized for random access:
-    - Windowed data: Windows are stored in chunks of shape
-      (n_windows_in_chunk, n_channels, n_times), where n_windows_in_chunk is
-      determined by ``chunk_size``.
-    - Raw / continuous data: Time is split into chunks of approximately
-      ``chunk_size`` samples (per channel), e.g., (n_channels, n_times_per_chunk).
+    - Windowed data: Each window is a separate chunk (1, n_channels, n_times)
+    - Raw data: Chunks of (n_channels, 10000) samples
 
     Examples
     --------

{braindecode-1.3.2.dev168583761 → braindecode-1.3.2.dev169626090}/braindecode/models/__init__.py

@@ -12,7 +12,6 @@ from .contrawr import ContraWR
 from .ctnet import CTNet
 from .deep4 import Deep4Net
 from .deepsleepnet import DeepSleepNet
-from .dgcnn import DGCNN
 from .eegconformer import EEGConformer
 from .eeginception_erp import EEGInceptionERP
 from .eeginception_mi import EEGInceptionMI
@@ -88,7 +87,6 @@ __all__ = [
     "EEGSym",
     "EEGSimpleConv",
     "EEGTCNet",
-    "DGCNN",
     "FBCNet",
     "FBLightConvNet",
     "FBMSNet",

{braindecode-1.3.2.dev168583761 → braindecode-1.3.2.dev169626090}/braindecode/models/base.py

@@ -86,44 +86,38 @@ class EEGModuleMixin(_BaseHubMixin, metaclass=NumpyDocstringInheritanceInitMeta)
     -----
     If some input signal-related parameters are not specified,
     there will be an attempt to infer them from the other parameters.
-    """
 
-    #: Template for model-specific Hub integration notes appended by
-    #: ``__init_subclass__``.  ``{name}`` is replaced with the concrete
-    #: model class name.
-    _HUB_NOTES_TEMPLATE = """
     .. rubric:: Hugging Face Hub integration
 
     When the optional ``huggingface_hub`` package is installed, all models
     automatically gain the ability to be pushed to and loaded from the
     Hugging Face Hub. Install with::
 
-        pip install braindecode[hub]
+        pip install braindecode[hug]
 
     **Pushing a model to the Hub:**
 
-    .. code-block::
+    .. code-block:: python
 
-        from braindecode.models import {name}
+        from braindecode.models import EEGNetv4
 
         # Train your model
-        model = {name}(n_chans=22, n_outputs=4, n_times=1000)
+        model = EEGNetv4(n_chans=22, n_outputs=4, n_times=1000)
         # ... training code ...
 
         # Push to the Hub
         model.push_to_hub(
-            repo_id="username/my-{name_lower}-model",
-            commit_message="Initial model upload",
+            repo_id="username/my-eegnet-model", commit_message="Initial model upload"
         )
 
     **Loading a model from the Hub:**
 
-    .. code-block::
+    .. code-block:: python
 
-        from braindecode.models import {name}
+        from braindecode.models import EEGNetv4
 
         # Load pretrained model
-        model = {name}.from_pretrained("username/my-{name_lower}-model")
+        model = EEGNetv4.from_pretrained("username/my-eegnet-model")
 
     The integration automatically handles EEG-specific parameters (n_chans,
     n_times, sfreq, chs_info, etc.) by saving them in a config file alongside
@@ -132,24 +126,19 @@ class EEGModuleMixin(_BaseHubMixin, metaclass=NumpyDocstringInheritanceInitMeta)
 
     .. important::
         Currently, only EEG-specific parameters (n_outputs, n_chans, n_times,
-        input_window_seconds, sfreq, chs_info) are saved to the Hub.
-        Model-specific parameters (e.g., dropout rates, activation functions,
-        number of filters) are not preserved and will use their default values
-        when loading from the Hub.
+        input_window_seconds, sfreq, chs_info) are saved to the Hub. Model-specific
+        parameters (e.g., dropout rates, activation functions, number of filters)
+        are not preserved and will use their default values when loading from the Hub.
+
+        To use non-default model parameters, specify them explicitly when calling
+        :func:`from_pretrained()`::
+
+            model = EEGNet.from_pretrained("user/model", dropout=0.3, activation='relu')
+
         Full parameter serialization will be addressed in a future update.
     """
 
     def __init_subclass__(cls, **kwargs):
-        # Append model-specific Hub integration notes to the docstring.
-        # This runs after the metaclass, so we concatenate rather than
-        # override any existing Notes section in the subclass.
-        if cls.__doc__ is not None:
-            hub_notes = cls._HUB_NOTES_TEMPLATE.format(
-                name=cls.__name__,
-                name_lower=cls.__name__.lower(),
-            )
-            cls.__doc__ = cls.__doc__.rstrip() + "\n" + hub_notes
-
         if not HAS_HF_HUB:
             super().__init_subclass__(**kwargs)
             return

{braindecode-1.3.2.dev168583761 → braindecode-1.3.2.dev169626090}/braindecode/models/bendr.py

@@ -3,10 +3,8 @@ import copy
 import torch
 from einops.layers.torch import Rearrange
 from torch import nn
-from torch.nn.utils.parametrize import register_parametrization
 
 from braindecode.models.base import EEGModuleMixin
-from braindecode.modules.parametrization import MaxNormParametrize
 
 
 class BENDR(EEGModuleMixin, nn.Module):
@@ -185,25 +183,6 @@ class BENDR(EEGModuleMixin, nn.Module):
     final_layer : bool, default=True
         If True, includes a final linear classification layer that maps from encoder_h to
         n_outputs. If False, the model outputs the contextualized features directly.
-    encoder_only : bool, default=False
-        If True, bypass the contextualizer and use 4-chunk temporal pooling on the encoder
-        output instead. This corresponds to the encoder-only configuration described in
-        Section 2.4 and Table 2 of Kostas et al. (2021) [bendr]_, which outperformed the
-        full model on 4 out of 5 downstream tasks. The encoder output is split into 4 equal
-        temporal chunks, each chunk is mean-pooled, and the results are concatenated to
-        produce a feature vector of size ``encoder_h * 4`` (2048-dim with default settings).
-        The contextualizer is still created (to allow loading pretrained weights) but is not
-        used in the forward pass. Requires input length of at least
-        ``4 * product(enc_downsample)`` samples (384 with default downsampling of 96x).
-    n_chans_pretrained : int or None, default=None
-        Number of input channels the pretrained weights expect (20 for the official BENDR
-        checkpoint). When set and ``n_chans != n_chans_pretrained``, a 1x1 Conv1d with
-        max-norm constraint projects from ``n_chans`` to ``n_chans_pretrained`` before the
-        encoder. This allows fine-tuning pretrained BENDR on datasets with arbitrary channel
-        counts. When using ``from_pretrained``, pass ``strict=False`` since the checkpoint
-        will not contain ``channel_projection`` weights.
-    chan_proj_max_norm : float, default=1.0
-        Max-norm constraint value for the channel projection weights.
     """
 
     def __init__(
@@ -230,9 +209,6 @@ class BENDR(EEGModuleMixin, nn.Module):
         enc_downsample=(3, 2, 2, 2, 2, 2),
         start_token=-5,  # Value for start token embedding
         final_layer=True,  # Whether to include the final linear layer
-        encoder_only=False,  # If True, bypass contextualizer and use 4-chunk pooling
-        n_chans_pretrained=None,  # Expected input channels of pretrained weights
-        chan_proj_max_norm=1.0,  # Max-norm for channel projection weights
     ):
         super().__init__(
             n_outputs=n_outputs,
@@ -249,22 +225,10 @@ class BENDR(EEGModuleMixin, nn.Module):
         self.encoder_h = encoder_h
         self.contextualizer_hidden = contextualizer_hidden
         self.include_final_layer = final_layer
-        self.encoder_only = encoder_only
-
-        # Channel projection for pretrained weight compatibility
-        encoder_n_chans = self.n_chans
-        if n_chans_pretrained is not None and self.n_chans != n_chans_pretrained:
-            conv = nn.Conv1d(self.n_chans, n_chans_pretrained, 1, bias=False)
-            register_parametrization(
-                conv, "weight", MaxNormParametrize(chan_proj_max_norm)
-            )
-            self.channel_projection = conv
-            encoder_n_chans = n_chans_pretrained
-        else:
-            self.channel_projection = None
 
+        # Encoder: Use parameters from __init__
         self.encoder = _ConvEncoderBENDR(
-            in_features=encoder_n_chans,
+            in_features=self.n_chans,
             encoder_h=encoder_h,
             dropout=drop_prob,
             projection_head=projection_head,
@@ -284,49 +248,35 @@ class BENDR(EEGModuleMixin, nn.Module):
             layer_drop=layer_drop,
             start_token=start_token,  # Keep fixed start token value
         )
-        # encoder_only → 4-chunk pooling produces encoder_h*4 features
-        # full model → start token produces encoder_h features
-        if self.encoder_only:
-            in_features = encoder_h * 4
-        else:
-            in_features = encoder_h
+        in_features = self.encoder.encoder_h  # Set in_features for final layer
 
         self.final_layer = None
         if self.include_final_layer:
-            # in_features: encoder_h*4 (encoder_only) or encoder_h (full model)
+            # Input to Linear will be [batch_size, encoder_h] after taking last timestep
             linear = nn.Linear(in_features=in_features, out_features=self.n_outputs)
             self.final_layer = nn.utils.parametrizations.weight_norm(
                 linear, name="weight", dim=1
             )
 
     def forward(self, x):
-        if self.channel_projection is not None:
-            x = self.channel_projection(x)
+        # Input x: [batch_size, n_chans, n_times]
         encoded = self.encoder(x)
         # encoded: [batch_size, encoder_h, n_encoded_times]
 
-        if self.encoder_only:
-            # 4-chunk temporal pooling (Kostas et al. 2021, Section 2.4)
-            n_time = encoded.shape[2]
-            if n_time < 4:
-                raise RuntimeError(
-                    f"Encoder output has {n_time} time steps, which is too few "
-                    f"for 4-chunk pooling (need at least 4). Increase input length."
-                )
-            # Use tensor_split for uneven chunks so no frames are dropped
-            chunks = torch.tensor_split(encoded, 4, dim=2)
-            feature = torch.cat([c.mean(dim=2) for c in chunks], dim=1)
-            # feature: [batch_size, encoder_h * 4]
-        else:
-            context = self.contextualizer(encoded)
-            # context: [batch_size, encoder_h, n_encoded_times + 1] (due to start token)
-
-            # Extract features - use the output corresponding to the start token (index 0)
-            # According to the paper (Kostas et al. 2021): "The transformer output of this
-            # initial position was not modified during pre-training, and only used for
-            # downstream tasks." This follows BERT's [CLS] token convention.
-            feature = context[:, :, 0]
-            # feature: [batch_size, encoder_h]
+        context = self.contextualizer(encoded)
+        # context: [batch_size, encoder_h, n_encoded_times + 1] (due to start token)
+
+        # Extract features - use the output corresponding to the start token (index 0)
+        # The output has shape [batch_size, features, seq_len+1]
+        # The start token was prepended at position 0 in the contextualizer before the
+        # transformer layers. After permutation back to [batch, features, seq_len+1],
+        # the start token output is at index 0.
+        # According to the paper (Kostas et al. 2021): "The transformer output of this
+        # initial position was not modified during pre-training, and only used for
+        # downstream tasks." This follows BERT's [CLS] token convention where the
+        # first token aggregates sequence information via self-attention.
+        feature = context[:, :, 0]
+        # feature: [batch_size, encoder_h]
 
         if self.final_layer is not None:
             feature = self.final_layer(feature)

{braindecode-1.3.2.dev168583761 → braindecode-1.3.2.dev169626090}/braindecode/models/eegsym.py

@@ -112,7 +112,7 @@ class EEGSym(EEGModuleMixin, nn.Module):
         corresponding to different frequency characteristics.
 
     Notes
-    -----
+    ----------
     * EEGSym achieved competitive accuracies across five large MI datasets [eegsym2022]_.
     * The model maintained high accuracy using a reduced set of electrodes (8 or 16 channels)
       [eegsym2022]_.

{braindecode-1.3.2.dev168583761 → braindecode-1.3.2.dev169626090}/braindecode/models/sstdpn.py

@@ -133,7 +133,7 @@ class SSTDPN(EEGModuleMixin, nn.Module):
         learning data, according to [Han2025]_.
 
     Notes
-    -----
+    ----------
     * The implementation of the DPL loss functions (:math:`\mathcal{L}_S`, :math:`\mathcal{L}_C`, :math:`\mathcal{L}_{EF}`)
       and the optimization of ICPs are typically handled outside the primary ``forward`` method, within the training strategy
       (see Ref. 52 in [Han2025]_).

{braindecode-1.3.2.dev168583761 → braindecode-1.3.2.dev169626090}/braindecode/models/summary.csv

@@ -47,4 +47,3 @@ BENDR,General,"Classification,Embedding",250,"n_chans, n_times, n_outputs",15714
 LUNA,General,"Classification,Embedding",128,"n_chans, n_times, sfreq, chs_info",7100731,"LUNA(n_chans=22, n_times=512, sfreq=128)","Convolution,Channel,Foundation Model"
 MEDFormer,General,Classification,250,"n_chans, n_outputs, n_times",5313924,"MEDFormer(n_chans=22, n_outputs=4, n_times=1000)","Foundation Model,Convolution"
 REVE,General,Classification,200,"n_outputs, n_times, n_chans",69481476,"REVE(n_times=1000, n_outputs=4, n_chans=19)","Foundation Model,Attention/Transformer"
-DGCNN,Emotion Recognition,Classification,128,"n_chans, n_outputs, n_times, chs_info",1037385,"DGCNN(n_chans=62, n_outputs=4, n_times=128)","Graph Neural Network,Channel"

{braindecode-1.3.2.dev168583761 → braindecode-1.3.2.dev169626090}/braindecode/models/util.py

@@ -133,7 +133,6 @@ models_mandatory_parameters: list[
         },
     ),
     ("CBraMod", ["n_outputs"], None),
-    ("DGCNN", ["n_chans", "n_outputs", "n_times", "chs_info"], None),
 ]
 
 ################################################################
@@ -302,7 +301,7 @@ def extract_channel_locations_from_chs_info(
     ----------
     chs_info : list of dict or None
         Channel information, typically from ``mne.Info.chs``. Each dict should
-        contain a 'loc' key with a 12-element array (MNE format) where indices 0:3
+        contain a 'loc' key with a 12-element array (MNE format) where indices 3:6
         represent the 3D cartesian coordinates.
     num_channels : int or None
         If specified, only extract the first ``num_channels`` channel locations.
@@ -316,7 +315,7 @@ def extract_channel_locations_from_chs_info(
 
     Notes
     -----
-    - This function handles both 12-element MNE location format (using indices 0:3)
+    - This function handles both 12-element MNE location format (using indices 3:6)
       and 3-element location format (using directly).
     - Invalid or missing locations cause extraction to stop at that point.
     - Returns None if no valid locations can be extracted.
@@ -348,9 +347,14 @@ def extract_channel_locations_from_chs_info(
         try:
             loc_array = np.asarray(loc, dtype=np.float32)
 
-            # MNE format: 12-element array with electrode position at indices 0:3
-            if loc_array.ndim == 1 and loc_array.size >= 3:
-                coordinates = loc_array[:3]
+            # MNE format: 12-element array with coordinates at indices 3:6
+            if loc_array.ndim == 1 and loc_array.size >= 6:
+                if loc_array.size == 12:
+                    # Standard MNE format
+                    coordinates = loc_array[3:6]
+                else:
+                    # Assume first 3 elements are coordinates
+                    coordinates = loc_array[:3]
             else:
                 break
 
@@ -361,13 +365,7 @@ def extract_channel_locations_from_chs_info(
     if len(locations) == 0:
         return None
 
-    result = np.stack(locations, axis=0)
-
-    # Check positions are not all zero / degenerate
-    if np.allclose(result, 0):
-        return None
-
-    return result
+    return np.stack(locations, axis=0)
 
 
 _summary_table = get_summary_table()

{braindecode-1.3.2.dev168583761 → braindecode-1.3.2.dev169626090}/braindecode/modules/attention.py

@@ -8,7 +8,6 @@ AttentionBaseNet class.
 
 # Authors: Martin Wimpff <martin.wimpff@iss.uni-stuttgart.de>
 #          Bruno Aristimunha <b.aristimunha@gmail.com>
-#          Sarthak Tayal <sarthaktayal2@gmail.com>
 #
 # License: BSD (3-clause)
 
@@ -61,7 +60,7 @@ class SqueezeAndExcitation(nn.Module):
         )
         self.nonlinearity = nn.ReLU()
         self.fc2 = nn.Conv2d(
-            in_channels=sq_channels,
+            in_channels=reduction_rate,
             out_channels=in_channels,
             kernel_size=1,
             bias=bias,

{braindecode-1.3.2.dev168583761 → braindecode-1.3.2.dev169626090}/braindecode/preprocessing/mne_preprocess.py

@@ -11,7 +11,6 @@ import mne.io
 import mne.preprocessing
 
 from braindecode.preprocessing.preprocess import Preprocessor
-from braindecode.util import _clean_docstring_sections
 
 
 def _is_standalone_function(func):
@@ -150,7 +149,7 @@ def _generate_mne_pre_processor(function):
     force_copy_false = is_standalone and has_copy_param
     class_attrs = {
         "__init__": _generate_init_method(function, force_copy_false),
-        "__doc__": wrapper_note + _clean_docstring_sections(function.__doc__ or ""),
+        "__doc__": wrapper_note + (function.__doc__ or ""),
         "__repr__": _generate_repr_method(class_name),
         "fn": function if is_standalone else function.__name__,
         "_is_standalone": is_standalone,