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

py_neuromodulation/nm_features.py

@@ -1,116 +0,0 @@
-import numpy as np
-
-from py_neuromodulation import (
-    nm_hjorth_raw,
-    nm_mne_connectivity,
-    nm_sharpwaves,
-    nm_coherence,
-    nm_fooof,
-    nm_nolds,
-    nm_features_abc,
-    nm_oscillatory,
-    nm_bursts,
-    nm_linelength,
-    nm_bispectra,
-)
-
-
-class Features:
-    """Class for calculating features."""
-
-    features: list[nm_features_abc.Feature] = []
-
-    def __init__(
-        self, s: dict, ch_names: list[str], sfreq: int | float
-    ) -> None:
-        """_summary_
-
-        Parameters
-        ----------
-        s : dict
-            _description_
-        ch_names : list[str]
-            _description_
-        sfreq : int | float
-            _description_
-
-        Raises
-        ------
-        ValueError
-            _description_
-        """
-
-        self.features = []
-
-        for feature in s["features"]:
-            if s["features"][feature] is False:
-                continue
-            match feature:
-                case "raw_hjorth":
-                    FeatureClass = nm_hjorth_raw.Hjorth
-                case "return_raw":
-                    FeatureClass = nm_hjorth_raw.Raw
-                case "bandpass_filter":
-                    FeatureClass = nm_oscillatory.BandPower
-                case "stft":
-                    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":
-                    FeatureClass = nm_fooof.FooofAnalyzer
-                case "nolds":
-                    FeatureClass = nm_nolds.Nolds
-                case "coherence":
-                    FeatureClass = nm_coherence.NM_Coherence
-                case "bursts":
-                    FeatureClass = nm_bursts.Burst
-                case "linelength":
-                    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}.")
-
-            FeatureClass.test_settings(s, ch_names, sfreq)
-            f_obj = FeatureClass(s, ch_names, sfreq)
-            self.features.append(f_obj)
-
-    def register_new_feature(self, feature: nm_features_abc.Feature) -> None:
-        """Register new feature.
-
-        Parameters
-        ----------
-        feature : nm_features_abc.Feature
-            New feature to add to feature list
-        """
-        self.features.append(feature)
-
-    def estimate_features(self, data: np.ndarray) -> dict:
-        """Calculate features, as defined in settings.json
-        Features are based on bandpower, raw Hjorth parameters and sharp wave
-        characteristics.
-
-        Parameters
-        ----------
-        data (np array) : (channels, time)
-
-        Returns
-        -------
-        dat (dict): naming convention : channel_method_feature_(f_band)
-        """
-
-        features_compute = {}
-
-        for feature in self.features:
-            features_compute = feature.calc_feature(
-                data,
-                features_compute,
-            )
-
-        return features_compute

py_neuromodulation/nm_features_abc.py

@@ -1,39 +0,0 @@
-from abc import ABC, abstractmethod
-import numpy as np
-from typing import Iterable
-
-
-class Feature(ABC):
-    @abstractmethod
-    def __init__(
-        self, settings: dict, ch_names: Iterable[str], sfreq: int | float
-    ) -> None:
-        pass
-
-    @staticmethod
-    @abstractmethod
-    def test_settings(
-        settings: dict,
-        ch_names: Iterable[str],
-        sfreq: int | float,
-    ):
-        """Method to check passed settings"""
-        pass
-
-    @abstractmethod
-    def calc_feature(self, data: np.array, features_compute: dict) -> dict:
-        """
-        Feature calculation method. Each method needs to loop through all channels
-
-        Parameters
-        ----------
-        data : np.array
-            (channels, time)
-        features_compute : dict
-        ch_names : Iterable[str]
-
-        Returns
-        -------
-        dict
-        """
-        pass

py_neuromodulation/nm_filter.py

