eegdash 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

eegdash/features/__init__.py

@@ -1,25 +1,53 @@
-# Features datasets
 from .datasets import FeaturesConcatDataset, FeaturesDataset
 from .decorators import (
     FeatureKind,
     FeaturePredecessor,
     bivariate_feature,
-    directed_bivariate_feature,
     multivariate_feature,
     univariate_feature,
 )
-
-# Feature extraction
 from .extractors import (
     BivariateFeature,
     DirectedBivariateFeature,
     FeatureExtractor,
-    FitableFeature,
     MultivariateFeature,
+    TrainableFeature,
     UnivariateFeature,
 )
-
-# Features:
-from .feature_bank import *
+from .feature_bank import *  # noqa: F401
+from .inspect import (
+    get_all_feature_extractors,
+    get_all_feature_kinds,
+    get_all_features,
+    get_feature_kind,
+    get_feature_predecessors,
+)
 from .serialization import load_features_concat_dataset
-from .utils import extract_features, fit_feature_extractors
+from .utils import (
+    extract_features,
+    fit_feature_extractors,
+)
+
+__all__ = [
+    "FeaturesConcatDataset",
+    "FeaturesDataset",
+    "FeatureKind",
+    "FeaturePredecessor",
+    "bivariate_feature",
+    "multivariate_feature",
+    "univariate_feature",
+    "BivariateFeature",
+    "DirectedBivariateFeature",
+    "FeatureExtractor",
+    "MultivariateFeature",
+    "TrainableFeature",
+    "UnivariateFeature",
+    "get_all_feature_extractors",
+    "get_all_feature_kinds",
+    "get_all_features",
+    "get_feature_kind",
+    "get_feature_predecessors",
+    "load_features_concat_dataset",
+    "extract_features",
+    "fit_feature_extractors",
+]

eegdash/features/datasets.py

@@ -4,8 +4,8 @@ import json
 import os
 import shutil
 import warnings
-from collections.abc import Callable, Iterable
-from typing import Dict, no_type_check
+from collections.abc import Callable
+from typing import Dict, List
 
 import numpy as np
 import pandas as pd
@@ -33,6 +33,7 @@ class FeaturesDataset(EEGWindowsDataset):
         Holds additional description about the continuous signal / subject.
     transform : callable | None
         On-the-fly transform applied to the example before it is returned.
+
     """
 
     def __init__(
@@ -95,10 +96,12 @@ def _compute_stats(
     return tuple(res)
 
 
-def _pooled_var(counts, means, variances, ddof):
+def _pooled_var(counts, means, variances, ddof, ddof_in=None):
+    if ddof_in is None:
+        ddof_in = ddof
     count = counts.sum(axis=0)
     mean = np.sum((counts / count) * means, axis=0)
-    var = np.sum(((counts - ddof) / (count - ddof)) * variances, axis=0)
+    var = np.sum(((counts - ddof_in) / (count - ddof)) * variances, axis=0)
     var[:] += np.sum((counts / (count - ddof)) * (means**2), axis=0)
     var[:] -= (count / (count - ddof)) * (mean**2)
     var[:] = var.clip(min=0)
@@ -156,6 +159,7 @@ class FeaturesConcatDataset(BaseConcatDataset):
         splits : dict
             A dictionary with the name of the split (a string) as key and the
             dataset as value.
+
         """
         if isinstance(by, str):
             split_ids = {
@@ -187,6 +191,7 @@ class FeaturesConcatDataset(BaseConcatDataset):
             DataFrame containing as many rows as there are windows in the
             BaseConcatDataset, with the metadata and description information
             for each window.
+
         """
         if not all([isinstance(ds, FeaturesDataset) for ds in self.datasets]):
             raise TypeError(
@@ -238,6 +243,7 @@ class FeaturesConcatDataset(BaseConcatDataset):
             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.
+
         """
         if len(self.datasets) == 0:
             raise ValueError("Expect at least one dataset")
@@ -323,25 +329,53 @@ class FeaturesConcatDataset(BaseConcatDataset):
                         json.dump(kwargs, f)
 
     def to_dataframe(
-        self, include_metadata=False, include_target=False, include_crop_inds=False
+        self,
+        include_metadata: bool | str | List[str] = False,
+        include_target: bool = False,
+        include_crop_inds: bool = False,
     ):
-        if include_metadata or (include_target and include_crop_inds):
+        if (
+            not isinstance(include_metadata, bool)
+            or include_metadata
+            or include_crop_inds
+        ):
+            include_dataset = False
+            if isinstance(include_metadata, bool) and include_metadata:
+                include_dataset = True
+                cols = self.datasets[0].metadata.columns
+            else:
+                cols = include_metadata
+                if isinstance(cols, bool) and not cols:
+                    cols = []
+                elif isinstance(cols, str):
+                    cols = [cols]
+                cols = set(cols)
+                if include_crop_inds:
+                    cols = {
+                        "i_dataset",
+                        "i_window_in_trial",
+                        "i_start_in_trial",
+                        "i_stop_in_trial",
+                        *cols,
+                    }
+                if include_target:
+                    cols.add("target")
+                cols = list(cols)
+                include_dataset = "i_dataset" in cols
+                if include_dataset:
+                    cols.remove("i_dataset")
             dataframes = [
-                ds.metadata.join(ds.features, how="right", lsuffix="_metadata")
+                ds.metadata[cols].join(ds.features, how="right", lsuffix="_metadata")
                 for ds in self.datasets
             ]
+            if include_dataset:
+                for i, df in enumerate(dataframes):
+                    df.insert(loc=0, column="i_dataset", value=i)
         elif include_target:
             dataframes = [
                 ds.features.join(ds.metadata["target"], how="left", rsuffix="_metadata")
                 for ds in self.datasets
             ]
-        elif include_crop_inds:
-            dataframes = [
-                ds.metadata.drop("target", axis="columns").join(
-                    ds.features, how="right", lsuffix="_metadata"
-                )
-                for ds in self.datasets
-            ]
         else:
             dataframes = [ds.features for ds in self.datasets]
         return pd.concat(dataframes, axis=0, ignore_index=True)
@@ -377,7 +411,7 @@ class FeaturesConcatDataset(BaseConcatDataset):
                 return_count=True,
                 return_mean=True,
                 return_var=True,
-                ddof=ddof,
+                ddof=0,
                 numeric_only=numeric_only,
             )
             for ds in self.datasets
