braindecode 1.8.1__tar.gz → 1.8.1.dev168490289__tar.gz

{braindecode-1.8.1 → braindecode-1.8.1.dev168490289}/NOTICE.txt

@@ -42,6 +42,7 @@ The following components are licensed under the MIT License:
 - `braindecode/models/medformer.py`
 - `braindecode/models/tcformer.py`
 - `braindecode/models/ifnet.py`
+- `braindecode/models/mirepnet.py`
 
 ### Apache-2.0 Licensed Files
 
@@ -50,6 +51,16 @@ The following components are licensed under the Apache License 2.0:
 - `braindecode/models/mvpformer.py`
 - `braindecode/models/zuna.py`
 - `braindecode/models/luna.py`
+- `braindecode/models/brant.py`
+- `braindecode/models/diver1.py`
+- `braindecode/models/mscformer.py`
+
+### USC Academic License Files
+
+[License](https://github.com/ShanechiLab/BaRISTA/blob/master/LICENSE.md)
+
+- `braindecode/models/barista.py`
+- `docs/_static/model/barista.jpeg`
 
 ## License Links
 
@@ -58,6 +69,7 @@ The following components are licensed under the Apache License 2.0:
 - [CC BY-NC-SA 4.0 License](https://creativecommons.org/licenses/by-nc-sa/4.0/)
 - [MIT License](https://opensource.org/licenses/MIT)
 - [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0)
+- [USC Academic License](https://github.com/ShanechiLab/BaRISTA/blob/master/LICENSE.md)
 
 ## Note
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.8.1
+Version: 1.8.1.dev168490289
 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.0
-Requires-Dist: torchaudio>=2.0
+Requires-Dist: torch>=2.4
+Requires-Dist: torchaudio>=2.4
 Requires-Dist: mne>=1.11.0
 Requires-Dist: mne_bids>=0.18
 Requires-Dist: h5py
@@ -44,9 +44,12 @@ 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"
+Requires-Dist: pytest-xdist>=3.8.0; extra == "tests"
 Requires-Dist: codecov; extra == "tests"
 Requires-Dist: pytest_cases; extra == "tests"
 Requires-Dist: mypy; extra == "tests"
@@ -57,7 +60,7 @@ Provides-Extra: typing
 Requires-Dist: exca>=0.5.10; extra == "typing"
 Requires-Dist: numpydantic>=1.7; extra == "typing"
 Provides-Extra: docs
-Requires-Dist: sphinx_gallery; extra == "docs"
+Requires-Dist: sphinx_gallery>=0.17; extra == "docs"
 Requires-Dist: sphinx_rtd_theme; extra == "docs"
 Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
 Requires-Dist: sphinx-autobuild; extra == "docs"

{braindecode-1.8.1 → braindecode-1.8.1.dev168490289}/braindecode/augmentation/functional.py

@@ -1002,7 +1002,7 @@ def sensors_rotation(
         ``mne`` through::
 
          >>> ten_twenty_montage = mne.channels.make_standard_montage(
-         ...    'standard_1020'
+         ...    'standard_1020'  # 'colin27_1020' on MNE >= 1.13
          ... ).get_positions()['ch_pos']
     axis : 'x' | 'y' | 'z'
         Axis around which to rotate.

{braindecode-1.8.1 → braindecode-1.8.1.dev168490289}/braindecode/augmentation/transforms.py

@@ -13,6 +13,8 @@ import numpy as np
 import torch
 from mne.channels import make_standard_montage
 
+from braindecode.util import resolve_montage_name
+
 from .base import Transform
 from .functional import (
     amplitude_scale,
@@ -703,7 +705,7 @@ def _get_standard_10_20_positions(raw_or_epoch=None, ordered_ch_names=None):
     )
     if ordered_ch_names is None:
         ordered_ch_names = raw_or_epoch.info["ch_names"]
-    ten_twenty_montage = make_standard_montage("standard_1020")
+    ten_twenty_montage = make_standard_montage(resolve_montage_name("standard_1020"))
     positions_dict = ten_twenty_montage.get_positions()["ch_pos"]
     positions_subdict = {
         k: positions_dict[k] for k in ordered_ch_names if k in positions_dict
@@ -729,7 +731,7 @@ class SensorsRotation(Transform):
         `mne` through::
 
          >>> ten_twenty_montage = mne.channels.make_standard_montage(
-         ...    'standard_1020'
+         ...    'standard_1020'  # 'colin27_1020' on MNE >= 1.13
          ... ).get_positions()['ch_pos']
 
     axis : 'x' | 'y' | 'z', optional

{braindecode-1.8.1 → braindecode-1.8.1.dev168490289}/braindecode/datasets/base.py

@@ -5,6 +5,7 @@
 #          Simon Brandt <simonbrandt@protonmail.com>
 #          David Sabbagh <dav.sabbagh@gmail.com>
 #          Robin Schirrmeister <robintibor@gmail.com>
+#          Sarthak Tayal <sarthaktayal2@gmail.com>
 #
 # License: BSD (3-clause)
 
@@ -1398,6 +1399,9 @@ class BaseConcatDataset(ConcatDataset, HubDatasetMixin, Generic[T]):
                 df = ds._windows.metadata
             else:
                 df = ds.metadata
+            if isinstance(df, pd.DataFrame):
+                # copy so the description columns stay out of the dataset
+                df = df.copy()
             for k, v in ds.description.items():
                 df[k] = v
             all_dfs.append(df)

{braindecode-1.8.1 → braindecode-1.8.1.dev168490289}/braindecode/datasets/tuh.py

@@ -25,6 +25,7 @@ import pandas as pd
 from joblib import Parallel, delayed
 
 from braindecode.datasets.base import BaseConcatDataset, RawDataset
+from braindecode.util import resolve_montage_name
 
 
 class TUH(BaseConcatDataset):
@@ -182,7 +183,9 @@ class TUH(BaseConcatDataset):
         }
         raw.rename_channels(mapping_strip)
 
-        montage1005 = mne.channels.make_standard_montage("standard_1005")
+        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
         }
@@ -207,7 +210,9 @@ class TUH(BaseConcatDataset):
 
     @staticmethod
     def _set_montage(raw):
-        montage = mne.channels.make_standard_montage("standard_1005")
+        montage = mne.channels.make_standard_montage(
+            resolve_montage_name("standard_1005")
+        )
         raw.set_montage(montage, on_missing="ignore")
 
     @staticmethod

{braindecode-1.8.1 → braindecode-1.8.1.dev168490289}/braindecode/datautil/serialization.py

@@ -1,6 +1,7 @@
 """Convenience functions for storing and loading of windows datasets."""
 
 # Authors: Lukas Gemein <l.gemein@gmail.com>
+#          Sarthak Tayal <sarthaktayal2@gmail.com>
 #
 # License: BSD (3-clause)
 
@@ -270,7 +271,9 @@ def _load_parallel(path, i, preload, is_raw, has_stored_windows):
     else:
         window_kwargs = _load_kwargs_json("window_kwargs", sub_dir)
         windows_ds_kwargs = [
-            kwargs[1] for kwargs in window_kwargs if kwargs[0] == "WindowsDataset"
+            kwargs[1]
+            for kwargs in window_kwargs
+            if kwargs[0] in ("WindowsDataset", "EEGWindowsDataset")
         ]
         windows_ds_kwargs = windows_ds_kwargs[0] if len(windows_ds_kwargs) == 1 else {}
         if is_raw:

{braindecode-1.8.1 → braindecode-1.8.1.dev168490289}/braindecode/functional/__init__.py

@@ -8,6 +8,7 @@ from .functions import (
     iou_1d,
     pairwise_iou_1d,
     plv_time,
+    rotate_pairs,
     safe_log,
     sinusoidal_positional_encoding,
     square,
@@ -25,6 +26,7 @@ __all__ = [
     "iou_1d",
     "pairwise_iou_1d",
     "plv_time",
+    "rotate_pairs",
     "safe_log",
     "sinusoidal_positional_encoding",
     "square",

braindecode-1.8.1.dev168490289/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)

{braindecode-1.8.1 → braindecode-1.8.1.dev168490289}/braindecode/functional/functions.py

@@ -12,6 +12,8 @@ import numpy as np
 import torch
 import torch.nn.functional as F
 
+from . import _real_dft
+
 
 def square(x):
     return x * x
@@ -165,18 +167,40 @@ def hilbert_freq(x: torch.Tensor, forward_fourier: bool = True) -> torch.Tensor:
     https://github.com/scipy/scipy/blob/v1.14.1/scipy/signal/_signaltools.py#L2287-L2394
 
     """
+    if _real_dft.needs_real_dft(x):
+        return _real_dft.hilbert_freq_real(x, forward_fourier).to(x.dtype)
+
+    input_dtype = x.dtype
+    # ``view_as_complex`` does not accept bfloat16 real/imaginary pairs.  The
+    # HPU path can produce bfloat16 Fourier coefficients under autocast, so do
+    # the complex-valued part in float32 and restore the real-valued contract
+    # at the boundary.  Promoting before the FFT also covers backends that do
+    # not implement bfloat16 FFT kernels.
+    if input_dtype == torch.bfloat16:
+        x = x.float()
+
     if forward_fourier:
+        seq_len = x.shape[-1]
         x = torch.fft.rfft(x, norm=None, dim=-1)
         x = torch.view_as_real(x)
+    else:
+        # The one-sided spectrum does not record whether the signal length
+        # was odd or even, so assume an even length here.
+        seq_len = 2 * (x.shape[-2] - 1)
     x = x * 2.0
     x[..., 0, :] = x[..., 0, :] / 2.0  # Don't multiply the DC-term by 2
+    if forward_fourier and seq_len % 2 == 0:
+        # Nor the Nyquist term, which only exists for even lengths
+        x[..., -1, :] = x[..., -1, :] / 2.0
     x = F.pad(
-        x, [0, 0, 0, x.shape[-2] - 2]
+        x, [0, 0, 0, seq_len - x.shape[-2]]
     )  # Fill Fourier coefficients to retain shape
     x = torch.view_as_complex(x)
     x = torch.fft.ifft(x, norm=None, dim=-1)  # returns complex signal
     x = torch.view_as_real(x)
 
+    if input_dtype == torch.bfloat16:
+        x = x.to(input_dtype)
     return x
 
 
@@ -446,3 +470,21 @@ def sinusoidal_positional_encoding(n_positions: int, dim: int) -> torch.Tensor:
     # ``.contiguous()`` so an odd-``dim`` truncation owns tight storage -- a
     # non-contiguous view over the padded width breaks safetensors buffer saving.
     return pe[:, :dim].contiguous()
+
+
+def rotate_pairs(x: torch.Tensor) -> torch.Tensor:
+    """Rotate adjacent feature pairs from ``(a, b)`` to ``(-b, a)``.
+
+    Parameters
+    ----------
+    x : torch.Tensor
+        Tensor of shape ``(..., features)`` with an even final dimension.
+
+    Returns
+    -------
+    torch.Tensor
+        Same shape, device and dtype as ``x``. Frequencies, positional indexing
+        and mixed-precision policy are left to the caller.
+    """
+    pairs = x.unflatten(-1, (-1, 2))
+    return torch.stack((-pairs[..., 1], pairs[..., 0]), dim=-1).flatten(-2)

{braindecode-1.8.1 → braindecode-1.8.1.dev168490289}/braindecode/models/__init__.py

@@ -3,10 +3,13 @@
 from .atcnet import ATCNet
 from .attentionbasenet import AttentionBaseNet
 from .attn_sleep import AttnSleep
+from .barista import BaRISTA
 from .base import EEGModuleMixin
 from .bendr import BENDR, InterpolatedBENDR
 from .biot import BIOT, InterpolatedBIOT
+from .brainbert import BrainBERT
 from .brainmodule import BrainModule
+from .brant import Brant
 from .cbramod import CBraMod
 from .codebrain import CodeBrain
 from .contrawr import ContraWR
@@ -15,6 +18,7 @@ from .dance import DANCE
 from .deep4 import Deep4Net
 from .deepsleepnet import DeepSleepNet
 from .dgcnn import DGCNN
+from .diver1 import DIVER1
 from .eegconformer import EEGConformer
 from .eegdino import EEGDINO
 from .eeginception_erp import EEGInceptionERP
@@ -38,6 +42,8 @@ from .labram import InterpolatedLaBraM, Labram
 from .luna import LUNA
 from .medformer import MEDFormer
 from .meta_neuromotor import MetaNeuromotorHand
+from .mirepnet import MIRepNet
+from .mscformer import MSCFormer
 from .msvtnet import MSVTNet
 from .mvpformer import MVPFormer
 from .neuropose import NeuroPose
@@ -84,9 +90,11 @@ __all__ = [
     "ATCNet",
     "AttnSleep",
     "AttentionBaseNet",
+    "BaRISTA",
     "EEGModuleMixin",
     "BIOT",
     "BENDR",
+    "BrainBERT",
     "CBraMod",
     "CodeBrain",
     "ContraWR",
@@ -94,7 +102,9 @@ __all__ = [
     "DANCE",
     "Deep4Net",
     "DeepSleepNet",
+    "DIVER1",
     "BrainModule",
+    "Brant",
     "EEGConformer",
     "EEGDINO",
     "EEGPT",
@@ -129,6 +139,8 @@ __all__ = [
     "extract_channel_locations_from_chs_info",
     "positions_from_chs_info",
     "MEDFormer",
+    "MIRepNet",
+    "MSCFormer",
     "MSVTNet",
     "MVPFormer",
     "PBT",