braindecode 1.8.0.dev1122__tar.gz → 1.8.0.dev1128__tar.gz

{braindecode-1.8.0.dev1122/braindecode.egg-info → braindecode-1.8.0.dev1128}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.8.0.dev1122
+Version: 1.8.0.dev1128
 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.0.dev1122 → braindecode-1.8.0.dev1128}/braindecode/datasets/bids/hub.py

@@ -28,6 +28,7 @@ The format follows a BIDS-inspired sourcedata structure:
 # License: BSD (3-clause)
 
 import contextlib
+import copy
 import json
 import logging
 import tempfile
@@ -56,6 +57,7 @@ from .hub_io import (
     _load_eegwindows_from_zarr,
     _load_raw_from_zarr,
     _load_windows_from_zarr,
+    _prepare_info_for_json,
     _save_eegwindows_to_zarr,
     _save_raw_to_zarr,
     _save_windows_to_zarr,
@@ -72,6 +74,33 @@ log = logging.getLogger(__name__)
 _LOCK_FILE = "format_info.json"
 
 
+def _normalize_kwargs_for_json(value, field_name):
+    """Return one preprocessing-kwargs value as native strict JSON."""
+
+    def _convert(obj):
+        if isinstance(obj, np.ndarray):
+            return _convert(obj.tolist())
+        if isinstance(obj, dict):
+            return {key: _convert(item) for key, item in obj.items()}
+        if isinstance(obj, (list, tuple)):
+            return [_convert(item) for item in obj]
+        if isinstance(obj, np.generic):
+            return _convert(obj.item())
+        return obj
+
+    try:
+        converted = _convert(value)
+        if isinstance(converted, str):
+            raise ValueError(
+                "a root string is ambiguous with the legacy encoded format"
+            )
+        return json.loads(json.dumps(converted, allow_nan=False))
+    except (OverflowError, RecursionError, TypeError, ValueError) as error:
+        raise ValueError(
+            f"{field_name} must contain only finite JSON-serializable values"
+        ) from error
+
+
 class HubDatasetMixin:
     """
     Mixin class for Hugging Face Hub integration with EEG datasets.
@@ -685,14 +714,57 @@ class HubDatasetMixin:
                 f"{output_path} already exists. Set overwrite=True to replace it."
             )
 
-        # Create zarr store (zarr v3 API)
-        root = zarr.open(str(output_path), mode="w")
-
         # Validate uniformity across all datasets using shared validation
         dataset_type, _, _ = hub_validation.validate_dataset_uniformity(self.datasets)
 
-        # Keep reference to first dataset for preprocessing kwargs
-        first_ds = self.datasets[0]
+        # Normalize every JSON value before opening the output store. The cached
+        # values below are the exact values handed to the write helpers.
+        prepared_infos = []
+        for ds in self.datasets:
+            if dataset_type == "WindowsDataset":
+                info = ds.windows.info
+            elif dataset_type in ("EEGWindowsDataset", "RawDataset"):
+                info = ds.raw.info
+            prepared_infos.append(_prepare_info_for_json(info.to_json_dict()))
+
+        prepared_kwargs = {}
+        for kwarg_name in [
+            "raw_preproc_kwargs",
+            "window_kwargs",
+            "window_preproc_kwargs",
+        ]:
+            expected_present = hasattr(self.datasets[0], kwarg_name)
+            expected_value = None
+            expected_token = None
+            for i_ds, ds in enumerate(self.datasets):
+                present = hasattr(ds, kwarg_name)
+                if present != expected_present:
+                    raise ValueError(
+                        f"{kwarg_name} on dataset {i_ds} has inconsistent presence; "
+                        "the Zarr format stores one global value"
+                    )
+                if not present:
+                    continue
+                value = _normalize_kwargs_for_json(
+                    getattr(ds, kwarg_name), f"{kwarg_name} on dataset {i_ds}"
+                )
+                value_token = json.dumps(
+                    value, sort_keys=True, separators=(",", ":"), allow_nan=False
+                )
+                if i_ds == 0:
+                    expected_value = value
+                    expected_token = value_token
+                elif value_token != expected_token:
+                    raise ValueError(
+                        f"{kwarg_name} on dataset {i_ds} differs from dataset 0; "
+                        "the Zarr format stores one global value"
+                    )
+            if expected_present:
+                prepared_kwargs[kwarg_name] = expected_value
+
+        # Create compressor and zarr store (zarr v3 API) only after preflight.
+        compressor = _create_compressor(compression, compression_level)
+        root = zarr.open(str(output_path), mode="w")
 
         # Store global metadata
         root.attrs["n_datasets"] = len(self.datasets)
@@ -706,21 +778,10 @@ class HubDatasetMixin:
         root.attrs["zarr_version"] = zarr.__version__
         root.attrs["scipy_version"] = scipy.__version__
 
-        # Save preprocessing kwargs (check first dataset, assuming uniform preprocessing)
-        # These are typically set by windowing functions on individual datasets
-        for kwarg_name in [
-            "raw_preproc_kwargs",
-            "window_kwargs",
-            "window_preproc_kwargs",
-        ]:
-            # Check first dataset for these attributes
-            if hasattr(first_ds, kwarg_name):
-                kwargs = getattr(first_ds, kwarg_name)
-                if kwargs:
-                    root.attrs[kwarg_name] = json.dumps(kwargs)
-
-        # Create compressor
-        compressor = _create_compressor(compression, compression_level)
+        # Save preprocessing kwargs from the preflight cache. These are
+        # typically set by windowing functions on individual datasets.
+        for kwarg_name, kwargs in prepared_kwargs.items():
+            root.attrs[kwarg_name] = kwargs
 
         # Save each recording
         for i_ds, ds in enumerate(self.datasets):
@@ -731,7 +792,7 @@ class HubDatasetMixin:
                 data = ds.windows.get_data()
                 metadata = ds.windows.metadata
                 description = ds.description
-                info_dict = ds.windows.info.to_json_dict()
+                info_dict = prepared_infos[i_ds]
                 target_name = ds.target_name if hasattr(ds, "target_name") else None
 
                 # Save using inlined function
@@ -750,7 +811,7 @@ class HubDatasetMixin:
                 raw = ds.raw
                 metadata = ds.metadata
                 description = ds.description
-                info_dict = ds.raw.info.to_json_dict()
+                info_dict = prepared_infos[i_ds]
                 targets_from = ds.targets_from
                 last_target_only = ds.last_target_only
 
@@ -771,7 +832,7 @@ class HubDatasetMixin:
                 # Get continuous raw data from RawDataset
                 raw = ds.raw
                 description = ds.description
-                info_dict = ds.raw.info.to_json_dict()
+                info_dict = prepared_infos[i_ds]
                 target_name = ds.target_name if hasattr(ds, "target_name") else None
 
                 # Save using inlined function
@@ -956,10 +1017,14 @@ class HubDatasetMixin:
             "window_preproc_kwargs",
         ]:
             if kwarg_name in root.attrs:
-                kwargs = json.loads(root.attrs[kwarg_name])
+                kwargs = root.attrs[kwarg_name]
+                if isinstance(kwargs, str):
+                    # Stores written by older braindecode versions kept
+                    # these attributes as double-encoded JSON strings.
+                    kwargs = json.loads(kwargs)
                 # Set on each individual dataset (where they were originally stored)
                 for ds in datasets:
-                    setattr(ds, kwarg_name, kwargs)
+                    setattr(ds, kwarg_name, copy.deepcopy(kwargs))
 
         return concat_ds
 

{braindecode-1.8.0.dev1122 → braindecode-1.8.0.dev1128}/braindecode/datasets/bids/hub_io.py

@@ -8,6 +8,7 @@ These functions keep the Zarr serialization details isolated from hub.py.
 from __future__ import annotations
 
 import json
+from numbers import Real
 from pathlib import Path
 
 import numpy as np
@@ -17,17 +18,78 @@ from mne.utils import _soft_import
 zarr = _soft_import("zarr", purpose="hugging face integration", strict=False)
 
 
+def _is_non_bool_real(value):
+    return not isinstance(value, (bool, np.bool_)) and isinstance(
+        value, (Real, np.integer, np.floating)
+    )
+
+
+def _prepare_info_for_json(obj, path="info", *, _in_numeric_sequence=False):
+    """Normalize an MNE Info value to strict JSON without losing sequence NaNs."""
+    if isinstance(obj, np.ndarray):
+        obj = obj.tolist()
+
+    if isinstance(obj, dict):
+        return {
+            key: _prepare_info_for_json(value, f"{path}.{key}")
+            for key, value in obj.items()
+        }
+
+    if isinstance(obj, (list, tuple)):
+        values = list(obj)
+        has_none = any(value is None for value in values)
+        has_number = any(_is_non_bool_real(value) for value in values)
+        all_none = bool(values) and all(value is None for value in values)
+        if all_none or (has_none and has_number):
+            raise ValueError(
+                f"{path} is ambiguous: numeric sequences cannot contain JSON null"
+            )
+
+        is_numeric_sequence = bool(values) and all(
+            _is_non_bool_real(value) for value in values
+        )
+        return [
+            _prepare_info_for_json(
+                value,
+                f"{path}[{index}]",
+                _in_numeric_sequence=is_numeric_sequence,
+            )
+            for index, value in enumerate(values)
+        ]
+
+    if isinstance(obj, (bool, np.bool_)):
+        return bool(obj)
+    if isinstance(obj, (int, np.integer)):
+        return int(obj)
+    if _is_non_bool_real(obj):
+        value = float(obj)
+        if np.isnan(value):
+            if _in_numeric_sequence:
+                return None
+            raise ValueError(f"{path} contains unsupported NaN")
+        if np.isposinf(value):
+            raise ValueError(f"{path} contains positive infinity")
+        if np.isneginf(value):
+            raise ValueError(f"{path} contains negative infinity")
+        return value
+    if obj is None or isinstance(obj, str):
+        return obj
+    raise ValueError(f"{path} contains a non-JSON-serializable value")
+
+
 def _restore_nan_from_json(obj):
-    """Restore NaN values from None in legacy zarr stores.
+    """Restore NaN values from None in JSON-loaded attributes.
 
-    Datasets saved before zarr v3 native NaN support used
-    ``_sanitize_for_json`` to convert NaN/Inf → None. This restores them
-    on load so ``mne.Info.from_json_dict`` gets proper NaN arrays.
+    JSON null is reserved for NaN only in non-boolean numeric sequences.
+    All-null lists are therefore the representation of validated all-NaN
+    sequences, while ordinary null values elsewhere remain unchanged.
     """
     if isinstance(obj, dict):
         return {k: _restore_nan_from_json(v) for k, v in obj.items()}
     if isinstance(obj, list):
-        if len(obj) > 0 and all(isinstance(x, (int, float, type(None))) for x in obj):
+        if len(obj) > 0 and all(
+            value is None or _is_non_bool_real(value) for value in obj
+        ):
             return [np.nan if x is None else x for x in obj]
         return [_restore_nan_from_json(v) for v in obj]
     return obj

{braindecode-1.8.0.dev1122 → braindecode-1.8.0.dev1128}/braindecode/models/base.py

@@ -198,7 +198,34 @@ class EEGModuleMixin(_BaseHubMixin, metaclass=_BraindecodeDocstringMeta):
     See :ref:`load-pretrained-models` for a complete tutorial.
     """
 
+    #: Attributes that :func:`torch.jit.script` must not introspect. The
+    #: signal-related properties raise :class:`ValueError` when their value was
+    #: neither given nor inferable, and ``mapping`` carries a postponed
+    #: annotation TorchScript cannot resolve. Either one aborts scripting
+    #: before ``forward`` is ever compiled.
+    __jit_ignored_attributes__ = [
+        *sorted(_EEG_PARAMS),
+        "_chs_info",
+        "input_shape",
+        "mapping",
+    ]
+    #: Rich MNE channel dictionaries are intentionally unavailable in scripted
+    #: forwards; they remain unchanged on eager models and in saved configs.
+    __jit_unused_properties__ = ["chs_info"]
+
     def __init_subclass__(cls, **kwargs):
+        # TorchScript only honours ``__jit_ignored_attributes__`` for
+        # properties defined directly on the concrete class: it collects them
+        # with ``vars(type(module))``, which skips inherited ones. Rebinding
+        # the very same property objects on each subclass makes them visible
+        # there without changing any runtime behaviour.
+        for name in cls.__jit_ignored_attributes__:
+            if name in cls.__dict__:
+                continue
+            prop = getattr(cls, name, None)
+            if isinstance(prop, property):
+                setattr(cls, name, prop)
+
         # Append model-specific Hub integration notes to the docstring.
         # This runs before the metaclass __init__, so the Hub notes will
         # be included in the docstring that the metaclass processes.
@@ -286,6 +313,12 @@ class EEGModuleMixin(_BaseHubMixin, metaclass=_BraindecodeDocstringMeta):
         self._chs_info = chs_info  # type: ignore[assignment]
         self._n_outputs = n_outputs  # type: ignore[assignment]
         self._n_chans = n_chans  # type: ignore[assignment]
+        # TorchScript cannot represent the rich MNE dictionaries in _chs_info.
+        # Keep the original eager state above and expose only the derived scalar
+        # to scripted signal-property getters.
+        self._n_chans_for_jit = (
+            len(chs_info) if n_chans is None and chs_info is not None else n_chans
+        )
         self._n_times = n_times  # type: ignore[assignment]
         self._sfreq = sfreq  # type: ignore[assignment]
 
@@ -310,6 +343,12 @@ class EEGModuleMixin(_BaseHubMixin, metaclass=_BraindecodeDocstringMeta):
 
     @property
     def n_chans(self) -> int:
+        if torch.jit.is_scripting():
+            if self._n_chans_for_jit is None:
+                raise ValueError(
+                    "n_chans could not be inferred. Either specify n_chans or chs_info."
+                )
+            return self._n_chans_for_jit
         if self._n_chans is None and self._chs_info is not None:
             return len(self._chs_info)
         elif self._n_chans is None:
@@ -319,7 +358,7 @@ class EEGModuleMixin(_BaseHubMixin, metaclass=_BraindecodeDocstringMeta):
         return self._n_chans
 
     @property
-    def chs_info(self) -> list[str]:
+    def chs_info(self) -> list[dict]:
         if self._chs_info is None:
             raise ValueError("chs_info not specified.")
         return self._chs_info

{braindecode-1.8.0.dev1122 → braindecode-1.8.0.dev1128}/braindecode/samplers/base.py

@@ -5,6 +5,7 @@ Sampler classes.
 # Authors: Hubert Banville <hubert.jbanville@gmail.com>
 #          Theo Gnassounou <>
 #          Young Truong <dt.young112@gmail.com>
+#          Sarthak Tayal <sarthaktayal2@gmail.com>
 #
 # License: BSD (3-clause)
 
@@ -219,6 +220,9 @@ class DistributedRecordingSampler(DistributedSampler):
 class SequenceSampler(RecordingSampler):
     """Sample sequences of consecutive windows.
 
+    Recordings holding fewer than ``n_windows`` windows cannot contain a full
+    sequence and contribute none.
+
     Parameters
     ----------
     metadata : pd.DataFrame
@@ -227,7 +231,7 @@ class SequenceSampler(RecordingSampler):
         Number of consecutive windows in a sequence.
     n_windows_stride : int
         Number of windows between two consecutive sequences.
-    random : bool
+    randomize : bool
         If True, sample sequences randomly. If False, sample sequences in
         order.
     random_state : np.random.RandomState | int | None
@@ -269,7 +273,10 @@ class SequenceSampler(RecordingSampler):
             .apply(lambda x: x[: end_offset : self.n_windows_stride])
             .values
         )
