eegdash 0.3.3.dev61__py3-none-any.whl → 0.5.0.dev180784713__py3-none-any.whl

eegdash/features/inspect.py

@@ -1,15 +1,50 @@
+from __future__ import annotations
+
 import inspect
 from collections.abc import Callable
 
 from . import extractors, feature_bank
-from .extractors import FeatureExtractor, MultivariateFeature, _get_underlying_func
+from .extractors import _get_underlying_func
+
+__all__ = [
+    "get_all_feature_extractors",
+    "get_all_feature_preprocessors",
+    "get_all_feature_kinds",
+    "get_all_features",
+    "get_feature_kind",
+    "get_feature_predecessors",
+]
+
+
+def get_feature_predecessors(feature_or_extractor: Callable | None) -> list:
+    """Get the dependency hierarchy for a feature or feature extractor.
 
+    This function recursively traverses the `parent_extractor_type` attribute
+    of a feature or extractor to build a list representing its dependency
+    lineage.
 
-def get_feature_predecessors(feature_or_extractor: Callable):
+    Parameters
+    ----------
+    feature_or_extractor : callable
+        The feature function or :class:`~eegdash.features.extractors.FeatureExtractor`
+        class to inspect.
+
+    Returns
+    -------
+    list
+        A nested list representing the dependency tree. For a simple linear
+        chain, this will be a flat list from the specific feature up to the
+        base :class:`~eegdash.features.extractors.FeatureExtractor`. For
+        multiple dependencies, it will contain tuples of sub-dependencies.
+
+    """
+    current = feature_or_extractor
+    if current is None:
+        return [None]
+    if isinstance(current, extractors.FeatureExtractor):
+        current = current.preprocessor
     current = _get_underlying_func(feature_or_extractor)
-    if current is FeatureExtractor:
-        return [current]
-    predecessor = getattr(current, "parent_extractor_type", [FeatureExtractor])
+    predecessor = getattr(current, "parent_extractor_type", [None])
     if len(predecessor) == 1:
         return [current, *get_feature_predecessors(predecessor[0])]
     else:
@@ -20,29 +55,105 @@ def get_feature_predecessors(feature_or_extractor: Callable):
         return [current, tuple(predecessors)]
 
 
-def get_feature_kind(feature: Callable):
+def get_feature_kind(feature: Callable) -> extractors.MultivariateFeature:
+    """Get the 'kind' of a feature function.
+
+    The feature kind (e.g., univariate, bivariate) is typically attached by a
+    decorator.
+
+    Parameters
+    ----------
+    feature : callable
+        The feature function to inspect.
+
+    Returns
+    -------
+    :class:`~eegdash.features.extractors.MultivariateFeature`
+        An instance of the feature kind (e.g., ``UnivariateFeature()``).
+
+    """
     return _get_underlying_func(feature).feature_kind
 
 
-def get_all_features():
+def get_all_features() -> list[tuple[str, Callable]]:
+    """Get a list of all available feature functions.
+
+    Scans the `eegdash.features.feature_bank` module for functions that have
+    been decorated to have a `feature_kind` attribute.
+
+    Returns
+    -------
+    list[tuple[str, callable]]
+        A list of (name, function) tuples for all discovered features.
+
+    """
+
     def isfeature(x):
         return hasattr(_get_underlying_func(x), "feature_kind")
 
     return inspect.getmembers(feature_bank, isfeature)
 
 
-def get_all_feature_extractors():
+def get_all_feature_extractors() -> list[tuple[str, Callable]]:
+    """Get a list of all available feature extractor callables.
+
+    A feature extractor is any callable in the feature bank that participates
+    in the feature graph, meaning it declares a ``parent_extractor_type``
+    via :class:`~eegdash.features.decorators.FeaturePredecessor`. This
+    includes both preprocessors and the final feature functions.
+
+    Returns
+    -------
+    list[tuple[str, callable]]
+        A list of (name, callable) tuples for all discovered feature
+        extractors.
+
+    """
+
     def isfeatureextractor(x):
