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

py_neuromodulation/__init__.py

@@ -2,13 +2,13 @@ import os
 import platform
 from pathlib import PurePath
 from importlib.metadata import version
-from .nm_logger import NMLogger
+from py_neuromodulation.utils.logging import NMLogger
 
 #####################################
 # Globals and environment variables #
 #####################################
 
-__version__ = version(__package__)  # get version from pyproject.toml
+__version__ = version("py_neuromodulation")  # get version from pyproject.toml
 
 # Check if the module is running headless (no display) for tests and doc builds
 PYNM_HEADLESS: bool = not os.environ.get("DISPLAY")
@@ -64,11 +64,17 @@ logger = NMLogger(__name__)  # logger initialization first to prevent circular i
 ####################################
 # API: Exposed classes and methods #
 ####################################
-from .nm_stream import Stream as Stream
-from .nm_run_analysis import DataProcessor as DataProcessor
-from .nm_settings import NMSettings as NMSettings
-from .nm_features import (
-    add_custom_feature as add_custom_feature,
-    remove_custom_feature as remove_custom_feature,
-    NMFeature as NMFeature,
-)
+from .stream.stream import Stream
+from .stream.data_processor import DataProcessor
+from .stream.settings import NMSettings
+
+from .analysis.feature_reader import FeatureReader
+from .features.feature_processor import add_custom_feature, remove_custom_feature
+
+from .utils import types
+from .utils import io
+
+from . import stream
+from . import analysis
+
+from .stream.settings import get_default_settings, get_fast_compute, reset_settings

py_neuromodulation/{nm_RMAP.py → analysis/RMAP.py}

@@ -8,8 +8,8 @@ import pandas as pd
 import nibabel as nib
 from matplotlib import pyplot as plt
 
-from py_neuromodulation.nm_plots import reg_plot
-from py_neuromodulation.nm_types import _PathLike
+from py_neuromodulation.plots import reg_plot
+from py_neuromodulation.types import _PathLike
 from py_neuromodulation import PYNM_DIR
 
 LIST_STRUC_UNCONNECTED_GRIDPOINTS_HULL = [256, 385, 417, 447, 819, 914]

py_neuromodulation/analysis/__init__.py

@@ -0,0 +1,4 @@
+from .plots import *
+from .stats import *
+from .decode import Decoder
+from .feature_reader import FeatureReader

py_neuromodulation/{nm_decode.py → analysis/decode.py}

@@ -65,11 +65,11 @@ class Decoder:
         label: np.ndarray | None = None,
         label_name: str | None = None,
         used_chs: list[str] = [],
-        model = LinearRegression(),
+        model=LinearRegression(),
         eval_method: Callable = r2_score,
-        cv_method = model_selection.KFold(n_splits=3, shuffle=False),
+        cv_method=model_selection.KFold(n_splits=3, shuffle=False),
         use_nested_cv: bool = False,
-        threshold_score = True,
+        threshold_score=True,
         mov_detection_threshold: float = 0.5,
         TRAIN_VAL_SPLIT: bool = False,
         RUN_BAY_OPT: bool = False,
@@ -89,7 +89,7 @@ class Decoder:
         model_save: bool = False,
     ) -> None:
         """Initialize here a feature file for processing
-        Read settings.json nm_channels.csv and features.csv
+        Read settings.json channels.csv and features.csv
         Read target label
 
         Parameters

py_neuromodulation/{nm_analysis.py → analysis/feature_reader.py}

@@ -10,10 +10,11 @@ from sklearn.model_selection import KFold
 
 from scipy.stats import zscore as scipy_zscore
 
-from py_neuromodulation import nm_IO, nm_plots
-from py_neuromodulation.nm_decode import Decoder
-from py_neuromodulation.nm_types import _PathLike
-from py_neuromodulation.nm_settings import NMSettings
+from py_neuromodulation.utils import io
+from py_neuromodulation.analysis import plots
+from py_neuromodulation.analysis.decode import Decoder
+from py_neuromodulation.utils.types import _PathLike
+from py_neuromodulation.stream.settings import NMSettings
 
 
 target_filter_str = {
@@ -46,14 +47,14 @@ class FeatureReader:
 
         """
         self.feature_dir = feature_dir