-        file_ids = [[i] * len(inds) for i, inds in enumerate(start_inds)]
+        # a typed array keeps the ids integer when a recording yields no sequence
+        file_ids = [
+            np.full(len(inds), i, dtype=np.int64) for i, inds in enumerate(start_inds)
+        ]
         return np.concatenate(start_inds), np.concatenate(file_ids)
 
     def __len__(self):
@@ -296,6 +303,10 @@ class BalancedSequenceSampler(RecordingSampler):
     3. Sample a window of the corresponding class in the selected recording.
     4. Extract a sequence of windows around the sampled window.
 
+    Recordings holding fewer than ``n_windows`` windows cannot contain a full
+    sequence and are left out of step 1, as they are in
+    :class:`SequenceSampler`.
+
     Parameters
     ----------
     metadata : pd.DataFrame
@@ -322,6 +333,33 @@ class BalancedSequenceSampler(RecordingSampler):
         self.n_windows = n_windows
         self.n_sequences = n_sequences
         self.info_class = self._init_info(metadata, required_keys=["target"])
+        self.long_enough_recordings = self._find_long_enough_recordings()
+
+    def _find_long_enough_recordings(self):
+        """Return the indices of the recordings that can hold a full sequence.
+
+        Returns
+        -------
+        np.ndarray :
+            Array of recording indices holding at least ``n_windows`` windows.
+        """
+        n_windows_per_rec = self.info["index"].apply(len).to_numpy()
+        if n_windows_per_rec.size == 0:
+            raise ValueError("Cannot build sequences from empty metadata.")
+
+        long_enough = np.flatnonzero(n_windows_per_rec >= self.n_windows)
+        if len(long_enough) == 0:
+            raise ValueError(
+                f"No recording holds enough windows to build a sequence of "
+                f"{self.n_windows} windows. The longest recording has "
+                f"{n_windows_per_rec.max()} windows. Reduce n_windows to at "
+                f"most that value."
+            )
+        return long_enough
+
+    def sample_recording(self):
+        """Return a random recording index among the ones long enough."""
+        return self.rng.choice(self.long_enough_recordings)
 
     def sample_class(self, rec_ind=None):
         """Return a random class.

braindecode-1.8.0.dev1128/braindecode/version.py

@@ -0,0 +1 @@
+__version__ = "1.8.0.dev1128"

{braindecode-1.8.0.dev1122 → braindecode-1.8.0.dev1128/braindecode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.8.0.dev1122
+Version: 1.8.0.dev1128
 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.0.dev1122 → braindecode-1.8.0.dev1128}/docs/whats_new.rst

@@ -28,6 +28,14 @@ Current 1.8.0 (GitHub)
 Enhancements
 ============
 
+- Models with TorchScript-compatible forward paths can now be passed straight
+  to :func:`torch.jit.script`, without first being rebuilt as a plain
+  :class:`torch.nn.Module`.
+  :class:`braindecode.models.base.EEGModuleMixin` hides its signal-related
+  properties and the ``mapping`` attribute from TorchScript introspection, so
+  scripting reaches ``forward`` instead of failing on the class attributes.
+  (:gh:`1115` by `Aditya Singh`_)
+
 - Add a transfer-learning tutorial illustrating the TUAB-to-NMT pathology
   workflow with offline synthetic recordings
   (:gh:`580` by `Mohammad Javad D`_ and `Bruno Aristimunha`_).
@@ -82,6 +90,29 @@ Bug fixes
 - Keep :class:`braindecode.preprocessing.EEGPrep` compatible with EEGPrep 0.3,
   which no longer exposes the ``eegprep.utils`` namespace used for sampling-rate
   validation (:gh:`1123` by `Bruno Aristimunha`_).
+- Write strict JSON in Hub dataset stores while preserving NaNs in numeric MNE
+  ``Info`` sequences. Unsupported scalar NaNs and infinities are rejected
+  before store creation, and preprocessing kwargs are stored as native strict
+  JSON while legacy string values remain readable (:gh:`1128` by `Azra Bano`_).
+
+- Leave recordings shorter than ``n_windows`` out of the draw in
+  :class:`braindecode.samplers.BalancedSequenceSampler` instead of failing on
+  them. Such a recording holds no valid sequence start, which made the sampling
+  range empty and raised ``ValueError: high <= 0`` on the first sequence that
+  landed there. :class:`braindecode.samplers.SequenceSampler` already skips
+  those recordings. A clear error now names the longest recording when none of
+  them can hold a sequence (:gh:`1125` by `Sarthak Tayal`_).
+
+- Keep ``file_ids`` of :class:`braindecode.samplers.SequenceSampler` integer.
+  The ids were built from untyped lists, so an empty list coming from a
+  recording too short for a sequence turned the concatenated array into
+  ``float64``, against the documented dtype and unusable as an index
+  (:gh:`1125` by `Sarthak Tayal`_).
+
+- Document the ``randomize`` parameter of
+  :class:`braindecode.samplers.SequenceSampler` under its own name. The
+  docstring described it as ``random``, which no signature accepts
+  (:gh:`1125` by `Sarthak Tayal`_).
 
 Code health
 ============
@@ -1593,3 +1624,5 @@ Authors
 .. _Fashad Ahmed: https://github.com/Fashad-Ahmed
 .. _Bhargav Kowshik: https://github.com/bkowshik
 .. _Jon Huml: https://github.com/jonathanhuml
+.. _Azra Bano: https://github.com/azrabano23
+.. _Aditya Singh: https://github.com/adityasingh2400

braindecode-1.8.0.dev1122/braindecode/version.py

@@ -1 +0,0 @@
-__version__ = "1.8.0.dev1122"