@@ -387,11 +421,13 @@ class FeaturesConcatDataset(BaseConcatDataset):
             np.array([s[1] for s in stats]),
             np.array([s[2] for s in stats]),
         )
-        _, _, var = _pooled_var(counts, means, variances, ddof)
+        _, _, var = _pooled_var(counts, means, variances, ddof, ddof_in=0)
         return pd.Series(var, index=self._numeric_columns())
 
-    def std(self, ddof=1, numeric_only=False, n_jobs=1):
-        return np.sqrt(self.var(ddof=ddof, numeric_only=numeric_only, n_jobs=n_jobs))
+    def std(self, ddof=1, numeric_only=False, eps=0, n_jobs=1):
+        return np.sqrt(
+            self.var(ddof=ddof, numeric_only=numeric_only, n_jobs=n_jobs) + eps
+        )
 
     def zscore(self, ddof=1, numeric_only=False, eps=0, n_jobs=1):
         stats = Parallel(n_jobs)(
@@ -400,7 +436,7 @@ class FeaturesConcatDataset(BaseConcatDataset):
                 return_count=True,
                 return_mean=True,
                 return_var=True,
-                ddof=ddof,
+                ddof=0,
                 numeric_only=numeric_only,
             )
             for ds in self.datasets
@@ -410,8 +446,8 @@ class FeaturesConcatDataset(BaseConcatDataset):
             np.array([s[1] for s in stats]),
             np.array([s[2] for s in stats]),
         )
-        _, mean, var = _pooled_var(counts, means, variances, ddof)
-        std = np.sqrt(var) + eps
+        _, mean, var = _pooled_var(counts, means, variances, ddof, ddof_in=0)
+        std = np.sqrt(var + eps)
         for ds in self.datasets:
             ds.features = (ds.features - mean) / std
 

eegdash/features/decorators.py

@@ -38,6 +38,14 @@ class FeatureKind:
 
 # Syntax sugar
 univariate_feature = FeatureKind(UnivariateFeature())
-bivariate_feature = FeatureKind(BivariateFeature())
-directed_bivariate_feature = FeatureKind(DirectedBivariateFeature())
+
+
+def bivariate_feature(func, directed=False):
+    if directed:
+        kind = DirectedBivariateFeature()
+    else:
+        kind = BivariateFeature()
+    return FeatureKind(kind)(func)
+
+
 multivariate_feature = FeatureKind(MultivariateFeature())