-        return inspect.isclass(x) and issubclass(x, FeatureExtractor)
+        y = _get_underlying_func(x)
+        return callable(y) and hasattr(y, "parent_extractor_type")
+
+    return inspect.getmembers(feature_bank, isfeatureextractor)
+
+
+def get_all_feature_preprocessors() -> list[tuple[str, Callable]]:
+    """Get a list of all available preprocessor functions.
+
+    Scans the `eegdash.features.feature_bank` module for all preprocessor functions.
+
+    Returns
+    -------
+    list[tuple[str, Callable]]
+        A list of (name, function) tuples for all discovered feature preprocessors.
+
+    """
+
+    def isfeatureextractor(x):
+        y = _get_underlying_func(x)
+        return (
+            callable(y)
+            and not hasattr(y, "feature_kind")
+            and hasattr(y, "parent_extractor_type")
+        )
+
+    return inspect.getmembers(feature_bank, isfeatureextractor)
+
+
+def get_all_feature_kinds() -> list[tuple[str, type[extractors.MultivariateFeature]]]:
+    """Get a list of all available feature 'kind' classes.
+
+    Scans the `eegdash.features.extractors` module for all classes that
+    subclass :class:`~eegdash.features.extractors.MultivariateFeature`.
 
-    return [
-        ("FeatureExtractor", FeatureExtractor),
-        *inspect.getmembers(feature_bank, isfeatureextractor),
-    ]
+    Returns
+    -------
+    list[tuple[str, type[eegdash.features.extractors.MultivariateFeature]]]
+        A list of (name, class) tuples for all discovered feature kinds.
 
+    """
 
-def get_all_feature_kinds():
     def isfeaturekind(x):
-        return inspect.isclass(x) and issubclass(x, MultivariateFeature)
+        return inspect.isclass(x) and issubclass(x, extractors.MultivariateFeature)
 
     return inspect.getmembers(extractors, isfeaturekind)

eegdash/features/serialization.py

@@ -1,8 +1,13 @@
-"""Convenience functions for storing and loading of features datasets.
+"""Convenience functions for storing and loading features datasets.
+
+See Also
+--------
+https://github.com/braindecode/braindecode/blob/master/braindecode/datautil/serialization.py#L165-L229
 
-see also: https://github.com/braindecode/braindecode//blob/master/braindecode/datautil/serialization.py#L165-L229
 """
 
+from __future__ import annotations
+
 from pathlib import Path
 
 import pandas as pd
@@ -13,33 +18,48 @@ from braindecode.datautil.serialization import _load_kwargs_json
 
 from .datasets import FeaturesConcatDataset, FeaturesDataset
 
+__all__ = [
+    "load_features_concat_dataset",
+]
+
+
+def load_features_concat_dataset(
+    path: str | Path, ids_to_load: list[int] | None = None, n_jobs: int = 1
+) -> FeaturesConcatDataset:
+    """Load a stored :class:`~eegdash.features.datasets.FeaturesConcatDataset` from a directory.
 
-def load_features_concat_dataset(path, ids_to_load=None, n_jobs=1):
-    """Load a stored FeaturesConcatDataset of FeaturesDatasets from files.
+    This function reconstructs a
+    :class:`~eegdash.features.datasets.FeaturesConcatDataset` by loading
+    individual :class:`~eegdash.features.datasets.FeaturesDataset` instances
+    from subdirectories within the given path. It uses joblib for parallel
+    loading.
 
     Parameters
     ----------
-    path: str | pathlib.Path
-        Path to the directory of the .fif / -epo.fif and .json files.
-    ids_to_load: list of int | None
-        Ids of specific files to load.
-    n_jobs: int
-        Number of jobs to be used to read files in parallel.
+    path : str or pathlib.Path
+        The path to the directory where the dataset was saved. This directory
+        should contain subdirectories (e.g., "0", "1", "2", ...) for each
+        individual dataset.
+    ids_to_load : list of int, optional
+        A list of specific dataset IDs (subdirectory names) to load. If None,
+        all subdirectories in the path will be loaded.
+    n_jobs : int, default 1
+        The number of jobs to use for parallel loading. -1 means using all
+        processors.
 
     Returns
     -------
-    concat_dataset: FeaturesConcatDataset of FeaturesDatasets
+    eegdash.features.datasets.FeaturesConcatDataset
+        A concatenated dataset containing the loaded
+        :class:`~eegdash.features.datasets.FeaturesDataset` instances.
 
     """
     # Make sure we always work with a pathlib.Path
     path = Path(path)
 
