py-neuromodulation 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

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,9 +39,11 @@ class Burst(nm_features_abc.Feature):
             )
         ).astype(int)
 
-        self.num_max_samples_ring_buffer = int(self.sfreq * self.time_duration_s)
+        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,
@@ -62,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, :]
@@ -98,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.num_max_samples_ring_buffer:]
+                        (
+                            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(
@@ -145,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
@@ -160,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_features.py

@@ -11,7 +11,7 @@ from py_neuromodulation import (
     nm_oscillatory,
     nm_bursts,
     nm_linelength,
-    nm_bispectra
+    nm_bispectra,
 )
 
 
@@ -56,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":
@@ -111,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, :]

py_neuromodulation/nm_fooof.py

@@ -1,7 +1,9 @@
+import logging
+from typing import Iterable
+
 import numpy as np
 from fooof import FOOOF
 from scipy import fft
-from typing import Iterable
 
 from py_neuromodulation import nm_features_abc
 
@@ -18,15 +20,6 @@ class FooofAnalyzer(nm_features_abc.Feature):
         self.ap_mode = "knee" if self.settings_fooof["knee"] else "fixed"
         self.max_n_peaks = self.settings_fooof["max_n_peaks"]
 
-        self.fm = FOOOF(
-            aperiodic_mode=self.ap_mode,
-            peak_width_limits=self.settings_fooof["peak_width_limits"],
-            max_n_peaks=self.settings_fooof["max_n_peaks"],
-            min_peak_height=self.settings_fooof["min_peak_height"],
-            peak_threshold=self.settings_fooof["peak_threshold"],
-            verbose=False,
-        )
-
         self.num_samples = int(
             self.settings_fooof["windowlength_ms"] * sfreq / 1000
         )
@@ -75,44 +68,70 @@ class FooofAnalyzer(nm_features_abc.Feature):
             spectrum = self._get_spectrum(data[ch_idx, :])
 
             try:
-                self.fm.fit(self.f_vec, spectrum, self.freq_range)
+                fm = FOOOF(
+                    aperiodic_mode=self.ap_mode,
+                    peak_width_limits=self.settings_fooof["peak_width_limits"],
+                    max_n_peaks=self.settings_fooof["max_n_peaks"],
+                    min_peak_height=self.settings_fooof["min_peak_height"],
+                    peak_threshold=self.settings_fooof["peak_threshold"],
+                    verbose=False,
+                )
+                fm.fit(self.f_vec, spectrum, self.freq_range)
             except Exception as e:
-                print(e)
-                print(f"failing spectrum: {spectrum}")
+                logging.critical(e, exc_info=True)
+
+            if fm.fooofed_spectrum_ is None:
+                FIT_PASSED = False
+            else:
+                FIT_PASSED = True
+
             if self.settings_fooof["aperiodic"]["exponent"]:
                 features_compute[f"{ch_name}_fooof_a_exp"] = (
-                    np.nan_to_num(self.fm.get_params("aperiodic_params", "exponent"))
-                    if self.fm.fooofed_spectrum_ is not None
+                    np.nan_to_num(fm.get_params("aperiodic_params", "exponent"))
+                    if FIT_PASSED is True
                     else None
                 )
 
             if self.settings_fooof["aperiodic"]["offset"]:
                 features_compute[f"{ch_name}_fooof_a_offset"] = (
-                    np.nan_to_num(self.fm.get_params("aperiodic_params", "offset"))
-                    if self.fm.fooofed_spectrum_ is not None
+                    np.nan_to_num(fm.get_params("aperiodic_params", "offset"))
+                    if FIT_PASSED is True
                     else None
                 )
-            
+
             if self.settings_fooof["aperiodic"]["knee"]:
-                features_compute[f"{ch_name}_fooof_a_knee"] = (
-                    np.nan_to_num(self.fm.get_params("aperiodic_params", "knee"))
-                    if self.fm.fooofed_spectrum_ is not None
-                    else None
+                if FIT_PASSED is False:
+                    knee_freq = None
+                else:
+                    if fm.get_params("aperiodic_params", "exponent") != 0:
+                        knee_fooof = fm.get_params("aperiodic_params", "knee")
+                        knee_freq = np.nan_to_num(
+                            knee_fooof
+                            ** (
+                                1
+                                / fm.get_params("aperiodic_params", "exponent")
+                            )
+                        )
+                    else:
+                        knee_freq = None
+
+                features_compute[f"{ch_name}_fooof_a_knee_frequency"] = (
+                    knee_freq
                 )
 
             peaks_bw = (
-                self.fm.get_params("peak_params", "BW")
-                if self.fm.fooofed_spectrum_ is not None
+                fm.get_params("peak_params", "BW")
+                if FIT_PASSED is True
                 else None
             )
             peaks_cf = (
-                self.fm.get_params("peak_params", "CF")
-                if self.fm.fooofed_spectrum_ is not None
+                fm.get_params("peak_params", "CF")
+                if FIT_PASSED is True
                 else None
             )
             peaks_pw = (
-                self.fm.get_params("peak_params", "PW")
-                if self.fm.fooofed_spectrum_ is not None
+                fm.get_params("peak_params", "PW")
+                if FIT_PASSED is True
                 else None
             )
 
@@ -122,7 +141,6 @@ class FooofAnalyzer(nm_features_abc.Feature):
                 peaks_pw = [peaks_pw]
 
             for peak_idx in range(self.max_n_peaks):
-
                 if self.settings_fooof["periodic"]["band_width"]:
                     features_compute[f"{ch_name}_fooof_p_{peak_idx}_bw"] = (
                         peaks_bw[peak_idx] if peak_idx < len(peaks_bw) else None

py_neuromodulation/nm_mne_connectivity.py

@@ -59,7 +59,7 @@ class MNEConnectivity(nm_features_abc.Feature):
         if epochs.events.shape[0] < 2:
             raise Exception(
                 f"A minimum of 2 epochs is required for mne_connectivity,"
-                f" got only {epochs.events.shape[0]}. Increase settings['segment_length']"
+                f" got only {epochs.events.shape[0]}. Increase settings['segment_length_features_ms']"
             )
         return epochs