braindecode 1.8.1.dev184305395__tar.gz → 2.0.0.dev178576941__tar.gz

{braindecode-1.8.1.dev184305395 → braindecode-2.0.0.dev178576941}/NOTICE.txt

@@ -40,13 +40,13 @@ The following components are licensed under the MIT License:
 
 - `braindecode/models/ctnet.py`
 - `braindecode/models/dance.py`
+- `braindecode/models/duin.py`
 - `braindecode/models/medformer.py`
 - `braindecode/models/tcformer.py`
 - `braindecode/models/ifnet.py`
 - `braindecode/models/mirepnet.py`
 - `braindecode/models/popt.py`
 - `braindecode/models/tfm_tokenizer.py`
-- `braindecode/modules/popt_modules.py`
 - `braindecode/models/brainomni.py`
 - `braindecode/modules/quantization.py`
 - `braindecode/modules/linear_attention.py`
@@ -54,6 +54,8 @@ The following components are licensed under the MIT License:
 - `docs/_static/model/seizure_transformer_arch.png`
 - `braindecode/models/guetschel2026.py`
 - `braindecode/models/tmsanet.py`
+- `braindecode/models/epint.py`
+- `braindecode/models/gcnsnet.py`
 
 The `brainomni.py` file is a derivative of `OpenTSLab/BrainOmni` (MIT), whose
 SEANet codec derives from Meta's `facebookresearch/encodec` (MIT). The

{braindecode-1.8.1.dev184305395/braindecode.egg-info → braindecode-2.0.0.dev178576941}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.8.1.dev184305395
+Version: 2.0.0.dev178576941
 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>
@@ -22,8 +22,8 @@ Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 License-File: NOTICE.txt
-Requires-Dist: torch>=2.4
-Requires-Dist: torchaudio>=2.4
+Requires-Dist: torch>=2.6
+Requires-Dist: torchaudio>=2.6
 Requires-Dist: mne>=1.11.0
 Requires-Dist: mne_bids>=0.18
 Requires-Dist: h5py
@@ -32,8 +32,8 @@ Requires-Dist: joblib
 Requires-Dist: torchinfo
 Requires-Dist: pandas
 Requires-Dist: wfdb>=4.3.1
-Requires-Dist: linear_attention_transformer
 Requires-Dist: docstring_inheritance
+Requires-Dist: einops
 Requires-Dist: pydantic>=2.0
 Provides-Extra: moabb
 Requires-Dist: moabb>=1.4.3; extra == "moabb"
@@ -50,6 +50,7 @@ Provides-Extra: tests
 Requires-Dist: pytest<9.1; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
 Requires-Dist: pytest-xdist>=3.8.0; extra == "tests"
+Requires-Dist: pytest-timeout; extra == "tests"
 Requires-Dist: codecov; extra == "tests"
 Requires-Dist: pytest_cases; extra == "tests"
 Requires-Dist: mypy; extra == "tests"

braindecode-2.0.0.dev178576941/braindecode/__init__.py

@@ -0,0 +1,53 @@
+import importlib
+from typing import TYPE_CHECKING
+
+from .version import __version__
+
+if TYPE_CHECKING:  # type checkers and IDEs see the classes; runtime uses __getattr__
+    from .classifier import EEGClassifier
+    from .regressor import EEGRegressor
+
+__all__ = [
+    "__version__",
+    "EEGClassifier",
+    "EEGRegressor",
+]
+
+# Subpackages reachable as ``braindecode.<name>`` after a bare ``import braindecode``.
+_SUBMODULES = frozenset(
+    {
+        "augmentation",
+        "classifier",
+        "datasets",
+        "datautil",
+        "eegneuralnet",
+        "functional",
+        "models",
+        "modules",
+        "preprocessing",
+        "regressor",
+        "samplers",
+        "training",
+        "util",
+        "visualization",
+    }
+)
+
+if not TYPE_CHECKING:  # hidden from checkers so misspelled names stay errors
+
+    def __getattr__(name):
+        # PEP 562: skorch, the datasets and the models load on first use.
+        if name == "EEGClassifier":
+            from .classifier import EEGClassifier
+
+            return EEGClassifier
+        if name == "EEGRegressor":
+            from .regressor import EEGRegressor
+
+            return EEGRegressor
+        if name in _SUBMODULES:
+            return importlib.import_module(f".{name}", __name__)
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    def __dir__():
+        return sorted(set(globals()) | set(__all__) | _SUBMODULES)

