braindecode 1.5.0.dev1007__tar.gz → 1.5.0.dev1010__tar.gz

{braindecode-1.5.0.dev1007/braindecode.egg-info → braindecode-1.5.0.dev1010}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.5.0.dev1007
+Version: 1.5.0.dev1010
 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.5.0.dev1007 → braindecode-1.5.0.dev1010}/braindecode/datasets/base.py

@@ -18,7 +18,7 @@ import shutil
 import warnings
 from abc import abstractmethod
 from collections import Counter
-from collections.abc import Callable
+from collections.abc import Callable, Hashable
 from glob import glob
 from pathlib import Path
 from typing import Any, Generic, Iterable, no_type_check
@@ -1340,6 +1340,124 @@ class BaseConcatDataset(ConcatDataset, HubDatasetMixin, Generic[T]):
             raise TypeError("target_transform must be a callable.")
         self._target_transform = fn
 
+    def set_target(self, column: Hashable) -> "BaseConcatDataset":
+        """Use ``column`` as the target ``y`` for every subdataset.
+
+        Dispatches on the subdataset type:
+
+        * For :class:`WindowsDataset` / :class:`EEGWindowsDataset`,
+          ``column`` is looked up in per-window ``metadata`` first, then in
+          the per-record ``description`` (broadcast to every window). The
+          resolved values overwrite ``ds.metadata['target']`` and ``ds.y``.
+          For :class:`WindowsDataset`, the underlying ``ds.windows.metadata``
+          is kept in sync so ``get_metadata()`` and the repr reflect the
+          new target.
+        * For :class:`RawDataset`, ``column`` must exist on the
+          ``description``. ``ds.target_name`` is set to ``column`` so
+          ``__getitem__`` reads ``description[column]`` as ``y`` on every
+          access — no rebuild needed.
+
+        Parameters
+        ----------
+        column : Hashable
+            Name of a metadata column or description field (BIDS entity,
+            participants.tsv extra, ...). Typically a string, but any
+            hashable that pandas accepts as a column label is allowed.
+
+        Returns
+        -------
+        self : BaseConcatDataset
+
+        Raises
+        ------
+        TypeError
+            If any subdataset is not a :class:`WindowsDataset`,
+            :class:`EEGWindowsDataset`, or :class:`RawDataset`, or if a
+            windowed subdataset has lazy (non-DataFrame) metadata.
+        ValueError
+            If ``column`` is not present on a subdataset's metadata or
+            description, or if a windowed subdataset has
+            ``targets_from='channels'`` (which would make this a silent
+            no-op since ``__getitem__`` reads y from misc channels, not
+            from ``metadata['target']``).
+        """
+        for i, ds in enumerate(self.datasets):
+            if isinstance(ds, (WindowsDataset, EEGWindowsDataset)):
+                if not isinstance(ds.metadata, pd.DataFrame):
+                    # _LazyDataFrame (lazy_metadata=True) does not implement
+                    # .copy()/__setitem__, so the in-place write below would
+                    # raise AttributeError. Surface the precondition cleanly.
+                    raise TypeError(
+                        "set_target requires a materialized metadata "
+                        f"DataFrame; datasets[{i}].metadata is "
+                        f"{type(ds.metadata).__name__}. Re-window with "
+                        "lazy_metadata=False to use set_target."
+                    )
+                if getattr(ds, "targets_from", "metadata") != "metadata":
+                    # __getitem__ would read y from misc channels; writing
+                    # metadata['target']/ds.y would be a silent no-op.
+                    raise ValueError(
+                        f"datasets[{i}] has targets_from="
+                        f"{ds.targets_from!r}; set_target only applies when "
+                        "targets_from='metadata' (otherwise __getitem__ "
+                        "derives y from misc channels and would ignore the "
+                        "rewritten target column)."
+                    )
+                n = len(ds)
+                md = ds.metadata
+                if column in md.columns:
+                    values = md[column].iloc[:n].to_list()
+                elif (
+                    isinstance(ds.description, pd.Series)
+                    and column in ds.description.index
+                ):
+                    values = [ds.description[column]] * n
+                else:
+                    desc_keys = (
+                        list(ds.description.index)
+                        if isinstance(ds.description, pd.Series)
+                        else []
+                    )
+                    raise ValueError(
+                        f"Column {column!r} not found on datasets[{i}]: "
+                        f"metadata cols={list(md.columns)}, "
+                        f"description keys={desc_keys}."
+                    )
+                # In-place write so the WindowsDataset's metadata and the
+                # underlying mne.Epochs.metadata (which start as the same
+                # object reference) both reflect the new target. Defensive
+                # second write covers the case where they got de-aliased
+                # earlier by a caller-side reassignment.
+                md["target"] = values
+                windows_obj = getattr(ds, "_windows", None)
+                if windows_obj is not None and windows_obj.metadata is not md:
+                    windows_obj.metadata["target"] = values
+                # values is already a fresh list (Series.to_list() / [x] * n);
+                # no defensive copy needed — pandas keeps its own representation
+                # for md["target"] so mutating ds.y won't reach back into it.
+                ds.y = values
+            elif isinstance(ds, RawDataset):
+                if (
+                    not isinstance(ds.description, pd.Series)
+                    or column not in ds.description.index
+                ):
+                    desc_keys = (
+                        list(ds.description.index)
+                        if isinstance(ds.description, pd.Series)
+                        else []
+                    )
+                    raise ValueError(
+                        f"Column {column!r} not found on datasets[{i}] "
+                        f"description (keys={desc_keys})."
+                    )
+                ds.target_name = column
+            else:
+                raise TypeError(
+                    "set_target requires WindowsDataset, EEGWindowsDataset, "
+                    f"or RawDataset; datasets[{i}] is {type(ds).__name__}."
+                )
+        return self
+
     def _outdated_save(self, path, overwrite=False):
         """This is a copy of the old saving function, that had inconsistent.
 

{braindecode-1.5.0.dev1007 → braindecode-1.5.0.dev1010}/braindecode/models/base.py

@@ -33,13 +33,25 @@ huggingface_hub = _soft_import(
 HAS_HF_HUB = huggingface_hub is not False
 
 
-class _BaseHubMixin:
-    pass
+_HF_INSTALL_HINT = (
+    "requires the `huggingface_hub` package. "
+    "Install with: pip install 'braindecode[hub]'"
+)
+
+
+class _BaseHubMixinStub:
+    @classmethod
+    def from_pretrained(cls, *args, **kwargs):
+        raise ImportError(f"{cls.__name__}.from_pretrained() {_HF_INSTALL_HINT}")
+
+    def push_to_hub(self, *args, **kwargs):
+        raise ImportError(f"{type(self).__name__}.push_to_hub() {_HF_INSTALL_HINT}")
 
 
 # Define base class for hub mixin
-if HAS_HF_HUB:
-    _BaseHubMixin: Type = huggingface_hub.PyTorchModelHubMixin  # type: ignore
+_BaseHubMixin: Type = (
+    huggingface_hub.PyTorchModelHubMixin if HAS_HF_HUB else _BaseHubMixinStub
+)
 
 
 def deprecated_args(obj, *old_new_args):

{braindecode-1.5.0.dev1007 → braindecode-1.5.0.dev1010}/braindecode/preprocessing/preprocess.py

@@ -6,6 +6,7 @@
 #          David Sabbagh <dav.sabbagh@gmail.com>
 #          Bruno Aristimunha <b.aristimunha@gmail.com>
 #          Léo Burgund <leo.burgund@gmail.com>
+#          Sarthak Tayal <sarthaktayal2@gmail.com>
 #
 # License: BSD (3-clause)
 
@@ -217,6 +218,7 @@ def preprocess(
     offset: int = 0,
     copy_data: bool | None = None,
     parallel_kwargs: dict | None = None,
+    max_nbytes: int | str | None = "1M",
 ):
     """Apply preprocessors to a concat dataset.
 
