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

docs/source/conf.py

@@ -0,0 +1,105 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+import sys
+import os
+import json
+import re
+from sphinx_gallery.sorting import FileNameSortKey
+import sphinx_gallery
+import py_neuromodulation
+
+print("CURRENT WORKING DIRECTORY")
+print(os.getcwd())
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+if os.path.basename(SCRIPT_DIR) == "source":
+    # this check is necessary, so we can also run the script from the root directory
+    SCRIPT_DIR = os.path.join(os.path.dirname(os.path.dirname(SCRIPT_DIR)), "py_neuromodulation")
+print(f"Script Directory to add: {SCRIPT_DIR}")
+sys.path.append(SCRIPT_DIR)
+
+print(sys.path)
+
+
+exclude_patterns = ["_build", "_templates"]
+
+
+# -- Project information -----------------------------------------------------
+project = 'py_neuromodulation'
+copyright = '2021, Timon Merk'
+author = 'Timon Merk'
+
+source_parsers = {
+    '.md': 'recommonmark.parser.CommonMarkParser',
+}
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.autosectionlabel',
+    'sphinx_gallery.gen_gallery',
+    'sphinx_togglebutton',
+]
+
+source_suffix = ['.rst', '.md', ]
+
+autosummary_generate = True
+
+PYDEVD_DISABLE_FILE_VALIDATION=1
+
+sphinx_gallery_conf = {
+    "examples_dirs": "../../examples",
+    "gallery_dirs": "auto_examples",
+    "within_subsection_order" : sphinx_gallery.sorting.FileNameSortKey,
+}
+
+#sphinx_gallery_conf = {
+#    "examples_dirs": "../../examples",
+#    "gallery_dirs": "auto_examples",
+#    #'plot_gallery': True,
+#    'thumbnail_size': (160, 112),
+#    'image_scrapers': ("matplotlib", ),
+#    'show_memory': True,
+#    'notebook_images': 'https://py-neuromodulation.readthedocs.io/en/latest/',
+#    'default_thumb_file': os.path.join('_static', 'RMAP_figure.png'),
+#}
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+html_theme = "pydata_sphinx_theme"
+html_static_path = ['_static']
+
+html_theme_options = {
+    "show_nav_level": 4,
+    "icon_links": [
+        dict(
+            name="GitHub",
+            url="https://github.com/neuromodulation/py_neuromodulation",
+            icon="fa-brands fa-square-github",
+        )
+    ],
+}
+
+# -- Intersphinx configuration -----------------------------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+    "numba": ("https://numba.readthedocs.io/en/latest", None),
+    "mne": ("https://mne.tools/stable", None),
+    "pandas" : ("https://pandas.pydata.org/docs", None),
+}
+

examples/plot_0_first_demo.py

