py-neuromodulation 0.0.2__tar.gz → 0.0.3__tar.gz

{py_neuromodulation-0.0.2 → py_neuromodulation-0.0.3}/PKG-INFO

@@ -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).

{py_neuromodulation-0.0.2 → py_neuromodulation-0.0.3}/README.rst

@@ -40,12 +40,24 @@ py_neuromodulation requires at least python 3.10. For installation you can use p
 
     pip install py-neuromodulation
 
-We recommend however installing the package in a new new conda environment:
+
+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
-    conda create -n pynm-test python=3.10
+    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`:
@@ -65,27 +77,27 @@ Then *py_neuromodulation* can be imported via:
 
 .. code-block::
 
-    import py_neuromodulation as py_nm
+    import py_neuromodulation as nm
 
 Basic Usage
 ===========
 
 .. code-block:: python
     
-    import py_neuromodulation as pn
+    import py_neuromodulation as nm
     import numpy as np
     
     NUM_CHANNELS = 5
     NUM_DATA = 10000
     sfreq = 1000  # Hz
-    feature_freq = 3  # Hz
+    sampling_rate_features_hz = 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)
+    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_first_demo.html>`_ for further introduction.
+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
 -------------------

py_neuromodulation-0.0.3/docs/build/_downloads/09df217f95985497f45d69e2d4bdc5b1/plot_2_example_add_feature.py

@@ -0,0 +1,68 @@
+"""
+===================
+Adding New Features 
+===================
+
+"""
+
+import py_neuromodulation as pn
+from py_neuromodulation import nm_features_abc
+import numpy as np
+from typing import Iterable
+
+# %%
+# In this example we will demonstrate how a new feature can be added to the existing feature pipeline.
+# This can be done simply by adding an object of the inherited :class:`~nm_features_abc.Feature` 
+# class to the stream `stream.run_analysis.features.features` list.
+
+data = np.random.random([1, 1000])
+
+stream = pn.Stream(sfreq=1000, data=data, sampling_rate_features_hz=10, verbose=False,)
+
+class NewFeature(nm_features_abc.Feature):
+    
+    def __init__(
+        self, settings: dict, ch_names: Iterable[str], sfreq: float
+    ) -> None:
+        self.s = settings
+        self.ch_names = ch_names
+    
+    def calc_feature(self, data: np.array, features_compute: dict) -> dict:
+        for ch_idx, ch in enumerate(self.ch_names):
+            features_compute[f"new_feature_{ch}"] = np.mean(data[ch_idx, :])
+
+        return features_compute
+
+    def test_settings():
+        pass
+
+newFeature = NewFeature(stream.settings, list(stream.nm_channels["name"]), stream.sfreq)
+stream.run_analysis.features.features.append(newFeature)
+
+features = stream.run_analysis.process(data)
+feature_name = f"new_feature_{stream.nm_channels['name'][0]}"
+
+print(f"{feature_name}: {features[feature_name]}")
+
+# %%
+# This example shows a simple newly instantiated feature class called `NewFeature`.
+# The instantiated `newFeature` object could then be added to the existing feature list by calling 
+# `stream.run_analysis.features.features.append(newFeature)`.
+#
+# To permanently add a novel feature, the new feature class needs to be added to 
+# the :class:`~nm_features` class. This can be done by inserting the feature_name in 
+# in the :class:`~nm_features.Feature` init function:
+# 
+# .. code-block:: python
+#
+#    for feature in s["features"]:
+#        if s["features"][feature] is False:
+#            continue
+#        match feature:
+#            case "new_feature":
+#                FeatureClass = nm_new_feature.NewFeature
+#            ...
+#
+# The new feature class can then be used by setting the `settings["feature"]["new_feature"]` value in the 
+# settings to true.
+#