-    # else we have a dataset saved in the new way with subdirectories in path
-    # for every dataset with description.json and -feat.parquet,
-    # target_name.json, raw_preproc_kwargs.json, window_kwargs.json,
-    # window_preproc_kwargs.json, features_kwargs.json
     if ids_to_load is None:
-        ids_to_load = [p.name for p in path.iterdir()]
+        # Get all subdirectories and sort them numerically
+        ids_to_load = [p.name for p in path.iterdir() if p.is_dir()]
         ids_to_load = sorted(ids_to_load, key=lambda i: int(i))
     ids_to_load = [str(i) for i in ids_to_load]
 
@@ -47,7 +67,28 @@ def load_features_concat_dataset(path, ids_to_load=None, n_jobs=1):
     return FeaturesConcatDataset(datasets)
 
 
-def _load_parallel(path, i):
+def _load_parallel(path: Path, i: str) -> FeaturesDataset:
+    """Load a single :class:`~eegdash.features.datasets.FeaturesDataset` from its subdirectory.
+
+    This is a helper function for
+    :func:`~eegdash.features.serialization.load_features_concat_dataset` that
+    handles the loading of one dataset's files (features, metadata, descriptions, etc.).
+
+    Parameters
+    ----------
+    path : pathlib.Path
+        The root directory of the saved
+        :class:`~eegdash.features.datasets.FeaturesConcatDataset`.
+    i : str
+        The identifier of the dataset to load, corresponding to its
+        subdirectory name.
+
+    Returns
+    -------
+    eegdash.features.datasets.FeaturesDataset
+        The loaded dataset instance.
+
+    """
     sub_dir = path / i
 
     parquet_name_pattern = "{}-feat.parquet"

eegdash/features/utils.py

@@ -14,15 +14,41 @@ from braindecode.datasets.base import (
     WindowsDataset,
 )
 
+from . import extractors
 from .datasets import FeaturesConcatDataset, FeaturesDataset
-from .extractors import FeatureExtractor
+
+__all__ = [
+    "extract_features",
+    "fit_feature_extractors",
+]
 
 
 def _extract_features_from_windowsdataset(
     win_ds: EEGWindowsDataset | WindowsDataset,
-    feature_extractor: FeatureExtractor,
+    feature_extractor: extractors.FeatureExtractor,
     batch_size: int = 512,
-):
+) -> FeaturesDataset:
+    """Extract features from a single `WindowsDataset`.
+
+    This is a helper function that iterates through a `WindowsDataset` in
+    batches, applies a `FeatureExtractor`, and returns the results as a
+    `FeaturesDataset`.
+
+    Parameters
+    ----------
+    win_ds : EEGWindowsDataset or WindowsDataset
+        The windowed dataset to extract features from.
+    feature_extractor : ~eegdash.features.extractors.FeatureExtractor
+        The feature extractor instance to apply.
+    batch_size : int, default 512
+        The number of windows to process in each batch.
+
+    Returns
+    -------
+    ~eegdash.features.datasets.FeaturesDataset
+        A new dataset containing the extracted features and associated metadata.
+
+    """
     metadata = win_ds.metadata
     if not win_ds.targets_from == "metadata":
         metadata = copy.deepcopy(metadata)
