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

docs/source/_build/html/_downloads/eaa4305c75b19a1e2eea941f742a6331/plot_4_example_gridPointProjection.py

@@ -0,0 +1,210 @@
+"""
+Grid Point Projection
+=====================
+
+"""
+
+# %%
+# In ECoG datasets the electrode locations are usually different. For this reason, we established a grid
+# with a set of points defined in a standardized MNI brain.
+# Data is then interpolated to this grid, such that they are common across patients, which allows across patient decoding use cases.
+# 
+# In this notebook, we will plot these grid points and see how the features extracted from our data can be projected into this grid space.
+# 
+# In order to do so, we'll read saved features that were computed in the ECoG movement notebook.
+# Please note that in order to do so, when running the feature estimation, the settings
+# 
+# .. note::
+#
+#     .. code-block:: python
+# 
+#         stream.settings['postprocessing']['project_cortex'] = True
+#         stream.settings['postprocessing']['project_subcortex'] = True
+# 
+#     need to be set to `True` for a cortical and/or subcortical projection.
+# 
+
+# %%
+import numpy as np
+import matplotlib.pyplot as plt
+
+import py_neuromodulation as nm
+from py_neuromodulation import (
+    nm_analysis,
+    nm_plots,
+    nm_IO,
+    nm_settings,
+    nm_define_nmchannels
+)
+
+
+# %%
+# Read features from BIDS data
+# ----------------------------
+#
+# We first estimate features, with the `grid_point` projection settings enabled for cortex. 
+
+
+# %%
+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
+)
+
+settings = nm_settings.get_default_settings()
+settings = nm_settings.set_settings_fast_compute(settings)
+
+settings["postprocessing"]["project_cortex"] = True
+
+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_CLEAN","MOV_LEFT_CLEAN"]
+)
+
+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[:, :int(sfreq*5)],
+    out_path_root=PATH_OUT,
+    folder_name=RUN_NAME,
+)
+
+# %%
+# From nm_analysis.py, we use the :class:~`nm_analysis.FeatureReader` class to load the data.
+
+# init analyzer
+feature_reader = nm_analysis.Feature_Reader(
+    feature_dir=PATH_OUT, feature_file=RUN_NAME
+)
+
+# %%
+# To perform the grid projection, for all computed features we check for every grid point if there is any electrode channel within the spatial range ```max_dist_mm```, and weight 
+# this electrode contact by the inverse distance and normalize across all electrode distances within the maximum distance range.
+# This gives us a projection matrix that we can apply to streamed data, to transform the feature-channel matrix *(n_features, n_channels)* into the grid point matrix *(n_features, n_gridpoints)*.
+# 
+# To save computation time, this projection matrix is precomputed before the real time run computation. 
+# The cortical grid is stored in *py_neuromodulation/grid_cortex.tsv* and the electrodes coordinates are stored in *_space-mni_electrodes.tsv* in a BIDS dataset.
+# 
+# .. note::
+#
+#     One remark is that our cortical and subcortical grids are defined for the **left** hemisphere of the brain and, therefore, electrode contacts are mapped to the left hemisphere.
+# 
+# From the analyzer, the user can plot the cortical projection with the function below, display the grid points and ECoG electrodes are crosses.
+# The yellow grid points are the ones that are active for that specific ECoG electrode location. The inactive grid points are shown in purple.
+
+feature_reader.plot_cort_projection()
+
+# %%
+# We can also plot only the ECoG electrodes or the grid points, with the help of the data saved in feature_reader.sidecar. BIDS sidecar files are json files where you store additional information, here it is used to save the ECoG strip positions and the grid coordinates, which are not part of the settings and nm_channels.csv. We can check what is stored in the file and then use the nmplotter.plot_cortex function:
+
+grid_plotter = nm_plots.NM_Plot(
+    ecog_strip=np.array(feature_reader.sidecar["coords"]["cortex_right"]["positions"]),
+    grid_cortex=np.array(feature_reader.sidecar["grid_cortex"]),
+    # grid_subcortex=np.array(feature_reader.sidecar["grid_subcortex"]),
+    sess_right=feature_reader.sidecar["sess_right"],
+    proj_matrix_cortex=np.array(feature_reader.sidecar["proj_matrix_cortex"])
+)
+
+# %%
+grid_plotter.plot_cortex(
+    grid_color=np.sum(np.array(feature_reader.sidecar["proj_matrix_cortex"]),axis=1),
+    lower_clim=0.,
+    upper_clim=1.0,
+    cbar_label="Used Grid Points",
+    title = "ECoG electrodes projected onto cortical grid"
+)
+
+# %%
+feature_reader.sidecar["coords"]["cortex_right"]["positions"]
+
+# %%
+feature_reader.nmplotter.plot_cortex(
+    ecog_strip=np.array(
+        feature_reader.sidecar["coords"]["cortex_right"]["positions"],
+    ),
+    lower_clim=0.,
+    upper_clim=1.0,
+    cbar_label="Used ECoG Electrodes",
+    title = "Plot of ECoG electrodes"
+)
+
+# %%
+feature_reader.nmplotter.plot_cortex(
+    np.array(
+        feature_reader.sidecar["grid_cortex"]
+    ),
+    lower_clim=0.,
+    upper_clim=1.0,
+    cbar_label="All Grid Points",
+    title = "All grid points"
+)
+
+# %%
+# The Projection Matrix
+# ---------------------
+# To go from the feature-channel matrix *(n_features, n_channels)* to the grid point matrix *(n_features, n_gridpoints)*
+# we need a projection matrix that has the shape *(n_channels, n_gridpoints)*.
+# It maps the strengths of the signals in each ECoG channel to the correspondent ones in the cortical grid.
+# In the cell below we plot this matrix, that has the property that the column sum over channels for each grid point is either 1 or 0.
+
+plt.figure(figsize=(8,5))
+plt.imshow(np.array(feature_reader.sidecar['proj_matrix_cortex']), aspect = 'auto')
+plt.colorbar(label = "Strength of ECoG signal in each grid point")
+plt.xlabel("ECoG channels")
+plt.ylabel("Grid points")
+plt.title("Matrix mapping from ECoG to grid")
+
+# %%
+# Feature Plot in the Grid: An Example of Post-processing
+# -------------------------------------------------------
+# First we take the dataframe with all the features in all time points.
+
+df = feature_reader.feature_arr
+
+# %%
+df.iloc[:5, :5]
+
+# %%
+# Then we filter for only 'avgref_fft_theta', which gives us the value for fft_theta in all 6 ECoG channels over all time points. Then we take only the 6th time point - as an arbitrary choice.
+
+fft_theta_oneTimePoint = np.asarray(df[df.columns[df.columns.str.contains(pat = 'avgref_fft_theta')]].iloc[5])
+fft_theta_oneTimePoint
+
+# %%
+# Then the projection of the features into the grid is gonna be the color of the grid points in the *plot_cortex* function.
+# That is the matrix multiplication of the projection matrix of the cortex and 6 values for the *fft_theta* feature above.
+
+grid_fft_Theta = np.array(feature_reader.sidecar["proj_matrix_cortex"]) @ fft_theta_oneTimePoint
+
+feature_reader.nmplotter.plot_cortex(np.array(
+    feature_reader.sidecar["grid_cortex"]),grid_color = grid_fft_Theta, set_clim = True, lower_clim=min(grid_fft_Theta[grid_fft_Theta>0]), upper_clim=max(grid_fft_Theta), cbar_label="FFT Theta Projection to Grid", title = "FFT Theta Projection to Grid")
+
+# %%
+# Lower and upper boundaries for clim were chosen to be the max and min values of the projection of the features (minimum value excluding zero). This can be checked in the cell below:
+
+grid_fft_Theta
+
+# %%
+# In the plot above we can see how the intensity of the fast fourier transform in the theta band varies for each grid point in the cortex, for one specific time point.

docs/source/auto_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.

docs/source/auto_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()