braindecode 1.2.0.dev184328194__py3-none-any.whl → 1.3.0.dev171178473__py3-none-any.whl

braindecode/preprocessing/preprocess.py

@@ -30,8 +30,8 @@ from numpy.typing import NDArray
 
 from braindecode.datasets.base import (
     BaseConcatDataset,
-    BaseDataset,
     EEGWindowsDataset,
+    RawDataset,
     WindowsDataset,
 )
 from braindecode.datautil.serialization import (
@@ -55,15 +55,15 @@ class Preprocessor(object):
 
     Parameters
     ----------
-    fn: str or callable
+    fn : str or callable
         If str, the Raw/Epochs object must have a method with that name.
         If callable, directly apply the callable to the object.
     apply_on_array : bool
-        Ignored if `fn` is not a callable. If True, the `apply_function` of Raw
-        and Epochs object will be used to run `fn` on the underlying arrays
-        directly. If False, `fn` must directly modify the Raw or Epochs object.
-    kwargs:
-        Keyword arguments to be forwarded to the MNE function.
+        Ignored if ``fn`` is not a callable. If True, the ``apply_function`` of Raw
+        and Epochs will be used to run ``fn`` on the underlying arrays directly.
+        If False, ``fn`` must directly modify the Raw or Epochs object.
+    **kwargs : dict
+        Keyword arguments forwarded to the MNE function or callable.
     """
 
     def __init__(self, fn: Callable | str, *, apply_on_array: bool = True, **kwargs):
@@ -112,39 +112,38 @@ def preprocess(
     n_jobs: int | None = None,
     offset: int = 0,
     copy_data: bool | None = None,
+    parallel_kwargs: dict | None = None,
 ):
     """Apply preprocessors to a concat dataset.
 
     Parameters
     ----------
-    concat_ds: BaseConcatDataset
-        A concat of BaseDataset or WindowsDataset datasets to be preprocessed.
-    preprocessors: list(Preprocessor)
-        List of Preprocessor objects to apply to the dataset.
+    concat_ds : BaseConcatDataset
+        A concat of ``RecordDataset`` to be preprocessed.
+    preprocessors : list of Preprocessor
+        Preprocessor objects to apply to each dataset.
     save_dir : str | None
-        If a string, the preprocessed data will be saved under the specified
-        directory and the datasets in ``concat_ds`` will be reloaded with
-        `preload=False`.
+        If provided, save preprocessed data under this directory and reload
+        datasets in ``concat_ds`` with ``preload=False``.
     overwrite : bool
-        When `save_dir` is provided, controls whether to delete the old
-        subdirectories that will be written to under `save_dir`. If False and
-        the corresponding subdirectories already exist, a ``FileExistsError``
-        will be raised.
+        When ``save_dir`` is provided, controls whether to delete the old
+        subdirectories that will be written to under ``save_dir``. If False and
+        the corresponding subdirectories already exist, a ``FileExistsError`` is raised.
     n_jobs : int | None
-        Number of jobs for parallel execution. See `joblib.Parallel` for
-        a more detailed explanation.
+        Number of jobs for parallel execution. See ``joblib.Parallel`` for details.
     offset : int
-        If provided, the integer is added to the id of the dataset in the
-        concat. This is useful in the setting of very large datasets, where
-        one dataset has to be processed and saved at a time to account for
-        its original position.
+        Integer added to the dataset id in the concat. Useful when processing
+        and saving very large datasets in chunks to preserve original positions.
     copy_data : bool | None
-        Whether the data passed to the different jobs should be copied or
-        passed by reference.
+        Whether the data passed to parallel jobs should be copied or passed by reference.
+    parallel_kwargs : dict | None
+        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.
 
     Returns
     -------
-    BaseConcatDataset:
+    BaseConcatDataset
         Preprocessed dataset.
     """
     # In case of serialization, make sure directory is available before
@@ -159,8 +158,12 @@ def preprocess(
 
     parallel_processing = (n_jobs is not None) and (n_jobs != 1)
 
-    job_prefer = "threads" if platform.system() == "Windows" else None
-    list_of_ds = Parallel(n_jobs=n_jobs, prefer=job_prefer)(
+    parallel_params = {} if parallel_kwargs is None else dict(parallel_kwargs)
+    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,
@@ -226,15 +229,15 @@ def _preprocess(
 
     Parameters
     ----------
-    ds: BaseDataset | WindowsDataset
+    ds: RecordDataset
         Dataset object to preprocess.
     ds_index : int
-        Index of the BaseDataset in its BaseConcatDataset. Ignored if save_dir
+        Index of the ``RecordDataset`` in its ``BaseConcatDataset``. Ignored if save_dir
         is None.
     preprocessors: list(Preprocessor)
         List of preprocessors to apply to the dataset.
     save_dir : str | None
-        If provided, save the preprocessed BaseDataset in the
+        If provided, save the preprocessed RecordDataset in the
         specified directory.
     overwrite : bool
         If True, overwrite existing file with the same name.
@@ -260,8 +263,8 @@ def _preprocess(
         _preprocess_raw_or_epochs(ds.windows, preprocessors)
     else:
         raise ValueError(
-            "Can only preprocess concatenation of BaseDataset or "
-            "WindowsDataset, with either a `raw` or `windows` attribute."
+            "Can only preprocess concatenation of RecordDataset, "
+            "with either a `raw` or `windows` attribute."
         )
 
     # Store preprocessing keyword arguments in the dataset
@@ -294,11 +297,11 @@ def _get_preproc_kwargs(preprocessors):
 
 
 def _set_preproc_kwargs(ds, preprocessors):
-    """Record preprocessing keyword arguments in BaseDataset or WindowsDataset.
+    """Record preprocessing keyword arguments in RecordDataset.
 
     Parameters
     ----------
-    ds : BaseDataset | WindowsDataset
+    ds : RecordDataset
         Dataset in which to record preprocessing keyword arguments.
     preprocessors : list
         List of preprocessors.
@@ -306,12 +309,12 @@ def _set_preproc_kwargs(ds, preprocessors):
     preproc_kwargs = _get_preproc_kwargs(preprocessors)
     if isinstance(ds, WindowsDataset):
         kind = "window"
-    if isinstance(ds, EEGWindowsDataset):
+    elif isinstance(ds, EEGWindowsDataset):
         kind = "raw"
-    elif isinstance(ds, BaseDataset):
+    elif isinstance(ds, RawDataset):
         kind = "raw"
     else:
-        raise TypeError(f"ds must be a BaseDataset or a WindowsDataset, got {type(ds)}")
+        raise TypeError(f"ds must be a RecordDataset, got {type(ds)}")
     setattr(ds, kind + "_preproc_kwargs", preproc_kwargs)
 
 

braindecode/preprocessing/util.py

@@ -0,0 +1,166 @@
+"""Utilities for preprocessing functionality in Braindecode."""
+
+# Authors: Christian Kothe <christian.kothe@intheon.io>
+#
+# License: BSD-3
+
+import base64
+import json
+import re
+from typing import Any
+
+import numpy as np
+from mne.io.base import BaseRaw
+
+__all__ = ["mne_store_metadata", "mne_load_metadata"]
+
+
+# Use a unique marker for embedding structured data in info['description']
+_MARKER_PATTERN = re.compile(r"<!-- braindecode-meta:\s*(\S+)\s*-->", re.DOTALL)
+_MARKER_START = "<!-- braindecode-meta:"
+_MARKER_END = "-->"
+
+# Marker key for numpy arrays
+_NP_ARRAY_TAG = "__numpy_array__"
+
+
+def _numpy_decoder(dct):
+    """Internal JSON decoder hook to handle numpy arrays."""
+    if dct.get(_NP_ARRAY_TAG):
+        arr = np.array(dct["data"], dtype=dct["dtype"])
+        return arr.reshape(dct["shape"])
+    return dct
+
+
+class NumpyEncoder(json.JSONEncoder):
+    """Custom JSON encoder hook to handle numpy arrays."""
+
+    def default(self, obj):
+        if isinstance(obj, np.ndarray):
+            # Reject complex-valued dtypes as they're not JSON serializable
+            if np.issubdtype(obj.dtype, np.complexfloating):
+                raise TypeError(
+                    f"Cannot serialize numpy array with complex dtype {obj.dtype}. "
+                    "Complex dtypes are not supported."
+                )
+            return {
+                _NP_ARRAY_TAG: True,
+                "dtype": obj.dtype.str,
+                "shape": obj.shape,
+                "data": obj.flatten().tolist(),
+            }
+        return super().default(obj)
+
+
+def _encode_payload(data: dict) -> str:
+    """Serializes, encodes, and formats data into a marker string."""
+    json_str = json.dumps(data, cls=NumpyEncoder)
+    encoded = base64.b64encode(json_str.encode("utf-8")).decode("ascii")
+    return f"{_MARKER_START} {encoded} {_MARKER_END}"
+
+
+def mne_store_metadata(
+    raw: BaseRaw, payload: Any, *, key: str, no_overwrite: bool = False
+) -> None:
+    """Embed a JSON-serializable metadata payload in an MNE BaseRaw dataset
+    under a specified key.
+
+    This will encode the payload as a base64-encoded JSON string and store it
+    in the `info['description']` field of the Raw object while preserving any
+    existing content. Note this is not particularly efficient and should not
+    be used for very large payloads.
+
+    Parameters
+    ----------
+    raw : BaseRaw
+        The MNE Raw object to store data in.
+    payload : Any
+        The JSON-serializable data to store.
+    key : str
+        The key under which to store the payload.
+    no_overwrite : bool
+        If True, will not overwrite an existing entry with the same key.
+
+    """
+    # the description is apparently the only viable place where custom metadata may be
+    # stored in MNE Raw objects that persists through saving/loading
+    description = raw.info.get("description") or ""
+
+    # Try to find existing eegprep data
+    if match := _MARKER_PATTERN.search(description):
+        # Parse existing data
+        try:
+            decoded = base64.b64decode(match.group(1)).decode("utf-8")
+            existing_data = json.loads(decoded, object_hook=_numpy_decoder)
+        except (ValueError, json.JSONDecodeError):
+            existing_data = {}
+        # Check no_overwrite condition
+        if no_overwrite and key in existing_data:
+            return
+        # Update data
+        existing_data[key] = payload
+        new_marker = _encode_payload(existing_data)
+        # Replace the old marker with updated one
+        new_description = _MARKER_PATTERN.sub(new_marker, description, count=1)
+    else:
+        # No existing data, append new marker
+        data = {key: payload}
+        new_marker = _encode_payload(data)
+        # Append with spacing if description exists
+        if description.strip():
+            new_description = f"{description.rstrip()}\n{new_marker}"
+        else:
+            new_description = new_marker
+
+    raw.info["description"] = new_description
+
+
+def mne_load_metadata(raw: BaseRaw, *, key: str, delete: bool = False) -> Any | None:
+    """Retrieves data that was previously stored using mne_store_metadata from an MNE
+    BaseRaw dataset.
+
+    This function can retrieve data from an MNE Raw object that was stored
+    using `mne_store_metadata`. It decodes the base64-encoded JSON string from the
+    `info['description']` field and extracts the payload associated with the
+    specified key.
+
+    Parameters
+    ----------
+    raw : BaseRaw
+        The MNE Raw object to retrieve data from.
+    key : str
+        The key under which the payload was stored.
+    delete : bool
+        If True, removes the key from the stored data after retrieval.
+
+    Returns
+    -------
+    Any | None
+        The retrieved payload, or None if not found.
+    """
+    description = raw.info.get("description") or ""
+    match = _MARKER_PATTERN.search(description)
+    if not match:
+        return None
+
+    try:
+        decoded = base64.b64decode(match.group(1)).decode("utf-8")
+        data = json.loads(decoded, object_hook=_numpy_decoder)
+    except (ValueError, json.JSONDecodeError):
+        return None
+
+    result = data.get(key)
+
+    if delete and key in data:
+        # Remove the key from data
+        del data[key]
+        if data:
+            # Still have other keys, update the marker
+            new_marker = _encode_payload(data)
+            new_description = _MARKER_PATTERN.sub(new_marker, description, count=1)
+        else:
+            # No more keys, remove the entire marker
+            new_description = _MARKER_PATTERN.sub("", description, count=1).rstrip()
+        raw.info["description"] = new_description
+
+    return result

braindecode/preprocessing/windowers.py

@@ -25,7 +25,12 @@ import pandas as pd
 from joblib import Parallel, delayed
 from numpy.typing import ArrayLike
 
-from ..datasets.base import BaseConcatDataset, EEGWindowsDataset, WindowsDataset
+from ..datasets.base import (
+    BaseConcatDataset,
+    EEGWindowsDataset,
+    RawDataset,
+    WindowsDataset,
+)
 
 
 class _LazyDataFrame:
@@ -189,7 +194,7 @@ def _get_use_mne_epochs(use_mne_epochs, reject, picks, flat, drop_bad_windows):
 
 # XXX it's called concat_ds...
 def create_windows_from_events(
-    concat_ds: BaseConcatDataset,
+    concat_ds: BaseConcatDataset[RawDataset],
     trial_start_offset_samples: int = 0,
     trial_stop_offset_samples: int = 0,
     window_size_samples: int | None = None,
@@ -206,7 +211,7 @@ def create_windows_from_events(
     use_mne_epochs: bool | None = None,
     n_jobs: int = 1,
     verbose: bool | str | int | None = "error",
-):
+) -> BaseConcatDataset[WindowsDataset | EEGWindowsDataset]:
     """Create windows based on events in mne.Raw.
 
     This function extracts windows of size window_size_samples in the interval
@@ -228,7 +233,7 @@ def create_windows_from_events(
 
     Parameters
     ----------
-    concat_ds: BaseConcatDataset
+    concat_ds: BaseConcatDataset[RawDataset]
         A concat of base datasets each holding raw and description.
     trial_start_offset_samples: int
         Start offset from original trial onsets, in samples. Defaults to zero.
@@ -268,7 +273,7 @@ def create_windows_from_events(
         rejection based on flatness is done. See mne.Epochs.
     on_missing: str
         What to do if one or several event ids are not found in the recording.
-        Valid keys are ‘error’ | ‘warning’ | ‘ignore’. See mne.Epochs.
+        Valid keys are ‘error' | ‘warning' | ‘ignore'. See mne.Epochs.
     accepted_bads_ratio: float, optional
         Acceptable proportion of trials with inconsistent length in a raw. If
         the number of trials whose length is exceeded by the window size is
@@ -286,7 +291,7 @@ def create_windows_from_events(
 
     Returns
     -------
-    windows_datasets: BaseConcatDataset
+    windows_datasets: BaseConcatDataset[WindowsDataset | EEGWindowsDataset]
         Concatenated datasets of WindowsDataset containing the extracted windows.
     """
     _check_windowing_arguments(
@@ -341,7 +346,7 @@ def create_windows_from_events(
 
 
 def create_fixed_length_windows(
-    concat_ds: BaseConcatDataset,
+    concat_ds: BaseConcatDataset[RawDataset],
     start_offset_samples: int = 0,
     stop_offset_samples: int | None = None,
     window_size_samples: int | None = None,
@@ -358,12 +363,12 @@ def create_fixed_length_windows(
     on_missing: str = "error",
     n_jobs: int = 1,
     verbose: bool | str | int | None = "error",
-):
+) -> BaseConcatDataset[EEGWindowsDataset]:
     """Windower that creates sliding windows.
 
     Parameters
     ----------
-    concat_ds: ConcatDataset
+    concat_ds: ConcatDataset[RawDataset]
         A concat of base datasets each holding raw and description.
     start_offset_samples: int
         Start offset from beginning of recording in samples.
@@ -398,7 +403,7 @@ def create_fixed_length_windows(
         by using the _LazyDataFrame (experimental).
     on_missing: str
         What to do if one or several event ids are not found in the recording.
-        Valid keys are ‘error’ | ‘warning’ | ‘ignore’. See mne.Epochs.
+        Valid keys are ‘error' | ‘warning' | ‘ignore'. See mne.Epochs.
     n_jobs: int
         Number of jobs to use to parallelize the windowing.
     verbose: bool | str | int | None
@@ -406,7 +411,7 @@ def create_fixed_length_windows(
 
     Returns
     -------
-    windows_datasets: BaseConcatDataset
+    windows_datasets: BaseConcatDataset[EEGWindowsDataset]
         Concatenated datasets of WindowsDataset containing the extracted windows.
     """
     stop_offset_samples, drop_last_window = (
@@ -473,11 +478,11 @@ def _create_windows_from_events(
     verbose="error",
     use_mne_epochs=False,
 ):
-    """Create WindowsDataset from BaseDataset based on events.
+    """Create WindowsDataset from RawDataset based on events.
 
     Parameters
     ----------
-    ds : BaseDataset
+    ds : RawDataset
         Dataset containing continuous data and description.
     infer_mapping : bool
         If True, extract all events from all datasets and map them to
@@ -648,11 +653,11 @@ def _create_fixed_length_windows(
     on_missing="error",
     verbose="error",
 ):
-    """Create WindowsDataset from BaseDataset with sliding windows.
+    """Create WindowsDataset from RawDataset with sliding windows.
 
     Parameters
     ----------
-    ds : BaseDataset
+    ds : RawDataset
         Dataset containing continuous data and description.
 
     See `create_fixed_length_windows` for description of other parameters.
@@ -750,7 +755,7 @@ def _create_fixed_length_windows(
 
 
 def create_windows_from_target_channels(
-    concat_ds,
+    concat_ds: BaseConcatDataset[RawDataset],
     window_size_samples=None,
     preload=False,
     picks=None,
@@ -759,7 +764,7 @@ def create_windows_from_target_channels(
     n_jobs=1,
     last_target_only=True,
     verbose="error",
-):
+) -> BaseConcatDataset[EEGWindowsDataset]:
     list_of_windows_ds = Parallel(n_jobs=n_jobs)(
         delayed(_create_windows_from_target_channels)(
             ds,
@@ -788,11 +793,11 @@ def _create_windows_from_target_channels(
     on_missing="error",
     verbose="error",
 ):
-    """Create WindowsDataset from BaseDataset using targets `misc` channels from mne.Raw.
+    """Create WindowsDataset from RawDataset using targets `misc` channels from mne.Raw.
 
     Parameters
     ----------
-    ds : BaseDataset
+    ds : RawDataset
         Dataset containing continuous data and description.
 
     See `create_fixed_length_windows` for description of other parameters.

braindecode/samplers/base.py

@@ -122,14 +122,14 @@ class DistributedRecordingSampler(DistributedSampler):
         DataFrame with at least one of {subject, session, run} columns for each
         window in the BaseConcatDataset to sample examples from. Normally
         obtained with `BaseConcatDataset.get_metadata()`. For instance,
-        `metadata.head()` might look like this:
-
-           i_window_in_trial  i_start_in_trial  i_stop_in_trial  target  subject    session    run
-        0                  0                 0              500      -1        4  session_T  run_0
-        1                  1               500             1000      -1        4  session_T  run_0
-        2                  2              1000             1500      -1        4  session_T  run_0
-        3                  3              1500             2000      -1        4  session_T  run_0
-        4                  4              2000             2500      -1        4  session_T  run_0
+        `metadata.head()` might look like this::
+
+            i_window_in_trial  i_start_in_trial  i_stop_in_trial  target  subject    session    run
+            0                  0                 0              500      -1        4  session_T  run_0
+            1                  1               500             1000      -1        4  session_T  run_0
+            2                  2              1000             1500      -1        4  session_T  run_0
+            3                  3              1500             2000      -1        4  session_T  run_0
+            4                  4              2000             2500      -1        4  session_T  run_0
 
     random_state : np.RandomState | int | None
         Random state.

braindecode/version.py

@@ -1 +1 @@
-__version__ = "1.2.0.dev184328194"
+__version__ = "1.3.0.dev171178473"

{braindecode-1.2.0.dev184328194.dist-info → braindecode-1.3.0.dev171178473.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: braindecode
-Version: 1.2.0.dev184328194
+Version: 1.3.0.dev171178473
 Summary: Deep learning software to decode EEG, ECG or MEG signals
 Author-email: Robin Tibor Schirrmeister <robintibor@gmail.com>
 Maintainer-email: Alexandre Gramfort <agramfort@meta.com>, Bruno Aristimunha Pinto <b.aristimunha@gmail.com>, Robin Tibor Schirrmeister <robintibor@gmail.com>
@@ -17,7 +17,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >3.10
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 License-File: NOTICE.txt
@@ -40,6 +40,10 @@ Requires-Dist: linear_attention_transformer
 Requires-Dist: docstring_inheritance
 Provides-Extra: moabb
 Requires-Dist: moabb>=1.2.0; extra == "moabb"
+Provides-Extra: eegprep
+Requires-Dist: eegprep[eeglabio]>=0.1.1; extra == "eegprep"
+Provides-Extra: hug
+Requires-Dist: huggingface_hub[torch]>=0.20.0; extra == "hug"
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
@@ -49,6 +53,10 @@ Requires-Dist: mypy; extra == "tests"
 Provides-Extra: docs
 Requires-Dist: sphinx_gallery; extra == "docs"
 Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+Requires-Dist: sphinx-autobuild; extra == "docs"
+Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
+Requires-Dist: sphinx_sitemap; extra == "docs"
 Requires-Dist: pydata_sphinx_theme; extra == "docs"
 Requires-Dist: numpydoc; extra == "docs"
 Requires-Dist: memory_profiler; extra == "docs"
@@ -59,8 +67,9 @@ Requires-Dist: lightning; extra == "docs"
 Requires-Dist: seaborn; extra == "docs"
 Requires-Dist: pre-commit; extra == "docs"
 Requires-Dist: openneuro-py; extra == "docs"
+Requires-Dist: plotly; extra == "docs"
 Provides-Extra: all
-Requires-Dist: braindecode[docs,moabb,tests]; extra == "all"
+Requires-Dist: braindecode[docs,eegprep,hug,moabb,tests]; extra == "all"
 Dynamic: license-file
 
 .. image:: https://badges.gitter.im/braindecodechat/community.svg