@@ -51,33 +77,59 @@ def _extract_features_from_windowsdataset(
             features_dict[k].extend(v)
     features_df = pd.DataFrame(features_dict)
     if not win_ds.targets_from == "metadata":
-        metadata.set_index("orig_index", drop=False, inplace=True)
         metadata.reset_index(drop=True, inplace=True)
-        metadata.drop("orig_index", axis=1, inplace=True)
+        metadata.drop("orig_index", axis=1, inplace=True, errors="ignore")
 
-    # FUTURE: truly support WindowsDataset objects
     return FeaturesDataset(
         features_df,
         metadata=metadata,
         description=win_ds.description,
         raw_info=win_ds.raw.info,
-        raw_preproc_kwargs=win_ds.raw_preproc_kwargs,
-        window_kwargs=win_ds.window_kwargs,
+        raw_preproc_kwargs=getattr(win_ds, "raw_preproc_kwargs", None),
+        window_kwargs=getattr(win_ds, "window_kwargs", None),
         features_kwargs=feature_extractor.features_kwargs,
     )
 
 
 def extract_features(
     concat_dataset: BaseConcatDataset,
-    features: FeatureExtractor | Dict[str, Callable] | List[Callable],
+    features: extractors.FeatureExtractor | Dict[str, Callable] | List[Callable],
     *,
     batch_size: int = 512,
     n_jobs: int = 1,
-):
+) -> FeaturesConcatDataset:
+    """Extract features from a concatenated dataset of windows.
+
+    This function applies a feature extractor to each `WindowsDataset` within a
+    `BaseConcatDataset` in parallel and returns a `FeaturesConcatDataset`
+    with the results.
+
+    Parameters
+    ----------
+    concat_dataset : BaseConcatDataset
+        A concatenated dataset of `WindowsDataset` or `EEGWindowsDataset`
+        instances.
+    features : ~eegdash.features.extractors.FeatureExtractor or dict or list
+        The feature extractor(s) to apply. Can be a
+        :class:`~eegdash.features.extractors.FeatureExtractor`
+        instance, a dictionary of named feature functions, or a list of
+        feature functions.
+    batch_size : int, default 512
+        The size of batches to use for feature extraction.
+    n_jobs : int, default 1
+        The number of parallel jobs to use for extracting features from the
+        datasets.
+
+    Returns
+    -------
+    ~eegdash.features.datasets.FeaturesConcatDataset
+        A new concatenated dataset containing the extracted features.
+
+    """
     if isinstance(features, list):
         features = dict(enumerate(features))
