py-neuromodulation 0.0.3__py3-none-any.whl → 0.0.5__py3-none-any.whl

py_neuromodulation/nm_nolds.py

@@ -1,93 +1,96 @@
-import numpy as np
-from typing import Iterable
-import nolds
-import warnings
-
-from py_neuromodulation import nm_features_abc, nm_oscillatory
-
-
-class Nolds(nm_features_abc.Feature):
-    def __init__(
-        self, settings: dict, ch_names: Iterable[str], sfreq: float
-    ) -> None:
-        self.s = settings
-        self.ch_names = ch_names
-
-        if len(self.s["nolds_features"]["data"]["frequency_bands"]) > 0:
-            self.bp_filter = nm_oscillatory.BandPower(
-                settings, ch_names, sfreq, use_kf=False
-            )
-
-    @staticmethod
-    def test_settings(
-        s: dict,
-        ch_names: Iterable[str],
-        sfreq: int | float,
-    ):
-        nolds_feature_cols = [
-            "sample_entropy",
-            "correlation_dimension",
-            "lyapunov_exponent",
-            "hurst_exponent",
-            "detrended_fluctutaion_analysis",
-        ]
-        if sum([s["nolds_features"][f] for f in nolds_feature_cols]) == 0:
-            warnings.warn(
-                "nolds feature enabled, but no nolds_feature type selected"
-            )
-
-        for fb in s["nolds_features"]["data"]["frequency_bands"]:
-            assert fb in list(
-                s["frequency_ranges_hz"].keys()
-            ), f"{fb} selected in nolds_features, but not defined in s['frequency_ranges_hz']"
-
-    def calc_feature(
-        self,
-        data: np.array,
-        features_compute: dict,
-    ) -> dict:
-
-        data = np.nan_to_num(data)
-        if self.s["nolds_features"]["data"]["raw"]:
-            features_compute = self.calc_nolds(data, features_compute)
-        if len(self.s["nolds_features"]["data"]["frequency_bands"]) > 0:
-            data_filt = self.bp_filter.bandpass_filter.filter_data(data)
-
-            for f_band_idx, f_band in enumerate(
-                self.s["nolds_features"]["data"]["frequency_bands"]
-            ):
-                # filter data now for a specific fband and pass to calc_nolds
-                features_compute = self.calc_nolds(
-                    data_filt[:, f_band_idx, :], features_compute, f_band
-                )  # ch, bands, samples
-        return features_compute
-
-    def calc_nolds(
-        self, data: np.array, features_compute: dict, data_str: str = "raw"
-    ) -> dict:
-
-        for ch_idx, ch_name in enumerate(self.ch_names):
-            dat = data[ch_idx, :]
-            empty_arr = dat.sum() == 0
-            if self.s["nolds_features"]["sample_entropy"]:
-                features_compute[
-                    f"{ch_name}_nolds_sample_entropy"
-                ] = nolds.sampen(dat) if not empty_arr else 0
-            if self.s["nolds_features"]["correlation_dimension"]:
-                features_compute[
-                    f"{ch_name}_nolds_correlation_dimension_{data_str}"
-                ] = nolds.corr_dim(dat, emb_dim=2) if not empty_arr else 0
-            if self.s["nolds_features"]["lyapunov_exponent"]:
-                features_compute[
-                    f"{ch_name}_nolds_lyapunov_exponent_{data_str}"
-                ] = nolds.lyap_r(dat) if not empty_arr else 0
-            if self.s["nolds_features"]["hurst_exponent"]:
-                features_compute[
-                    f"{ch_name}_nolds_hurst_exponent_{data_str}"
-                ] = nolds.hurst_rs(dat) if not empty_arr else 0
-            if self.s["nolds_features"]["detrended_fluctutaion_analysis"]:
-                features_compute[
-                    f"{ch_name}_nolds_detrended_fluctutaion_analysis_{data_str}"
-                ] = nolds.dfa(dat) if not empty_arr else 0
-
-        return features_compute
+import numpy as np
+from collections.abc import Iterable
+
+from py_neuromodulation.nm_types import NMBaseModel
+from typing import TYPE_CHECKING
+
+from py_neuromodulation.nm_features import NMFeature
+from py_neuromodulation.nm_types import BoolSelector
+
+from pydantic import field_validator
+
+if TYPE_CHECKING:
+    from py_neuromodulation.nm_settings import NMSettings
+
+
+class NoldsFeatures(BoolSelector):
+    sample_entropy: bool = False
+    correlation_dimension: bool = False
+    lyapunov_exponent: bool = True
+    hurst_exponent: bool = False
+    detrended_fluctuation_analysis: bool = False
+
+
+class NoldsSettings(NMBaseModel):
+    raw: bool = True
+    frequency_bands: list[str] = ["low_beta"]
+    features: NoldsFeatures = NoldsFeatures()
+
+    @field_validator("frequency_bands")
+    def fbands_spaces_to_underscores(cls, frequency_bands):
+        return [f.replace(" ", "_") for f in frequency_bands]
+
+
+class Nolds(NMFeature):
+    def __init__(
+        self, settings: "NMSettings", ch_names: Iterable[str], sfreq: float
+    ) -> None:
+        self.settings = settings.nolds_features
+        self.ch_names = ch_names
+
+        if len(self.settings.frequency_bands) > 0:
+            from py_neuromodulation.nm_oscillatory import BandPower
+
+            self.bp_filter = BandPower(settings, ch_names, sfreq, use_kf=False)
+
+        # Check if the selected frequency bands are defined in the global settings
+        for fb in settings.nolds_features.frequency_bands:
+            assert (
+                fb in settings.frequency_ranges_hz
+            ), f"{fb} selected in nolds_features, but not defined in s['frequency_ranges_hz']"
+
+    def calc_feature(self, data: np.ndarray) -> dict:
+        feature_results = {}
+        data = np.nan_to_num(data)
+        if self.settings.raw:
+            feature_results = self.calc_nolds(data, feature_results)
+        if len(self.settings.frequency_bands) > 0:
+            data_filt = self.bp_filter.bandpass_filter.filter_data(data)
+
+            for f_band_idx, f_band in enumerate(self.settings.frequency_bands):
+                # filter data now for a specific fband and pass to calc_nolds
+                feature_results = self.calc_nolds(
+                    data_filt[:, f_band_idx, :], feature_results, f_band
+                )  # ch, bands, samples
+        return feature_results
+
+    def calc_nolds(
+        self, data: np.ndarray, feature_results: dict, data_str: str = "raw"
+    ) -> dict:
+        for ch_idx, ch_name in enumerate(self.ch_names):
+            for f_name in self.settings.features.get_enabled():
+                feature_results[f"{ch_name}_nolds_{f_name}_{data_str}"] = (
+                    self.calc_nolds_feature(f_name, data[ch_idx, :])
+                    if data[ch_idx, :].sum()
+                    else 0
+                )
+
+        return feature_results
+
+    @staticmethod
+    def calc_nolds_feature(f_name: str, dat: np.ndarray):
+        import nolds
+
+        match f_name:
+            case "sample_entropy":
+                return nolds.sampen(dat)
+            case "correlation_dimension":
+                return nolds.corr_dim(dat, emb_dim=2)
+            case "lyapunov_exponent":
+                return nolds.lyap_r(dat)
+            case "hurst_exponent":
+                return nolds.hurst_rs(dat)
+            case "detrended_fluctuation_analysis":
+                return nolds.dfa(dat)
+            case _:
+                raise ValueError(f"Invalid nolds feature name: {f_name}")