@@ -244,14 +246,20 @@ def preprocess(
         Additional keyword arguments forwarded to ``joblib.Parallel``.
         Defaults to None (equivalent to ``{}``).
         See https://joblib.readthedocs.io/en/stable/generated/joblib.Parallel.html for details.
+    max_nbytes : int, str, or None
+        Threshold (in bytes; or e.g. ``"1M"``) above which joblib memory-maps
+        preloaded arrays as read-only when dispatching to worker processes.
+        Effective only when ``n_jobs != 1``. Pass ``None`` to disable memory
+        mapping when a preprocessor resizes the underlying data (for example
+        ``filterbank``), which would otherwise fail with an ``mmap can't
+        resize a readonly`` error. ``parallel_kwargs['max_nbytes']`` takes
+        precedence if both are provided.
 
     Returns
     -------
     BaseConcatDataset
         Preprocessed dataset.
     """
-    # In case of serialization, make sure directory is available before
-    # preprocessing
     if save_dir is not None and not overwrite:
         _check_save_dir_empty(save_dir)
 
@@ -266,22 +274,35 @@ def preprocess(
     parallel_params.setdefault(
         "prefer", "threads" if platform.system() == "Windows" else None
     )
-
-    list_of_ds = Parallel(n_jobs=n_jobs, **parallel_params)(
-        delayed(_preprocess)(
-            ds,
-            i + offset,
-            preprocessors,
-            save_dir,
-            overwrite,
-            copy_data=(
-                (parallel_processing and (save_dir is None))
-                if copy_data is None
-                else copy_data
-            ),
+    parallel_params.setdefault("max_nbytes", max_nbytes)
+
+    try:
+        list_of_ds = Parallel(n_jobs=n_jobs, **parallel_params)(
+            delayed(_preprocess)(
+                ds,
+                i + offset,
+                preprocessors,
+                save_dir,
+                overwrite,
+                copy_data=(
+                    (parallel_processing and (save_dir is None))
+                    if copy_data is None
+                    else copy_data
+                ),
+            )
+            for i, ds in enumerate(concat_ds.datasets)
         )
-        for i, ds in enumerate(concat_ds.datasets)
-    )
+    except (BufferError, ValueError, OSError) as exc:
+        msg = str(exc).lower().replace("-", "")
+        if "mmap" in msg and "readonly" in msg:
+            raise RuntimeError(
+                "Parallel preprocessing failed because joblib memory-mapped "
+                "a preloaded array that a preprocessor then attempted to "
+                "resize (e.g. ``filterbank``). Pass ``max_nbytes=None`` to "
+                "``preprocess`` to disable memory mapping, or supply a "
+                "``save_dir`` so the data is reloaded with ``preload=False``."
+            ) from exc
+        raise
 
     if save_dir is not None:  # Reload datasets and replace in concat_ds
         ids_to_load = [i + offset for i in range(len(concat_ds.datasets))]

{braindecode-1.5.0.dev1007 → braindecode-1.5.0.dev1010}/braindecode/preprocessing/windowers.py

@@ -498,7 +498,7 @@ def create_fixed_length_windows(
         EEGWindowsDataset objects with the extracted windows, depending on
         the value of ``use_mne_epochs``.
     """
-    stop_offset_samples, drop_last_window = (
+    stop_offset_samples, window_stride_samples, drop_last_window = (
         _check_and_set_fixed_length_window_arguments(
             start_offset_samples,
             stop_offset_samples,
@@ -886,7 +886,10 @@ def _create_fixed_length_windows(
     if mapping is not None:
         # in case of multiple targets
         if isinstance(target, pd.Series):
-            target = target.replace(mapping).to_list()
+            # Plain comprehension instead of Series.replace(mapping):
+            # replace() emits a pandas FutureWarning about silent downcasting
+            # and the result is immediately list-ified anyway.
+            target = [mapping.get(v, v) for v in target]
         # in case of single value target
         else:
             target = mapping[target]
@@ -1245,8 +1248,14 @@ def _check_and_set_fixed_length_window_arguments(
     lazy_metadata,
 ):
     """Raises warnings for incorrect input arguments and will set correct default values for
-    stop_offset_samples & drop_last_window, if necessary.
+    stop_offset_samples, window_stride_samples & drop_last_window, if necessary.
     """
+    # default stride to window size for non-overlapping windows
+    if window_size_samples is not None and window_stride_samples is None:
+        window_stride_samples = window_size_samples
+        if drop_last_window is None:
+            drop_last_window = True
+
     _check_windowing_arguments(
         start_offset_samples,
         stop_offset_samples,
@@ -1295,7 +1304,7 @@ def _check_and_set_fixed_length_window_arguments(
         raise ValueError(
             "Cannot have drop_last_window=False and lazy_metadata=True at the same time."
         )
-    return stop_offset_samples, drop_last_window
+    return stop_offset_samples, window_stride_samples, drop_last_window
 
 
 def _get_windowing_kwargs(windowing_func_locals):

braindecode-1.5.0.dev1010/braindecode/version.py

@@ -0,0 +1 @@
+__version__ = "1.5.0.dev1010"

{braindecode-1.5.0.dev1007 → braindecode-1.5.0.dev1010/braindecode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.5.0.dev1007
+Version: 1.5.0.dev1010
 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.5.0.dev1007 → braindecode-1.5.0.dev1010}/docs/whats_new.rst

@@ -22,12 +22,22 @@
 .. _current:
 
 
-Current 1.5.0 (GitHub)
+Current 1.5.0 (stable)
 ===============================
 
 Enhancements
 ============
 
+- Add :meth:`braindecode.datasets.BaseConcatDataset.set_target` to swap
+  any per-window metadata column or per-record description field
+  (e.g. a BIDS entity, a participants.tsv extra) into the dataset's
+  target ``y`` in one call, replacing the manual
+  ``for ds in concat.datasets: ds.metadata.loc[:, 'target'] = ...; ds.y = ...``
+  loop. Dispatches on the subdataset type: writes
+  ``metadata['target']`` / ``ds.y`` for windowed records, and points
+  ``target_name`` at the chosen description field for raw records.
+  By `Bruno Aristimunha`_.
+
 - Redesign the documentation landing page (``docs/index.rst``) in a
   pyhealth.dev-style layout: animated brain → EEG → net hero, fact strip
   highlighting MOABB / EEGDash interoperability, interactive model-zoo
@@ -140,11 +150,6 @@ API and behavior changes
   :class:`braindecode.models.InterpolatedLaBraM`. (:gh:`993`
   by `Pierre Guetschel`_)
 
-Requirements
-============
-
-- None yet
-
 Bug fixes
 ==========
 
@@ -173,6 +178,10 @@ Bug fixes
 - Fix ``TypeError: type 'Any' is not subscriptable`` when importing
   ``braindecode.models.config`` without ``numpydantic`` installed on
   Python 3.12+ (:gh:`871` by `Sarthak Tayal`_)
+- Fix :func:`braindecode.preprocessing.create_fixed_length_windows` crashing
+  when only ``window_size_samples`` is provided without ``window_stride_samples``,
+  stride now defaults to window size as documented
+  (:gh:`990` by `Sarthak Tayal`_)
 - Add ``channel_embedding`` parameter to :class:`braindecode.models.SignalJEPA` and
   :class:`braindecode.models.SignalJEPA_Contextual` to load pre-trained channel
   embedding weights when fine-tuning on a subset of the pre-training channels.
@@ -187,11 +196,6 @@ Bug fixes
 - Retry transient TLS failures from ``physionet.org`` when fetching
   :class:`braindecode.datasets.SleepPhysionet` (by `Bruno Aristimunha`_)
 
-Code health
-============
-
-- None yet
-
 
 Current 1.4.0 (stable)
 ===============================
@@ -289,6 +293,11 @@ Requirements
 
 Bugs
 =====
+- Improve the error message when :meth:`from_pretrained` or :meth:`push_to_hub`
+  are called without the optional ``huggingface_hub`` dependency installed.
+  Users now get a clear :class:`ImportError` with installation instructions
+  (``pip install 'braindecode[hub]'``) instead of an ``AttributeError``.
+  (:gh:`1024` by `@copilot`_)
 - Fix the documentation header "Cite Braindecode" announcement link: it used a bare
   ``cite.html`` URL, which browsers resolve relative to the current page path and led
   to 404s (for example from ``install/install.html``). The link is now built with
@@ -341,6 +350,14 @@ Bugs
   marked all model-specific parameters as "The description is missing"
   when ``DOCSTRING_INHERITANCE_ENABLE=1`` was set during documentation
   builds (:gh:`971` by `Bruno Aristimunha`_)
+- Expose ``max_nbytes`` directly on
+  :func:`braindecode.preprocessing.preprocess.preprocess` and turn the
+  cryptic ``mmap can't resize a readonly`` failure (raised when joblib
+  memory-maps a preloaded array that a preprocessor later tries to
+  resize) into an actionable error explaining how to fix it: pass
+  ``max_nbytes=None`` to disable memory mapping, or supply a ``save_dir``
+  so data is reloaded with ``preload=False``
+  (:gh:`325` by `Sarthak Tayal`_)
 
 Code health
 ============

braindecode-1.5.0.dev1007/braindecode/version.py

@@ -1 +0,0 @@
-__version__ = "1.5.0.dev1007"