eegdash/features/extractors.py

@@ -16,9 +16,9 @@ def _get_underlying_func(func):
     return f
 
 
-class FitableFeature(ABC):
+class TrainableFeature(ABC):
     def __init__(self):
-        self._is_fitted = False
+        self._is_trained = False
         self.clear()
 
     @abstractmethod
@@ -39,12 +39,12 @@ class FitableFeature(ABC):
             )
 
 
-class FeatureExtractor(FitableFeature):
+class FeatureExtractor(TrainableFeature):
     def __init__(
         self, feature_extractors: Dict[str, Callable], **preprocess_kwargs: Dict
     ):
         self.feature_extractors_dict = self._validate_execution_tree(feature_extractors)
-        self._is_fitable = self._check_is_fitable(feature_extractors)
+        self._is_trainable = self._check_is_trainable(feature_extractors)
         super().__init__()
 
         # bypassing FeaturePredecessor to avoid circular import
@@ -70,32 +70,31 @@ class FeatureExtractor(FitableFeature):
             assert type(self) in pe_type
         return feature_extractors
 
-    def _check_is_fitable(self, feature_extractors):
-        is_fitable = False
+    def _check_is_trainable(self, feature_extractors):
+        is_trainable = False
         for fname, f in feature_extractors.items():
             if isinstance(f, FeatureExtractor):
-                is_fitable = f._is_fitable
+                is_trainable = f._is_trainable
             else:
                 f = _get_underlying_func(f)
-                if isinstance(f, FitableFeature):
-                    is_fitable = True
-            if is_fitable:
+                if isinstance(f, TrainableFeature):
+                    is_trainable = True
+            if is_trainable:
                 break
-        return is_fitable
+        return is_trainable
 
     def preprocess(self, *x, **kwargs):
         return (*x,)
 
-    def feature_channel_names(self, ch_names):
-        return [""]
-
     def __call__(self, *x, _batch_size=None, _ch_names=None):
         assert _batch_size is not None
         assert _ch_names is not None
-        if self._is_fitable:
+        if self._is_trainable:
             super().__call__()
         results_dict = dict()
         z = self.preprocess(*x, **self.preprocess_kwargs)
+        if not isinstance(z, tuple):
+            z = (z,)
         for fname, f in self.feature_extractors_dict.items():
             if isinstance(f, FeatureExtractor):
                 r = f(*z, _batch_size=_batch_size, _ch_names=_ch_names)
@@ -126,28 +125,28 @@ class FeatureExtractor(FitableFeature):
             results_dict[name] = value
 
     def clear(self):
-        if not self._is_fitable:
+        if not self._is_trainable:
             return
         for fname, f in self.feature_extractors_dict.items():
             f = _get_underlying_func(f)
-            if isinstance(f, FitableFeature):
+            if isinstance(f, TrainableFeature):
                 f.clear()
 
     def partial_fit(self, *x, y=None):
-        if not self._is_fitable:
+        if not self._is_trainable:
             return
         z = self.preprocess(*x, **self.preprocess_kwargs)
         for fname, f in self.feature_extractors_dict.items():
             f = _get_underlying_func(f)
-            if isinstance(f, FitableFeature):
+            if isinstance(f, TrainableFeature):
                 f.partial_fit(*z, y=y)
 
     def fit(self):
-        if not self._is_fitable:
+        if not self._is_trainable:
             return
         for fname, f in self.feature_extractors_dict.items():
             f = _get_underlying_func(f)
-            if isinstance(f, FitableFeature):
+            if isinstance(f, TrainableFeature):
                 f.fit()
         super().fit()
 

eegdash/features/feature_bank/complexity.py

@@ -4,6 +4,7 @@ from sklearn.neighbors import KDTree
 
 from ..decorators import FeaturePredecessor, univariate_feature
 from ..extractors import FeatureExtractor
