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

py_neuromodulation/nm_bispectra.py

@@ -0,0 +1,168 @@
+from typing import Iterable
+import numpy as np
+from pybispectra import compute_fft, get_example_data_paths, WaveShape
+
+from py_neuromodulation import nm_features_abc
+
+
+class Bispectra(nm_features_abc.Feature):
+    def __init__(
+        self, settings: dict, ch_names: Iterable[str], sfreq: int | float
+    ) -> None:
+        super().__init__(settings, ch_names, sfreq)
+        self.sfreq = sfreq
+        self.ch_names = ch_names
+        self.s = settings
+        self.f1s = settings["bispectrum"]["f1s"]
+        self.f2s = settings["bispectrum"]["f2s"]
+
+    @staticmethod
+    def test_settings(
+        settings: dict,
+        ch_names: Iterable[str],
+        sfreq: int | float,
+    ):
+        s = settings
+
+        def test_range(f_name, filter_range):
+            assert isinstance(
+                filter_range[0],
+                int,
+            ), f"bispectrum frequency range {f_name} needs to be of type int, got {filter_range[0]}"
+            assert isinstance(
+                filter_range[1],
+                int,
+            ), f"bispectrum frequency range {f_name} needs to be of type int, got {filter_range[1]}"
+            assert (
+                filter_range[1] > filter_range[0]
+            ), f"second frequency range value needs to be higher than first one, got {filter_range}"
+            assert filter_range[0] < sfreq and filter_range[1] < sfreq, (
+                "filter frequency range has to be smaller than sfreq, "
+                f"got sfreq {sfreq} and filter range {filter_range}"
+            )
+
+        test_range("f1s", s["bispectrum"]["f1s"])
+        test_range("f2s", s["bispectrum"]["f2s"])
+
+        for feature_name, val in s["bispectrum"]["components"].items():
+            assert isinstance(
+                val, bool
+            ), f"bispectrum component {feature_name} has to be of type bool, got {val}"
+
+        for feature_name, val in s["bispectrum"]["bispectrum_features"].items():
+            assert isinstance(
+                val, bool
+            ), f"bispectrum feature {feature_name} has to be of type bool, got {val}"
+
+        assert (
+            f_band_bispectrum in s["frequency_ranges_hz"]
+            for f_band_bispectrum in s["bispectrum"]["frequency_bands"]
+        ), (
+            "bispectrum selected frequency bands don't match the ones"
+            "specified in s['frequency_ranges_hz']"
+            f"bispectrum frequency bands: {s['bispectrum']['frequency_bands']}"
+            f"specified frequency_ranges_hz: {s['frequency_ranges_hz']}"
+        )
+
+    def compute_bs_features(
+        self,
+        spectrum_ch: np.array,
+        features_compute: dict,
+        ch_name: str,
+        component: str,
+        f_band: str,
+    ) -> dict:
+        for bispectrum_feature in self.s["bispectrum"]["bispectrum_features"]:
+            if bispectrum_feature == "mean":
+                func = np.nanmean
+            if bispectrum_feature == "sum":
+                func = np.nansum
+            if bispectrum_feature == "var":
+                func = np.nanvar
+
+            if f_band is not None:
+                str_feature = "_".join(
+                    [
+                        ch_name,
+                        "Bispectrum",
+                        component,
+                        bispectrum_feature,
+                        f_band,
+                    ]
+                )
+            else:
+                str_feature = "_".join(
+                    [
+                        ch_name,
+                        "Bispectrum",
+                        component,
+                        bispectrum_feature,
+                        "whole_fband_range",
+                    ]
+                )
+
+            features_compute[str_feature] = func(spectrum_ch)
+
+        return features_compute
+
+    def calc_feature(self, data: np.array, features_compute: dict) -> dict:
+        for ch_idx, ch_name in enumerate(self.ch_names):
+            fft_coeffs, freqs = compute_fft(
+                data=np.expand_dims(data[ch_idx, :], axis=(0, 1)),
+                sampling_freq=self.sfreq,
+                n_points=data.shape[1],
+                verbose=False,
+            )
+
+            f_spectrum_range = freqs[
+                np.logical_and(
+                    freqs >= np.min([self.f1s, self.f2s]),
+                    freqs <= np.max([self.f1s, self.f2s]),
+                )
+            ]
+
+            waveshape = WaveShape(
+                data=fft_coeffs,
+                freqs=freqs,
+                sampling_freq=self.sfreq,
+                verbose=False,
+            )
+
+            waveshape.compute(
+                f1s=(self.f1s[0], self.f1s[-1]), f2s=(self.f2s[0], self.f2s[-1])
+            )
+
+            bispectrum = np.squeeze(waveshape.results._data)
+
+            for component in self.s["bispectrum"]["components"]:
+                if self.s["bispectrum"]["components"][component]:
+                    if component == "real":
+                        spectrum_ch = bispectrum.real
+                    if component == "imag":
+                        spectrum_ch = bispectrum.imag
+                    if component == "absolute":
+                        spectrum_ch = np.abs(bispectrum)
+                    if component == "phase":
+                        spectrum_ch = np.angle(bispectrum)
+
+                for fb in self.s["bispectrum"]["frequency_bands"]:
+                    range_ = (
+                        f_spectrum_range >= self.s["frequency_ranges_hz"][fb][0]
+                    ) & (
+                        f_spectrum_range <= self.s["frequency_ranges_hz"][fb][1]
+                    )
+                    # waveshape.results.plot()
+                    data_bs = spectrum_ch[range_, range_]
+
+                    features_compute = self.compute_bs_features(
+                        data_bs, features_compute, ch_name, component, fb
+                    )
+
+                if self.s["bispectrum"][
+                    "compute_features_for_whole_fband_range"
+                ]:
+                    features_compute = self.compute_bs_features(
+                        spectrum_ch, features_compute, ch_name, component, None
+                    )
+
+        return features_compute