-    if not isinstance(features, FeatureExtractor):
-        features = FeatureExtractor(features)
+    if not isinstance(features, extractors.FeatureExtractor):
+        features = extractors.FeatureExtractor(features)
     feature_ds_list = list(
         tqdm(
             Parallel(n_jobs=n_jobs, return_as="generator")(
@@ -95,13 +147,35 @@ def extract_features(
 
 def fit_feature_extractors(
     concat_dataset: BaseConcatDataset,
-    features: FeatureExtractor | Dict[str, Callable] | List[Callable],
+    features: extractors.FeatureExtractor | Dict[str, Callable] | List[Callable],
     batch_size: int = 8192,
-):
+) -> extractors.FeatureExtractor:
+    """Fit trainable feature extractors on a dataset.
+
+    If the provided feature extractor (or any of its sub-extractors) is
+    trainable (i.e., subclasses
+    :class:`~eegdash.features.extractors.TrainableFeature`), this function
+    iterates through the dataset to fit it.
+
+    Parameters
+    ----------
+    concat_dataset : BaseConcatDataset
+        The dataset to use for fitting the feature extractors.
+    features : ~eegdash.features.extractors.FeatureExtractor or dict or list
+        The feature extractor(s) to fit.
+    batch_size : int, default 8192
+        The batch size to use when iterating through the dataset for fitting.
+
+    Returns
+    -------
+    ~eegdash.features.extractors.FeatureExtractor
+        The fitted feature extractor.
+
+    """
     if isinstance(features, list):
         features = dict(enumerate(features))
-    if not isinstance(features, FeatureExtractor):
-        features = FeatureExtractor(features)
+    if not isinstance(features, extractors.FeatureExtractor):
+        features = extractors.FeatureExtractor(features)
     if not features._is_trainable:
         return features
     features.clear()

eegdash/hbn/__init__.py

@@ -0,0 +1,28 @@
+# Authors: The EEGDash contributors.
+# License: BSD-3-Clause
+# Copyright the EEGDash contributors.
+
+"""Healthy Brain Network (HBN) specific utilities and preprocessing.
+
+This module provides specialized functions for working with the Healthy Brain Network
+dataset, including preprocessing pipelines, annotation handling, and windowing utilities
+tailored for HBN EEG data analysis.
+"""
+
+from .preprocessing import hbn_ec_ec_reannotation
+from .windows import (
+    add_aux_anchors,
+    add_extras_columns,
+    annotate_trials_with_target,
+    build_trial_table,
+    keep_only_recordings_with,
+)
+
+__all__ = [
+    "hbn_ec_ec_reannotation",
+    "build_trial_table",
+    "annotate_trials_with_target",
+    "add_aux_anchors",
+    "add_extras_columns",
+    "keep_only_recordings_with",
+]

eegdash/hbn/preprocessing.py

@@ -0,0 +1,105 @@
+# Authors: The EEGDash contributors.
+# License: BSD-3-Clause
+# Copyright the EEGDash contributors.
+
+"""Preprocessing utilities specific to the Healthy Brain Network dataset.
+
+This module contains preprocessing classes and functions designed specifically for
+HBN EEG data, including specialized annotation handling for eyes-open/eyes-closed
+paradigms and other HBN-specific preprocessing steps.
+"""
+
+import mne
+import numpy as np
+
+from braindecode.preprocessing import Preprocessor
+
+from ..logging import logger
+
+
+class hbn_ec_ec_reannotation(Preprocessor):
+    """Preprocessor to reannotate HBN data for eyes-open/eyes-closed events.
+
+    This preprocessor is specifically designed for Healthy Brain Network (HBN)
+    datasets. It identifies existing annotations for "instructed_toCloseEyes"
+    and "instructed_toOpenEyes" and creates new, regularly spaced annotations
+    for "eyes_closed" and "eyes_open" segments, respectively.
+
+    This is useful for creating windowed datasets based on these new, more
+    precise event markers.
+
+    Notes
+    -----
+    This class inherits from :class:`braindecode.preprocessing.Preprocessor`
+    and is intended to be used within a braindecode preprocessing pipeline.
+
+    """
+
+    def __init__(self):
+        super().__init__(fn=self.transform, apply_on_array=False)
+
+    def transform(self, raw: mne.io.Raw) -> mne.io.Raw:
+        """Create new annotations for eyes-open and eyes-closed periods.
+
+        This function finds the original "instructed_to..." annotations and
+        generates new annotations every 2 seconds within specific time ranges
+        relative to the original markers:
+        - "eyes_closed": 15s to 29s after "instructed_toCloseEyes"
+        - "eyes_open": 5s to 19s after "instructed_toOpenEyes"
+
+        The original annotations in the `mne.io.Raw` object are replaced by
+        this new set of annotations.
+
+        Parameters
+        ----------
+        raw : mne.io.Raw
+            The raw MNE object containing the HBN data and original annotations.
+
+        Returns
+        -------
+        mne.io.Raw
+            The raw MNE object with the modified annotations.
+
+        """
+        events, event_id = mne.events_from_annotations(raw)
+
+        logger.info("Original events found with ids: %s", event_id)
+
+        # Create new events array for 2-second segments
+        new_events = []
+        sfreq = raw.info["sfreq"]
+
+        close_event_id = event_id.get("instructed_toCloseEyes")
+        if close_event_id:
+            for event in events[events[:, 2] == close_event_id]:
+                # For each original event, create events every 2s from 15s to 29s after
+                start_times = event[0] + np.arange(15, 29, 2) * sfreq
+                new_events.extend([[int(t), 0, 1] for t in start_times])
+
+        open_event_id = event_id.get("instructed_toOpenEyes")
+        if open_event_id:
+            for event in events[events[:, 2] == open_event_id]:
+                # For each original event, create events every 2s from 5s to 19s after
+                start_times = event[0] + np.arange(5, 19, 2) * sfreq
+                new_events.extend([[int(t), 0, 2] for t in start_times])
+
+        if not new_events:
+            logger.warning(
+                "Could not find 'instructed_toCloseEyes' or 'instructed_toOpenEyes' "
+                "annotations. No new events created."
+            )
+            return raw
+
+        # replace events in raw
+        new_events = np.array(new_events)
+
+        annot_from_events = mne.annotations_from_events(
+            events=new_events,
+            event_desc={1: "eyes_closed", 2: "eyes_open"},
+            sfreq=raw.info["sfreq"],
+            orig_time=raw.info.get("meas_date"),
+        )
+
+        raw.set_annotations(annot_from_events)
+
+        return raw