@@ -0,0 +1,189 @@
+"""
+First Demo
+==========
+
+This Demo will showcase the feature estimation and
+exemplar analysis using simulated data.
+"""
+
+import numpy as np
+from matplotlib import pyplot as plt
+
+import py_neuromodulation as nm
+
+from py_neuromodulation import nm_analysis, nm_define_nmchannels, nm_plots
+
+# %%
+# Data Simulation
+# ---------------
+# We will now generate some exemplar data with 10 second duration for 6 channels with a sample rate of 1 kHz.
+
+
+def generate_random_walk(NUM_CHANNELS, TIME_DATA_SAMPLES):
+    # from https://towardsdatascience.com/random-walks-with-python-8420981bc4bc
+    dims = NUM_CHANNELS
+    step_n = TIME_DATA_SAMPLES - 1
+    step_set = [-1, 0, 1]
+    origin = (np.random.random([1, dims]) - 0.5) * 1  # Simulate steps in 1D
+    step_shape = (step_n, dims)
+    steps = np.random.choice(a=step_set, size=step_shape)
+    path = np.concatenate([origin, steps]).cumsum(0)
+    return path.T
+
+
+NUM_CHANNELS = 6
+sfreq = 1000
+TIME_DATA_SAMPLES = 10 * sfreq
+data = generate_random_walk(NUM_CHANNELS, TIME_DATA_SAMPLES)
+time = np.arange(0, TIME_DATA_SAMPLES / sfreq, 1 / sfreq)
+
+plt.figure(figsize=(8, 4), dpi=100)
+for ch_idx in range(data.shape[0]):
+    plt.plot(time, data[ch_idx, :])
+plt.xlabel("Time [s]")
+plt.ylabel("Amplitude")
+plt.title("Example random walk data")
+
+# %%
+# Now let’s define the necessary setup files we will be using for data
+# preprocessing and feature estimation. Py_neuromodualtion is based on two
+# parametrization files: the *nm_channels.tsv* and the *nm_setting.json*.
+#
+# nm_channels
+# ~~~~~~~~~~~
+#
+# The *nm_channel* dataframe. This dataframe contains the columns
+#
+# +-----------------------------------+-----------------------------------+
+# | Column name                       | Description                       |
+# +===================================+===================================+
+# | **name**                          | name of the channel               |
+# +-----------------------------------+-----------------------------------+
+# | **rereference**                   | different channel name for        |
+# |                                   | bipolar re-referencing, or        |
+# |                                   | average for common average        |
+# |                                   | re-referencing                    |
+# +-----------------------------------+-----------------------------------+
+# | **used**                          | 0 or 1, channel selection         |
+# +-----------------------------------+-----------------------------------+
+# | **target**                        | 0 or 1, for some decoding         |
+# |                                   | applications we can define target |
+# |                                   | channels, e.g. EMG channels       |
+# +-----------------------------------+-----------------------------------+
+# | **type**                          | channel type according to the     |
+# |                                   | `mne-python`_ toolbox             |
+# |                                   |                                   |
+# |                                   |                                   |
+# |                                   |                                   |
+# |                                   |                                   |
+# |                                   | e.g. ecog, eeg, ecg, emg, dbs,    |
+# |                                   | seeg etc.                         |
+# +-----------------------------------+-----------------------------------+
+# | **status**                        | good or bad, used for channel     |
+# |                                   | quality indication                |
+# +-----------------------------------+-----------------------------------+
+# | **new_name**                      | this keyword can be specified to  |
+# |                                   | indicate for example the used     |
+# |                                   | rereferncing scheme               |
+# +-----------------------------------+-----------------------------------+
+#
+# .. _mne-python: https://mne.tools/stable/auto_tutorials/raw/10_raw_overview.html#sphx-glr-auto-tutorials-raw-10-raw-overview-py
+#
+# The :class:`~nm_stream_abc` can either be created as a *.tsv* text file, or as a pandas
+# DataFrame. There are some helper functions that let you create the
+# nm_channels without much effort:
+
+nm_channels = nm_define_nmchannels.get_default_channels_from_data(
+    data, car_rereferencing=True
+)
+
+nm_channels
+
+# %%
+# Using this function default channel names and a common average re-referencing scheme is specified.
+# Alternatively the *nm_define_nmchannels.set_channels* function can be used to pass each column values.
+#
+# nm_settings
+# -----------
+# Next, we will initialize the nm_settings dictionary and use the default settings, reset them, and enable a subset of features:
+
+settings = nm.nm_settings.get_default_settings()
+settings = nm.nm_settings.reset_settings(settings)
+
+
+# %%
+# The setting itself is a .json file which contains the parametrization for preprocessing, feature estimation, postprocessing and
+# definition with which sampling rate features are being calculated.
+# In this example `sampling_rate_features_hz` is specified to be 10 Hz, so every 100ms a new set of features is calculated.
+#
+# For many features the `segment_length_features_ms` specifies the time dimension of the raw signal being used for feature calculation. Here it is specified to be 1000 ms.
+#
+# We will now enable the features:
+#
+# * fft
+# * bursts
+# * sharpwave
+#
+# and stay with the default preprcessing methods:
+#
+# * notch_filter
+# * re_referencing
+#
+# and use *z-score* postprocessing normalization.
+
+settings["features"]["fft"] = True
+settings["features"]["bursts"] = True
+settings["features"]["sharpwave_analysis"] = True
+
+# %%
+# We are now ready to go to instantiate the *Stream* and call the *run* method for feature estimation:
+
+stream = nm.Stream(
+    settings=settings,
+    nm_channels=nm_channels,
+    verbose=True,
+    sfreq=sfreq,
+    line_noise=50,
+)
+
+features = stream.run(data)
+
+# %%
+# Feature Analysis
+# ----------------
+#
+# There is a lot of output, which we could omit by verbose being False, but let's have a look what was being computed.
+# We will therefore use the :class:`~nm_analysis` class to showcase some functions. For multi-run -or subject analysis we will pass here the feature_file "sub" as default directory:
+
+analyzer = nm_analysis.Feature_Reader(
+    feature_dir=stream.PATH_OUT, feature_file=stream.PATH_OUT_folder_name
+)
+
+# %%
+# Let's have a look at the resulting "feature_arr" DataFrame:
+
+analyzer.feature_arr.iloc[:10, :7]
+
+# %%
+# Seems like a lot of features were calculated. The `time` column tells us about each row time index.
+# For the 6 specified channels, it is each 31 features.
+# We can now use some in-built plotting functions for visualization.
+#
+# .. note::
+#
+#     Due to the nature of simulated data, some of the features have constant values, which are not displayed through the image normalization.
+#
+#
+
+analyzer.plot_all_features(ch_used="ch1")
+
+# %%
+nm_plots.plot_corr_matrix(
+    figsize=(25, 25),
+    show_plot=True,
+    feature=analyzer.feature_arr,
+)
+
+# %%
+# The upper correlation matrix shows the correlation of every feature of every channel to every other.
+# This notebook demonstrated a first demo how features can quickly be generated. For further feature modalities and decoding applications check out the next notebooks.