py_neuromodulation/nm_bursts.py

@@ -1,6 +1,7 @@
 import enum
 import numpy as np
 from typing import Iterable
+from scipy import signal
 
 from py_neuromodulation import nm_features_abc, nm_filter
 
@@ -9,12 +10,16 @@ class Burst(nm_features_abc.Feature):
     def __init__(
         self, settings: dict, ch_names: Iterable[str], sfreq: float
     ) -> None:
-
         self.s = settings
         self.sfreq = sfreq
         self.ch_names = ch_names
         self.threshold = self.s["burst_settings"]["threshold"]
         self.time_duration_s = self.s["burst_settings"]["time_duration_s"]
+        self.samples_overlap = int(
+            self.sfreq
+            * (self.s["segment_length_features_ms"] / 1000)
+            / self.s["sampling_rate_features_hz"]
+        )
 
         self.fband_names = self.s["burst_settings"]["frequency_bands"]
         self.f_ranges = [
@@ -34,11 +39,11 @@ class Burst(nm_features_abc.Feature):
             )
         ).astype(int)
 
-        self.number_samples_calc_features = int(
-            self.sfreq / self.s["sampling_rate_features_hz"]
+        self.num_max_samples_ring_buffer = int(
+            self.sfreq * self.time_duration_s
         )
 
-        self.bandpass_filter = nm_filter.BandPassFilter(
+        self.bandpass_filter = nm_filter.MNEFilter(
             f_ranges=self.f_ranges,
             sfreq=self.sfreq,
             filter_length=self.sfreq - 1,
@@ -64,35 +69,40 @@ class Burst(nm_features_abc.Feature):
         ch_names: Iterable[str],
         sfreq: int | float,
     ):
-        assert (
-            isinstance(settings["burst_settings"]["threshold"], (float, int))
+        assert isinstance(
+            settings["burst_settings"]["threshold"], (float, int)
         ), f"burst settings threshold needs to be type int or float, got: {settings['burst_settings']['threshold']}"
         assert (
             0 < settings["burst_settings"]["threshold"] < 100
         ), f"burst setting threshold needs to be between 0 and 100, got: {settings['burst_settings']['threshold']}"
-        assert (
-            isinstance(settings["burst_settings"]["time_duration_s"], (float, int))
+        assert isinstance(
+            settings["burst_settings"]["time_duration_s"], (float, int)
         ), f"burst settings time_duration_s needs to be type int or float, got: {settings['burst_settings']['time_duration_s']}"
         assert (
             settings["burst_settings"]["time_duration_s"] > 0
         ), f"burst setting time_duration_s needs to be greater than 0, got: {settings['burst_settings']['time_duration_s']}"
 
         for fband_burst in settings["burst_settings"]["frequency_bands"]:
-            assert (
-                fband_burst in list(settings["frequency_ranges_hz"].keys())
+            assert fband_burst in list(
+                settings["frequency_ranges_hz"].keys()
             ), f"bursting {fband_burst} needs to be defined in settings['frequency_ranges_hz']"
 
-        for burst_feature in settings["burst_settings"]["burst_features"].keys():
+        for burst_feature in settings["burst_settings"][
+            "burst_features"
+        ].keys():
             assert isinstance(
-                settings["burst_settings"]["burst_features"][burst_feature], bool
+                settings["burst_settings"]["burst_features"][burst_feature],
+                bool,
             ), (
                 f"bursting feature {burst_feature} needs to be type bool, "
                 f"got: {settings['burst_settings']['burst_features'][burst_feature]}"
             )
-    def calc_feature(self, data: np.array, features_compute: dict) -> dict:
 
+    def calc_feature(self, data: np.array, features_compute: dict) -> dict:
         # filter_data returns (n_channels, n_fbands, n_samples)
-        filtered_data = self.bandpass_filter.filter_data(data)
+        filtered_data = np.abs(
+            signal.hilbert(self.bandpass_filter.filter_data(data), axis=2)
+        )
         for ch_idx, ch_name in enumerate(self.ch_names):
             for fband_idx, fband_name in enumerate(self.fband_names):
                 new_dat = filtered_data[ch_idx, fband_idx, :]
@@ -100,8 +110,12 @@ class Burst(nm_features_abc.Feature):
                     self.data_buffer[ch_name][fband_name] = new_dat
                 else:
                     self.data_buffer[ch_name][fband_name] = np.concatenate(
-                        (self.data_buffer[ch_name][fband_name], new_dat), axis=0
-                    )
+                        (
+                            self.data_buffer[ch_name][fband_name],
+                            new_dat[-self.samples_overlap :],
+                        ),
+                        axis=0,
+                    )[-self.num_max_samples_ring_buffer :]
 
                 # calc features
                 burst_thr = np.percentile(
@@ -147,9 +161,9 @@ class Burst(nm_features_abc.Feature):
                 if self.data_buffer[ch_name][fband_name][-1] > burst_thr:
                     in_burst = True
 
-                features_compute[
-                    f"{ch_name}_bursts_{fband_name}_in_burst"
-                ] = in_burst
+                features_compute[f"{ch_name}_bursts_{fband_name}_in_burst"] = (
+                    in_burst
+                )
         return features_compute
 
     @staticmethod
@@ -162,25 +176,23 @@ class Burst(nm_features_abc.Feature):
         bursts = np.zeros((beta_averp_norm.shape[0] + 1), dtype=bool)
         bursts[1:] = beta_averp_norm >= burst_thr
         deriv = np.diff(bursts)
-        isburst = False
         burst_length = []
         burst_amplitude = []
-        burst_start = 0
 
-        for index, burst_state in enumerate(deriv):
-            if burst_state == True:
-                if isburst == True:
-                    burst_length.append(index - burst_start)
-                    burst_amplitude.append(beta_averp_norm[burst_start:index])
+        burst_time_points = np.where(deriv == True)[0]
 
-                    isburst = False
-                else:
-                    burst_start = index
-                    isburst = True
+        for i in range(burst_time_points.size // 2):
+            burst_length.append(
+                burst_time_points[2 * i + 1] - burst_time_points[2 * i]
+            )
+            burst_amplitude.append(
+                beta_averp_norm[
+                    burst_time_points[2 * i] : burst_time_points[2 * i + 1]
+                ]
+            )
 
         # the last burst length (in case isburst == True) is omitted,
         # since the true burst length cannot be estimated
-
         burst_length = np.array(burst_length) / sfreq
 
         return burst_amplitude, burst_length

py_neuromodulation/nm_coherence.py

@@ -111,7 +111,7 @@ class CoherenceObject:
 
 class NM_Coherence(nm_features_abc.Feature):
 
-    coherence_objects: Iterable[CoherenceObject] = []
+    
 
     def __init__(
         self, settings: dict, ch_names: Iterable[str], sfreq: float
@@ -119,6 +119,7 @@ class NM_Coherence(nm_features_abc.Feature):
         self.s = settings
         self.sfreq = sfreq
         self.ch_names = ch_names
+        self.coherence_objects: Iterable[CoherenceObject] = []
 
         for idx_coh in range(len(self.s["coherence"]["channels"])):
             fband_names = self.s["coherence"]["frequency_bands"]

py_neuromodulation/nm_define_nmchannels.py

@@ -17,7 +17,7 @@ def set_channels(
     ecog_only: bool = False,
     used_types: Optional[Iterable[str]] = ("ecog", "dbs", "seeg"),
     target_keywords: Optional[Iterable[str]] = ("mov", "squared", "label"),
-):
+) -> pd.DataFrame:
     """Return dataframe with channel-specific settings in nm_channels format.
 
         Return an nm_channels dataframe with the columns: "name", "rereference",

py_neuromodulation/nm_features.py

@@ -11,6 +11,7 @@ from py_neuromodulation import (
     nm_oscillatory,
     nm_bursts,
     nm_linelength,
+    nm_bispectra,
 )
 
 
@@ -55,6 +56,8 @@ class Features:
                     FeatureClass = nm_oscillatory.STFT
                 case "fft":
                     FeatureClass = nm_oscillatory.FFT
+                case "welch":
+                    FeatureClass = nm_oscillatory.Welch
                 case "sharpwave_analysis":
                     FeatureClass = nm_sharpwaves.SharpwaveAnalyzer
                 case "fooof":
@@ -69,6 +72,8 @@ class Features:
                     FeatureClass = nm_linelength.LineLength
                 case "mne_connectivity":
                     FeatureClass = nm_mne_connectivity.MNEConnectivity
+                case "bispectrum":
+                    FeatureClass = nm_bispectra.Bispectra
                 case _:
                     raise ValueError(f"Unknown feature found. Got: {feature}.")
 
@@ -108,4 +113,4 @@ class Features:
                 features_compute,
             )
 
-        return features_compute
+        return features_compute

py_neuromodulation/nm_filter.py

@@ -1,16 +1,23 @@
 """Module for filter functionality."""
+
+import logging
+
+logger = logging.getLogger("PynmLogger")
+
 import mne
 from mne.filter import _overlap_add_filter
 import numpy as np
 
 
-class BandPassFilter:
-    """Bandpass filters data in given frequency ranges.
+class MNEFilter:
+    """mne.filter wrapper
 
     This class stores for given frequency band ranges the filter
     coefficients with length "filter_len".
     The filters can then be used sequentially for band power estimation with
     apply_filter().
+    Note that this filter can be a bandpass, bandstop, lowpass, or highpass filter
+    depending on the frequency ranges given (see further details in mne.filter.create_filter).
 
     Parameters
     ----------
@@ -35,7 +42,7 @@ class BandPassFilter:
 
     def __init__(
         self,
-        f_ranges: list[list[int | float | None]],
+        f_ranges: list[list[int | float | None]] | list[int | float | None],
         sfreq: int | float,
         filter_length: str | float = "999ms",
         l_trans_bandwidth: int | float | str = 4,
@@ -43,22 +50,36 @@ class BandPassFilter:
         verbose: bool | int | str | None = None,
     ) -> None:
         filter_bank = []
-        # mne create_filter function only accepts str and int
+        # mne create_filter function only accepts str and int for filter_length
         if isinstance(filter_length, float):
             filter_length = int(filter_length)
 
+        if not isinstance(f_ranges[0], list):
+            f_ranges = [f_ranges]
+
         for f_range in f_ranges:
-            filt = mne.filter.create_filter(
-                None,
-                sfreq,
-                l_freq=f_range[0],
-                h_freq=f_range[1],
-                fir_design="firwin",
-                l_trans_bandwidth=l_trans_bandwidth,  # type: ignore
-                h_trans_bandwidth=h_trans_bandwidth,  # type: ignore
-                filter_length=filter_length,  # type: ignore
-                verbose=verbose,
-            )
+            try:
+                filt = mne.filter.create_filter(
+                    None,
+                    sfreq,
+                    l_freq=f_range[0],
+                    h_freq=f_range[1],
+                    fir_design="firwin",
+                    l_trans_bandwidth=l_trans_bandwidth,  # type: ignore
+                    h_trans_bandwidth=h_trans_bandwidth,  # type: ignore
+                    filter_length=filter_length,  # type: ignore
+                    verbose=verbose,
+                )
+            except:
+                filt = mne.filter.create_filter(
+                    None,
+                    sfreq,
+                    l_freq=f_range[0],
+                    h_freq=f_range[1],
+                    fir_design="firwin",
+                    verbose=verbose,
+                    # filter_length=filter_length,
+                )
             filter_bank.append(filt)
         self.filter_bank = np.vstack(filter_bank)
 
@@ -77,10 +98,6 @@ class BandPassFilter:
         np.ndarray, shape (n_channels, n_fbands, n_samples)
             Filtered data.
 
-        Raises
-        ------
-        ValueError
-            If data.ndim > 2
         """
         if data.ndim > 2:
             raise ValueError(
@@ -89,15 +106,29 @@ class BandPassFilter:
             )
         if data.ndim == 1:
             data = np.expand_dims(data, axis=0)
+
         filtered = np.array(
             [
                 [
-                    np.convolve(flt, chan, mode="same")
-                    for flt in self.filter_bank
+                    np.convolve(filt, chan, mode="same")
+                    for filt in self.filter_bank
                 ]
                 for chan in data
             ]
         )
+
+        # ensure here that the output dimension matches the input dimension
+        if data.shape[1] != filtered.shape[-1]:
+            # select the middle part of the filtered data
+            middle_index = filtered.shape[-1] // 2
+            filtered = filtered[
+                :,
+                :,
+                middle_index
+                - data.shape[1] // 2 : middle_index
+                + data.shape[1] // 2,
+            ]
+
         return filtered
 
 
@@ -125,7 +156,7 @@ class NotchFilter:
         # Code is copied from filter.py notch_filter
         if freqs.size == 0:
             self.filter_bank = None
-            print(
+            logger.warning(
                 "WARNING: notch_filter is activated but data is not being"
                 f" filtered. This may be due to a low sampling frequency or"
                 f" incorrect specifications. Make sure your settings are"
@@ -170,19 +201,19 @@ class NotchFilter:
             phase="zero",
             fir_window="hamming",
             fir_design="firwin",
-            verbose=False
+            verbose=False,
         )
 
     def process(self, data: np.ndarray) -> np.ndarray:
         if self.filter_bank is None:
             return data
         return _overlap_add_filter(
-                x=data,
-                h=self.filter_bank,
-                n_fft=None,
-                phase="zero",
-                picks=None,
-                n_jobs=1,
-                copy=True,
-                pad="reflect_limited",
-            )
+            x=data,
+            h=self.filter_bank,
+            n_fft=None,
+            phase="zero",
+            picks=None,
+            n_jobs=1,
+            copy=True,
+            pad="reflect_limited",
+        )

py_neuromodulation/nm_filter_preprocessing.py

@@ -0,0 +1,91 @@
+import numpy as np
+
+from py_neuromodulation import nm_filter
+
+
+class PreprocessingFilter:
+
+    def __init__(self, settings: dict, sfreq: int | float) -> None:
+        self.s = settings
+        self.sfreq = sfreq
+        self.filters = []
+
+        if self.s["preprocessing_filter"]["bandstop_filter"] is True:
+            self.filters.append(
+                nm_filter.MNEFilter(
+                    f_ranges=[
+                        self.s["preprocessing_filter"][
+                            "bandstop_filter_settings"
+                        ]["frequency_high_hz"],
+                        self.s["preprocessing_filter"][
+                            "bandstop_filter_settings"
+                        ]["frequency_low_hz"],
+                    ],
+                    sfreq=self.sfreq,
+                    filter_length=self.sfreq - 1,
+                    verbose=False,
+                )
+            )
+
+        if self.s["preprocessing_filter"]["bandpass_filter"] is True:
+            self.filters.append(
+                nm_filter.MNEFilter(
+                    f_ranges=[
+                        self.s["preprocessing_filter"][
+                            "bandpass_filter_settings"
+                        ]["frequency_low_hz"],
+                        self.s["preprocessing_filter"][
+                            "bandpass_filter_settings"
+                        ]["frequency_high_hz"],
+                    ],
+                    sfreq=self.sfreq,
+                    filter_length=self.sfreq - 1,
+                    verbose=False,
+                )
+            )
+        if self.s["preprocessing_filter"]["lowpass_filter"] is True:
+            self.filters.append(
+                nm_filter.MNEFilter(
+                    f_ranges=[
+                        None,
+                        self.s["preprocessing_filter"][
+                            "lowpass_filter_settings"
+                        ]["frequency_cutoff_hz"],
+                    ],
+                    sfreq=self.sfreq,
+                    filter_length=self.sfreq - 1,
+                    verbose=False,
+                )
+            )
+        if self.s["preprocessing_filter"]["highpass_filter"] is True:
+            self.filters.append(
+                nm_filter.MNEFilter(
+                    f_ranges=[
+                        self.s["preprocessing_filter"][
+                            "highpass_filter_settings"
+                        ]["frequency_cutoff_hz"],
+                        None,
+                    ],
+                    sfreq=self.sfreq,
+                    filter_length=self.sfreq - 1,
+                    verbose=False,
+                )
+            )
+
+    def process(self, data: np.ndarray) -> np.ndarray:
+        """Preprocess data according to the initialized list of PreprocessingFilter objects
+
+        Args:
+            data (numpy ndarray) :
+                shape(n_channels, n_samples) - data to be preprocessed.
+
+        Returns:
+            preprocessed_data (numpy ndarray):
+            shape(n_channels, n_samples) - preprocessed data
+        """
+
+        for filter in self.filters:
+            data = filter.filter_data(
+                data if len(data.shape) == 2 else data[:, 0, :]
+            )
+        return data if len(data.shape) == 2 else data[:, 0, :]