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

docs/source/conf.py

@@ -1,105 +0,0 @@
-# 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

@@ -1,189 +0,0 @@
-"""
-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

@@ -1,240 +0,0 @@
-"""
-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

@@ -1,76 +0,0 @@
-"""
-===================
-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.
-#