braindecode 1.8.1.dev169883370__tar.gz → 1.8.1.dev170036056__tar.gz

{braindecode-1.8.1.dev169883370 → braindecode-1.8.1.dev170036056}/NOTICE.txt

@@ -52,6 +52,7 @@ The following components are licensed under the MIT License:
 - `braindecode/modules/linear_attention.py`
 - `braindecode/models/seizure_transformer.py`
 - `docs/_static/model/seizure_transformer_arch.png`
+- `braindecode/models/guetschel2026.py`
 - `braindecode/models/tmsanet.py`
 
 The `brainomni.py` file is a derivative of `OpenTSLab/BrainOmni` (MIT), whose

{braindecode-1.8.1.dev169883370/braindecode.egg-info → braindecode-1.8.1.dev170036056}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.8.1.dev169883370
+Version: 1.8.1.dev170036056
 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.1.dev169883370 → braindecode-1.8.1.dev170036056}/braindecode/augmentation/functional.py

@@ -932,7 +932,7 @@ def _rotate_signals(
         transformed_X = X.clone()
         sensors_positions = list(sensors_positions_matrix)
         for s, rot_sensors_matrix in enumerate(rot_sensors_matrices):
-            rot_sensors_positions = list(rot_sensors_matrix.T)
+            rot_sensors_positions = list(rot_sensors_matrix)
             for time in range(X.shape[-1]):
                 interpolator_t = Rbf(*sensors_positions, X[s, :, time])
                 transformed_X[s, :, time] = torch.from_numpy(

{braindecode-1.8.1.dev169883370 → braindecode-1.8.1.dev170036056}/braindecode/datasets/base.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 import bisect
 import html as _html
 import json
+import mmap
 import os
 import shutil
 import warnings
@@ -28,6 +29,7 @@ import mne
 import mne.io
 import numpy as np
 import pandas as pd
+from mne.io.constants import FIFF
 from mne.utils import _soft_import
 from mne.utils.docs import deprecated
 from torch.utils.data import ConcatDataset, Dataset, IterableDataset
@@ -220,6 +222,47 @@ def _compute_ch_pos(info, targets_from):
     return pos
 
 
+def _read_fif_window(raw, start, stop):
+    """Samples ``start:stop`` of a lazy FIF raw, copied from the file in one go.
+
+    mne reads, casts and calibrates the FIF data buffers of a range one at a
+    time (60 Python steps for a 60-s window saved with 1-s buffers, each through
+    a buffered file whose buffer is 4 MB on network file systems). Here one
+    slice of the memory-mapped file holds the bytes of every buffer in the
+    range and one multiply calibrates them, with mne's arithmetic (float64 data
+    times ``raw._cals``), so the values equal ``raw._getitem``'s. Returns None
+    (the caller uses mne) unless ``raw`` is a lazy, single-file, uncompressed
+    FIF raw of float32 buffers without projector, compensation or gaps.
+    """
+    if (
+        not isinstance(raw, mne.io.Raw)
+        or raw.preload
+        or len(raw._raw_extras) != 1
+        or raw._projector is not None
+        or raw._comp is not None
+    ):
+        return None
+    extra = raw._raw_extras[0]
+    fname, bounds = extra["filename"], extra["bounds"]
+    if not isinstance(fname, Path) or fname.suffix == ".gz":
+        return None
+    start, stop = start + raw._first_samps[0], stop + raw._first_samps[0]
+    first = np.searchsorted(bounds, start, side="right") - 1
+    ents = extra["ent"][first : np.searchsorted(bounds, stop)]
+    if not ents or any(e is None or e.type != FIFF.FIFFT_FLOAT for e in ents):
+        return None
+    pos = ents[0].pos
+    # mmap: no copy through a 4 MB read buffer, and a cold file is read around
+    # the window by the kernel (as mne's 4 MB reads did), not window by window
+    with open(fname, "rb") as f, mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ) as m:
+        buf = m[pos : ents[-1].pos + 16 + ents[-1].size]
+    one = np.concatenate(
+        [np.frombuffer(buf, ">f4", e.size // 4, e.pos + 16 - pos) for e in ents]
+    ).reshape(-1, extra["orig_nchan"])[start - bounds[first] : stop - bounds[first]]
+    picked = one[:, raw._read_picks[0]].T
+    return np.multiply(picked, raw._cals[:, np.newaxis], order="C")
+
+
 def _window_info(crop_inds, sfreq):
     """Extract window size from crop indices.
 
@@ -823,9 +866,11 @@ class EEGWindowsDataset(_ZarrMixin, RecordDataset):
         if self._zarr_data is not None:
             X = self._zarr_data[:, i_start:i_stop]
         else:
-            X = self.raw._getitem(
-                (slice(None), slice(i_start, i_stop)), return_times=False
-            )
+            X = _read_fif_window(self.raw, i_start, i_stop)
+            if X is None:
+                X = self.raw._getitem(
+                    (slice(None), slice(i_start, i_stop)), return_times=False
+                )
         X = np.array(X, dtype="float32")
         if self.transform is not None:
             X = self.transform(X)
@@ -1672,7 +1717,8 @@ class BaseConcatDataset(ConcatDataset, HubDatasetMixin, Generic[T]):
                 kwargs_path = os.path.join(path, ".".join([kwarg_name, "json"]))
                 kwargs = getattr(self, kwarg_name)
                 if kwargs is not None:
-                    json.dump(kwargs, open(kwargs_path, "w"))
+                    with open(kwargs_path, "w") as f:
+                        json.dump(kwargs, f)
 
     @property
     def description(self) -> pd.DataFrame:
@@ -1742,7 +1788,10 @@ class BaseConcatDataset(ConcatDataset, HubDatasetMixin, Generic[T]):
         # Create path if it doesn't exist
         os.makedirs(path, exist_ok=True)
 
-        path_contents = os.listdir(path)
+        # With an offset the caller fills one directory piece by piece (preprocess
+        # saves each recording at its index), so the other entries are expected:
+        # skip the scan that would stat them all on every call and list them in a warning.
+        path_contents = os.listdir(path) if offset == 0 else []
         n_sub_dirs = len(
             [e for e in path_contents if os.path.isdir(os.path.join(path, e))]
         )

{braindecode-1.8.1.dev169883370 → braindecode-1.8.1.dev170036056}/braindecode/datasets/tuh.py

@@ -11,10 +11,12 @@ TUH Abnormal EEG Corpus.
 from __future__ import annotations
 
 import glob
+import json
 import os
 import re
 import warnings
 from datetime import datetime, timezone
+from functools import cache
 from pathlib import Path
 from typing import Iterable, Literal
 from unittest import mock
@@ -183,11 +185,8 @@ class TUH(BaseConcatDataset):
         }
         raw.rename_channels(mapping_strip)
 
-        montage1005 = mne.channels.make_standard_montage(
-            resolve_montage_name("standard_1005")
-        )
         mapping_eeg_names = {
-            c.upper(): c for c in montage1005.ch_names if c.upper() in raw.ch_names
+            c.upper(): c for c in _standard_1005().ch_names if c.upper() in raw.ch_names
         }
 
         # Set channels whose type could not be inferred (defaulted to "eeg") to "misc":
@@ -210,10 +209,7 @@ class TUH(BaseConcatDataset):
 
     @staticmethod
     def _set_montage(raw):
-        montage = mne.channels.make_standard_montage(
-            resolve_montage_name("standard_1005")
-        )
-        raw.set_montage(montage, on_missing="ignore")
+        raw.set_montage(_standard_1005(), on_missing="ignore")
 
     @staticmethod
     def _create_dataset(
@@ -245,7 +241,11 @@ class TUH(BaseConcatDataset):
         # file paths, use this instead as before
         if "year" in description:
             meas_date = meas_date.replace(*description[["year", "month", "day"]])
-        raw.set_meas_date(meas_date)
+        # FIF (e.g. preprocess(..., save_dir=...)) stores dates from 1901-12-13 to
+        # 2038-01-19 only: undated recordings (year 1 above) and de-identified ones
+        # (TUAB has 1899-12-30) keep their date in the description only.
+        in_fif_range = -(2**31) <= meas_date.timestamp() < 2**31
+        raw.set_meas_date(meas_date if in_fif_range else None)
 
         d = {
             "age": int(age),
@@ -255,9 +255,9 @@ class TUH(BaseConcatDataset):
         # if not, get it from meas_date in raw.info and add to description
         # if meas_date is None, create fake one
         if "year" not in description:
-            d["year"] = raw.info["meas_date"].year
-            d["month"] = raw.info["meas_date"].month
-            d["day"] = raw.info["meas_date"].day
+            d["year"] = meas_date.year
+            d["month"] = meas_date.month
+            d["day"] = meas_date.day
 
         # read info relevant for preprocessing from raw without loading it
         if add_physician_reports:
@@ -269,6 +269,12 @@ class TUH(BaseConcatDataset):
         return base_dataset
 
 
+@cache
+def _standard_1005():
+    # Built once per process: set_montage copies the montage before using it.
+    return mne.channels.make_standard_montage(resolve_montage_name("standard_1005"))
+
+
 def _create_description(file_paths, version, ds_name):
     descriptions = [
         _parse_description_from_file_path(f, version, ds_name) for f in file_paths
@@ -289,7 +295,8 @@ def _read_date(file_path):
     date_path = file_path.replace(".edf", "_date.txt")
     # if date file exists, read it
     if os.path.exists(date_path):
-        description = pd.read_json(date_path, typ="series").to_dict()
+        with open(date_path) as f:
+            description = json.load(f)
     # otherwise read edf file, extract date and store to file
     else:
         raw = mne.io.read_raw_edf(file_path, preload=False, verbose="error")

{braindecode-1.8.1.dev169883370 → braindecode-1.8.1.dev170036056}/braindecode/datautil/serialization.py

@@ -79,7 +79,8 @@ def _outdated_load_concat_dataset(path, preload, ids_to_load=None, target_name=N
     for path in paths:
         if is_raw and target_name is None:
             target_file_name = path / "target_name.json"
-            target_name = json.load(open(target_file_name, "r"))["target_name"]
+            with open(target_file_name) as f:
+                target_name = json.load(f)["target_name"]
 
         all_signals, description = _load_signals_and_description(
             path=path, preload=preload, is_raw=is_raw, ids_to_load=ids_to_load
@@ -264,7 +265,8 @@ def _load_parallel(path, i, preload, is_raw, has_stored_windows):
     target_file_path = sub_dir / "target_name.json"
     target_name = None
     if target_file_path.exists():
-        target_name = json.load(open(target_file_path, "r"))["target_name"]
+        with open(target_file_path) as f:
+            target_name = json.load(f)["target_name"]
 
     if is_raw and (not has_stored_windows):
         dataset = RawDataset(signals, description, target_name)
@@ -304,8 +306,8 @@ def _load_kwargs_json(kwargs_name, sub_dir):
     kwargs_file_name = ".".join([kwargs_name, "json"])
     kwargs_file_path = os.path.join(sub_dir, kwargs_file_name)
     if os.path.exists(kwargs_file_path):
-        kwargs = json.load(open(kwargs_file_path, "r"))
-        return kwargs
+        with open(kwargs_file_path) as f:
+            return json.load(f)
 
 
 def _is_outdated_saved(path):

{braindecode-1.8.1.dev169883370 → braindecode-1.8.1.dev170036056}/braindecode/models/__init__.py

@@ -39,6 +39,7 @@ from .emg2qwerty import EMG2QwertyNet
 from .fbcnet import FBCNet
 from .fblightconvnet import FBLightConvNet
 from .fbmsnet import FBMSNet
+from .guetschel2026 import Guetschel2026
 from .hybrid import HybridNet
 from .ifnet import IFNet
 from .labram import Labram
@@ -139,6 +140,7 @@ __all__ = [
     "FBCNet",
     "FBLightConvNet",
     "FBMSNet",
+    "Guetschel2026",
     "MetaNeuromotorHand",
     "HybridNet",
     "IFNet",

{braindecode-1.8.1.dev169883370 → braindecode-1.8.1.dev170036056}/braindecode/models/attn_sleep.py

@@ -143,6 +143,10 @@ class AttnSleep(EEGModuleMixin, nn.Module):
             sfreq=sfreq,
         )
         del n_outputs, n_chans, chs_info, n_times, input_window_seconds, sfreq
+        if self._n_chans_for_jit not in (None, 1):
+            raise ValueError(
+                f"AttnSleep takes single-channel input; got n_chans={self._n_chans_for_jit}."
+            )
 
         self.mapping = {
             "fc.weight": "final_layer.weight",

{braindecode-1.8.1.dev169883370 → braindecode-1.8.1.dev170036056}/braindecode/models/base.py

@@ -46,6 +46,24 @@ _GEOMETRY_KWARGS = (
 )
 
 
+def _too_short_input_error(exc: RuntimeError, input_shape) -> Optional[ValueError]:
+    """ValueError for a layer that found the input too short, else None."""
+    if not str(exc).endswith(
+        (
+            "Output size is too small",
+            "Kernel size can't be greater than actual input size",
+        )
+    ):
+        return None
+    return ValueError(
+        "During model prediction RuntimeError was thrown showing that at some "
+        f"layer `{str(exc).split('.')[-1]}` (see above in the stacktrace). This "
+        "could be caused by providing too small `n_times`/`input_window_seconds`. "
+        "Model may require longer chunks of signal in the input than "
+        f"{input_shape}."
+    )
+
+
 _HF_INSTALL_HINT = (
     "requires the `huggingface_hub` package. "
     "Install with: pip install 'braindecode[hub]'"
@@ -483,6 +501,18 @@ class EEGModuleMixin(_BaseHubMixin, metaclass=_BraindecodeDocstringMeta):
         # Called by torch.jit.script before compiling the model.
         return make_parametrizations_scriptable(self)
 
+    def __call__(self, *args, **kwargs):
+        # An input shorter than the layers need raises ValueError, not a torch
+        # RuntimeError from deep inside forward.
+        try:
+            return super().__call__(*args, **kwargs)
+        except RuntimeError as exc:
+            shape = tuple(args[0].shape) if args and hasattr(args[0], "shape") else None
+            error = _too_short_input_error(exc, shape)
+            if error is None:
+                raise
+            raise error from exc
+
     def get_output_shape(self) -> tuple[int, ...]:
         """Returns shape of neural network output for batch size equal 1.
 
@@ -506,21 +536,10 @@ class EEGModuleMixin(_BaseHubMixin, metaclass=_BraindecodeDocstringMeta):
                     .shape
                 )
             except RuntimeError as exc:
-                if str(exc).endswith(
-                    (
-                        "Output size is too small",
-                        "Kernel size can't be greater than actual input size",
-                    )
-                ):
-                    msg = (
-                        "During model prediction RuntimeError was thrown showing that at some "
-                        f"layer `{str(exc).split('.')[-1]}` (see above in the stacktrace). This "
-                        "could be caused by providing too small `n_times`/`input_window_seconds`. "
-                        "Model may require longer chunks of signal in the input than "
-                        f"{self.input_shape}."
-                    )
-                    raise ValueError(msg) from exc
-                raise exc
+                error = _too_short_input_error(exc, self.input_shape)
+                if error is None:
+                    raise
+                raise error from exc
 
     def get_config(self) -> dict:
         """Return a JSON-serializable dict of all ``__init__`` parameters.

{braindecode-1.8.1.dev169883370 → braindecode-1.8.1.dev170036056}/braindecode/models/brainomni.py

@@ -29,15 +29,21 @@ from braindecode.modules.quantization import ResidualVectorQuantizer
 
 
 class _SELU(nn.SELU):
-    """``nn.SELU`` written as ``scale * x`` / ELU: same values and gradients, and
-    trainable on Gaudi, whose ELU backward only supports ``scale == 1``."""
+    """``nn.SELU`` as ``ELU(x, alpha * scale)`` times ``scale`` where ``x > 0``:
+    same values and gradients, and trainable on Gaudi, whose ELU backward only
+    supports ``scale == 1``."""
 
     def forward(self, x: torch.Tensor) -> torch.Tensor:
         alpha, scale = (
             1.6732632423543772848170429916717,
             1.0507009873554804934193349852946,
         )
-        return torch.where(x > 0, x * scale, F.elu(x, alpha * scale))
+        # ELU is x on the positive side, so this equals the where(x > 0, x * scale,
+        # elu) form bit for bit, without its zero-filled where backward. The
+        # factor is at least float32, like the scalar multiply's compute type.
+        one = x.new_ones((), dtype=torch.promote_types(x.dtype, torch.float32))
+        factor = torch.where(x > 0, one * scale, one)
+        return (F.elu(x, alpha * scale) * factor).to(x.dtype)
 
 
 class BrainTokenizer(EEGModuleMixin, nn.Module, license="mit"):

{braindecode-1.8.1.dev169883370 → braindecode-1.8.1.dev170036056}/braindecode/models/csbrain.py

@@ -314,6 +314,11 @@ class CSBrain(EEGModuleMixin, nn.Module):
             sfreq=sfreq,
         )
         del n_chans, chs_info, n_times, input_window_seconds, sfreq, n_outputs
+        n_times = self._n_times_or_none()
+        if n_times is not None and n_times % patch_size:
+            raise ValueError(
+                f"n_times ({n_times}) must be a multiple of patch_size ({patch_size})."
+            )
 
         self.rearrange = Rearrange(
             "batch n_chans (n_patch patch_size) -> batch n_chans n_patch patch_size",

{braindecode-1.8.1.dev169883370 → braindecode-1.8.1.dev170036056}/braindecode/models/deep4.py

@@ -170,6 +170,10 @@ class Deep4Net(EEGModuleMixin, nn.Sequential):
         ):
             resolved_n_times = round(self._input_window_seconds * self._sfreq)
 
+        if resolved_n_times is not None and resolved_n_times >= min_n_times:
+            # The bound above ignores stride_before_pool and an integer
+            # final_conv_length; inputs it admits are checked with the exact one.
+            min_n_times = self._get_min_n_times(exact=True)
         if resolved_n_times is not None and resolved_n_times < min_n_times:
             scaling_factor = resolved_n_times / min_n_times
             warn(
@@ -363,13 +367,15 @@ class Deep4Net(EEGModuleMixin, nn.Sequential):
 
         self.train()
 
-    def _get_min_n_times(self) -> int:
+    def _get_min_n_times(self, exact: bool = False) -> int:
         """
         Calculate the minimum number of time samples required for the model
         to work with the given temporal parameters.
         """
         # Start with the minimum valid output length of the network (1)
         min_len = 1
+        if exact and isinstance(self.final_conv_length, int):
+            min_len = self.final_conv_length
 
         # List of conv kernel sizes and pool parameters for the 4 blocks, in reverse order
         # Each tuple: (filter_length, pool_length, pool_stride)
@@ -382,6 +388,9 @@ class Deep4Net(EEGModuleMixin, nn.Sequential):
 
         # Work backward from the last layer to the input
         for filter_len, pool_len, pool_stride in block_params:
+            if exact and self.stride_before_pool:  # strided conv, then pool stride 1
+                min_len = pool_stride * (min_len + pool_len - 2) + filter_len
+                continue
             # Reverse the pooling operation
             # L_in = stride * (L_out - 1) + kernel_size
             min_len = pool_stride * (min_len - 1) + pool_len

{braindecode-1.8.1.dev169883370 → braindecode-1.8.1.dev170036056}/braindecode/models/dgcnn.py

@@ -142,6 +142,11 @@ def _build_initial_adjacency(chs_info, n_chans, n_neighbors=5):
     electrode_positions = extract_channel_locations_from_chs_info(
         chs_info, num_channels=n_chans
     )
+    # MNE stores NaN for a channel without a position.
+    if electrode_positions is not None and not (
+        len(electrode_positions) == n_chans and np.isfinite(electrode_positions).all()
+    ):
+        electrode_positions = None
 
     if electrode_positions is None and chs_info is not None:
         # Try to infer positions from channel names via a standard montage
@@ -162,6 +167,8 @@ def _build_initial_adjacency(chs_info, n_chans, n_neighbors=5):
                 "with 3-D positions or that channel names match a standard montage."
             )
 
+    if n_chans < 2:
+        raise ValueError("DGCNN needs at least 2 channels to build its channel graph.")
     n_neighbors_capped = min(n_neighbors, n_chans - 1)
 
     # Pairwise Euclidean distances

{braindecode-1.8.1.dev169883370 → braindecode-1.8.1.dev170036056}/braindecode/models/eegnex.py

@@ -9,6 +9,7 @@ import torch
 import torch.nn as nn
 from einops.layers.torch import Rearrange
 
+from braindecode.functional import fft_conv1d, prefer_fft_conv
 from braindecode.models.base import EEGModuleMixin
 from braindecode.modules import Conv2dWithConstraint, LinearWithConstraint
 
@@ -234,7 +235,7 @@ class EEGNeX(EEGModuleMixin, nn.Module):
         )
 
         self.block_2 = nn.Sequential(
-            nn.Conv2d(
+            _TemporalConv(
                 in_channels=self.filter_1,
                 out_channels=self.filter_2,
                 kernel_size=self.kernel_block_1_2,
@@ -352,3 +353,17 @@ class EEGNeX(EEGModuleMixin, nn.Module):
             self.filter_1 * T5
         )  # filter_1 is the number of channels before flatten
         return final_in_features
+
+
+class _TemporalConv(nn.Conv2d):
+    """``(1, k)`` Conv2d with "same" output length; on CPU, through
+    :func:`~braindecode.functional.fft_conv1d` where
+    :func:`~braindecode.functional.prefer_fft_conv` expects it to be faster."""
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        if not prefer_fft_conv(x, self.kernel_size[1]):
+            return self._conv_forward(x, self.weight, self.bias)
+        b, _, h, t = x.shape  # the conv1d of each of the b * h rows
+        x = x.transpose(1, 2).reshape(b * h, -1, t)
+        x = fft_conv1d(x, self.weight.squeeze(2), self.bias)
+        return x.unflatten(0, [b, h]).transpose(1, 2)