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

py_neuromodulation/nm_stream_abc.py

@@ -1,218 +1,166 @@
-"""Module that contains PNStream ABC."""
-
-from abc import ABC, abstractmethod
-import os
-import pathlib
-import _pickle as cPickle
-
-from .utils import _logging  # logger initialization
-
-# Logger use in different modules: logger = logging.getLogger("PynmLogger")
-
-
-import pandas as pd
-from sklearn import base
-
-from py_neuromodulation import (
-    nm_features,
-    nm_IO,
-    nm_plots,
-    nm_run_analysis,
-    nm_settings,
-)
-
-_PathLike = str | os.PathLike
-
-
-class PNStream(ABC):
-
-    settings: dict
-    nm_channels: pd.DataFrame
-    run_analysis: nm_run_analysis.DataProcessor
-    features: nm_features.Features
-    coords: dict
-    sfreq: int | float
-    sfreq_feature: int | float = None
-    path_grids: _PathLike | None
-    model: base.BaseEstimator | None
-    sess_right: bool | None
-    verbose: bool
-    PATH_OUT: _PathLike | None
-    PATH_OUT_folder_name: _PathLike | None
-
-    def __init__(
-        self,
-        sfreq: int | float,
-        nm_channels: pd.DataFrame | _PathLike,
-        settings: dict | _PathLike | None = None,
-        line_noise: int | float | None = 50,
-        sampling_rate_features_hz: int | float | None = None,
-        path_grids: _PathLike | None = None,
-        coord_names: list | None = None,
-        coord_list: list | None = None,
-        verbose: bool = True,
-    ) -> None:
-        """Stream initialization
-
-        Parameters
-        ----------
-        sfreq : int | float
-            sampling frequency of data in Hertz
-        nm_channels : pd.DataFrame | _PathLike
-            parametrization of channels (see nm_define_channels.py for initialization)
-        settings : dict | _PathLike | None, optional
-            features settings can be a dictionary or path to the nm_settings.json, by default the py_neuromodulation/nm_settings.json are read
-        line_noise : int | float | None, optional
-            line noise, by default 50
-        sampling_rate_features_hz : int | float | None, optional
-            feature sampling rate, by default None
-        path_grids : _PathLike | None, optional
-            path to grid_cortex.tsv and/or gird_subcortex.tsv, by default Non
-        coord_names : list | None, optional
-            coordinate name in the form [coord_1_name, coord_2_name, etc], by default None
-        coord_list : list | None, optional
-            coordinates in the form [[coord_1_x, coord_1_y, coord_1_z], [coord_2_x, coord_2_y, coord_2_z],], by default None
-        verbose : bool, optional
-            print out stream computation time information, by default True
-        """
-        self.settings = self._load_settings(settings)
-
-        if sampling_rate_features_hz is not None:
-            self.settings["sampling_rate_features_hz"] = (
-                sampling_rate_features_hz
-            )
-
-        self.nm_channels = self._load_nm_channels(nm_channels)
-        if path_grids is None:
-            path_grids = pathlib.Path(__file__).parent.resolve()
-        self.path_grids = path_grids
-        self.verbose = verbose
-        self.sfreq = sfreq
-        self.line_noise = line_noise
-        self.coord_names = coord_names
-        self.coord_list = coord_list
-        self.sess_right = None
-        self.projection = None
-        self.model = None
-
-        self.run_analysis = nm_run_analysis.DataProcessor(
-            sfreq=self.sfreq,
-            settings=self.settings,
-            nm_channels=self.nm_channels,
-            path_grids=self.path_grids,
-            coord_names=coord_names,
-            coord_list=coord_list,
-            line_noise=line_noise,
-            verbose=self.verbose,
-        )
-
-    @abstractmethod
-    def run(self):
-        """Reinitialize the stream
-        This might be handy in case the nm_channels or nm_settings changed
-        """
-
-        self.run_analysis = nm_run_analysis.DataProcessor(
-            sfreq=self.sfreq,
-            settings=self.settings,
-            nm_channels=self.nm_channels,
-            path_grids=self.path_grids,
-            coord_names=self.coord_names,
-            coord_list=self.coord_list,
-            line_noise=self.line_noise,
-            verbose=self.verbose,
-        )
-
-    @abstractmethod
-    def _add_timestamp(
-        self, feature_series: pd.Series, idx: int | None = None
-    ) -> pd.Series:
-        """Add to feature_series "time" keyword
-        For Bids specify with fs_features, for real time analysis with current time stamp
-        """
-
-    @staticmethod
-    def _get_sess_lat(coords: dict) -> bool:
-        if len(coords["cortex_left"]["positions"]) == 0:
-            return True
-        if len(coords["cortex_right"]["positions"]) == 0:
-            return False
-        raise ValueError(
-            "Either cortex_left or cortex_right positions must be provided."
-        )
-
-    @staticmethod
-    def _load_nm_channels(
-        nm_channels: pd.DataFrame | _PathLike,
-    ) -> pd.DataFrame:
-        if not isinstance(nm_channels, pd.DataFrame):
-            nm_channels = nm_IO.load_nm_channels(nm_channels)
-
-        if nm_channels.query("used == 1 and target == 0").shape[0] == 0:
-            raise ValueError(
-                "No channels selected for analysis that have column 'used' = 1 and 'target' = 0. Please check your nm_channels"
-            )
-
-        return nm_channels
-
-    @staticmethod
-    def _load_settings(settings: dict | _PathLike | None) -> dict:
-        if isinstance(settings, dict):
-            return settings
-        if settings is None:
-            return nm_settings.get_default_settings()
-        return nm_IO.read_settings(str(settings))
-
-    def load_model(self, model_name: _PathLike) -> None:
-        """Load sklearn model, that utilizes predict"""
-        with open(model_name, "rb") as fid:
-            self.model = cPickle.load(fid)
-
-    def save_after_stream(
-        self,
-        out_path_root: _PathLike | None = None,
-        folder_name: str = "sub",
-        feature_arr: pd.DataFrame | None = None,
-    ) -> None:
-        """Save features, settings, nm_channels and sidecar after run"""
-
-        if out_path_root is None:
-            out_path_root = os.getcwd()
-        # create derivate folder_name output folder if doesn't exist
-        if os.path.exists(os.path.join(out_path_root, folder_name)) is False:
-            os.makedirs(os.path.join(out_path_root, folder_name))
-
-        self.PATH_OUT = out_path_root
-        self.PATH_OUT_folder_name = folder_name
-        self.save_sidecar(out_path_root, folder_name)
-
-        if feature_arr is not None:
-            self.save_features(out_path_root, folder_name, feature_arr)
-
-        self.save_settings(out_path_root, folder_name)
-
-        self.save_nm_channels(out_path_root, folder_name)
-
-    def save_features(
-        self,
-        out_path_root: _PathLike,
-        folder_name: str,
-        feature_arr: pd.DataFrame,
-    ) -> None:
-        nm_IO.save_features(feature_arr, out_path_root, folder_name)
-
-    def save_nm_channels(
-        self, out_path_root: _PathLike, folder_name: str
-    ) -> None:
-        self.run_analysis.save_nm_channels(out_path_root, folder_name)
-
-    def save_settings(self, out_path_root: _PathLike, folder_name: str) -> None:
-        self.run_analysis.save_settings(out_path_root, folder_name)
-
-    def save_sidecar(self, out_path_root: _PathLike, folder_name: str) -> None:
-        """Save sidecar incduing fs, coords, sess_right to
-        out_path_root and subfolder 'folder_name'"""
-        additional_args = {"sess_right": self.sess_right}
-        self.run_analysis.save_sidecar(
-            out_path_root, folder_name, additional_args
-        )
+"""Module that contains NMStream ABC."""
+
+from abc import ABC, abstractmethod
+
+import pandas as pd
+
+from py_neuromodulation.nm_run_analysis import DataProcessor
+from py_neuromodulation.nm_settings import NMSettings
+from py_neuromodulation.nm_types import _PathLike, FeatureName
+from py_neuromodulation import nm_IO, PYNM_DIR
+
+
+class NMStream(ABC):
+    def __init__(
+        self,
+        sfreq: float,
+        nm_channels: pd.DataFrame | _PathLike,
+        settings: "NMSettings | _PathLike | None" = None,
+        line_noise: float | None = 50,
+        sampling_rate_features_hz: float | None = None,
+        path_grids: _PathLike | None = None,
+        coord_names: list | None = None,
+        stream_name: str
+        | None = "example_stream",  # Timon: do we need those in the nmstream_abc?
+        stream_lsl: bool = False,
+        coord_list: list | None = None,
+        verbose: bool = True,
+    ) -> None:
+        """Stream initialization
+
+        Parameters
+        ----------
+        sfreq : float
+            sampling frequency of data in Hertz
+        nm_channels : pd.DataFrame | _PathLike
+            parametrization of channels (see nm_define_channels.py for initialization)
+        settings : NMSettings | _PathLike | None, optional
+            Initialized nm_settings.NMSettings object, by default the py_neuromodulation/nm_settings.yaml are read
+            and passed into a settings object
+        line_noise : float | None, optional
+            line noise, by default 50
+        sampling_rate_features_hz : float | None, optional
+            feature sampling rate, by default None
+        path_grids : _PathLike | None, optional
+            path to grid_cortex.tsv and/or gird_subcortex.tsv, by default Non
+        coord_names : list | None, optional
+            coordinate name in the form [coord_1_name, coord_2_name, etc], by default None
+        coord_list : list | None, optional
+            coordinates in the form [[coord_1_x, coord_1_y, coord_1_z], [coord_2_x, coord_2_y, coord_2_z],], by default None
+        verbose : bool, optional
+            print out stream computation time information, by default True
+        """
+        self.settings: NMSettings = NMSettings.load(settings)
+
+        # If features that use frequency ranges are on, test them against nyquist frequency
+        use_freq_ranges: list[FeatureName] = [
+            "bandpass_filter",
+            "stft",
+            "fft",
+            "welch",
+            "bursts",
+            "coherence",
+            "nolds",
+            "bispectrum",
+        ]
+
+        need_nyquist_check = any(
+            (f in use_freq_ranges for f in self.settings.features.get_enabled())
+        )
+
+        if need_nyquist_check:
+            assert all(
+                fb.frequency_high_hz < sfreq / 2
+                for fb in self.settings.frequency_ranges_hz.values()
+            ), (
+                "If a feature that uses frequency ranges is selected, "
+                "the frequency band ranges need to be smaller than the nyquist frequency.\n"
+                f"Got sfreq = {sfreq} and fband ranges:\n {self.settings.frequency_ranges_hz}"
+            )
+
+        if sampling_rate_features_hz is not None:
+            self.settings.sampling_rate_features_hz = sampling_rate_features_hz
+
+        self.nm_channels = self._load_nm_channels(nm_channels)
+        if path_grids is None:
+            path_grids = PYNM_DIR
+        self.path_grids = path_grids
+        self.verbose = verbose
+        self.sfreq = sfreq
+        self.line_noise = line_noise
+        self.coord_names = coord_names
+        self.coord_list = coord_list
+        self.sess_right = None
+        self.projection = None
+        self.model = None
+
+        self.data_processor = DataProcessor(
+            sfreq=self.sfreq,
+            settings=self.settings,
+            nm_channels=self.nm_channels,
+            path_grids=self.path_grids,
+            coord_names=coord_names,
+            coord_list=coord_list,
+            line_noise=line_noise,
+            verbose=self.verbose,
+        )
+
+    @abstractmethod
+    def run(self) -> pd.DataFrame:
+        """Reinitialize the stream
+        This might be handy in case the nm_channels or nm_settings changed
+        """
+
+        self.data_processor = DataProcessor(
+            sfreq=self.sfreq,
+            settings=self.settings,
+            nm_channels=self.nm_channels,
+            path_grids=self.path_grids,
+            coord_names=self.coord_names,
+            coord_list=self.coord_list,
+            line_noise=self.line_noise,
+            verbose=self.verbose,
+        )
+
+    @staticmethod
+    def _load_nm_channels(
+        nm_channels: pd.DataFrame | _PathLike,
+    ) -> pd.DataFrame:
+        if not isinstance(nm_channels, pd.DataFrame):
+            nm_channels = nm_IO.load_nm_channels(nm_channels)
+
+        if nm_channels.query("used == 1 and target == 0").shape[0] == 0:
+            raise ValueError(
+                "No channels selected for analysis that have column 'used' = 1 and 'target' = 0. Please check your nm_channels"
+            )
+
+        return nm_channels
+
+    def save_after_stream(
+        self,
+        out_dir: _PathLike = "",
+        prefix: str = "",
+        feature_arr: pd.DataFrame | None = None,
+    ) -> None:
+        """Save features, settings, nm_channels and sidecar after run"""
+
+        self.save_sidecar(out_dir, prefix)
+
+        if feature_arr is not None:
+            nm_IO.save_features(feature_arr, out_dir, prefix)
+
+        self.save_settings(out_dir, prefix)
+
+        self.save_nm_channels(out_dir, prefix)
+
+    def save_nm_channels(self, out_dir: _PathLike, prefix: str = "") -> None:
+        self.data_processor.save_nm_channels(out_dir, prefix)
+
+    def save_settings(self, out_dir: _PathLike, prefix: str = "") -> None:
+        self.data_processor.save_settings(out_dir, prefix)
+
+    def save_sidecar(self, out_dir: _PathLike, prefix: str = "") -> None:
+        """Save sidecar incduing fs, coords, sess_right to
+        out_path_root and subfolder 'folder_name'"""
+        additional_args = {"sess_right": self.sess_right}
+        self.data_processor.save_sidecar(out_dir, prefix, additional_args)