{braindecode-1.8.1.dev184305395 → braindecode-2.0.0.dev178576941}/braindecode/augmentation/__init__.py

@@ -10,9 +10,11 @@ from .transforms import (
     ChannelsReref,
     ChannelsShuffle,
     ChannelsSymmetry,
+    CutMix,
     FrequencyShift,
     FTSurrogate,
     GaussianNoise,
+    LabelSmoothing,
     MaskEncoding,
     Mixup,
     SegmentationReconstruction,
@@ -36,8 +38,10 @@ __all__ = [
     "SignFlip",
     "FTSurrogate",
     "ChannelsShuffle",
+    "CutMix",
     "ChannelsDropout",
     "GaussianNoise",
+    "LabelSmoothing",
     "ChannelsSymmetry",
     "SmoothTimeMask",
     "BandstopFilter",

{braindecode-1.8.1.dev184305395 → braindecode-2.0.0.dev178576941}/braindecode/augmentation/base.py

@@ -9,10 +9,11 @@
 from numbers import Real
 from typing import Any, Callable, Optional, Union
 
+import numpy as np
 import torch
 from sklearn.utils import check_random_state
 from torch import Tensor, nn
-from torch.utils.data import DataLoader
+from torch.utils.data import DataLoader, get_worker_info
 from torch.utils.data._utils.collate import default_collate
 
 from .functional import identity
@@ -171,7 +172,13 @@ class Compose(Transform):
         self.transforms = transforms
         super().__init__()
 
-    def forward(self, X, y):
+    def forward(self, X, y=None):
+        # like Transform.forward, return only X when no target is given (each
+        # transform then returns a single tensor, not an (X, y) pair)
+        if y is None:
+            for transform in self.transforms:
+                X = transform(X)
+            return X
         for transform in self.transforms:
             X, y = transform(X, y)
         return X, y
@@ -185,6 +192,59 @@ def _as_mixed_target(y, lam_dtype):
     return y, y, lam
 
 
+def _transform_rngs(transform):
+    """Return the ``RandomState`` objects of a transform, in a fixed order.
+
+    Walks the transform, its submodules and the ``transforms`` of a
+    :class:`Compose`, and lists each ``rng`` once (pooled transforms of
+    :class:`braindecode.augmentation.TrivialAugment` share theirs). The global
+    numpy generator, used with ``random_state=None``, is included: a spawned
+    worker receives a pickled copy of it, which torch does not reseed.
+    """
+    rngs, seen, stack = [], set(), [transform]
+    while stack:
+        tr = stack.pop(0)
+        if id(tr) in seen:
+            continue
+        seen.add(id(tr))
+        # Compose forwards to its children without using its inherited RNG.
+        rng = None if type(tr) is Compose else getattr(tr, "rng", None)
+        if isinstance(rng, np.random.RandomState) and id(rng) not in seen:
+            seen.add(id(rng))
+            rngs.append(rng)
+        children = list(getattr(tr, "transforms", None) or [])
+        if isinstance(tr, nn.Module):
+            children += list(tr.children())
+        stack.extend(children)
+    return rngs
+
+
+def _assert_stackable(items, name):
+    # Fixed expansion concatenates the clean originals with the transformed
+    # copies, so every copy must keep the original's shape except along the
+    # batch dimension. A transform that reshapes X or y (e.g. one returning
+    # class distributions instead of class indices) would otherwise fail deep
+    # inside torch.cat with a bare dimension-mismatch RuntimeError.
+    reference = items[0]
+    for item in items[1:]:
+        pairs = (
+            zip(reference, item)
+            if isinstance(reference, (tuple, list))
+            else [(reference, item)]
+        )
+        for ref_part, part in pairs:
+            if part.dim() != ref_part.dim() or part.shape[1:] != ref_part.shape[1:]:
+                raise ValueError(
+                    f"The transform returned {name} with shape "
+                    f"{tuple(part.shape)} instead of {tuple(ref_part.shape)}: "
+                    f"the fixed-expansion mode (n_augmentation > 0) keeps the "
+                    f"clean originals and concatenates the transformed "
+                    f"copies, so it cannot accommodate a transform that "
+                    f"changes the shape of {name}. Use n_augmentation = 0 "
+                    f"(in-place augmentation) instead."
+                )
+
+
 class _AugmentationCollate:
     """Collate that applies a transform to each batch, with optional expansion.
 
@@ -205,15 +265,44 @@ class _AugmentationCollate:
         ``(1 + n_augmentation)`` times the original size. When the transform
         mixes targets, as :class:`braindecode.augmentation.Mixup` does, ``y``
         stays the ``(y_a, y_b, lam)`` triple and the clean originals get a
-        mixing coefficient of one.
+        mixing coefficient of one. In this mode a transform that changes the
+        shape of ``X`` or ``y`` is rejected with a clear
+        :class:`ValueError`, as its copies cannot be concatenated with the
+        clean originals.
     """
 
     def __init__(self, transform, device=None, n_augmentation=0):
         self.transform = transform
         self.device = device
         self.n_augmentation = n_augmentation
+        self.worker_seeds = None
+        self._worker_rngs_seeded = False
+
+    def draw_worker_seeds(self):
+        """Draw, from each generator of the transform, a seed for the workers.
+
+        Called in the main process when a multi-process iteration starts. A
+        worker receives a copy of the transform whose generators are in the
+        state of the main process; without a new seed, every worker, and every
+        epoch, would draw the same augmentations.
+        """
+        self.worker_seeds = [
+            int(rng.randint(2**31)) for rng in _transform_rngs(self.transform)
+        ]
+
+    def _seed_worker_rngs(self):
+        if self._worker_rngs_seeded or self.worker_seeds is None:
+            return
+        worker_info = get_worker_info()
+        if worker_info is None:
+            return
+        self._worker_rngs_seeded = True
+        rngs = _transform_rngs(self.transform)
+        for rng, seed in zip(rngs, self.worker_seeds):
+            rng.seed(np.random.SeedSequence([seed, worker_info.id]).generate_state(1))
 
     def __call__(self, batch):
+        self._seed_worker_rngs()
         collated = default_collate(batch)
         X, y = collated[:2]
         if self.device is not None:
@@ -233,13 +322,16 @@ class _AugmentationCollate:
             for aug_y in ys
             if isinstance(aug_y, (tuple, list)) and len(aug_y) == 3
         ]
+        _assert_stackable(xs, "X")
         if mixed_ys:
             # a target-mixing transform such as Mixup returns (y_a, y_b, lam),
             # so the parts are concatenated one by one and the untouched copies
             # are given a mixing coefficient of one
             lam_dtype = mixed_ys[0][2].dtype
             ys = [_as_mixed_target(aug_y, lam_dtype) for aug_y in ys]
+            _assert_stackable(ys, "y")
             return torch.cat(xs), tuple(torch.cat(part) for part in zip(*ys))
+        _assert_stackable(ys, "y")
         return torch.cat(xs), torch.cat(ys)
 
 
@@ -262,7 +354,10 @@ class AugmentedDataLoader(DataLoader):
         the clean originals are kept and ``n_augmentation`` independently
         transformed copies are appended. This expresses augmentations defined as
         a fixed set-expansion (e.g. the EEG-Inception MI 6x training set,
-        ``n_augmentation=5``). In this mode batches are returned as ``(X, y)``.
+        ``n_augmentation=5``). In this mode batches are returned as ``(X, y)``
+        and transforms that change the shape of ``X`` or ``y`` are rejected
+        with a :class:`ValueError`, as their copies cannot be concatenated
+        with the clean originals.
     **kwargs : dict, optional
         keyword arguments to pass to standard DataLoader class.
     """
@@ -295,3 +390,10 @@ class AugmentedDataLoader(DataLoader):
             transform, device=device, n_augmentation=n_augmentation
         )
         super().__init__(dataset, collate_fn=self.collated_tr, **kwargs)
+
+    def __iter__(self):
+        # the workers get a copy of the transform; give them new seeds so that
+        # seeded transforms differ across workers and epochs
+        if self.num_workers > 0:
+            self.collated_tr.draw_worker_seeds()
+        return super().__iter__()

{braindecode-1.8.1.dev184305395 → braindecode-2.0.0.dev178576941}/braindecode/augmentation/functional.py

@@ -19,7 +19,22 @@ from mne.filter import notch_filter
 from scipy.interpolate import Rbf
 from sklearn.utils import check_random_state
 from torch.fft import fft, ifft
-from torch.nn.functional import pad
+from torch.nn.functional import one_hot, pad
+
+
+def _max_float_dtype(device: torch.device | str) -> torch.dtype:
+    """float64, or float32 on Apple MPS, which has no float64."""
+    return torch.float32 if torch.device(device).type == "mps" else torch.float64
+
+
+def _to_device(t: torch.Tensor, device: torch.device | str) -> torch.Tensor:
+    """Move ``t`` to ``device``, in single precision on MPS (no float64 there)."""
+    if torch.device(device).type == "mps":
+        if t.dtype == torch.float64:
+            return t.float().to(device)
+        if t.dtype == torch.complex128:
+            return t.to(torch.complex64).to(device)
+    return t.to(device)
 
 
 def identity(X: torch.Tensor, y: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
@@ -92,10 +107,11 @@ def _new_random_fft_phase_odd(
     rng = check_random_state(random_state)
     random_phase = torch.from_numpy(
         2j * np.pi * rng.random((batch_size, c, (n - 1) // 2))
-    ).to(device)
+    )
+    random_phase = _to_device(random_phase, device)
     return torch.cat(
         [
-            torch.zeros((batch_size, c, 1), device=device),
+            torch.zeros((batch_size, c, 1), device=device, dtype=random_phase.dtype),
             random_phase,
             -torch.flip(random_phase, [-1]),
         ],
@@ -113,12 +129,13 @@ def _new_random_fft_phase_even(
     rng = check_random_state(random_state)
     random_phase = torch.from_numpy(
         2j * np.pi * rng.random((batch_size, c, n // 2 - 1))
-    ).to(device)
+    )
+    random_phase = _to_device(random_phase, device)
     return torch.cat(
         [
-            torch.zeros((batch_size, c, 1), device=device),
+            torch.zeros((batch_size, c, 1), device=device, dtype=random_phase.dtype),
             random_phase,
-            torch.zeros((batch_size, c, 1), device=device),
+            torch.zeros((batch_size, c, 1), device=device, dtype=random_phase.dtype),
             -torch.flip(random_phase, [-1]),
         ],
         dim=-1,
@@ -178,7 +195,7 @@ def ft_surrogate(
         and 0 <= phase_noise_magnitude <= 1
     ), f"eps must be a float between 0 and 1. Got {phase_noise_magnitude}."
 
-    f = fft(X.double(), dim=-1)
+    f = fft(X.to(_max_float_dtype(X.device)), dim=-1)
     device = X.device
 
     n = f.shape[-1]
@@ -580,6 +597,7 @@ def _frequency_shift(X: torch.Tensor, fs: float, f_shift: float) -> torch.Tensor
         _f_shift = torch.as_tensor(f_shift).float()
     else:
         raise ValueError(f"Invalid f_shift type: {type(f_shift)}")
+    _f_shift = _f_shift.to(X.device)
     f_shift_stack = _f_shift.repeat(N_padded, n_channels, 1)
     reshaped_f_shift = f_shift_stack.permute(
         *torch.arange(f_shift_stack.ndim - 1, -1, -1)
@@ -911,7 +929,15 @@ def _rotate_signals(
     sensors_positions_matrix: torch.Tensor,
     spherical: bool = True,
 ) -> torch.Tensor:
-    sensors_positions_matrix = sensors_positions_matrix.to(X.device)
+    if X.device.type == "mps":
+        # MPS has no float64: compute the small (n_chans x n_chans) spherical
+        # spline matrices on CPU in double precision, only move the result
+        # (two separate steps: a combined device + dtype .to() from MPS
+        # returns zeros with some torch versions)
+        sensors_positions_matrix = sensors_positions_matrix.cpu().double()
+        rotations = [rotation.cpu().double() for rotation in rotations]
+    else:
+        sensors_positions_matrix = sensors_positions_matrix.to(X.device)
     rot_sensors_matrices = [
         rotation.matmul(sensors_positions_matrix) for rotation in rotations
     ]
@@ -921,9 +947,10 @@ def _rotate_signals(
                 torch.as_tensor(
                     _torch_make_interpolation_matrix(
                         sensors_positions_matrix.T, rot_sensors_matrix.T
-                    ),
-                    device=X.device,
-                ).float()
+                    )
+                )
+                .float()
+                .to(X.device)
                 for rot_sensors_matrix in rot_sensors_matrices
             ]
         )
@@ -1062,10 +1089,12 @@ def mixup(
         Online: https://arxiv.org/abs/1710.09412
     .. [2] https://github.com/facebookresearch/mixup-cifar10/blob/master/train.py
     """