-        self.feature_list: list[str] = nm_IO.get_run_list_indir(self.feature_dir)
+        self.feature_list: list[str] = io.get_run_list_indir(self.feature_dir)
         self.feature_file = feature_file if feature_file else self.feature_list[0]
 
         FILE_BASENAME = PurePath(self.feature_file).stem
         PATH_READ_FILE = str(PurePath(self.feature_dir, FILE_BASENAME, FILE_BASENAME))
 
         self.settings = NMSettings.from_file(PATH_READ_FILE)
-        self.sidecar = nm_IO.read_sidecar(PATH_READ_FILE)
+        self.sidecar = io.read_sidecar(PATH_READ_FILE)
         if self.sidecar["sess_right"] is None:
             if "coords" in self.sidecar:
                 if len(self.sidecar["coords"]["cortex_left"]["ch_names"]) > 0:
@@ -61,22 +62,22 @@ class FeatureReader:
                 if len(self.sidecar["coords"]["cortex_right"]["ch_names"]) > 0:
                     self.sidecar["sess_right"] = True
         self.sfreq = self.sidecar["sfreq"]
-        self.nm_channels = nm_IO.read_nm_channels(PATH_READ_FILE)
-        self.feature_arr = nm_IO.read_features(PATH_READ_FILE)
+        self.channels = io.read_channels(PATH_READ_FILE)
+        self.feature_arr = io.read_features(PATH_READ_FILE)
 