py_neuromodulation/nm_types.py

@@ -0,0 +1,193 @@
+from os import PathLike
+from math import isnan
+from typing import NamedTuple, Type, Any, Literal
+from importlib import import_module
+from pydantic import ConfigDict, Field, model_validator, BaseModel
+from pprint import pformat
+from collections.abc import Sequence
+
+###################################
+########## TYPE ALIASES  ##########
+###################################
+
+_PathLike = str | PathLike
+
+FeatureName = Literal[
+    "raw_hjorth",
+    "return_raw",
+    "bandpass_filter",
+    "stft",
+    "fft",
+    "welch",
+    "sharpwave_analysis",
+    "fooof",
+    "nolds",
+    "coherence",
+    "bursts",
+    "linelength",
+    "mne_connectivity",
+    "bispectrum",
+]
+
+PreprocessorName = Literal[
+    "preprocessing_filter",
+    "notch_filter",
+    "raw_resampling",
+    "re_referencing",
+    "raw_normalization",
+]
+
+NormMethod = Literal[
+    "mean",
+    "median",
+    "zscore",
+    "zscore-median",
+    "quantile",
+    "power",
+    "robust",
+    "minmax",
+]
+
+
+###################################
+###### LAZY MODULE IMPORTS  #######
+###################################
+class ImportDetails(NamedTuple):
+    module_name: str
+    class_name: str
+
+
+def get_class(module_details: ImportDetails) -> Type[Any]:
+    return getattr(
+        import_module("py_neuromodulation." + module_details.module_name),
+        module_details.class_name,
+    )
+
+
+###################################
+######## PYDANTIC CLASSES  ########
+###################################
+
+
+class NMBaseModel(BaseModel):
+    model_config = ConfigDict(validate_assignment=False, extra="allow")
+
+    def __init__(self, *args, **kwargs) -> None:
+        if kwargs:
+            super().__init__(**kwargs)
+        else:
+            field_names = list(self.model_fields.keys())
+            kwargs = {}
+            for i in range(len(args)):
+                kwargs[field_names[i]] = args[i]
+            super().__init__(**kwargs)
+
+    def __str__(self):
+        return pformat(self.model_dump())
+
+    def __repr__(self):
+        return pformat(self.model_dump())
+
+    def validate(self) -> Any:  # type: ignore
+        return self.model_validate(self.model_dump())
+
+    def __getitem__(self, key):
+        return getattr(self, key)
+
+    def __setitem__(self, key, value) -> None:
+        setattr(self, key, value)
+
+
+class FrequencyRange(NMBaseModel):
+    frequency_low_hz: float = Field(default=0, gt=0)
+    frequency_high_hz: float = Field(default=0, gt=0)
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+
+    def __getitem__(self, item: int):
+        match item:
+            case 0:
+                return self.frequency_low_hz
+            case 1:
+                return self.frequency_high_hz
+            case _:
+                raise IndexError(f"Index {item} out of range")
+
+    def as_tuple(self) -> tuple[float, float]:
+        return (self.frequency_low_hz, self.frequency_high_hz)
+
+    def __iter__(self):  # type: ignore
+        return iter(self.as_tuple())
+
+    @model_validator(mode="after")
+    def validate_range(self):
+        if not (isnan(self.frequency_high_hz) or isnan(self.frequency_low_hz)):
+            assert (
+                self.frequency_high_hz > self.frequency_low_hz
+            ), "Frequency high must be greater than frequency low"
+        return self
+
+    @classmethod
+    def create_from(cls, input) -> "FrequencyRange":
+        match input:
+            case FrequencyRange():
+                return input
+            case dict() if "frequency_low_hz" in input and "frequency_high_hz" in input:
+                return FrequencyRange(
+                    input["frequency_low_hz"], input["frequency_high_hz"]
+                )
+            case Sequence() if len(input) == 2:
+                return FrequencyRange(input[0], input[1])
+            case _:
+                raise ValueError("Invalid input for FrequencyRange creation.")
+
+    @model_validator(mode="before")
+    @classmethod
+    def check_input(cls, input):
+        match input:
+            case dict() if "frequency_low_hz" in input and "frequency_high_hz" in input:
+                return input
+            case Sequence() if len(input) == 2:
+                return {"frequency_low_hz": input[0], "frequency_high_hz": input[1]}
+            case _:
+                raise ValueError(
+                    "Value for FrequencyRange must be a dictionary, "
+                    "or a sequence of 2 numeric values, "
+                    f"but got {input} instead."
+                )
+
+
+class BoolSelector(NMBaseModel):
+    def get_enabled(self):
+        return [
+            f
+            for f in self.model_fields.keys()
+            if (isinstance(self[f], bool) and self[f])
+        ]
+
+    def enable_all(self):
+        for f in self.model_fields.keys():
+            if isinstance(self[f], bool):
+                self[f] = True
+
+    def disable_all(self):
+        for f in self.model_fields.keys():
+            if isinstance(self[f], bool):
+                self[f] = False
+
+    def __iter__(self):  # type: ignore
+        return iter(self.model_dump().keys())
+
+    @classmethod
+    def list_all(cls):
+        return list(cls.model_fields.keys())
+
+    @classmethod
+    def print_all(cls):
+        for f in cls.list_all():
+            print(f)
+
+    @classmethod
+    def get_fields(cls):
+        return cls.model_fields