py_neuromodulation/nm_normalization.py

@@ -1,214 +1,173 @@
-"""Module for real-time data normalization."""
-from enum import Enum
-
-from sklearn import preprocessing
-import numpy as np
-class NORM_METHODS(Enum):
-    MEAN = "mean"
-    MEDIAN = "median"
-    ZSCORE = "zscore"
-    ZSCORE_MEDIAN = "zscore-median"
-    QUANTILE = "quantile"
-    POWER = "power"
-    ROBUST = "robust"
-    MINMAX = "minmax"
-
-
-def test_normalization_settings(
-    normalization_time_s: int | float, normalization_method: str, clip: bool
-):
-    assert isinstance(
-        normalization_time_s,
-        (float, int),
-    )
-
-    assert isinstance(
-        normalization_method, str
-    ), "normalization method needs to be of type string"
-
-    assert normalization_method in [e.value for e in NORM_METHODS], (
-        f"select a valid normalization method, got {normalization_method}, "
-        f"valid options are {[e.value for e in NORM_METHODS]}"
-    )
-
-    assert isinstance(clip, (float, int, bool))
-
-
-class RawNormalizer:
-    def __init__(
-        self,
-        sfreq: int | float,
-        sampling_rate_features_hz: int,
-        normalization_method: str = "zscore",
-        normalization_time_s: int | float = 30,
-        clip: bool | int | float = False,
-    ) -> None:
-        """Normalize raw data.
-
-        normalize_samples : int
-            number of past samples considered for normalization
-        sample_add : int
-            number of samples to add to previous
-        method : str | default is 'mean'
-            data is normalized via subtraction of the 'mean' or 'median' and
-            subsequent division by the 'mean' or 'median'. For z-scoring enter
-            'zscore'.
-        clip : int | float, optional
-            value at which to clip after normalization
-        """
-
-        test_normalization_settings(normalization_time_s, normalization_method, clip)
-
-        self.method = normalization_method
-        self.clip = clip
-        self.num_samples_normalize = int(normalization_time_s * sfreq)
-        self.add_samples = int(sfreq / sampling_rate_features_hz)
-        self.previous = None
-
-    def process(self, data: np.ndarray) -> np.ndarray:
-        data = data.T
-        if self.previous is None:
-            self.previous = data
-            return data.T
-
-        self.previous = np.vstack((self.previous, data[-self.add_samples :]))
-
-        data, self.previous = _normalize_and_clip(
-            current=data,
-            previous=self.previous,
-            method=self.method,
-            clip=self.clip,
-            description="raw",
-        )
-        if self.previous.shape[0] >= self.num_samples_normalize:
-            self.previous = self.previous[1:]
-
-        return data.T
-
-
-class FeatureNormalizer:
-    def __init__(
-        self,
-        sampling_rate_features_hz: int,
-        normalization_method: str = "zscore",
-        normalization_time_s: int | float = 30,
-        clip: bool | int | float = False,
-    ) -> None:
-        """Normalize raw data.
-
-        normalize_samples : int
-            number of past samples considered for normalization
-        sample_add : int
-            number of samples to add to previous
-        method : str | default is 'mean'
-            data is normalized via subtraction of the 'mean' or 'median' and
-            subsequent division by the 'mean' or 'median'. For z-scoring enter
-            'zscore'.
-        clip : int | float, optional
-            value at which to clip after normalization
-        """
-
-        test_normalization_settings(normalization_time_s, normalization_method, clip)
-
-        self.method = normalization_method
-        self.clip = clip
-        self.num_samples_normalize = int(
-            normalization_time_s * sampling_rate_features_hz
-        )
-        self.previous = None
-
-    def process(self, data: np.ndarray) -> np.ndarray:
-        if self.previous is None:
-            self.previous = data
-            return data
-
-        self.previous = np.vstack((self.previous, data))
-
-        data, self.previous = _normalize_and_clip(
-            current=data,
-            previous=self.previous,
-            method=self.method,
-            clip=self.clip,
-            description="feature",
-        )
-        if self.previous.shape[0] >= self.num_samples_normalize:
-            self.previous = self.previous[1:]
-
-        return data
-
-"""
-Functions to check for NaN's before deciding which Numpy function to call
-"""
-def nan_mean(data, axis):
-    return np.nanmean(data, axis=axis) if np.any(np.isnan(sum(data))) else np.mean(data, axis=axis)
-
-def nan_std(data, axis):
-    return np.nanstd(data, axis=axis) if np.any(np.isnan(sum(data))) else np.std(data, axis=axis)
-
-def nan_median(data, axis):
-    return np.nanmedian(data, axis=axis) if np.any(np.isnan(sum(data))) else np.median(data, axis=axis)
-
-def _normalize_and_clip(
-    current: np.ndarray,
-    previous: np.ndarray,
-    method: str,
-    clip: int | float | bool,
-    description: str,
-) -> tuple[np.ndarray, np.ndarray]:
-    """Normalize data."""
-    match method:
-        case NORM_METHODS.MEAN.value:
-            mean = nan_mean(previous, axis=0)
-            current = (current - mean) / mean
-        case NORM_METHODS.MEDIAN.value:
-            median = nan_median(previous, axis=0)
-            current = (current - median) / median
-        case NORM_METHODS.ZSCORE.value:
-            current = (current - nan_mean(previous, axis=0)) / nan_std(previous, axis=0)
-        case NORM_METHODS.ZSCORE_MEDIAN.value:
-            current = (current - nan_median(previous, axis=0)) / nan_std(previous, axis=0)
-        # For the following methods we check for the shape of current
-        # when current is a 1D array, then it is the post-processing normalization,
-        # and we need to expand, and remove the extra dimension afterwards
-        # When current is a 2D array, then it is pre-processing normalization, and
-        # there's no need for expanding.
-        case (NORM_METHODS.QUANTILE.value | 
-              NORM_METHODS.ROBUST.value | 
-              NORM_METHODS.MINMAX.value | 
-              NORM_METHODS.POWER.value):
-            
-            norm_methods = {
-                NORM_METHODS.QUANTILE.value : lambda: preprocessing.QuantileTransformer(n_quantiles=300),
-                NORM_METHODS.ROBUST.value : preprocessing.RobustScaler,
-                NORM_METHODS.MINMAX.value : preprocessing.MinMaxScaler,
-                NORM_METHODS.POWER.value : preprocessing.PowerTransformer
-            }
-                
-            current = (
-                norm_methods[method]()
-                .fit(np.nan_to_num(previous))
-                .transform(
-                    # if post-processing: pad dimensions to 2
-                    np.reshape(current, (2-len(current.shape))*(1,) + current.shape)
-                    )
-                .squeeze() # if post-processing: remove extra dimension
-            )
-            
-        case _:
-            raise ValueError(
-                f"Only {[e.value for e in NORM_METHODS]} are supported as "
-                f"{description} normalization methods. Got {method}."
-            )
-
-    if clip:
-        current = _clip(data=current, clip=clip)
-    return current, previous
-
-
-def _clip(data: np.ndarray, clip: bool | int | float) -> np.ndarray:
-    """Clip data."""
-    if clip is True:
-        clip = 3.0  # default value
-    else:
-        clip = float(clip)
-    return np.nan_to_num(data).clip(min=-clip, max=clip)
+"""Module for real-time data normalization."""
+
+import numpy as np
+from typing import TYPE_CHECKING, Callable, Literal, get_args
+
+from py_neuromodulation.nm_types import NMBaseModel, Field, NormMethod
+from py_neuromodulation.nm_preprocessing import NMPreprocessor
+
+if TYPE_CHECKING:
+    from py_neuromodulation.nm_settings import NMSettings
+
+NormalizerType = Literal["raw", "feature"]
+
+
+class NormalizationSettings(NMBaseModel):
+    normalization_time_s: float = 30
+    normalization_method: NormMethod = "zscore"
+    clip: float = Field(default=3, ge=0)
+
+    @staticmethod
+    def list_normalization_methods() -> list[NormMethod]:
+        return list(get_args(NormMethod))
+
+
+class Normalizer(NMPreprocessor):
+    def __init__(
+        self,
+        sfreq: float,
+        settings: "NMSettings",
+        type: NormalizerType,
+    ) -> None:
+
+        self.type = type
+        self.settings: NormalizationSettings
+
+        match self.type:
+            case "raw":
+                self.settings = settings.raw_normalization_settings.validate()
+                self.add_samples = int(sfreq / settings.sampling_rate_features_hz)
+            case "feature":
+                self.settings = settings.feature_normalization_settings.validate()
+                self.add_samples = 0
+
+        # For type = "feature" sfreq = sampling_rate_features_hz
+        self.num_samples_normalize = int(self.settings.normalization_time_s * sfreq)
+
+        self.previous: np.ndarray = np.empty((0, 0))  # Default empty array
+
+        self.method = self.settings.normalization_method
+        self.using_sklearn = self.method in ["quantile", "power", "robust", "minmax"]
+
+        if self.using_sklearn:
+            import sklearn.preprocessing as skpp
+
+            NORM_METHODS_SKLEARN: dict[NormMethod, Callable] = {
+                "quantile": lambda: skpp.QuantileTransformer(n_quantiles=300),
+                "robust": skpp.RobustScaler,
+                "minmax": skpp.MinMaxScaler,
+                "power": skpp.PowerTransformer,
+            }
+
+            self.normalizer = norm_sklearn(NORM_METHODS_SKLEARN[self.method]())
+
+        else:
+            NORM_FUNCTIONS = {
+                "mean": norm_mean,
+                "median": norm_median,
+                "zscore": norm_zscore,
+                "zscore-median": norm_zscore_median,
+            }
+            self.normalizer = NORM_FUNCTIONS[self.method]
+
+    def process(self, data: np.ndarray) -> np.ndarray:
+        # TODO: does feature normalization need to be transposed too?
+        if self.type == "raw":
+            data = data.T
+
+        if self.previous.size == 0:  # Check if empty
+            self.previous = data
+            return data if self.type == "raw" else data.T
+
+        self.previous = np.vstack((self.previous, data[-self.add_samples :]))
+
+        data = self.normalizer(data, self.previous)
+
+        if self.settings.clip:
+            data = data.clip(min=-self.settings.clip, max=self.settings.clip)
+
+
+        self.previous = self.previous[-self.num_samples_normalize + 1 :]
+
+        data = np.nan_to_num(data)
+
+        return data if self.type == "raw" else data.T
+
+
+class RawNormalizer(Normalizer):
+    def __init__(self, sfreq: float, settings: "NMSettings") -> None:
+        super().__init__(sfreq, settings, "raw")
+
+
+class FeatureNormalizer(Normalizer):
+    def __init__(self, settings: "NMSettings") -> None:
+        super().__init__(settings.sampling_rate_features_hz, settings, "feature")
+
+
+""" Functions to check for NaN's before deciding which Numpy function to call """
+
+
+def nan_mean(data: np.ndarray, axis: int) -> np.ndarray:
+    return (
+        np.nanmean(data, axis=axis)
+        if np.any(np.isnan(sum(data)))
+        else np.mean(data, axis=axis)
+    )
+
+
+def nan_std(data: np.ndarray, axis: int) -> np.ndarray:
+    return (
+        np.nanstd(data, axis=axis)
+        if np.any(np.isnan(sum(data)))
+        else np.std(data, axis=axis)
+    )
+
+
+def nan_median(data: np.ndarray, axis: int) -> np.ndarray:
+    return (
+        np.nanmedian(data, axis=axis)
+        if np.any(np.isnan(sum(data)))
+        else np.median(data, axis=axis)
+    )
+
+
+def norm_mean(current, previous):
+    mean = nan_mean(previous, axis=0)
+    return (current - mean) / mean
+
+
+def norm_median(current, previous):
+    median = nan_median(previous, axis=0)
+    return (current - median) / median
+
+
+def norm_zscore(current, previous):
+    std = nan_std(previous, axis=0)
+    std[std == 0] = 1 # same behavior as sklearn
+    return (current - nan_mean(previous, axis=0)) / std
+
+
+def norm_zscore_median(current, previous):
+    std = nan_std(previous, axis=0)
+    std[std == 0] = 1 # same behavior as sklearn
+    return (current - nan_median(previous, axis=0)) / std
+
+
+def norm_sklearn(sknormalizer):
+    # For the following methods we check for the shape of current
+    # when current is a 1D array, then it is the post-processing normalization,
+    # and we need to expand, and remove the extra dimension afterwards
+    # When current is a 2D array, then it is pre-processing normalization, and
+    # there's no need for expanding.
+
+    def sk_normalizer(current, previous):
+        return (
+            sknormalizer.fit(np.nan_to_num(previous))
+            .transform(
+                # if post-processing: pad dimensions to 2
+                np.reshape(current, (2 - len(current.shape)) * (1,) + current.shape)
+            )
+            .squeeze()  # if post-processing: remove extra dimension # type: ignore
+        )
+
+    return sk_normalizer