Braindecode 1.8.1.dev169794550__tar.gz → 1.8.1.dev169869285__tar.gz

{braindecode-1.8.1.dev169794550 → braindecode-1.8.1.dev169869285}/NOTICE.txt

@@ -13,9 +13,10 @@ The following components are licensed under the Creative Commons Attribution-Non
 
 - `braindecode/models/eegminer.py`
 - `braindecode/models/meta_neuromotor.py`
+- `braindecode/models/sleepfm.py`
 - `braindecode/models/brainmodule.py`
-
-As well as class later imported into the `braindecode.models.module` named as GeneralizedGaussianFilter.
+- `braindecode/models/neurorvq.py`
+- `braindecode/models/neurorvq_tokenizer.py`
 
 The `meta_neuromotor.py` file is a derivative of
 `facebookresearch/generic-neuromotor-interface`, released by Meta Platforms,
@@ -39,19 +40,42 @@ 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/models/brainomni.py`
+- `braindecode/modules/quantization.py`
+- `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`
+- `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
+`quantization.py` module holds the residual vector quantization derived from
+`lucidrains/vector-quantize-pytorch` (MIT) and the BrainOmni port.
+The `linear_attention.py` module is the part of
+`lucidrains/linear-attention-transformer` (MIT) that BIOT and TFMTokenizer run.
 
 ### Apache-2.0 Licensed Files
 
 The following components are licensed under the Apache License 2.0:
 
+- `braindecode/models/axon.py`
 - `braindecode/models/mvpformer.py`
 - `braindecode/models/zuna.py`
 - `braindecode/models/luna.py`
+- `braindecode/models/mapa.py`
 - `braindecode/models/brant.py`
+- `braindecode/models/diver1.py`
+- `braindecode/models/mscformer.py`
 
 ### USC Academic License Files
 

{braindecode-1.8.1.dev169794550/braindecode.egg-info → braindecode-1.8.1.dev169869285}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.8.1.dev169794550
+Version: 1.8.1.dev169869285
 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>
@@ -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"
@@ -44,6 +44,8 @@ Requires-Dist: huggingface_hub[torch]>=0.20.0; extra == "hub"
 Requires-Dist: zarr>=3.0; extra == "hub"
 Provides-Extra: viz
 Requires-Dist: captum>=0.7.0; extra == "viz"
+Provides-Extra: sae
+Requires-Dist: sae-lens==6.51.3; extra == "sae"
 Provides-Extra: tests
 Requires-Dist: pytest<9.1; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
@@ -58,6 +60,8 @@ Provides-Extra: typing
 Requires-Dist: exca>=0.5.10; extra == "typing"
 Requires-Dist: numpydantic>=1.7; extra == "typing"
 Provides-Extra: docs
+Requires-Dist: pytest<9.1; extra == "docs"
+Requires-Dist: sphinx-markdown-builder==0.6.11; extra == "docs"
 Requires-Dist: sphinx_gallery>=0.17; extra == "docs"
 Requires-Dist: sphinx_rtd_theme; extra == "docs"
 Requires-Dist: sphinx-autodoc-typehints; extra == "docs"

{braindecode-1.8.1.dev169794550 → braindecode-1.8.1.dev169869285}/braindecode/augmentation/__init__.py

@@ -10,9 +10,11 @@ from .transforms import (
     ChannelsReref,
     ChannelsShuffle,
     ChannelsSymmetry,
+    CutMix,
     FrequencyShift,
     FTSurrogate,
     GaussianNoise,
+    LabelSmoothing,
     MaskEncoding,
     Mixup,
     SegmentationReconstruction,
@@ -23,6 +25,7 @@ from .transforms import (
     SignFlip,
     SmoothTimeMask,
     TimeReverse,
+    TrivialAugment,
 )
 
 __all__ = [
@@ -30,12 +33,15 @@ __all__ = [
     "IdentityTransform",
     "Compose",
     "AugmentedDataLoader",
+    "TrivialAugment",
     "TimeReverse",
     "SignFlip",
     "FTSurrogate",
     "ChannelsShuffle",
+    "CutMix",
     "ChannelsDropout",
     "GaussianNoise",
+    "LabelSmoothing",
     "ChannelsSymmetry",
     "SmoothTimeMask",
     "BandstopFilter",

{braindecode-1.8.1.dev169794550 → braindecode-1.8.1.dev169869285}/braindecode/augmentation/base.py

@@ -171,7 +171,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

{braindecode-1.8.1.dev169794550 → braindecode-1.8.1.dev169869285}/braindecode/augmentation/functional.py

@@ -3,6 +3,7 @@
 #          Gustavo Rodrigues <gustavenrique01@gmail.com>
 #          Bruna Lopes <brunajaflopes@gmail.com>
 #          Sarthak Tayal <sarthaktayal2@gmail.com>
+#          Anton Soloviev <anton@praviel.com>
 #
 # License: BSD (3-clause)
 
@@ -18,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]:
@@ -91,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]),
         ],
@@ -112,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,
@@ -177,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]
@@ -579,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)
@@ -910,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
     ]
@@ -920,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
             ]
         )
@@ -931,7 +959,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(
@@ -1061,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()
 
@@ -1074,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,
@@ -1093,7 +1262,8 @@ def segmentation_reconstruction(
     y : torch.Tensor
         EEG labels for the example or batch.
     n_segments : int
-        Number of segments to use in the batch.
+        Number of segments to use in the batch. Any remaining samples are
+        included in the last segment.
     data_classes : list[tuple[int, torch.Tensor]]
         List of tuples. Each tuple contains the class index and the corresponding EEG data.
     rand_indices : array-like
@@ -1133,6 +1303,8 @@ def segmentation_reconstruction(
         for idx_segment in range(n_segments):
             start = idx_segment * segment_size
             end = (idx_segment + 1) * segment_size
+            if idx_segment == n_segments - 1:
+                end = window_size
 
             # Perform the data augmentation
             X_aug[np.arange(n_trials), :, start:end] = X_class[