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

py_neuromodulation/nm_stream_offline.py

@@ -1,17 +1,28 @@
 """Module for offline data streams."""
-import math
-import os
 
+import os
+from joblib import Parallel, delayed
 import numpy as np
 import pandas as pd
+from itertools import count
+import logging
+
+logger = logging.getLogger("PynmLogger")
+
+import mne
 
-from py_neuromodulation import nm_generator, nm_IO, nm_stream_abc, nm_define_nmchannels
+from py_neuromodulation import (
+    nm_generator,
+    nm_IO,
+    nm_stream_abc,
+    nm_define_nmchannels,
+)
 
 _PathLike = str | os.PathLike
 
 
 class _OfflineStream(nm_stream_abc.PNStream):
-    """Offline stream base class. 
+    """Offline stream base class.
     This class can be inhereted for different types of offline streams, e.g. epoch-based or continuous.
 
     Parameters
@@ -19,19 +30,38 @@ class _OfflineStream(nm_stream_abc.PNStream):
     nm_stream_abc : nm_stream_abc.PNStream
     """
 
-    def _add_labels(
-        self, features: pd.DataFrame, data: np.ndarray
-    ) -> pd.DataFrame:
-        """Add resampled labels to features if there are target channels."""
+    def _add_target(
+        self, feature_series: pd.Series, data: np.ndarray
+    ) -> pd.Series:
+        """Add target channels to feature series.
+
+        Parameters
+        ----------
+        feature_series : pd.Series
+        data : np.ndarray
+            Raw data with shape (n_channels, n_samples). Channels not for feature computation are also included
+
+        Returns
+        -------
+        pd.Series
+            feature series with target channels added
+        """
+
         if self.nm_channels["target"].sum() > 0:
-            features = nm_IO.add_labels(
-                features=features,
-                settings=self.settings,
-                nm_channels=self.nm_channels,
-                raw_arr_data=data,
-                fs=self.sfreq,
-            )
-        return features
+            if not self.target_idx_initialized:
+                self.target_indexes = self.nm_channels[
+                    self.nm_channels["target"] == 1
+                ].index
+                self.target_names = self.nm_channels.loc[
+                    self.target_indexes, "name"
+                ].to_list()
+                self.target_idx_initialized = True
+
+            for target_idx, target_name in zip(
+                self.target_indexes, self.target_names
+            ):
+                feature_series[target_name] = data[target_idx, -1]
+        return feature_series
 
     def _add_timestamp(
         self, feature_series: pd.Series, cnt_samples: int
@@ -41,11 +71,10 @@ class _OfflineStream(nm_stream_abc.PNStream):
         Due to normalization run_analysis needs to keep track of the counted
         samples. These are accessed here for time conversion.
         """
-        timestamp = cnt_samples * 1000 / self.sfreq
         feature_series["time"] = cnt_samples * 1000 / self.sfreq
 
         if self.verbose:
-            print(
+            logging.info(
                 str(np.round(feature_series["time"] / 1000, 2))
                 + " seconds of data processed"
             )
@@ -76,46 +105,149 @@ class _OfflineStream(nm_stream_abc.PNStream):
             )
         return data.to_numpy()
 
+    def _check_settings_for_parallel(self):
+        """Check specified settings and raise error if parallel processing is not possible.
+
+        Raises:
+            ValueError: depending on the settings, parallel processing is not possible
+        """
+
+        if "raw_normalization" in self.settings["preprocessing"]:
+            raise ValueError(
+                "Parallel processing is not possible with raw_normalization normalization."
+            )
+        if self.settings["postprocessing"]["feature_normalization"] is True:
+            raise ValueError(
+                "Parallel processing is not possible with feature normalization."
+            )
+        if self.settings["features"]["bursts"] is True:
+            raise ValueError(
+                "Parallel processing is not possible with burst estimation."
+            )
+
+    def _process_batch(self, data_batch, cnt_samples):
+        feature_series = self.run_analysis.process(
+            data_batch.astype(np.float64)
+        )
+        feature_series = self._add_timestamp(feature_series, cnt_samples)
+        feature_series = self._add_target(
+            feature_series=feature_series, data=data_batch
+        )
+        return feature_series
+
     def _run_offline(
         self,
         data: np.ndarray,
         out_path_root: _PathLike | None = None,
         folder_name: str = "sub",
+        parallel: bool = False,
+        n_jobs: int = -2,
     ) -> pd.DataFrame:
         generator = nm_generator.raw_data_generator(
             data=data,
             settings=self.settings,
             sfreq=self.sfreq,
         )