examples/plot_1_example_BIDS.py

@@ -0,0 +1,240 @@
+"""
+ECoG Movement decoding example 
+==============================
+
+"""
+
+# %%
+# This example notebook read openly accessible data from the publication
+# *Electrocorticography is superior to subthalamic local field potentials
+# for movement decoding in Parkinson’s disease*
+# (`Merk et al. 2022 <https://elifesciences.org/articles/75126>_`).
+# The dataset is available `here <https://doi.org/10.7910/DVN/IO2FLM>`_.
+#
+# For simplicity one example subject is automatically shipped within
+# this repo at the *py_neuromodulation/data* folder, stored in
+# `iEEG BIDS <https://www.nature.com/articles/s41597-019-0105-7>`_ format.
+
+# %%
+from sklearn import metrics, model_selection, linear_model
+import matplotlib.pyplot as plt
+
+import py_neuromodulation as nm
+from py_neuromodulation import (
+    nm_analysis,
+    nm_decode,
+    nm_define_nmchannels,
+    nm_IO,
+    nm_plots,
+    nm_settings,
+)
+
+# %%
+# Let's read the example using `mne_bids <https://mne.tools/mne-bids/stable/index.html>`_.
+# The resulting raw object is of type `mne.RawArray <https://mne.tools/stable/generated/mne.io.RawArray.html>`_.
+# We can use the properties such as sampling frequency, channel names, channel types all from the mne array and create the *nm_channels* DataFrame:
+
+(
+    RUN_NAME,
+    PATH_RUN,
+    PATH_BIDS,
+    PATH_OUT,
+    datatype,
+) = nm_IO.get_paths_example_data()
+
+(
+    raw,
+    data,
+    sfreq,
+    line_noise,
+    coord_list,
+    coord_names,
+) = nm_IO.read_BIDS_data(
+    PATH_RUN=PATH_RUN, BIDS_PATH=PATH_BIDS, datatype=datatype
+)
+
+nm_channels = nm_define_nmchannels.set_channels(
+    ch_names=raw.ch_names,
+    ch_types=raw.get_channel_types(),
+    reference="default",
+    bads=raw.info["bads"],
+    new_names="default",
+    used_types=("ecog", "dbs", "seeg"),
+    target_keywords=["MOV_RIGHT"],
+)
+
+nm_channels
+
+# %%
+# This example contains the grip force movement traces, we'll use the *MOV_RIGHT* channel as a decoding target channel.
+# Let's check some of the raw feature and time series traces:
+
+plt.figure(figsize=(12, 4), dpi=300)
+plt.subplot(121)
+plt.plot(raw.times, data[-1, :])
+plt.xlabel("Time [s]")
+plt.ylabel("a.u.")
+plt.title("Movement label")
+plt.xlim(0, 20)
+
+plt.subplot(122)
+for idx, ch_name in enumerate(nm_channels.query("used == 1").name):
+    plt.plot(raw.times, data[idx, :] + idx * 300, label=ch_name)
+plt.legend(bbox_to_anchor=(1, 0.5), loc="center left")
+plt.title("ECoG + STN-LFP time series")
+plt.xlabel("Time [s]")
+plt.ylabel("Voltage a.u.")
+plt.xlim(0, 20)
+
+# %%
+settings = nm_settings.get_default_settings()
+settings = nm_settings.set_settings_fast_compute(settings)
+
+settings["features"]["welch"] = True
+settings["features"]["fft"] = True
+settings["features"]["bursts"] = True
+settings["features"]["sharpwave_analysis"] = True
+settings["features"]["coherence"] = True
+settings["coherence"]["channels"] = [["LFP_RIGHT_0", "ECOG_RIGHT_0"]]
+settings["coherence"]["frequency_bands"] = ["high beta", "low gamma"]
+settings["sharpwave_analysis_settings"]["estimator"]["mean"] = []
+for sw_feature in list(
+    settings["sharpwave_analysis_settings"]["sharpwave_features"].keys()
+):
+    settings["sharpwave_analysis_settings"]["sharpwave_features"][
+        sw_feature
+    ] = True
+    settings["sharpwave_analysis_settings"]["estimator"]["mean"].append(
+        sw_feature
+    )
+
+# %%
+stream = nm.Stream(
+    sfreq=sfreq,
+    nm_channels=nm_channels,
+    settings=settings,
+    line_noise=line_noise,
+    coord_list=coord_list,
+    coord_names=coord_names,
+    verbose=True,
+)
+
+# %%
+features = stream.run(
+    data=data,
+    out_path_root=PATH_OUT,
+    folder_name=RUN_NAME,
+)
+
+# %%
+# Feature Analysis Movement
+# -------------------------
+# The obtained performances can now be read and visualized using the :class:`nm_analysis.Feature_Reader`.
+
+# initialize analyzer
+feature_reader = nm_analysis.Feature_Reader(
+    feature_dir=PATH_OUT,
+    feature_file=RUN_NAME,
+)
+feature_reader.label_name = "MOV_RIGHT"
+feature_reader.label = feature_reader.feature_arr["MOV_RIGHT"]
+
+# %%
+feature_reader.feature_arr.iloc[100:108, -6:]
+
+# %%
+print(feature_reader.feature_arr.shape)
+
+# %%
+feature_reader._get_target_ch()
+
+# %%
+feature_reader.plot_target_averaged_channel(
+    ch="ECOG_RIGHT_0",
+    list_feature_keywords=None,
+    epoch_len=4,
+    threshold=0.5,
+    ytick_labelsize=7,
+    figsize_x=12,
+    figsize_y=12,
+)
+
+# %%
+feature_reader.plot_all_features(
+    ytick_labelsize=6,
+    clim_low=-2,
+    clim_high=2,
+    ch_used="ECOG_RIGHT_0",
+    time_limit_low_s=0,
+    time_limit_high_s=20,
+    normalize=True,
+    save=True,
+)
+
+# %%
+nm_plots.plot_corr_matrix(
+    feature=feature_reader.feature_arr.filter(regex="ECOG_RIGHT_0"),
+    ch_name="ECOG_RIGHT_0-avgref",
+    feature_names=feature_reader.feature_arr.filter(
+        regex="ECOG_RIGHT_0-avgref"
+    ).columns,
+    feature_file=feature_reader.feature_file,
+    show_plot=True,
+    figsize=(15, 15),
+)
+
+# %%
+# Decoding
+# --------
+#
+# The main focus of the *py_neuromodulation* pipeline is feature estimation.
+# Nevertheless, the user can also use the pipeline for machine learning decoding.
+# It can be used for regression and classification problems and also dimensionality reduction such as PCA and CCA.
+#
+# Here, we show an example using the XGBOOST classifier. The used labels came from a continuous grip force movement target, named "MOV_RIGHT".
+#
+# First we initialize the :class:`~nm_decode.Decoder` class, which the specified *validation method*, here being a simple 3-fold cross validation,
+# the evaluation metric, used machine learning model, and the channels we want to evaluate performances for.
+#
+# There are many more implemented methods, but we will here limit it to the ones presented.
+
+model = linear_model.LinearRegression()
+
+feature_reader.decoder = nm_decode.Decoder(
+    features=feature_reader.feature_arr,
+    label=feature_reader.label,
+    label_name=feature_reader.label_name,
+    used_chs=feature_reader.used_chs,
+    model=model,
+    eval_method=metrics.r2_score,
+    cv_method=model_selection.KFold(n_splits=3, shuffle=True),
+)
+
+# %%
+performances = feature_reader.run_ML_model(
+    estimate_channels=True,
+    estimate_gridpoints=False,
+    estimate_all_channels_combined=True,
+    save_results=True,
+)
+
+# %%
+# The performances are a dictionary that can be transformed into a DataFrame:
+
+df_per = feature_reader.get_dataframe_performances(performances)
+
+df_per
+
+# %%
+ax = nm_plots.plot_df_subjects(
+    df_per,
+    x_col="sub",
+    y_col="performance_test",
+    hue="ch_type",
+    PATH_SAVE=PATH_OUT / RUN_NAME / (RUN_NAME + "_decoding_performance.png"),
+    figsize_tuple=(8, 5),
+)
+ax.set_ylabel(r"$R^2$ Correlation")
+ax.set_xlabel("Subject 000")
+ax.set_title("Performance comparison Movement decoding")
+plt.tight_layout()

examples/plot_2_example_add_feature.py

@@ -0,0 +1,76 @@
+"""
+===================
+Adding New Features 
+===================
+
+"""
+
+import py_neuromodulation as nm
+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 = nm.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.
+#