-    device = X.device
     batch_size, n_channels, n_times = X.shape
 
-    X_mix = torch.zeros((batch_size, n_channels, n_times)).to(device)
+    X_mix = X.new_zeros(
+        (batch_size, n_channels, n_times),
+        dtype=X.dtype if X.is_floating_point() else torch.get_default_dtype(),
+    )
     y_a = y.clone()
     y_b = y[idx_perm].clone()
 
@@ -1075,6 +1104,145 @@ def mixup(
     return X_mix, (y_a, y_b, lam)
 
 
+def cutmix(
+    X: torch.Tensor,
+    y: torch.Tensor,
+    idx_perm: torch.Tensor,
+    cut_t_start: torch.Tensor,
+    cut_t_len: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Paste a time region of shuffled examples into the original examples.
+
+    See [1]_ for details.
+
+    Parameters
+    ----------
+    X : torch.Tensor
+        EEG data in form ``batch_size, n_channels, n_times``
+    y : torch.Tensor
+        Target of length ``batch_size``
+    idx_perm : torch.Tensor
+        Permuted indices of example that are mixed into original examples.
+    cut_t_start : torch.Tensor
+        Start index of the pasted time region for each example.
+    cut_t_len : torch.Tensor
+        Length of the pasted time region for each example.
+
+    Returns
+    -------
+    tuple
+        ``X``, ``y``. Where ``X`` is augmented and ``y`` is a tuple of length
+        3 containing the labels of the two mixed examples and the fraction of
+        each example kept from the original, ``1 - cut_t_len / n_times``.
+
+    References
+    ----------
+    .. [1] Sangdoo Yun, Dongyoon Han, Seong Joon Oh, Sanghyuk Chun,
+        Junsuk Choe, Youngjoon Yoo (2019). CutMix: Regularization Strategy
+        to Train Strong Classifiers with Localizable Features. In 2019
+        IEEE/CVF International Conference on Computer Vision (ICCV)
+        Online: https://arxiv.org/abs/1905.04899
+    """
+    n_times = X.shape[-1]
+    t = torch.arange(n_times, device=X.device)
+    start = cut_t_start[:, None]
+    in_cut = (t >= start) & (t < start + cut_t_len[:, None])
+    X_mix = torch.where(in_cut[:, None], X[idx_perm], X)
+    lam = (n_times - cut_t_len).to(X.dtype) / n_times
+    return X_mix, (y.clone(), y[idx_perm].clone(), lam)
+
+
+def label_smoothing(
+    X: torch.Tensor,
+    y: torch.Tensor,
+    epsilon: float,
+    num_classes: int | None = None,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Smooth targets toward the uniform distribution over the classes.
+
+    See [1]_ for details.
+
+    Parameters
+    ----------
+    X : torch.Tensor
+        EEG data in form ``batch_size, n_channels, n_times``. Returned
+        unchanged.
+    y : torch.Tensor
+        Target of length ``batch_size`` holding class indices (float values
+        are accepted when they are integral), or a floating-point tensor of
+        shape ``batch_size, num_classes`` holding target distributions.
+    epsilon : float
+        Smoothing parameter between 0 and 1: the weight of the uniform
+        distribution mixed into the targets. ``0`` returns the unsmoothed
+        targets.
+    num_classes : int | None, optional
+        Number of classes. Required when ``y`` holds class indices; when
+        ``y`` already holds distributions, it must match the size of the
+        last dimension of ``y``. Defaults to None.
+
+    Returns
+    -------
+    tuple
+        ``X``, ``y``. Where ``X`` is unchanged and ``y`` is a
+        floating-point tensor of shape ``batch_size, num_classes`` whose
+        rows sum to one.
+
+    References
+    ----------
+    .. [1] Christian Szegedy, Vincent Vanhoucke, Jonathon Shlens and
+        Zbigniew Wojna (2016). Rethinking the Inception Architecture for
+        Computer Vision. In 2016 IEEE Conference on Computer Vision and
+        Pattern Recognition (CVPR), pp. 2818-2826.
+        Online: https://arxiv.org/abs/1512.00567
+    """
+    if not isinstance(epsilon, Real) or not 0.0 <= float(epsilon) <= 1.0:
+        raise ValueError(
+            f"epsilon should be a real number between 0 and 1. Got {epsilon!r}."
+        )
+    if num_classes is not None and (
+        not isinstance(num_classes, int)
+        or isinstance(num_classes, bool)
+        or num_classes < 2
+    ):
+        raise ValueError(
+            f"num_classes should be an integer of at least 2. Got {num_classes!r}."
+        )
+
+    if y.dim() == 1:
+        # class-index targets: smooth their one-hot encoding
+        if num_classes is None:
+            raise ValueError("num_classes is required when y holds class indices.")
+        if not torch.all(y == y.floor()):
+            raise ValueError(
+                "y holds non-integral values; class-index targets should be "
+                "integers or integral floats."
+            )
+        if y.numel() > 0 and (y.min() < 0 or y.max() >= num_classes):
+            raise ValueError(f"y holds class indices outside [0, {num_classes}).")
+        one_hot_y = one_hot(y.long(), num_classes).to(dtype=X.dtype)
+        return X, one_hot_y * (1.0 - epsilon) + epsilon / num_classes
+
+    if y.is_floating_point() and y.dim() >= 2:
+        # target distributions: interpolate them toward the uniform one
+        n_classes = y.shape[-1]
+        if num_classes is not None and num_classes != n_classes:
+            raise ValueError(
+                f"num_classes ({num_classes}) does not match the size of the "
+                f"last dimension of y ({n_classes})."
+            )
+        if n_classes < 2:
+            raise ValueError(
+                f"y should hold distributions over at least 2 classes. Got {n_classes}."
+            )
+        return X, y * (1.0 - epsilon) + epsilon / n_classes
+
+    raise ValueError(
+        "y should hold class indices or floating-point target distributions "
+        f"with a class dimension; got dtype {y.dtype} and shape "
+        f"{tuple(y.shape)}."
+    )
+
+
 def segmentation_reconstruction(
     X: torch.Tensor,
     y: torch.Tensor,