+from .signal import SIGNAL_PREDECESSORS
 
 __all__ = [
     "EntropyFeatureExtractor",
@@ -28,6 +29,7 @@ def _channel_app_samp_entropy_counts(x, m, r, l):
     return kdtree.query_radius(x_emb, r, count_only=True)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 class EntropyFeatureExtractor(FeatureExtractor):
     def preprocess(self, x, m=2, r=0.2, l=1):
         rr = r * x.std(axis=-1)
@@ -55,6 +57,7 @@ def complexity_sample_entropy(counts_m, counts_mp1):
     return -np.log(A / B)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def complexity_svd_entropy(x, m=10, tau=1):
     x_emb = np.empty((*x.shape[:-1], (x.shape[-1] - m + 1) // tau, m))
@@ -65,6 +68,7 @@ def complexity_svd_entropy(x, m=10, tau=1):
     return -np.sum(s * np.log(s), axis=-1)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 @nb.njit(cache=True, fastmath=True)
 def complexity_lempel_ziv(x, threshold=None):

eegdash/features/feature_bank/csp.py

@@ -4,7 +4,7 @@ import scipy
 import scipy.linalg
 
 from ..decorators import multivariate_feature
-from ..extractors import FitableFeature
+from ..extractors import TrainableFeature
 
 __all__ = [
     "CommonSpatialPattern",
@@ -22,7 +22,7 @@ def _update_mean_cov(count, mean, cov, x_count, x_mean, x_cov):
 
 
 @multivariate_feature
-class CommonSpatialPattern(FitableFeature):
+class CommonSpatialPattern(TrainableFeature):
     def __init__(self):
         super().__init__()
 

eegdash/features/feature_bank/dimensionality.py

@@ -2,8 +2,8 @@ import numba as nb
 import numpy as np
 from scipy import special
 
-from ..decorators import univariate_feature
-from .signal import signal_zero_crossings
+from ..decorators import FeaturePredecessor, univariate_feature
+from .signal import SIGNAL_PREDECESSORS, signal_zero_crossings
 
 __all__ = [
     "dimensionality_higuchi_fractal_dim",
@@ -14,6 +14,7 @@ __all__ = [
 ]
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 @nb.njit(cache=True, fastmath=True)
 def dimensionality_higuchi_fractal_dim(x, k_max=10, eps=1e-7):
@@ -32,6 +33,7 @@ def dimensionality_higuchi_fractal_dim(x, k_max=10, eps=1e-7):
     return hfd
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def dimensionality_petrosian_fractal_dim(x):
     nd = signal_zero_crossings(np.diff(x, axis=-1))
@@ -39,6 +41,7 @@ def dimensionality_petrosian_fractal_dim(x):
     return log_n / (np.log(nd) + log_n)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def dimensionality_katz_fractal_dim(x):
     dists = np.abs(np.diff(x, axis=-1))
@@ -49,7 +52,6 @@ def dimensionality_katz_fractal_dim(x):
     return log_n / (np.log(d / L) + log_n)
 
 
-@univariate_feature
 @nb.njit(cache=True, fastmath=True)
 def _hurst_exp(x, ns, a, gamma_ratios, log_n):
     h = np.empty(x.shape[:-1])
@@ -75,6 +77,7 @@ def _hurst_exp(x, ns, a, gamma_ratios, log_n):
     return h
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def dimensionality_hurst_exp(x):
     ns = np.unique(np.power(2, np.arange(2, np.log2(x.shape[-1]) - 1)).astype(int))
@@ -88,6 +91,7 @@ def dimensionality_hurst_exp(x):
     return _hurst_exp(x, ns, a, gamma_ratios, log_n)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 @nb.njit(cache=True, fastmath=True)
 def dimensionality_detrended_fluctuation_analysis(x):

eegdash/features/feature_bank/signal.py

@@ -1,11 +1,13 @@
 import numbers
 
 import numpy as np
-from scipy import stats
+from scipy import signal, stats
 
-from ..decorators import univariate_feature
+from ..decorators import FeaturePredecessor, univariate_feature
+from ..extractors import FeatureExtractor
 
 __all__ = [
+    "HilbertFeatureExtractor",
     "signal_mean",
     "signal_variance",
     "signal_skewness",
@@ -23,51 +25,70 @@ __all__ = [
 ]
 
 
+@FeaturePredecessor(FeatureExtractor)
+class HilbertFeatureExtractor(FeatureExtractor):
+    def preprocess(self, x):
+        return np.abs(signal.hilbert(x - x.mean(axis=-1, keepdims=True), axis=-1))
+
+
+SIGNAL_PREDECESSORS = [FeatureExtractor, HilbertFeatureExtractor]
+
+
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_mean(x):
     return x.mean(axis=-1)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_variance(x, **kwargs):
     return x.var(axis=-1, **kwargs)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_std(x, **kwargs):
     return x.std(axis=-1, **kwargs)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_skewness(x, **kwargs):
     return stats.skew(x, axis=x.ndim - 1, **kwargs)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_kurtosis(x, **kwargs):
     return stats.kurtosis(x, axis=x.ndim - 1, **kwargs)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_root_mean_square(x):
     return np.sqrt(np.power(x, 2).mean(axis=-1))
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_peak_to_peak(x, **kwargs):
     return np.ptp(x, axis=-1, **kwargs)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_quantile(x, q: numbers.Number = 0.5, **kwargs):
     return np.quantile(x, q=q, axis=-1, **kwargs)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_line_length(x):
     return np.abs(np.diff(x, axis=-1)).mean(axis=-1)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_zero_crossings(x, threshold=1e-15):
     zero_ind = np.logical_and(x > -threshold, x < threshold)
@@ -78,16 +99,21 @@ def signal_zero_crossings(x, threshold=1e-15):
     return zero_cross
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_hjorth_mobility(x):
     return np.diff(x, axis=-1).std(axis=-1) / x.std(axis=-1)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_hjorth_complexity(x):
-    return np.diff(x, 2, axis=-1).std(axis=-1) / x.std(axis=-1)
+    return (np.diff(x, 2, axis=-1).std(axis=-1) * x.std(axis=-1)) / np.diff(
+        x, axis=-1
+    ).var(axis=-1)
 
 
+@FeaturePredecessor(*SIGNAL_PREDECESSORS)
 @univariate_feature
 def signal_decorrelation_time(x, fs=1):
     f = np.fft.fft(x - x.mean(axis=-1, keepdims=True), axis=-1)

eegdash/features/inspect.py

@@ -0,0 +1,48 @@
+import inspect
+from collections.abc import Callable
+
+from . import extractors, feature_bank
+from .extractors import FeatureExtractor, MultivariateFeature, _get_underlying_func
+
+
+def get_feature_predecessors(feature_or_extractor: Callable):
+    current = _get_underlying_func(feature_or_extractor)
+    if current is FeatureExtractor:
+        return [current]
+    predecessor = getattr(current, "parent_extractor_type", [FeatureExtractor])
+    if len(predecessor) == 1:
+        return [current, *get_feature_predecessors(predecessor[0])]
+    else:
+        predecessors = [get_feature_predecessors(pred) for pred in predecessor]
+        for i in range(len(predecessors)):
+            if isinstance(predecessors[i], list) and len(predecessors[i]) == 1:
+                predecessors[i] = predecessors[i][0]
+        return [current, tuple(predecessors)]
+
+
+def get_feature_kind(feature: Callable):
+    return _get_underlying_func(feature).feature_kind
+
+
+def get_all_features():
+    def isfeature(x):
+        return hasattr(_get_underlying_func(x), "feature_kind")
+
+    return inspect.getmembers(feature_bank, isfeature)
+
+
+def get_all_feature_extractors():
+    def isfeatureextractor(x):
+        return inspect.isclass(x) and issubclass(x, FeatureExtractor)
+
+    return [
+        ("FeatureExtractor", FeatureExtractor),
+        *inspect.getmembers(feature_bank, isfeatureextractor),
+    ]
+
+
+def get_all_feature_kinds():
+    def isfeaturekind(x):
+        return inspect.isclass(x) and issubclass(x, MultivariateFeature)
+
+    return inspect.getmembers(extractors, isfeaturekind)

eegdash/features/serialization.py

@@ -1,10 +1,8 @@
-"""
-Convenience functions for storing and loading of features datasets.
+"""Convenience functions for storing and loading of features datasets.
 
 see also: https://github.com/braindecode/braindecode//blob/master/braindecode/datautil/serialization.py#L165-L229
 """
 
-import json
 from pathlib import Path
 
 import pandas as pd
@@ -34,6 +32,7 @@ def load_features_concat_dataset(path, ids_to_load=None, n_jobs=1):
     Returns
     -------
     concat_dataset: FeaturesConcatDataset of FeaturesDatasets
+
     """
     # Make sure we always work with a pathlib.Path
     path = Path(path)

eegdash/features/utils.py

@@ -102,7 +102,7 @@ def fit_feature_extractors(
         features = dict(enumerate(features))
     if not isinstance(features, FeatureExtractor):
         features = FeatureExtractor(features)
-    if not features._is_fitable:
+    if not features._is_trainable:
         return features
     features.clear()
     concat_dl = DataLoader(