-        features = []
+
         sample_add = self.sfreq / self.run_analysis.sfreq_features
 
         offset_time = self.settings["segment_length_features_ms"]
-        #offset_start = np.ceil(offset_time / 1000 * self.sfreq).astype(int)
+        # offset_start = np.ceil(offset_time / 1000 * self.sfreq).astype(int)
         offset_start = offset_time / 1000 * self.sfreq
 
-        cnt_samples = offset_start
+        if parallel:
+            l_features = Parallel(n_jobs=n_jobs, verbose=10)(
+                delayed(self._process_batch)(data_batch, cnt_samples)
+                for data_batch, cnt_samples in zip(
+                    generator, count(offset_start, sample_add)
+                )
+            )
 
-        while True:
-            data_batch = next(generator, None)
-            if data_batch is None:
-                break
-            feature_series = self.run_analysis.process(data_batch.astype(np.float64))
-            feature_series = self._add_timestamp(feature_series, cnt_samples)
-            features.append(feature_series)
+        else:
+            l_features = []
+            cnt_samples = offset_start
+            while True:
+                data_batch = next(generator, None)
+                if data_batch is None:
+                    break
+                feature_series = self.run_analysis.process(
+                    data_batch.astype(np.float64)
+                )
+                feature_series = self._add_timestamp(
+                    feature_series, cnt_samples
+                )
 
-            if self.model is not None:
-                prediction = self.model.predict(feature_series)
+                feature_series = self._add_target(
+                    feature_series=feature_series, data=data_batch
+                )
 
-            cnt_samples += sample_add
+                l_features.append(feature_series)
 
-        feature_df = pd.DataFrame(features)
-        feature_df = self._add_labels(features=feature_df, data=data)
+                cnt_samples += sample_add
+        feature_df = pd.DataFrame(l_features)
 
         self.save_after_stream(out_path_root, folder_name, feature_df)
 
         return feature_df
 
+    def plot_raw_signal(
+        self,
+        sfreq: float = None,
+        data: np.array = None,
+        lowpass: float = None,
+        highpass: float = None,
+        picks: list = None,
+        plot_time: bool = True,
+        plot_psd: bool = False,
+    ) -> None:
+        """Use MNE-RawArray Plot to investigate PSD or raw_signal plot.
+
+        Parameters
+        ----------
+        sfreq : float
+            sampling frequency [Hz]
+        data : np.array, optional
+            data (n_channels, n_times), by default None
+        plot_time : bool, optional
+            mne.io.RawArray.plot(), by default True
+        plot_psd : bool, optional
+            mne.io.RawArray.plot(), by default True
+
+        Raises
+        ------
+        ValueError
+            raise Exception when no data is passed
+        """
+        if self.data is None and data is None:
+            raise ValueError("No data passed to plot_raw_signal function.")
+
+        if data is None and self.data is not None:
+            data = self.data
+
+        if sfreq is None:
+            sfreq = self.sfreq
+
+        if self.nm_channels is not None:
+            ch_names = self.nm_channels["name"].to_list()
+            ch_types = self.nm_channels["type"].to_list()
+        else:
+            ch_names = [f"ch_{i}" for i in range(data.shape[0])]
+            ch_types = ["ecog" for i in range(data.shape[0])]
+
+        # create mne.RawArray
+        info = mne.create_info(
+            ch_names=ch_names, sfreq=sfreq, ch_types=ch_types
+        )
+        raw = mne.io.RawArray(data, info)
+
+        if picks is not None:
+            raw = raw.pick(picks)
+        self.raw = raw
+        if plot_time:
+            raw.plot(highpass=highpass, lowpass=lowpass)
+        if plot_psd:
+            raw.compute_psd().plot()
+
 
 class Stream(_OfflineStream):
     def __init__(
@@ -129,7 +261,7 @@ class Stream(_OfflineStream):
         path_grids: _PathLike | None = None,
         coord_names: list | None = None,
         coord_list: list | None = None,
-        verbose: bool = True,     
+        verbose: bool = True,
     ) -> None:
         """Stream initialization
 
@@ -154,11 +286,13 @@ class Stream(_OfflineStream):
         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
+            log stream computation time information, by default True
         """
 
         if nm_channels is None and data is not None:
-            nm_channels = nm_define_nmchannels.get_default_channels_from_data(data)
+            nm_channels = nm_define_nmchannels.get_default_channels_from_data(
+                data
+            )
 
         if nm_channels is None and data is None:
             raise ValueError(
@@ -179,11 +313,15 @@ class Stream(_OfflineStream):
 
         self.data = data
 
+        self.target_idx_initialized = False
+
     def run(
         self,
         data: np.ndarray | pd.DataFrame = None,
         out_path_root: _PathLike | None = None,
         folder_name: str = "sub",
+        parallel: bool = False,
+        n_jobs: int = -2,
     ) -> pd.DataFrame:
         """Call run function for offline stream.
 
@@ -210,8 +348,11 @@ class Stream(_OfflineStream):
         elif self.data is not None:
             data = self._handle_data(self.data)
         elif self.data is None and data is None:
-            raise ValueError(
-                "No data passed to run function."
-            )
+            raise ValueError("No data passed to run function.")
+
+        if parallel is True:
+            self._check_settings_for_parallel()
 
-        return self._run_offline(data, out_path_root, folder_name)
+        return self._run_offline(
+            data, out_path_root, folder_name, parallel=parallel, n_jobs=n_jobs
+        )

py_neuromodulation/utils/_logging.py

@@ -0,0 +1,24 @@
+import logging
+
+# include the filename in the log output
+# Configure the logger
+logger = logging.getLogger("PynmLogger")
+logger.setLevel(logging.INFO)
+
+# Create a file handler and set its level to DEBUG
+file_handler = logging.FileHandler("logfile_pynm.log")
+file_handler.setLevel(logging.INFO)
+
+# console_handler = logging.StreamHandler()
+# console_handler.setLevel(logging.DEBUG)
+
+# Create a formatter and add it to the handler
+formatter = logging.Formatter(
+    "%(asctime)s:%(levelname)s:%(name)s:%(filename)s:%(message)s"
+)
+file_handler.setFormatter(formatter)
+# console_handler.setFormatter(formatter)
+
+# Add the file handler to the logger
+logger.addHandler(file_handler)
+# logger.addHandler(console_handler)

{py_neuromodulation-0.0.2.dist-info → py_neuromodulation-0.0.3.dist-info}/METADATA

@@ -1,142 +1,182 @@
-Metadata-Version: 2.1
-Name: py_neuromodulation
-Version: 0.0.2
-Summary: Real-time analysis of intracranial neurophysiology recordings.
-Keywords: real-time,eeg,ieeg,dbs,ecog,electrocorticography,deep-brain-stimulation,machine-learning
-Author-email: Timon Merk <timon.merk@charite.de>
-Maintainer: Timon Merk
-Requires-Python: >=3.10
-Description-Content-Type: text/x-rst
-Classifier: Development Status :: 2 - Pre-Alpha
-Classifier: License :: OSI Approved :: MIT License 
-Classifier: Programming Language :: Python
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Dist: mne
-Requires-Dist: filterpy >= 1.4.5
-Requires-Dist: fooof
-Requires-Dist: imbalanced-learn
-Requires-Dist: matplotlib >= 3.3.4
-Requires-Dist: mne-bids >= 0.8
-Requires-Dist: mne-connectivity
-Requires-Dist: mrmr-selection
-Requires-Dist: nolds
-Requires-Dist: numpy >= 1.21.2
-Requires-Dist: pandas >= 1.2.2
-Requires-Dist: pip
-Requires-Dist: pynput
-Requires-Dist: pybids
-Requires-Dist: scikit-image
-Requires-Dist: scikit-learn >= 0.24.2
-Requires-Dist: scikit-optimize
-Requires-Dist: scipy >= 1.7.1
-Requires-Dist: seaborn >= 0.11
-Requires-Dist: notebook
-Requires-Dist: ipython
-Requires-Dist: pybispectra
-Requires-Dist: black ; extra == "dev"
-Requires-Dist: pytest ; extra == "dev"
-Requires-Dist: pytest-cov ; extra == "dev"
-Project-URL: bugtracker, https://github.com/neuromodulation/py_neuromodulation/issues
-Project-URL: repository, https://github.com/neuromodulation/py_neuromodulation
-Provides-Extra: dev
-
-py_neuromodulation
-==================
-
-Analyzing neural data can be a troublesome, trial and error prone,
-and beginner unfriendly process. *py_neuromodulation* allows using a simple
-interface for extraction of established neurophysiological features and includes commonly applied pre -and postprocessing methods.
-
-Only **time series data** with a corresponding **sampling frequency** are required for feature extraction.
-
-The output will be a `pandas.DataFrame <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html>`_ including different time-resolved computed features. Internally a **stream** get's initialized,
-which resembles an *online* data-stream that can in theory also be be used with a hardware acquisition system. 
-
-The following features are currently included:
-
-* oscillatory: fft, stft or bandpass filtered band power
-* `temporal waveform shape <https://www.sciencedirect.com/science/article/pii/S1364661316302182>`_
-* `fooof <https://fooof-tools.github.io/fooof/>`_
-* `mne_connectivity estimates <https://mne.tools/mne-connectivity/stable/index.html>`_ 
-* `Hjorth parameter <https://en.wikipedia.org/wiki/Hjorth_parameters>`_
-* `non-linear dynamical estimates <https://nolds.readthedocs.io/en/latest/>`_
-* various burst features
-* line length 
-* and more...
-
-
-Find here the preprint of **py_neuromodulation** called *"Invasive neurophysiology and whole brain connectomics for neural decoding in patients with brain implants"* [1]_.
-
-The original intention for writing this toolbox was movement decoding from invasive brain signals [2]_.
-The application however could be any neural decoding problem.
-*py_neuromodulation* offers wrappers around common practice machine learning methods for efficient analysis.
-
-Find the documentation here http://py-neuromodulation.readthedocs.io for example usage and parametrization.
-
-Installation
-============
-
-py_neuromodulation requires at least python 3.10. For installation you can use pip:
-
-.. code-block::
-
-    pip install py-neuromodulation
-
-We recommend however installing the package in a new new conda environment:
-
-.. code-block::
-
-    git clone https://github.com/neuromodulation/py_neuromodulation.git
-    conda create -n pynm-test python=3.10
-    conda activate pynm-test
-
-Then install the packages listed in the `pyproject.toml`:
-
-.. code-block::
-
-    pip install .
-
-
-Optionally the ipython kernel can be specified for the installed pynm-test conda environment:
-
-.. code-block::
-
-    ipython kernel install --user --name=pynm-test
-
-Then *py_neuromodulation* can be imported via:
-
-.. code-block::
-
-    import py_neuromodulation as py_nm
-
-Basic Usage
-===========
-
-.. code-block:: python
-    
-    import py_neuromodulation as pn
-    import numpy as np
-    
-    NUM_CHANNELS = 5
-    NUM_DATA = 10000
-    sfreq = 1000  # Hz
-    feature_freq = 3  # Hz
-
-    data = np.random.random([NUM_CHANNELS, NUM_DATA])
-
-    stream = pn.Stream(sfreq=sfreq, data=data, sampling_rate_features_hz=sampling_rate_features_hz)
-    features = stream.run()
-
-Check the `Usage <https://py-neuromodulation.readthedocs.io/en/latest/usage.html>`_ and `First examples <https://py-neuromodulation.readthedocs.io/en/latest/auto_examples/plot_first_demo.html>`_ for further introduction.
-
-Contact information
--------------------
-For any question or suggestion please find my contact
-information at `my GitHub profile <https://github.com/timonmerk>`_.
-
-References
-----------
-
-.. [1] Merk, T. et al. *Invasive neurophysiology and whole brain connectomics for neural decoding in patients with brain implants*, `https://doi.org/10.21203/rs.3.rs-3212709/v1` (2023).
-.. [2] Merk, T. et al. *Electrocorticography is superior to subthalamic local field potentials for movement decoding in Parkinson’s disease*. Elife 11, e75126, `https://doi.org/10.7554/eLife.75126` (2022).
-
+Metadata-Version: 2.1
+Name: py_neuromodulation
+Version: 0.0.3
+Summary: Real-time analysis of intracranial neurophysiology recordings.
+Author-email: Timon Merk <timon.merk@charite.de>
+Maintainer: Timon Merk
+License: MIT License
+        
+        Copyright (c) 2021 Interventional Cognitive Neuromodulation - Neumann Lab Berlin
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: bugtracker, https://github.com/neuromodulation/py_neuromodulation/issues
+Project-URL: repository, https://github.com/neuromodulation/py_neuromodulation
+Keywords: real-time,eeg,ieeg,dbs,ecog,electrocorticography,deep-brain-stimulation,machine-learning
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License 
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: mne
+Requires-Dist: filterpy >=1.4.5
+Requires-Dist: fooof
+Requires-Dist: imbalanced-learn
+Requires-Dist: matplotlib >=3.3.4
+Requires-Dist: mne-bids >=0.8
+Requires-Dist: mne-connectivity
+Requires-Dist: mrmr-selection
+Requires-Dist: nolds
+Requires-Dist: numpy >=1.21.2
+Requires-Dist: pandas >=1.2.2
+Requires-Dist: pip
+Requires-Dist: pynput
+Requires-Dist: pybids
+Requires-Dist: scikit-image
+Requires-Dist: scikit-learn >=0.24.2
+Requires-Dist: scikit-optimize
+Requires-Dist: scipy >=1.7.1
+Requires-Dist: seaborn >=0.11
+Requires-Dist: notebook
+Requires-Dist: ipython
+Requires-Dist: pybispectra >=1.0.0
+Requires-Dist: pyparrm
+Requires-Dist: pyarrow >=14.0.2
+Requires-Dist: joblib >=1.3.2
+Requires-Dist: black >=24.2.0
+Requires-Dist: pytest >=8.0.2
+Requires-Dist: wget
+Provides-Extra: dev
+Requires-Dist: black ; extra == 'dev'
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: pytest-cov ; extra == 'dev'
+
+py_neuromodulation
+==================
+
+Analyzing neural data can be a troublesome, trial and error prone,
+and beginner unfriendly process. *py_neuromodulation* allows using a simple
+interface for extraction of established neurophysiological features and includes commonly applied pre -and postprocessing methods.
+
+Only **time series data** with a corresponding **sampling frequency** are required for feature extraction.
+
+The output will be a `pandas.DataFrame <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html>`_ including different time-resolved computed features. Internally a **stream** get's initialized,
+which resembles an *online* data-stream that can in theory also be be used with a hardware acquisition system. 
+
+The following features are currently included:
+
+* oscillatory: fft, stft or bandpass filtered band power
+* `temporal waveform shape <https://www.sciencedirect.com/science/article/pii/S1364661316302182>`_
+* `fooof <https://fooof-tools.github.io/fooof/>`_
+* `mne_connectivity estimates <https://mne.tools/mne-connectivity/stable/index.html>`_ 
+* `Hjorth parameter <https://en.wikipedia.org/wiki/Hjorth_parameters>`_
+* `non-linear dynamical estimates <https://nolds.readthedocs.io/en/latest/>`_
+* various burst features
+* line length 
+* and more...
+
+
+Find here the preprint of **py_neuromodulation** called *"Invasive neurophysiology and whole brain connectomics for neural decoding in patients with brain implants"* [1]_.
+
+The original intention for writing this toolbox was movement decoding from invasive brain signals [2]_.
+The application however could be any neural decoding problem.
+*py_neuromodulation* offers wrappers around common practice machine learning methods for efficient analysis.
+
+Find the documentation here http://py-neuromodulation.readthedocs.io for example usage and parametrization.
+
+Installation
+============
+
+py_neuromodulation requires at least python 3.10. For installation you can use pip:
+
+.. code-block::
+
+    pip install py-neuromodulation
+
+
+We recommend however installing the package using `rye <https://rye-up.com/guide/installation/>`_:
+
+.. code-block::
+
+    git clone https://github.com/neuromodulation/py_neuromodulation.git
+    rye pin 3.11
+    rye sync
+
+And then activating the virtual environment e.g. in Windows using:
+
+.. code-block::
+
+    .\.venv\Scripts\activate
+
+Alternatively you can also install the package in a conda environment:
+
+    conda create -n pynm-test python=3.11
+    conda activate pynm-test
+
+Then install the packages listed in the `pyproject.toml`:
+
+.. code-block::
+
+    pip install .
+
+
+Optionally the ipython kernel can be specified for the installed pynm-test conda environment:
+
+.. code-block::
+
+    ipython kernel install --user --name=pynm-test
+
+Then *py_neuromodulation* can be imported via:
+
+.. code-block::
+
+    import py_neuromodulation as nm
+
+Basic Usage
+===========
+
+.. code-block:: python
+    
+    import py_neuromodulation as nm
+    import numpy as np
+    
+    NUM_CHANNELS = 5
+    NUM_DATA = 10000
+    sfreq = 1000  # Hz
+    sampling_rate_features_hz = 3  # Hz
+
+    data = np.random.random([NUM_CHANNELS, NUM_DATA])
+
+    stream = nm.Stream(sfreq=sfreq, data=data, sampling_rate_features_hz=sampling_rate_features_hz)
+    features = stream.run()
+
+Check the `Usage <https://py-neuromodulation.readthedocs.io/en/latest/usage.html>`_ and `First examples <https://py-neuromodulation.readthedocs.io/en/latest/auto_examples/plot_0_first_demo.html>`_ for further introduction.
+
+Contact information
+-------------------
+For any question or suggestion please find my contact
+information at `my GitHub profile <https://github.com/timonmerk>`_.
+
+References
+----------
+
+.. [1] Merk, T. et al. *Invasive neurophysiology and whole brain connectomics for neural decoding in patients with brain implants*, `https://doi.org/10.21203/rs.3.rs-3212709/v1` (2023).
+.. [2] Merk, T. et al. *Electrocorticography is superior to subthalamic local field potentials for movement decoding in Parkinson’s disease*. Elife 11, e75126, `https://doi.org/10.7554/eLife.75126` (2022).