@@ -1,219 +0,0 @@
-"""Module for filter functionality."""
-
-import logging
-
-logger = logging.getLogger("PynmLogger")
-
-import mne
-from mne.filter import _overlap_add_filter
-import numpy as np
-
-
-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
-    ----------
-    f_ranges : list of lists
-        Frequency ranges. Inner lists must be of length 2.
-    sfreq : int | float
-        Sampling frequency.
-    filter_length : str, optional
-        Filter length. Human readable (e.g. "1000ms", "1s"), by default "999ms"
-    l_trans_bandwidth : int | float | str, optional
-        Length of the lower transition band or "auto", by default 4
-    h_trans_bandwidth : int | float | str, optional
-        Length of the higher transition band or "auto", by default 4
-    verbose : bool | None, optional
-        Verbosity level, by default None
-
-    Attributes
-    ----------
-    filter_bank: np.ndarray shape (n,)
-        Factor to upsample by.
-    """
-
-    def __init__(
-        self,
-        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,
-        h_trans_bandwidth: int | float | str = 4,
-        verbose: bool | int | str | None = None,
-    ) -> None:
-        filter_bank = []
-        # 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:
-            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)
-
-    def filter_data(self, data: np.ndarray) -> np.ndarray:
-        """Apply previously calculated (bandpass) filters to data.
-
-        Parameters
-        ----------
-        data : np.ndarray (n_samples, ) or (n_channels, n_samples)
-            Data to be filtered
-        filter_bank : np.ndarray, shape (n_fbands, filter_len)
-            Output of calc_bandpass_filters.
-
-        Returns
-        -------
-        np.ndarray, shape (n_channels, n_fbands, n_samples)
-            Filtered data.
-
-        """
-        if data.ndim > 2:
-            raise ValueError(
-                f"Data must have one or two dimensions. Got:"
-                f" {data.ndim} dimensions."
-            )
-        if data.ndim == 1:
-            data = np.expand_dims(data, axis=0)
-
-        filtered = np.array(
-            [
-                [
-                    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
-
-
-class NotchFilter:
-    def __init__(
-        self,
-        sfreq: int | float,
-        line_noise: int | float | None = None,
-        freqs: np.ndarray | None = None,
-        notch_widths: int | np.ndarray | None = 3,
-        trans_bandwidth: int = 6.8,
-    ) -> None:
-        if line_noise is None and freqs is None:
-            raise ValueError(
-                "Either line_noise or freqs must be defined if notch_filter is"
-                "activated."
-            )
-        if freqs is None:
-            freqs = np.arange(line_noise, sfreq / 2, line_noise, dtype=int)
-
-        if freqs.size > 0:
-            if freqs[-1] >= sfreq / 2:
-                freqs = freqs[:-1]
-
-        # Code is copied from filter.py notch_filter
-        if freqs.size == 0:
-            self.filter_bank = None
-            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"
-                f" correct. Got: {sfreq = }, {line_noise = }, {freqs = }."
-            )
-            return
-
-        filter_length = int(sfreq - 1)
-        if notch_widths is None:
-            notch_widths = freqs / 200.0
-        elif np.any(notch_widths < 0):
-            raise ValueError("notch_widths must be >= 0")
-        else:
-            notch_widths = np.atleast_1d(notch_widths)
-            if len(notch_widths) == 1:
-                notch_widths = notch_widths[0] * np.ones_like(freqs)
-            elif len(notch_widths) != len(freqs):
-                raise ValueError(
-                    "notch_widths must be None, scalar, or the "
-                    "same length as freqs"
-                )
-
-        # Speed this up by computing the fourier coefficients once
-        tb_half = trans_bandwidth / 2.0
-        lows = [
-            freq - nw / 2.0 - tb_half for freq, nw in zip(freqs, notch_widths)
-        ]
-        highs = [
-            freq + nw / 2.0 + tb_half for freq, nw in zip(freqs, notch_widths)
-        ]
-
-        self.filter_bank = mne.filter.create_filter(
-            data=None,
-            sfreq=sfreq,
-            l_freq=highs,
-            h_freq=lows,
-            filter_length=filter_length,  # type: ignore
-            l_trans_bandwidth=tb_half,  # type: ignore
-            h_trans_bandwidth=tb_half,  # type: ignore
-            method="fir",
-            iir_params=None,
-            phase="zero",
-            fir_window="hamming",
-            fir_design="firwin",
-            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",
-        )

py_neuromodulation/nm_filter_preprocessing.py

@@ -1,91 +0,0 @@
-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,159 +0,0 @@
-import logging
-from typing import Iterable
-
-import numpy as np
-from fooof import FOOOF
-from scipy import fft
-
-from py_neuromodulation import nm_features_abc
-
-
-class FooofAnalyzer(nm_features_abc.Feature):
-    def __init__(
-        self, settings: dict, ch_names: Iterable[str], sfreq: float
-    ) -> None:
-        self.settings_fooof = settings["fooof"]
-        self.sfreq = sfreq
-        self.ch_names = ch_names
-
-        self.freq_range = self.settings_fooof["freq_range_hz"]
-        self.ap_mode = "knee" if self.settings_fooof["knee"] else "fixed"
-        self.max_n_peaks = self.settings_fooof["max_n_peaks"]
-
-        self.num_samples = int(
-            self.settings_fooof["windowlength_ms"] * sfreq / 1000
-        )
-
-        self.f_vec = np.arange(0, int(self.num_samples / 2) + 1, 1)
-
-    def test_settings(
-        s: dict,
-        ch_names: Iterable[str],
-        sfreq: int | float,
-    ):
-        assert isinstance(s["fooof"]["aperiodic"]["exponent"], bool)
-        assert isinstance(s["fooof"]["aperiodic"]["offset"], bool)
-        assert isinstance(s["fooof"]["aperiodic"]["knee"], bool)
-        assert isinstance(s["fooof"]["periodic"]["center_frequency"], bool)
-        assert isinstance(s["fooof"]["periodic"]["band_width"], bool)
-        assert isinstance(s["fooof"]["periodic"]["height_over_ap"], bool)
-        assert isinstance(s["fooof"]["knee"], bool)
-        assert isinstance(s["fooof"]["windowlength_ms"], (int, float))
-        assert (
-            s["fooof"]["windowlength_ms"] <= s["segment_length_features_ms"]
-        ), (
-            "fooof windowlength_ms needs to be smaller equal than segment_length_features_ms "
-            f"got windowlength_ms: {s['fooof']['windowlength_ms']} and {s['segment_length_features_ms']}"
-        )
-
-        assert (
-            s["fooof"]["freq_range_hz"][0] < sfreq
-            and s["fooof"]["freq_range_hz"][1] < sfreq
-        ), f"fooof frequency range needs to be below sfreq, got {s['fooof']['freq_range_hz']}"
-
-    def _get_spectrum(self, data: np.array):
-        """return absolute value fft spectrum"""
-
-        data = data[-self.num_samples :]
-        Z = np.abs(fft.rfft(data))
-
-        return Z
-
-    def calc_feature(
-        self,
-        data: np.array,
-        features_compute: dict,
-    ) -> dict:
-        for ch_idx, ch_name in enumerate(self.ch_names):
-            spectrum = self._get_spectrum(data[ch_idx, :])
-
-            try:
-                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:
-                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(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(fm.get_params("aperiodic_params", "offset"))
-                    if FIT_PASSED is True
-                    else None
-                )
-
-            if self.settings_fooof["aperiodic"]["knee"]:
-                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 = (
-                fm.get_params("peak_params", "BW")
-                if FIT_PASSED is True
-                else None
-            )
-            peaks_cf = (
-                fm.get_params("peak_params", "CF")
-                if FIT_PASSED is True
-                else None
-            )
-            peaks_pw = (
-                fm.get_params("peak_params", "PW")
-                if FIT_PASSED is True
-                else None
-            )
-
-            if type(peaks_bw) is np.float64 or peaks_bw is None:
-                peaks_bw = [peaks_bw]
-                peaks_cf = [peaks_cf]
-                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
-                    )
-
-                if self.settings_fooof["periodic"]["center_frequency"]:
-                    features_compute[f"{ch_name}_fooof_p_{peak_idx}_cf"] = (
-                        peaks_cf[peak_idx] if peak_idx < len(peaks_bw) else None
-                    )
-
-                if self.settings_fooof["periodic"]["height_over_ap"]:
-                    features_compute[f"{ch_name}_fooof_p_{peak_idx}_pw"] = (
-                        peaks_pw[peak_idx] if peak_idx < len(peaks_bw) else None
-                    )
-
-        return features_compute

py_neuromodulation/nm_generator.py

@@ -1,37 +0,0 @@
-from typing import Iterator
-
-import numpy as np
-
-
-def raw_data_generator(
-    data: np.ndarray,
-    settings: dict,
-    sfreq: int,
-) -> Iterator[np.ndarray]:
-    """
-    This generator function mimics online data acquisition.
-    The data are iteratively sampled with sfreq_new.
-    Arguments
-    ---------
-        ieeg_raw (np array): shape (channels, time)
-        sfreq: int
-        sfreq_new: int
-        offset_time: int | float
-    Returns
-    -------
-        np.array: new batch for run function of full segment length shape
-    """
-    sfreq_new = settings["sampling_rate_features_hz"]
-    offset_time = settings["segment_length_features_ms"]
-    offset_start = offset_time / 1000 * sfreq
-
-    ratio_samples_features = sfreq / sfreq_new
-
-    ratio_counter = 0
-    for cnt in range(data.shape[1]+1):  # shape + 1 guarantees that the last sample is also included
-
-        if (cnt - offset_start) >= ratio_samples_features * ratio_counter:
-
-            ratio_counter += 1
-
-            yield data[:, np.floor(cnt-offset_start).astype(int) : cnt]