-        self.ch_names = self.nm_channels.new_name
+        self.ch_names = self.channels.new_name
         self.used_chs = list(
-            self.nm_channels[
-                (self.nm_channels["target"] == 0) & (self.nm_channels["used"] == 1)
+            self.channels[
+                (self.channels["target"] == 0) & (self.channels["used"] == 1)
             ]["new_name"]
         )
-        self.ch_names_ECOG = self.nm_channels.query(
+        self.ch_names_ECOG = self.channels.query(
             '(type=="ecog") and (used == 1) and (status=="good")'
         ).new_name.to_list()
 
         # init plotter
-        self.nmplotter = nm_plots.NM_Plot()
-        if self.nm_channels["target"].sum() > 0:
+        self.nmplotter = plots.NM_Plot()
+        if self.channels["target"].sum() > 0:
             self.label_name = self._get_target_ch()
             self.label = self.read_target_ch(
                 self.feature_arr,
@@ -86,7 +87,7 @@ class FeatureReader:
             )
 
     def _get_target_ch(self) -> str:
-        target_names = list(self.nm_channels[self.nm_channels["target"] == 1]["name"])
+        target_names = list(self.channels[self.channels["target"] == 1]["name"])
         target_clean = [
             target_name
             for target_name in target_names
@@ -312,7 +313,7 @@ class FeatureReader:
             threshold=threshold,
         )
 
-        nm_plots.plot_epochs_avg(
+        plots.plot_epochs_avg(
             X_epoch=X_epoch,
             y_epoch=y_epoch,
             epoch_len=epoch_len,
@@ -376,7 +377,7 @@ class FeatureReader:
         else:
             df = self.feature_arr[self.feature_arr.columns[::-1]]
 
-        nm_plots.plot_all_features(
+        plots.plot_all_features(
             df=df,
             time_limit_low_s=time_limit_low_s,
             time_limit_high_s=time_limit_high_s,
@@ -517,12 +518,12 @@ class FeatureReader:
     def plot_feature_series_time(
         self,
     ):
-        self.nmplotter.plot_feature_series_time(self.feature_arr)
+        plots.plot_feature_series_time(self.feature_arr)
 
     def plot_corr_matrix(
         self,
     ):
-        return nm_plots.plot_corr_matrix(
+        return plots.plot_corr_matrix(
             self.feature_arr,
         )
 
@@ -963,7 +964,7 @@ class FeatureReader:
                         )
 
         if save_results:
-            nm_IO.save_general_dict(
+            io.save_general_dict(
                 dict_=performance_dict,
                 path_out=PATH_OUT,
                 prefix=folder_name,

py_neuromodulation/{nm_plots.py → analysis/plots.py}

@@ -1,13 +1,11 @@
 import numpy as np
 import pandas as pd
-from scipy.stats import zscore as scipy_zscore
 from matplotlib import pyplot as plt
 from matplotlib import gridspec
 import seaborn as sb
 from pathlib import PurePath
-
-from py_neuromodulation.nm_types import _PathLike
-from py_neuromodulation import logger
+from py_neuromodulation import logger, PYNM_DIR
+from py_neuromodulation.utils.types import _PathLike
 
 
 def plot_df_subjects(
@@ -83,8 +81,10 @@ def plot_epoch(
     str_label: str = "",
     ytick_labelsize: float | None = None,
 ):
+    from scipy.stats import zscore
+
     if z_score is None:
-        X_epoch = scipy_zscore(
+        X_epoch = zscore(
             np.nan_to_num(np.nanmean(np.squeeze(X_epoch), axis=0)),
             axis=0,
             nan_policy="omit",
@@ -128,9 +128,8 @@ def plot_epoch(
 def reg_plot(
     x_col: str, y_col: str, data: pd.DataFrame, out_path_save: str | None = None
 ):
-    
-    from py_neuromodulation.nm_stats import permutationTestSpearmansRho
-    
+    from py_neuromodulation.analysis.stats import permutationTestSpearmansRho
+
     plt.figure(figsize=(4, 4), dpi=300)
     rho, p = permutationTestSpearmansRho(
         data[x_col],
@@ -307,6 +306,8 @@ def plot_epochs_avg(
     figsize_x: float = 8,
     figsize_y: float = 8,
 ) -> None:
+    from scipy.stats import zscore
+
     # cut channel name of for axis + "_" for more dense plot
     if not feature_names:
         if cut_ch_name_cols and None not in (ch_name, feature_names):
@@ -315,7 +316,7 @@ def plot_epochs_avg(
             ]
 
     if normalize_data:
-        X_epoch_mean = scipy_zscore(
+        X_epoch_mean = zscore(
             np.nanmean(np.squeeze(X_epoch), axis=0), axis=0, nan_policy="omit"
         ).T
     else:
@@ -424,6 +425,8 @@ def plot_all_features(
     OUT_PATH: _PathLike = "",
     feature_file: str = "",
 ):
+    from scipy.stats import zscore
+
     if time_limit_high_s is not None:
         df = df[df["time"] < time_limit_high_s * 1000]
     if time_limit_low_s is not None:
@@ -431,7 +434,7 @@ def plot_all_features(
 
     cols_plt = [c for c in df.columns if c != "time"]
     if normalize:
-        data_plt = scipy_zscore(df[cols_plt], nan_policy="omit")
+        data_plt = zscore(df[cols_plt], nan_policy="omit")
     else:
         data_plt = df[cols_plt]
 
@@ -460,6 +463,47 @@ def plot_all_features(
         plt.savefig(plt_path, bbox_inches="tight")
 
 
+def read_plot_modules(
+    PATH_PLOT: _PathLike = PYNM_DIR / "plots",
+):
+    """Read required .mat files for plotting
+
+    Parameters
+    ----------
+    PATH_PLOT : regexp, optional
+        path to plotting files, by default
+    """
+    from py_neuromodulation.utils.io import loadmat
+
+    faces = loadmat(PurePath(PATH_PLOT, "faces.mat"))
+    vertices = loadmat(PurePath(PATH_PLOT, "Vertices.mat"))
+    grid = loadmat(PurePath(PATH_PLOT, "grid.mat"))["grid"]
+    stn_surf = loadmat(PurePath(PATH_PLOT, "STN_surf.mat"))
+    x_ver = stn_surf["vertices"][::2, 0]
+    y_ver = stn_surf["vertices"][::2, 1]
+    x_ecog = vertices["Vertices"][::1, 0]
+    y_ecog = vertices["Vertices"][::1, 1]
+    z_ecog = vertices["Vertices"][::1, 2]
+    x_stn = stn_surf["vertices"][::1, 0]
+    y_stn = stn_surf["vertices"][::1, 1]
+    z_stn = stn_surf["vertices"][::1, 2]
+
+    return (
+        faces,
+        vertices,
+        grid,
+        stn_surf,
+        x_ver,
+        y_ver,
+        x_ecog,
+        y_ecog,
+        z_ecog,
+        x_stn,
+        y_stn,
+        z_stn,
+    )
+
+
 class NM_Plot:
     def __init__(
         self,
@@ -475,8 +519,6 @@ class NM_Plot:
         self.sess_right = sess_right
         self.proj_matrix_cortex = proj_matrix_cortex
 
-        from py_neuromodulation.nm_IO import read_plot_modules
-
         (
             self.faces,
             self.vertices,

py_neuromodulation/{nm_stats.py → analysis/stats.py}

@@ -9,11 +9,6 @@ import pandas as pd
 import scipy.stats as stats
 
 
-def fitlm(x, y):
-    import statsmodels.api as sm
-    return sm.OLS(y, sm.add_constant(x)).fit()
-
-
 def fitlm_kfold(x, y, kfold_splits=5):
     from sklearn.linear_model import LinearRegression
     from sklearn.model_selection import KFold
@@ -28,7 +23,6 @@ def fitlm_kfold(x, y, kfold_splits=5):
     for i, (train, test) in enumerate(kfold.split(x, y)):
         model.fit(x.iloc[train, :], y.iloc[train, :])
         score = model.score(x.iloc[test, :], y.iloc[test, :])
-        # mdl = fitlm(np.squeeze(y.iloc[test,:].transpose()), np.squeeze(model.predict(x.iloc[test, :])))
         scores.append(score)
         coeffs = np.vstack((coeffs, model.coef_))
     coeffs = list(np.delete(coeffs, 0))
@@ -303,9 +297,9 @@ def cluster_wise_p_val_correction(p_arr, p_sig=0.05, num_permutations=10000):
     p (float) : significance level of highest cluster
     p_min_index : indices of significant samples
     """
-    from skimage.measure import label as measure_label
+    from scipy.ndimage import label as measure_label
 
-    labels, num_clusters = measure_label(p_arr <= p_sig, return_num=True)
+    labels, num_clusters = measure_label(p_arr <= p_sig)
 
     # loop through clusters of p_val series or image
     index_cluster = {}

py_neuromodulation/{nm_settings.yaml → default_settings.yaml}

@@ -1,5 +1,4 @@
 ---
-
 ########################
 ### General settings ###
 ########################
@@ -15,7 +14,6 @@ frequency_ranges_hz: # frequency band ranges can be added, removed and altered
   high_gamma: [90, 200]
   HFA: [200, 400]
 
-
 # Enabled features
 features:
   raw_hjorth: true
@@ -62,7 +60,6 @@ preprocessing_filter:
   lowpass_filter_cutoff_hz: 200
   highpass_filter_cutoff_hz: 3
 
-
 ################################
 ### Postprocessing settings ####
 ################################
@@ -82,7 +79,6 @@ project_cortex_settings:
 project_subcortex_settings:
   max_dist_mm: 5
 
-
 #################################
 ### Feature specific settings ###
 #################################
@@ -154,6 +150,7 @@ sharpwave_analysis_settings:
   sharpwave_features:
     peak_left: false
     peak_right: false
+    num_peaks: false
     trough: false
     width: false
     prominence: true
@@ -185,7 +182,7 @@ sharpwave_analysis_settings:
     var: []
   apply_estimator_between_peaks_and_troughs: true
 
-coherence:
+coherence_settings:
   channels: [] # List of channel pairs, empty by default. Each pair is a list of two channels.
   # Example channels: [[STN_RIGHT_0, ECOG_RIGHT_0], [STN_RIGHT_1, ECOG_RIGHT_1]]
   frequency_bands: [high_beta]
@@ -196,8 +193,9 @@ coherence:
   method:
     coh: true
     icoh: true
+  nperseg: 128
 
-fooof:
+fooof_settings:
   aperiodic:
     exponent: true
     offset: true
@@ -214,7 +212,7 @@ fooof:
   freq_range_hz: [2, 40]
   knee: true
 
-nolds_features:
+nolds_settings:
   sample_entropy: false
   correlation_dimension: false
   lyapunov_exponent: true
@@ -224,11 +222,11 @@ nolds_features:
     raw: true
     frequency_bands: [low_beta]
 
-mne_connectiviy:
+mne_connectiviy_settings:
   method: plv
   mode: multitaper
 
-bispectrum:
+bispectrum_settings:
   f1s: [5, 35]
   f2s: [5, 35]
   compute_features_for_whole_fband_range: true

py_neuromodulation/features/__init__.py

@@ -0,0 +1,31 @@
+# Expose feature settings
+from py_neuromodulation.features.bispectra import BispectraSettings
+from py_neuromodulation.features.coherence import CoherenceSettings
+from py_neuromodulation.features.fooof import FooofSettings
+from py_neuromodulation.features.mne_connectivity import MNEConnectivitySettings
+from py_neuromodulation.features.nolds import NoldsSettings
+from py_neuromodulation.features.sharpwaves import SharpwaveSettings
+from py_neuromodulation.features.bursts import BurstsSettings
+from py_neuromodulation.features.oscillatory import OscillatorySettings
+from py_neuromodulation.features.bandpower import BandPowerSettings
+
+
+# Expose feature classes
+from py_neuromodulation.features.linelength import LineLength
+from py_neuromodulation.features.hjorth_raw import Hjorth, Raw
+from py_neuromodulation.features.bispectra import Bispectra
+from py_neuromodulation.features.coherence import Coherence
+from py_neuromodulation.features.fooof import FooofAnalyzer
+from py_neuromodulation.features.mne_connectivity import MNEConnectivity
+from py_neuromodulation.features.nolds import Nolds
+from py_neuromodulation.features.sharpwaves import SharpwaveAnalyzer
+from py_neuromodulation.features.bursts import Bursts
+from py_neuromodulation.features.oscillatory import FFT, STFT, Welch
+from py_neuromodulation.features.bandpower import BandPower
+
+# Expose feature processor and custom feature functions
+from py_neuromodulation.features.feature_processor import (
+    FeatureProcessors,
+    add_custom_feature,
+    remove_custom_feature,
+)

py_neuromodulation/features/bandpower.py

@@ -0,0 +1,165 @@
+import numpy as np
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+from pydantic import field_validator
+
+from py_neuromodulation.utils.types import NMBaseModel, BoolSelector, NMFeature
+
+if TYPE_CHECKING:
+    from py_neuromodulation.stream.settings import NMSettings
+    from py_neuromodulation.filter import KalmanSettings
+
+
+class BandpowerFeatures(BoolSelector):
+    activity: bool = True
+    mobility: bool = False
+    complexity: bool = False
+
+
+class BandPowerSettings(NMBaseModel):
+    segment_lengths_ms: dict[str, int] = {
+        "theta": 1000,
+        "alpha": 500,
+        "low beta": 333,
+        "high beta": 333,
+        "low gamma": 100,
+        "high gamma": 100,
+        "HFA": 100,
+    }
+    bandpower_features: BandpowerFeatures = BandpowerFeatures()
+    log_transform: bool = True
+    kalman_filter: bool = False
+
+    @field_validator("bandpower_features")
+    @classmethod
+    def bandpower_features_validator(cls, bandpower_features: BandpowerFeatures):
+        assert (
+            len(bandpower_features.get_enabled()) > 0
+        ), "Set at least one bandpower_feature to True."
+
+        return bandpower_features
+
+    def validate_fbands(self, settings: "NMSettings") -> None:
+        for fband_name, seg_length_fband in self.segment_lengths_ms.items():
+            assert seg_length_fband <= settings.segment_length_features_ms, (
+                f"segment length {seg_length_fband} needs to be smaller than "
+                f" settings['segment_length_features_ms'] = {settings.segment_length_features_ms}"
+            )
+
+        for fband_name in settings.frequency_ranges_hz.keys():
+            assert fband_name in self.segment_lengths_ms, (
+                f"frequency range {fband_name} "
+                "needs to be defined in settings.bandpass_filter_settings.segment_lengths_ms]"
+            )
+
+
+class BandPower(NMFeature):
+    def __init__(
+        self,
+        settings: "NMSettings",
+        ch_names: Sequence[str],
+        sfreq: float,
+        use_kf: bool | None = None,
+    ) -> None:
+        settings.validate()
+
+        self.bp_settings: BandPowerSettings = settings.bandpass_filter_settings
+        self.kalman_filter_settings: KalmanSettings = settings.kalman_filter_settings
+        self.sfreq = sfreq
+        self.ch_names = ch_names
+        self.KF_dict: dict = {}
+
+        from py_neuromodulation.filter import MNEFilter
+
+        self.bandpass_filter = MNEFilter(
+            f_ranges=[
+                tuple(frange) for frange in settings.frequency_ranges_hz.values()
+            ],
+            sfreq=self.sfreq,
+            filter_length=self.sfreq - 1,
+            verbose=False,
+        )
+
+        if use_kf or (use_kf is None and self.bp_settings.kalman_filter):
+            self.init_KF("bandpass_activity")
+
+        seglengths = self.bp_settings.segment_lengths_ms
+
+        self.feature_params = []
+        for ch_idx, ch_name in enumerate(self.ch_names):
+            for f_band_idx, f_band in enumerate(settings.frequency_ranges_hz.keys()):
+                seglength_ms = seglengths[f_band]
+                seglen = int(np.floor(self.sfreq / 1000 * seglength_ms))
+                for bp_feature in self.bp_settings.bandpower_features.get_enabled():
+                    feature_name = "_".join([ch_name, "bandpass", bp_feature, f_band])
+                    self.feature_params.append(
+                        (
+                            ch_idx,
+                            f_band_idx,
+                            seglen,
+                            bp_feature,
+                            feature_name,
+                        )
+                    )
+
+    def init_KF(self, feature: str) -> None:
+        from py_neuromodulation.filter import define_KF
+
+        for f_band in self.kalman_filter_settings.frequency_bands:
+            for channel in self.ch_names:
+                self.KF_dict["_".join([channel, feature, f_band])] = define_KF(
+                    self.kalman_filter_settings.Tp,
+                    self.kalman_filter_settings.sigma_w,
+                    self.kalman_filter_settings.sigma_v,
+                )
+
+    def update_KF(self, feature_calc: np.floating, KF_name: str) -> np.floating:
+        if KF_name in self.KF_dict:
+            self.KF_dict[KF_name].predict()
+            self.KF_dict[KF_name].update(feature_calc)
+            feature_calc = self.KF_dict[KF_name].x[0]
+        return feature_calc
+
+    def calc_feature(self, data: np.ndarray) -> dict:
+        data = self.bandpass_filter.filter_data(data)
+
+        feature_results = {}
+        for (
+            ch_idx,
+            f_band_idx,
+            seglen,
+            bp_feature,
+            feature_name,
+        ) in self.feature_params:
+            feature_results[feature_name] = self.calc_bp_feature(
+                bp_feature, feature_name, data[ch_idx, f_band_idx, -seglen:]
+            )
+
+        return feature_results
+
+    def calc_bp_feature(self, bp_feature, feature_name, data):
+        match bp_feature:
+            case "activity":
+                feature_calc = np.var(data)
+                if self.bp_settings.log_transform:
+                    feature_calc = np.log10(feature_calc)
+                if self.KF_dict:
+                    feature_calc = self.update_KF(feature_calc, feature_name)
+            case "mobility":
+                feature_calc = np.sqrt(np.var(np.diff(data)) / np.var(data))
+            case "complexity":
+                feature_calc = self.calc_complexity(data)
+            case _:
+                raise ValueError(f"Unknown bandpower feature: {bp_feature}")
+
+        return np.nan_to_num(feature_calc)
+
+    @staticmethod
+    def calc_complexity(data: np.ndarray) -> float:
+        dat_deriv = np.diff(data)
+        deriv_variance = np.var(dat_deriv)
+        mobility = np.sqrt(deriv_variance / np.var(data))
+        dat_deriv_2_var = np.var(np.diff(dat_deriv))
+        deriv_mobility = np.sqrt(dat_deriv_2_var / deriv_variance)
+
+        return deriv_mobility / mobility