py-neuromodulation 0.0.7__tar.gz → 0.1.0__tar.gz

{py_neuromodulation-0.0.7 → py_neuromodulation-0.1.0}/.github/workflows/docs_pages.yml

@@ -24,13 +24,13 @@ jobs:
       - name: Set up Python with uv
         uses: drivendataorg/setup-python-uv-action@v1
         with:
-          python-version: '3.10'
+          python-version: '3.11'
           cache: packages
           cache-dependency-path: pyproject.toml
  
       - name: Install dependencies
         run: |
-          uv pip install .[docs]
+          pip install .[docs]
 
       - name: make the sphinx docs
         run: |

{py_neuromodulation-0.0.7 → py_neuromodulation-0.1.0}/.gitignore

@@ -191,9 +191,23 @@ out_per
 # Profiler files
 /*.prof
 /profiling/*
-
+# Test output
+test_data/
+# various lock files
+package-lock.json
+package-lock.json.bak
+uv.lock
+# temporarily ignore the frontend build
+/gui_dev/dist
+/gui/frontend
+# Node modules
 gui_dev/node_modules/*
+# LSL log file
+lsllog.txt
+#Old Bun binary lockfile
+bun.lockb
 test/data/*
-
 uv.lock
-lsllog.txt
+
+sub_SETTINGS.yaml
+sub_SIDECAR.json

{py_neuromodulation-0.0.7 → py_neuromodulation-0.1.0}/PKG-INFO

@@ -1,9 +1,11 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: py_neuromodulation
-Version: 0.0.7
+Version: 0.1.0
 Summary: Real-time analysis of intracranial neurophysiology recordings.
-Project-URL: bugtracker, https://github.com/neuromodulation/py_neuromodulation/issues
-Project-URL: repository, https://github.com/neuromodulation/py_neuromodulation
+Project-URL: Homepage, https://neuromodulation.github.io/py_neuromodulation/
+Project-URL: Documentation, https://neuromodulation.github.io/py_neuromodulation/
+Project-URL: Repository, https://github.com/neuromodulation/py_neuromodulation
+Project-URL: Issues, https://github.com/neuromodulation/py_neuromodulation/issues
 Author-email: Timon Merk <timon.merk@charite.de>
 Maintainer: Timon Merk
 License: MIT License
@@ -34,7 +36,10 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
+Requires-Dist: cbor2>=5.6.4
+Requires-Dist: fastapi
 Requires-Dist: fooof
+Requires-Dist: imbalanced-learn
 Requires-Dist: joblib>=1.3.2
 Requires-Dist: llvmlite>=0.43.0
 Requires-Dist: matplotlib>=3.9.0
@@ -43,18 +48,25 @@ Requires-Dist: mne-bids>=0.8
 Requires-Dist: mne-connectivity
 Requires-Dist: mne-lsl>=1.2.0
 Requires-Dist: mrmr-selection
+Requires-Dist: msgpack>=1.1.0
+Requires-Dist: nibabel>=5.3.2
 Requires-Dist: nolds>=0.6.1
 Requires-Dist: numba>=0.60.0
 Requires-Dist: numpy>=1.21.2
+Requires-Dist: numpy>=2.0.0
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: pyarrow>=14.0.2
 Requires-Dist: pybispectra>=1.2.0
 Requires-Dist: pydantic>=2.7.3
 Requires-Dist: pyparrm
+Requires-Dist: pywebview
 Requires-Dist: scikit-learn>=0.24.2
 Requires-Dist: scikit-optimize
 Requires-Dist: scipy>=1.7.1
 Requires-Dist: seaborn>=0.11
+Requires-Dist: skops>=0.10.0
+Requires-Dist: uvicorn[standard]>=0.30.6
+Requires-Dist: uvloop; platform_system != 'Windows'
 Provides-Extra: dev
 Requires-Dist: notebook; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
@@ -81,6 +93,8 @@ Description-Content-Type: text/x-rst
 py_neuromodulation
 ==================
 
+Documentation: https://neuromodulation.github.io/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.

{py_neuromodulation-0.0.7 → py_neuromodulation-0.1.0}/README.rst

@@ -1,6 +1,8 @@
 py_neuromodulation
 ==================
 
+Documentation: https://neuromodulation.github.io/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.

py_neuromodulation-0.1.0/docs/source/RMAP.rst

@@ -0,0 +1,8 @@
+RMAP
+====
+
+.. autoclass:: analysis.RMAP.ConnectivityChannelSelector
+      :members:
+
+.. autoclass:: analysis.RMAP.RMAPCross_Val_ChannelSelector
+      :members:

py_neuromodulation-0.1.0/docs/source/api_documentation.rst

@@ -0,0 +1,84 @@
+API Documentation
+=================
+
+
+Analysis
+--------
+
+.. toctree::
+   :maxdepth: 4
+
+   decode
+   feature_reader
+   plots
+   RMAP
+   stats
+
+
+Feature Classes
+---------------
+
+.. toctree::
+   :maxdepth: 4
+
+   bispectra
+   bursts
+   coherence
+   fooof
+   hjorth
+   linelength
+   mne_connectivity
+   nolds
+   oscillatory
+   sharpwaves
+   bandpower
+
+
+Filter
+------
+
+.. toctree::
+   :maxdepth: 4
+
+   mne_filter
+   notch_filter
+
+
+Processing
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   artifacts
+   normalization
+   projection
+   rereference
+   resample
+
+
+stream
+------
+
+.. toctree::
+   :maxdepth: 4
+
+   generator
+   mnelsl_player
+   mnelsl_stream
+   settings
+   stream
+
+
+utils
+-----
+
+.. toctree::
+   :maxdepth: 4
+
+   channels
+   database
+   io
+   logging
+   types
+

py_neuromodulation-0.1.0/docs/source/artifacts.rst

@@ -0,0 +1,5 @@
+artifacts
+=========
+
+.. autoclass:: processing.artifacts.PARRMArtifactRejection
+      :members:

py_neuromodulation-0.1.0/docs/source/bandpower.rst

@@ -0,0 +1,5 @@
+bandpower
+=========
+
+.. autoclass:: features.bandpower.BandPower
+      :members:

py_neuromodulation-0.1.0/docs/source/bispectra.rst

@@ -0,0 +1,5 @@
+bispectra
+=========
+
+.. autoclass:: features.bispectra.Bispectra
+      :members:

py_neuromodulation-0.1.0/docs/source/bursts.rst

@@ -0,0 +1,5 @@
+bursts
+======
+
+.. autoclass:: features.bursts.Bursts
+      :members:

py_neuromodulation-0.1.0/docs/source/channels.rst

@@ -0,0 +1,5 @@
+channels
+========
+
+.. automodule:: utils.channels
+      :members:

py_neuromodulation-0.1.0/docs/source/coherence.rst

@@ -0,0 +1,5 @@
+coherence
+=========
+
+.. autoclass:: features.coherence.Coherence
+      :members:

py_neuromodulation-0.1.0/docs/source/contributing.rst

@@ -0,0 +1,87 @@
+Contribution Guide
+==================
+
+Welcome to the contributing guide of py_neuromodulation! We are very happy that you are interested in our project.
+
+In general we recommend placing questions and issues in the `GitHub issue tracker <https://github.com/neuromodulation/py_neuromodulation/issues>`_.
+
+For code formatting we use `ruff <https://docs.astral.sh/ruff/formatter/>`_.
+
+For code development, we recommend using the package manager `uv <https://docs.astral.sh/uv/getting-started/installation/>`_.
+
+To setup the python environment, type
+
+::
+
+    uv python install 3.11
+    uv venv
+
+
+Depending on your operating system, activate the rye virtual environment: 
+
+::
+
+    . .venv/bin/activate
+
+And install the pyproject.toml dependencies:
+
+:: 
+
+    then sync the environment with
+
+::
+
+    uv sync
+
+To install the documentation dependencies use pip:
+
+::
+
+    uv pip install -e .[docs]
+
+
+GUI development
+---------------
+
+Backend
+~~~~~~~
+
+
+The GUI is setup as a react application with a `FastAPI <https://fastapi.tiangolo.com/>`_ backend with a `uvicorn <https://www.uvicorn.org/>`_ server.
+The ``gui/backend/app_manager.py`` is the main entry point for the GUI backend. Here multiple tasks are defined and started using python `multiprocessing`.
+In debug mode, `vite <https://vite.dev/>`_ is within ``gui/backend/app_manager.run_vite`` used to serve the frontend. In a subprocess ``bun run dev`` is called.
+In production mode ``gui/backend/app_manager.run_backend`` directly serves the frontend from the `gui/frontend` directory, if `debug=False`.
+Uvicorn (``gui/backend/app_manager.run_uvicorn``) runs an ASGI server, which deploys the FastAPI backend (``gui/backend/app_backend.PyNMBackend``).
+Within the backend, multiple `get` and `post` routes are setup to interact with the frontend.
+
+.. raw:: html
+
+   <br>
+
+A *py_neuromodulation* state object is defined within the ``gui/backend/app_pynm.PyNMState`` class.
+The state is initialized at the beginning of each App launch, and the settings and channels of the `nm.stream` are then modified during runtime.
+Importantly, a ``stream.backend_interface`` is defined which creates an `asyncio` loop to interact with the `nm.stream` object.
+Python `multiprocessing.Queue` objects are used for frontend communication, for starting or stopping the stream, or sending data to the frontend through websockets.
+Within the ``gui/backend/app_socket.WebSocketManger``, the computed features and raw values are first serialized through `CBOR <https://cbor2.readthedocs.io/en/latest/usage.html>`_ and then sent to the frontend.
+
+Frontend
+~~~~~~~~
+
+The frontend is a `react <https://react.dev/>`_ application, which is stored in the `gui_dev` directory.
+There are session, settings and socket `zustand <https://zustand-demo.pmnd.rs/>`_ stores. 
+Additionally, different pages and components are defined. `Plotly <https://plotly.com/javascript/>`_ is used for real-time dashboard visualization.
+
+For GUI build, `bun <https://bun.sh/package-manager>`_ can be used to build the package. It is then saved into the `gui/frontend` directory.
+
+Building the GUI in *gui_dev* folder:
+
+::
+
+    bun run build
+
+Additionally, the script ``run_gui.py`` can be modified to be in `dev` mode:
+
+::
+
+    App(dev=True).launch()
+

py_neuromodulation-0.1.0/docs/source/database.rst

@@ -0,0 +1,5 @@
+database
+========
+
+.. autoclass:: utils.database.NMDatabase
+      :members:

py_neuromodulation-0.1.0/docs/source/decode.rst

@@ -0,0 +1,5 @@
+decode
+======
+
+.. autoclass:: analysis.decode.Decoder
+      :members:

py_neuromodulation-0.1.0/docs/source/feature_reader.rst

@@ -0,0 +1,5 @@
+feature_reader
+==============
+
+.. autoclass:: analysis.feature_reader.FeatureReader
+      :members:

py_neuromodulation-0.1.0/docs/source/fooof.rst

@@ -0,0 +1,5 @@
+fooof
+=====
+
+.. autoclass:: features.fooof.FooofAnalyzer
+      :members:

py_neuromodulation-0.1.0/docs/source/generator.rst

@@ -0,0 +1,5 @@
+generator
+=========
+
+.. autoclass:: stream.generator.RawDataGenerator
+      :members:

py_neuromodulation-0.1.0/docs/source/gui.rst

@@ -0,0 +1,112 @@
+GUI
+===
+
+In this section we will explain the setup and use of the *py_neuromodulation* GUI.
+First, the GUI dependencies can be installed with `uv`:
+
+.. code-block:: bash
+
+    uv pip install -e .[gui]
+
+The GUI can be started by running the following command:
+
+.. code-block:: bash
+
+    run_gui
+
+The ``run_gui`` command also starts a LabStreamingLayer stream from the `py_neuromodulation/data/` example directory.
+The GUI is a react application, that can then be accessed via the browser at the following address:
+
+.. code-block:: bash
+
+    http://localhost:50001
+
+The GUI is divided into three main sections:
+  * **Source selection**: Data input which could be:
+     * offline stored file, e.g. in `mne.io.read_raw <https://mne.tools/1.8/generated/mne.io.read_raw.html>`_ format or a simply `.txt` or `.npy` file
+     * a `LabStreamingLayer <https://labstreaminglayer.org/#/>`_ stream
+  * **channel selection**: Definition of re-referencing, usage, target selection for the list of available channels
+  * **Feature selection**: Choosing the features for computation with the corresponding parameters
+
+The source selection is shown in the following image:
+
+.. image:: ../_static/sourceselection.png
+   :alt: GUI
+   :align: center
+
+When clicking on the `SELECT FILE` button, a file dialog will open, where the user can select the file to be loaded:
+
+.. image:: ../_static/fileselection.png
+   :alt: GUI
+   :align: center
+
+Internally, available meta data such as sampling rate, line noise, available channel names will be read and a stream initialized.
+Alternatively, the user can select a LabStreamingLayer stream by clicking on the upper `LSL STREAM` button. The available streams will be shown in a menu:
+
+.. image:: ../_static/lslselection.png
+   :alt: GUI
+   :align: center
+
+Clicking on the row of the desired stream will initialize then a stream with the read sampling rate, channel names and default settings.
+A `.skops` decoding model, such as an openly-published `movement decoding model <https://zenodo.org/records/10794370>`_ can be loaded by clicking on the `LOAD MODEL` button.
+
+Next, by selecting `SELECT CHANNELS`, the user is directed to the channel selection section:
+
+.. image:: ../_static/channelselection.png
+   :alt: GUI
+   :align: center
+
+Here the channel names, re-referencing, `mne supported types <https://mne.tools/stable/generated/mne.pick_types.html>`_ and target selection can be defined.
+Next, by clicking on `SETTINGS`, the user is directed to the feature selection:
+
+.. image:: ../_static/settings.png
+   :alt: GUI
+   :align: center
+
+Here, many pre-processing, feature estimation and post-processing settings can be defined.
+The main settings
+
+  * `sampling rate features [Hz]`
+  * `segment length features [ms]`
+
+are defined the upper left section.
+Additionally, frequency bands can be modified, added or deleted.
+Once the settings are modified, they are internally validated for potential errors which would then be displayed:
+
+.. image:: ../_static/pydantic.png
+   :alt: GUI
+   :align: center
+
+Once the settings are correct, the user can click `SAVE & RUN STREAM` to jump to the stream control and feature visualization panel.
+Here, different graphs can be selected by clicking on the corresponding graph list:
+
+  * `Raw data`
+  * `PSD plot`
+  * `Heatmap`
+  * `Band power graph`
+  * `Decoding graph`
+
+When clicking on `RUN STREAM`, the stream will start and the selected features will be computed in real-time.
+In the terminal the feature computation is logged, and features and raw signals are displayed in the GUI:
+
+.. image:: ../_static/graphs.png
+   :alt: GUI
+   :align: center
+
+Additionally, a heatmap with selected features can be displayed with the decoded model output:
+
+.. image:: ../_static/decoding.png
+   :alt: GUI
+   :align: center
+
+.. raw:: html
+
+   <br>
+
+In the :doc:`contributing </contributing>`  section we explain in further detail the GUI setup. 
+
+Known issues
+~~~~~~~~~~~~
+
+Currently the GUI dashboard for live feature visualization is not fully functional with too many selected channels and PSD features.
+The websocket connection will then be broken off and no further features will be visualized, but the backend *nm.stream* will still be running, and raw data continued to be processed and saved. 

py_neuromodulation-0.1.0/docs/source/hjorth.rst

@@ -0,0 +1,5 @@
+hjorth
+======
+
+.. autoclass:: features.hjorth_raw.Hjorth
+      :members:

{py_neuromodulation-0.0.7 → py_neuromodulation-0.1.0}/docs/source/index.rst

@@ -13,6 +13,7 @@ The *py_neuromodulation* toolbox allows for real time capable feature estimation
    installation
    usage
    auto_examples/index
+   gui
    api_documentation
    contributing
 

py_neuromodulation-0.1.0/docs/source/io.rst

@@ -0,0 +1,5 @@
+io
+==
+
+.. automodule:: utils.io
+      :members:

py_neuromodulation-0.1.0/docs/source/linelength.rst

@@ -0,0 +1,5 @@
+linelength
+==========
+
+.. autoclass:: features.linelength.LineLength
+      :members:

py_neuromodulation-0.1.0/docs/source/logging.rst

@@ -0,0 +1,5 @@
+logging
+=======
+
+.. autoclass:: utils.logging.NMLogger
+      :members:

py_neuromodulation-0.1.0/docs/source/mne_connectivity.rst

@@ -0,0 +1,5 @@
+mne_connectivity
+================
+
+.. autoclass:: features.mne_connectivity.MNEConnectivity
+      :members:

py_neuromodulation-0.1.0/docs/source/mne_filter.rst

@@ -0,0 +1,5 @@
+mne_filter
+==========
+
+.. autoclass:: filter.mne_filter.MNEFilter
+      :members:

py_neuromodulation-0.1.0/docs/source/mnelsl_player.rst

@@ -0,0 +1,5 @@
+mnelsl_player
+==============
+
+.. autoclass:: stream.mnelsl_player.LSLOfflinePlayer
+      :members:

py_neuromodulation-0.1.0/docs/source/mnelsl_stream.rst

@@ -0,0 +1,5 @@
+mnelsl_stream
+=============
+
+.. autoclass:: stream.mnelsl_stream.LSLStream
+      :members:

py_neuromodulation-0.1.0/docs/source/nolds.rst

@@ -0,0 +1,5 @@
+nolds
+=====
+
+.. autoclass:: features.nolds.Nolds
+      :members:

py_neuromodulation-0.1.0/docs/source/normalization.rst

@@ -0,0 +1,5 @@
+normalization
+=============
+
+.. autoclass:: processing.normalization.Normalizer
+      :members:

py_neuromodulation-0.1.0/docs/source/notch_filter.rst

@@ -0,0 +1,5 @@
+notch_filter
+============
+
+.. autoclass:: filter.notch_filter.NotchFilter
+      :members:

py_neuromodulation-0.1.0/docs/source/oscillatory.rst

@@ -0,0 +1,11 @@
+oscillatory
+===========
+
+.. autoclass:: features.oscillatory.FFT
+      :members:
+
+.. autoclass:: features.oscillatory.Welch
+      :members:
+
+.. autoclass:: features.oscillatory.STFT
+      :members:

py_neuromodulation-0.1.0/docs/source/plots.rst

@@ -0,0 +1,5 @@
+plots
+=====
+
+.. autoclass:: analysis.plots.NM_Plot
+      :members:

py_neuromodulation-0.1.0/docs/source/projection.rst

@@ -0,0 +1,5 @@
+projection
+==========
+
+.. autoclass:: processing.projection.Projection
+      :members:

py_neuromodulation-0.1.0/docs/source/rereference.rst

@@ -0,0 +1,5 @@
+rereference
+===========
+
+.. autoclass:: processing.rereference.ReReferencer
+      :members:

py_neuromodulation-0.1.0/docs/source/resample.rst

@@ -0,0 +1,5 @@
+resample
+========
+
+.. autoclass:: processing.resample.Resampler
+      :members:

py_neuromodulation-0.1.0/docs/source/settings.rst

@@ -0,0 +1,5 @@
+settings
+========
+
+.. autoclass:: stream.settings.NMSettings
+      :members:

py_neuromodulation-0.1.0/docs/source/sharpwaves.rst

@@ -0,0 +1,5 @@
+sharpwaves
+==========
+
+.. autoclass:: features.sharpwaves.SharpwaveAnalyzer
+      :members:

py_neuromodulation-0.1.0/docs/source/stats.rst

@@ -0,0 +1,5 @@
+stats
+=====
+
+.. automodule:: analysis.stats
+      :members:

py_neuromodulation-0.1.0/docs/source/stream.rst

@@ -0,0 +1,5 @@
+Stream
+======
+
+.. autoclass:: stream.stream.Stream
+      :members: