braindecode 1.8.1.dev169794550__tar.gz → 1.8.1.dev169883370__tar.gz

{braindecode-1.8.1.dev169794550 → braindecode-1.8.1.dev169883370}/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,
@@ -43,15 +44,35 @@ The following components are licensed under the MIT License:
 - `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`
+- `braindecode/models/seizure_transformer.py`
+- `docs/_static/model/seizure_transformer_arch.png`
+- `braindecode/models/tmsanet.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.dev169883370}/PKG-INFO

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

@@ -23,6 +23,7 @@ from .transforms import (
     SignFlip,
     SmoothTimeMask,
     TimeReverse,
+    TrivialAugment,
 )
 
 __all__ = [
@@ -30,6 +31,7 @@ __all__ = [
     "IdentityTransform",
     "Compose",
     "AugmentedDataLoader",
+    "TrivialAugment",
     "TimeReverse",
     "SignFlip",
     "FTSurrogate",

{braindecode-1.8.1.dev169794550 → braindecode-1.8.1.dev169883370}/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)
 
@@ -1093,7 +1094,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 +1135,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[

{braindecode-1.8.1.dev169794550 → braindecode-1.8.1.dev169883370}/braindecode/augmentation/transforms.py

@@ -1457,3 +1457,188 @@ class BandRotation(Transform):
             "circular_jitter": self.circular_jitter,
             "random_state": self.rng,
         }
+
+
+class TrivialAugment(Transform):
+    """Apply one randomly sampled label-preserving augmentation per example.
+
+    For every example, independently samples one transform from the pool
+    below and one of ``num_bins`` strengths evenly spaced between that
+    transform's bounds, as in TrivialAugment [1]_. Examples that draw the
+    same transform and strength are transformed in one call; each pooled
+    transform still draws its own randomness per example.
+
+    Default pool (no assumption on the signal's unit, sampling frequency or
+    montage):
+
+    * :class:`TimeReverse` — no strength parameter.
+    * :class:`SignFlip` — no strength parameter.
+    * :class:`FTSurrogate` — phase noise magnitude, 0.2 to 1.
+    * :class:`ChannelsDropout` — channel drop probability, 0.05 to 0.4.
+    * :class:`ChannelsShuffle` — shuffle probability, 0.1 to 0.75.
+    * :class:`SmoothTimeMask` — mask length as a fraction of the window
+      length, 0.05 to 0.25.
+    * :class:`GaussianNoise` — noise standard deviation as a fraction of the
+      sub-batch standard deviation (volts or microvolts alike), 0.02 to 0.3.
+    * :class:`AmplitudeScale` — scale interval ``(1/s, s)``, ``s`` from 1.25
+      to 2.5.
+
+    ``sfreq`` adds :class:`BandstopFilter` (bandwidth 0.5 to 4 Hz, capped
+    2.5 Hz below Nyquist) and :class:`FrequencyShift` (maximum shift 0.5 to
+    2 Hz); ``sensors_positions_matrix`` adds :class:`SensorsRotation` around
+    the z axis (5 to 25 degrees).
+
+    Parameters
+    ----------
+    probability : float, optional
+        Probability of augmenting each example. Defaults to 1.0.
+    sfreq : float | None, optional
+        Sampling frequency of the signals, in Hz. Defaults to None.
+    sensors_positions_matrix : array-like | None, optional
+        Sensor positions of shape ``(3, n_channels)`` (see
+        :class:`SensorsRotation`). Defaults to None.
+    num_bins : int, optional
+        Number of strength levels per transform. Defaults to 10.
+    random_state : int | numpy.random.RandomState, optional
+        Seed shared by the per-example sampler and every pooled transform.
+        Defaults to None.
+
+    Attributes
+    ----------
+    op_names : list of str
+        Names of the transforms in the pool, in sampling order.
+
+    References
+    ----------
+    .. [1] Müller, S. G., & Hutter, F. (2021). TrivialAugment:
+       Tuning-free Yet State-of-the-Art Data Augmentation. Proceedings of
+       the IEEE/CVF International Conference on Computer Vision (ICCV),
+       pp. 774-782.
+    """
+
+    def __init__(
+        self,
+        probability=1.0,
+        sfreq=None,
+        sensors_positions_matrix=None,
+        num_bins=10,
+        random_state=None,
+    ):
+        super().__init__(probability=probability, random_state=random_state)
+        if not isinstance(num_bins, (int, np.integer)) or num_bins < 1:
+            raise ValueError(f"num_bins must be a positive integer, got {num_bins}")
+        self.num_bins = int(num_bins)
+        rng = self.rng
+        # (name, strength bounds or None, make(strength) or None: built per call)
+        specs = [
+            ("TimeReverse", None, lambda s: TimeReverse(1.0, random_state=rng)),
+            ("SignFlip", None, lambda s: SignFlip(1.0, random_state=rng)),
+            (
+                "FTSurrogate",
+                (0.2, 1.0),
+                lambda s: FTSurrogate(1.0, phase_noise_magnitude=s, random_state=rng),
+            ),
+            (
+                "ChannelsDropout",
+                (0.05, 0.4),
+                lambda s: ChannelsDropout(1.0, p_drop=s, random_state=rng),
+            ),
+            (
+                "ChannelsShuffle",
+                (0.1, 0.75),
+                lambda s: ChannelsShuffle(1.0, p_shuffle=s, random_state=rng),
+            ),
+            ("SmoothTimeMask", (0.05, 0.25), None),
+            ("GaussianNoise", (0.02, 0.3), None),
+            (
+                "AmplitudeScale",
+                (1.25, 2.5),
+                lambda s: AmplitudeScale(1.0, interval=(1.0 / s, s), random_state=rng),
+            ),
+        ]
+        if sfreq is not None:
+            nyquist = sfreq / 2.0
+            # BandstopFilter needs bandwidth < nyquist - 2; keep a margin
+            max_bandwidth = min(4.0, nyquist - 2.5)
+            if max_bandwidth <= 0.5:
+                raise ValueError(
+                    f"sfreq={sfreq} is too small to sample valid band-stop "
+                    "bandwidths (needs at least 6.0 Hz)."
+                )
+            specs += [
+                (
+                    "BandstopFilter",
+                    (0.5, max_bandwidth),
+                    lambda s: BandstopFilter(
+                        1.0,
+                        sfreq=sfreq,
+                        bandwidth=s,
+                        max_freq=nyquist,
+                        random_state=rng,
+                    ),
+                ),
+                (
+                    "FrequencyShift",
+                    (0.5, 2.0),
+                    lambda s: FrequencyShift(
+                        1.0, sfreq=sfreq, max_delta_freq=s, random_state=rng
+                    ),
+                ),
+            ]
+        if sensors_positions_matrix is not None:
+            specs.append(
+                (
+                    "SensorsRotation",
+                    (5.0, 25.0),
+                    lambda s: SensorsRotation(
+                        1.0,
+                        sensors_positions_matrix=sensors_positions_matrix,
+                        max_degrees=s,
+                        random_state=rng,
+                    ),
+                )
+            )
+
+        self._pool = []
+        for name, bounds, make in specs:
+            if bounds is None:
+                strengths = [None]
+            else:
+                strengths = np.linspace(*bounds, self.num_bins).tolist()
+            variants = None if make is None else [make(s) for s in strengths]
+            self._pool.append((name, strengths, variants))
+        # pre-built transforms as submodules (pickle, ``.to()``)
+        self._static_transforms = torch.nn.ModuleList(
+            v for _, _, variants in self._pool if variants for v in variants
+        )
+        self.op_names = [name for name, _, _ in self._pool]
+
+    def operation(self, X, y):
+        """Apply one sampled transform and strength to each example of X."""
+        n_strengths = np.array([len(strengths) for _, strengths, _ in self._pool])
+        op_ids = self.rng.randint(0, len(self._pool), size=X.shape[0])
+        bin_ids = self.rng.randint(0, self.num_bins, size=X.shape[0])
+        # magnitude-free transforms collapse all examples onto bin 0
+        bin_ids[n_strengths[op_ids] == 1] = 0
+        keys = op_ids * self.num_bins + bin_ids
+
+        out_X, out_y = X.clone(), y.clone()
+        for key in np.unique(keys):
+            group = torch.from_numpy(np.flatnonzero(keys == key)).to(X.device)
+            op_i, bin_j = divmod(int(key), self.num_bins)
+            name, strengths, variants = self._pool[op_i]
+            X_sub = X[group]
+            if variants is not None:
+                transform = variants[bin_j]
+            elif name == "SmoothTimeMask":
+                n_mask = max(1, int(round(strengths[bin_j] * X.shape[-1])))
+                transform = SmoothTimeMask(
+                    1.0, mask_len_samples=n_mask, random_state=self.rng
+                )
+            else:  # GaussianNoise, std relative to the sub-batch (unit-free)
+                std = strengths[bin_j] * X_sub.std().item()
+                transform = GaussianNoise(1.0, std=std, random_state=self.rng)
+            tr_X, tr_y = transform(X_sub, y[group])
+            out_X[group] = tr_X.to(out_X.dtype)
+            out_y[group] = tr_y
+        return out_X, out_y

{braindecode-1.8.1.dev169794550 → braindecode-1.8.1.dev169883370}/braindecode/classifier.py

@@ -207,15 +207,17 @@ class EEGClassifier(_EEGNeuralNet, NeuralNetClassifier):
 
         Returns
         -------
-        trial_predictions : np.ndarray
+        trial_predictions : np.ndarray | list of np.ndarray
             3-dimensional array (n_trials x n_classes x n_predictions), where
             the number of predictions depend on the chosen window size and the
-            receptive field of the network.
-        trial_targets : np.ndarray
-            Ground-truth targets from the dataset in a 2-dimensional array
-            (n_trials x n_targets). Only returned when ``return_targets=True``.
-            The number of targets depends on the decoding paradigm and can be
-            either a single value, multiple values, or a sequence.
+            receptive field of the network. If trials have different lengths,
+            a list with one (n_classes x n_predictions) array per trial.
+        trial_targets : np.ndarray | list of np.ndarray
+            Ground-truth targets from the dataset. Only returned when
+            ``return_targets=True``. An ``np.ndarray`` with a leading trial
+            dimension: ``(n_trials,)`` for scalar targets, with further
+            dimensions for multi-value or equal-length sequence targets. If
+            trial lengths differ, a list with one target array per trial.
         """
         if not self.cropped:
             warnings.warn(

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

@@ -815,7 +815,8 @@ def _get_header(*args, **kwargs):
     for paths_dict in [_TUH_EEG_PATHS, _TUH_EEG_ABNORMAL_PATHS, _TUH_EEG_EVENTS_PATHS]:
         for version_dict in paths_dict.values():
             all_paths.update(version_dict)
-    return all_paths[args[0]]
+    # Mock keys use POSIX separators; pathlib emits backslashes on Windows.
+    return all_paths[os.fspath(args[0]).replace("\\", "/")]
 
 
 _TUH_EEG_PATHS = {

{braindecode-1.8.1.dev169794550 → braindecode-1.8.1.dev169883370}/braindecode/eegneuralnet.py

@@ -144,7 +144,7 @@ class _EEGNeuralNet(NeuralNet, abc.ABC):
             i_window_in_trials.append(i[0].cpu().numpy())
             i_window_stops.append(i[2].cpu().numpy())
             with torch.no_grad():
-                preds.append(to_numpy(self.module_.forward(X.to(self.device))))
+                preds.append(to_numpy(self.module_(X.to(self.device))))
             window_ys.append(y.cpu().numpy())
         preds = np.concatenate(preds)
         i_window_in_trials = np.concatenate(i_window_in_trials)

{braindecode-1.8.1.dev169794550 → braindecode-1.8.1.dev169883370}/braindecode/functional/__init__.py

@@ -3,13 +3,17 @@ from .functions import (
     daubechies_filters,
     drop_path,
     dwt_max_level,
+    fft_conv1d,
     hilbert_freq,
     identity,
     iou_1d,
     pairwise_iou_1d,
     plv_time,
+    prefer_fft_conv,
+    rotate_pairs,
     safe_log,
     sinusoidal_positional_encoding,
+    spectral_input,
     square,
     wavelet_decomposition,
 )
@@ -20,13 +24,17 @@ __all__ = [
     "daubechies_filters",
     "drop_path",
     "dwt_max_level",
+    "fft_conv1d",
     "hilbert_freq",
     "identity",
     "iou_1d",
     "pairwise_iou_1d",
     "plv_time",
+    "prefer_fft_conv",
+    "rotate_pairs",
     "safe_log",
     "sinusoidal_positional_encoding",
+    "spectral_input",
     "square",
     "wavelet_decomposition",
     "glorot_weight_zero_bias",

braindecode-1.8.1.dev169883370/braindecode/functional/_real_dft.py

@@ -0,0 +1,138 @@
+"""Real-valued DFT helpers for accelerators without complex tensors.
+
+Intel Gaudi (HPU) has no complex dtype, so ``torch.fft`` with complex outputs
+cannot run there. These helpers express the one-sided DFT, and the inverse
+transforms built on top of it, as matmuls against a cosine/sine basis. Under
+bfloat16 autocast those matmuls would run in bfloat16, whereas ``torch.fft`` is
+never downcast, so callers wrap the numerically sensitive parts with
+:func:`fp32_island`.
+"""
+
+# Authors: Bruno Aristimunha <b.aristimunha@gmail.com>
+#
+# License: BSD (3-clause)
+import functools
+
+import torch
+
+
+def needs_real_dft(x: torch.Tensor) -> bool:
+    """Whether ``x`` lives on a device without complex-tensor FFT support."""
+    return x.device.type == "hpu"
+
+
+def fp32_island(fn):
+    """Run ``fn`` with autocast disabled, in at least float32 precision.
+
+    Any bfloat16/float16 tensor argument is upcast to float32 before ``fn``
+    runs; float32 and float64 arguments are left untouched, so the same code
+    path can also be checked against a float64 ``torch.fft`` reference.
+    """
+
+    @functools.wraps(fn)
+    def wrapped(*args, **kwargs):
+        ref = next(a for a in args if isinstance(a, torch.Tensor))
+        with torch.autocast(device_type=ref.device.type, enabled=False):
+            args = tuple(
+                a.float()
+                if isinstance(a, torch.Tensor)
+                and a.is_floating_point()
+                and torch.finfo(a.dtype).bits < 32
+                else a
+                for a in args
+            )
+            return fn(*args, **kwargs)
+
+    return wrapped
+
+
+def real_dft_basis(n, *, device, dtype):
+    """One-sided cosine/sine basis of an ``n``-point DFT, shape ``(n // 2 + 1, n)``.
+
+    The phase index is reduced modulo ``n`` in integers before scaling, so the
+    DC row is exact (``sin`` is exactly zero there); the Nyquist row (present
+    for even ``n``) is exact to floating-point precision.
+    """
+    if n <= 0:
+        raise ValueError("n must be positive")
+    if (n // 2) * (n - 1) >= 2**31:
+        # The int32 phase index below would overflow and give wrong phases.
+        raise ValueError(f"n={n} exceeds the 65536 samples of the real-valued DFT")
+    freqs = torch.arange(n // 2 + 1, device=device, dtype=torch.int32)
+    samples = torch.arange(n, device=device, dtype=torch.int32)
+    phase_index = (freqs[:, None] * samples[None, :]) % n
+    angles = 2 * torch.pi * phase_index.to(dtype) / n
+    return angles.cos(), angles.sin()
+
+
+def real_rfft(x):
+    """Real and imaginary parts of ``torch.fft.rfft(x, dim=-1)`` without complex tensors."""
+    n = x.shape[-1]
+    cosine, sine = real_dft_basis(n, device=x.device, dtype=x.dtype)
+    return x @ cosine.transpose(0, 1), -(x @ sine.transpose(0, 1))
+
+
+def real_irfft(real, imag, *, n):
+    """``torch.fft.irfft(torch.complex(real, imag), n=n, dim=-1)`` without complex tensors."""
+    if real.shape[-1] != n // 2 + 1:
+        raise ValueError(
+            f"expected {n // 2 + 1} one-sided bins for n={n}, got {real.shape[-1]}"
+        )
+    cosine, sine = real_dft_basis(n, device=real.device, dtype=real.dtype)
+    output = real[..., :1] @ cosine[:1, :]
+    if n % 2 == 0:
+        interior = slice(1, -1)
+        output = output + real[..., -1:] @ cosine[-1:, :]
+    else:
+        interior = slice(1, None)
+    if real.shape[-1] > (2 if n % 2 == 0 else 1):
+        output = output + 2 * (
+            real[..., interior] @ cosine[interior, :]
+            - imag[..., interior] @ sine[interior, :]
+        )
+    return output / n
+
+
+def real_analytic_ifft(real, imag, *, n):
+    """Inverse ``n``-point FFT of a one-sided spectrum, without complex tensors.
+
+    ``real``/``imag`` hold the bins ``0 .. n // 2`` of a length-``n`` spectrum
+    whose remaining (negative-frequency) bins are zero, so this is a plain
+    (non-Hermitian) inverse DFT, not :func:`real_irfft`. Returns the real and
+    imaginary parts of the generally complex time-domain signal, each of shape
+    ``(..., n)``. This is the last step of :func:`hilbert_freq_real`.
+    """
+    if real.shape[-1] != n // 2 + 1:
+        raise ValueError(
+            f"expected {n // 2 + 1} one-sided bins for n={n}, got {real.shape[-1]}"
+        )
+    cosine, sine = real_dft_basis(n, device=real.device, dtype=real.dtype)
+    out_real = (real @ cosine - imag @ sine) / n
+    out_imag = (real @ sine + imag @ cosine) / n
+    return out_real, out_imag
+
+
+@torch.jit.unused
+def hilbert_freq_real(x: torch.Tensor, forward_fourier: bool) -> torch.Tensor:
+    """Real-valued equivalent of :func:`braindecode.functional.hilbert_freq`.
+
+    Lives here rather than in ``functions.py`` because ``torch.jit.unused`` needs
+    real annotations, and ``functions.py`` uses ``from __future__ import annotations``.
+    """
+
+    @fp32_island
+    def compute(x):
+        if forward_fourier:
+            seq_len = x.shape[-1]
+            real, imag = real_rfft(x)
+        else:
+            seq_len = 2 * (x.shape[-2] - 1)
+            real, imag = x[..., 0], x[..., 1]
+        scale = torch.full((real.shape[-1],), 2.0, dtype=real.dtype, device=real.device)
+        scale[0] = 1.0  # Don't multiply the DC-term by 2
+        if forward_fourier and seq_len % 2 == 0:
+            scale[-1] = 1.0  # Nor the Nyquist term, which only exists for even lengths
+        out_real, out_imag = real_analytic_ifft(real * scale, imag * scale, n=seq_len)
+        return torch.stack((out_real, out_imag), dim=-1)
+
+    return compute(x)