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

examples/plot_3_example_sharpwave_analysis.py

@@ -0,0 +1,219 @@
+"""
+Analyzing temporal features
+===========================
+
+"""
+
+# %%
+# Time series data can be characterized using oscillatory components, but assumptions of sinusoidality are for real data rarely fulfilled.
+# See *"Brain Oscillations and the Importance of Waveform Shape"* `Cole et al 2017 <https://doi.org/10.1016/j.tics.2016.12.008>`_ for a great motivation.
+# We implemented here temporal characteristics based on individual trough and peak relations, 
+# based on the :meth:~`scipy.signal.find_peaks` method. The function parameter *distance* can be specified in the *nm_settings.json*.
+# Temporal features can be calculated twice for troughs and peaks. In the settings, this can be specified by setting *estimate* to true
+# in *detect_troughs* and/or *detect_peaks*. A statistical measure (e.g. mean, max, median, var) can be defined as a resulting feature from the peak and 
+# trough estimates using the *apply_estimator_between_peaks_and_troughs* setting.
+# 
+# In py_neuromodulation the following characteristics are implemented:
+# 
+# .. note::
+#     The nomenclature is written here for sharpwave troughs, but detection of peak characteristics can be computed in the same way.
+# 
+# -  prominence:
+#    :math:`V_{prominence} = |\frac{V_{peak-left} + V_{peak-right}}{2}| - V_{trough}`
+# -  sharpness:
+#    :math:`V_{sharpnesss} = \frac{(V_{trough} - V_{trough-5 ms}) + (V_{trough} - V_{trough+5 ms})}{2}`
+# -  rise and decay rise time
+# -  rise and decay steepness
+# -  width (between left and right peaks)
+# -  interval (between troughs)
+# 
+# Additionally, different filter ranges can be parametrized using the *filter_ranges_hz* setting.
+# Filtering is necessary to remove high frequent signal fluctuations, but limits also the true estimation of sharpness and prominence due to signal smoothing.
+
+import seaborn as sb
+from matplotlib import pyplot as plt
+from scipy import signal
+import numpy as np
+
+import py_neuromodulation as nm
+from py_neuromodulation import (
+    nm_define_nmchannels,
+    nm_IO,
+    nm_settings,
+)
+
+
+# %%
+# We will first read the example ECoG data and plot the identified features on the filtered time series. 
+
+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["features"]["fft"] = True
+settings["features"]["bursts"] = False
+settings["features"]["sharpwave_analysis"] = True
+settings["features"]["coherence"] = False
+
+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)
+
+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"]
+)
+
+stream = nm.Stream(
+    sfreq=sfreq,
+    nm_channels=nm_channels,
+    settings=settings,
+    line_noise=line_noise,
+    coord_list=coord_list,
+    coord_names=coord_names,
+    verbose=False,
+)
+sw_analyzer = stream.run_analysis.features.features[1]
+
+# %%
+# The plotted example time series, visualized on a short time scale, shows the relation of identified peaks, troughs, and estimated features:
+data_plt = data[5, 1000:4000]
+
+
+sw_analyzer._initialize_sw_features()
+filtered_dat = np.convolve(
+    data_plt,
+    sw_analyzer.list_filter[0][1],
+    mode="same"
+)
+#filtered_dat = filtered_dat[500:-500]
+
+troughs = signal.find_peaks(-filtered_dat, distance=10)[0]
+peaks = signal.find_peaks(filtered_dat, distance=5)[0]
+
+sw_analyzer.data_process_sw = filtered_dat
+sw_analyzer.analyze_waveform()
+
+WIDTH = BAR_WIDTH = 4
+BAR_OFFSET = 50
+OFFSET_TIME_SERIES = -100
+SCALE_TIMESERIES = 1
+
+hue_colors = sb.color_palette("viridis_r", 6)
+
+plt.figure(figsize=(5, 3), dpi=300)
+plt.plot(OFFSET_TIME_SERIES + data_plt, color="gray", linewidth=0.5, alpha=0.5, label="original ECoG data")
+plt.plot(OFFSET_TIME_SERIES + filtered_dat*SCALE_TIMESERIES, linewidth=0.5, color="black", label="[5-30]Hz filtered data")
+
+plt.plot(peaks, OFFSET_TIME_SERIES + filtered_dat[peaks]*SCALE_TIMESERIES, "x", label="peaks",markersize=3, color="darkgray")
+plt.plot(troughs, OFFSET_TIME_SERIES + filtered_dat[troughs]*SCALE_TIMESERIES, "x", label="troughs", markersize=3, color="lightgray")
+
+plt.bar(troughs+BAR_WIDTH, np.array(sw_analyzer.prominence)*4, bottom=BAR_OFFSET, width=WIDTH, color=hue_colors[0], label="Prominence", alpha=0.5)
+plt.bar(troughs+BAR_WIDTH*2, -np.array(sw_analyzer.sharpness)*6, bottom=BAR_OFFSET, width=WIDTH, color=hue_colors[1], label="Sharpness", alpha=0.5)
+plt.bar(troughs+BAR_WIDTH*3, np.array(sw_analyzer.interval)*5, bottom=BAR_OFFSET, width=WIDTH, color=hue_colors[2], label="Interval", alpha=0.5)
+plt.bar(troughs+BAR_WIDTH*4, np.array(sw_analyzer.rise_time)*5, bottom=BAR_OFFSET, width=WIDTH, color=hue_colors[3], label="Rise time", alpha=0.5)
+
+plt.xticks(np.arange(0, data_plt.shape[0], 200), np.round(np.arange(0, int(data_plt.shape[0]/1000), 0.2), 2))
+plt.xlabel("Time [s]")
+plt.title("Temporal waveform shape features")
+plt.legend(loc='center left', bbox_to_anchor=(1, 0.5))
+plt.ylim(-550, 700)
+plt.xlim(0, 200)
+plt.ylabel("a.u.")
+plt.tight_layout()
+
+# %%
+# See in the following example a time series example, that is aligned to movement. With movement onset the prominence, sharpness, and interval features are reduced:
+
+plt.figure(figsize=(8, 5), dpi=300)
+plt.plot(OFFSET_TIME_SERIES + data_plt, color="gray", linewidth=0.5, alpha=0.5, label="original ECoG data")
+plt.plot(OFFSET_TIME_SERIES + filtered_dat*SCALE_TIMESERIES, linewidth=0.5, color="black", label="[5-30]Hz filtered data")
+
+plt.plot(peaks, OFFSET_TIME_SERIES + filtered_dat[peaks]*SCALE_TIMESERIES, "x", label="peaks",markersize=3, color="darkgray")
+plt.plot(troughs, OFFSET_TIME_SERIES + filtered_dat[troughs]*SCALE_TIMESERIES, "x", label="troughs", markersize=3, color="lightgray")
+
+plt.bar(troughs+BAR_WIDTH, np.array(sw_analyzer.prominence)*4, bottom=BAR_OFFSET, width=WIDTH, color=hue_colors[0], label="Prominence", alpha=0.5)
+plt.bar(troughs+BAR_WIDTH*2, -np.array(sw_analyzer.sharpness)*6, bottom=BAR_OFFSET, width=WIDTH, color=hue_colors[1], label="Sharpness", alpha=0.5)
+plt.bar(troughs+BAR_WIDTH*3, np.array(sw_analyzer.interval)*5, bottom=BAR_OFFSET, width=WIDTH, color=hue_colors[2], label="Interval", alpha=0.5)
+plt.bar(troughs+BAR_WIDTH*4, np.array(sw_analyzer.rise_time)*5, bottom=BAR_OFFSET, width=WIDTH, color=hue_colors[3], label="Rise time", alpha=0.5)
+
+plt.axvline(x=1500, label="Movement start", color="red")
+
+#plt.xticks(np.arange(0, 2000, 200), np.round(np.arange(0, 2, 0.2), 2))
+plt.xticks(np.arange(0, data_plt.shape[0], 200), np.round(np.arange(0, int(data_plt.shape[0]/1000), 0.2), 2))
+plt.xlabel("Time [s]")
+plt.title("Temporal waveform shape features")
+plt.legend(loc='center left', bbox_to_anchor=(1, 0.5))
+plt.ylim(-450, 400)
+plt.ylabel("a.u.")
+plt.tight_layout()
+
+# %%
+# In the *sharpwave_analysis_settings* the *estimator* keyword further specifies which statistic is computed based on the individual
+# features in one batch. The "global" setting *segment_length_features_ms* specifies the time duration for feature computation.
+# Since there can be a different number of identified waveform shape features for different batches (i.e. different number of peaks/troughs),
+# taking a statistical measure (e.g. the maximum or mean) will be necessary for feature comparison. 
+
+# %%
+# Example time series computation for movement decoding
+# -----------------------------------------------------
+# We will now read the ECoG example/data and investigate if samples differ across movement states. Therefore we compute features and enable the default *sharpwave* features.  
+
+settings = nm_settings.get_default_settings()
+settings = nm_settings.reset_settings(settings)
+settings["features"]["sharpwave_analysis"] = True
+settings["sharpwave_analysis_settings"]["interval"] = False
+settings["sharpwave_analysis_settings"]["filter_ranges"] = [[5, 80]]
+
+nm_channels["used"] = 0  # set only two ECoG channels for faster computation to true
+nm_channels.loc[[3, 8], "used"] = 1
+
+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,
+)
+
+df_features = stream.run(data=data[:, :30000])
+
+# %%
+# We can then plot two exemplary features, prominence and interval, and see that the movement amplitude can be clustered with those two features alone:
+
+plt.figure(figsize=(5, 3), dpi=300)
+plt.scatter(
+    df_features["ECOG_RIGHT_0-avgref_Sharpwave_Max_prominence_range_5_80"],
+    df_features["ECOG_RIGHT_5-avgref_Sharpwave_Mean_interval_range_5_80"],
+    c=df_features["MOV_RIGHT"], alpha=0.8, s=30
+)
+cbar = plt.colorbar()
+cbar.set_label("Movement amplitude")
+plt.xlabel("Prominence a.u.")
+plt.ylabel("Interval a.u.")
+plt.title("Temporal features predict movement amplitude")
+plt.tight_layout()

examples/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.

examples/plot_5_example_rmap_computing.py

@@ -0,0 +1,64 @@
+"""
+R-Map computation
+=================
+
+"""
+# %%
+# sphinx_gallery_thumbnail_path = '_static/RMAP_figure.png'
+
+# %%
+# Across patient decoding using R-Map optimal connectivity
+# --------------------------------------------------------
+# 
+# ECoG electrode placement is commonly very heterogeneous across patients and cohorts. 
+# To still facilitate approaches that are able to perform decoding applications without patient individual training, 
+# two across-patient decoding approaches were previously investigated for movement decoding:
+# 
+# 
+# * grid-point decoding
+# * optimal connectivity channel decoding
+# 
+#
+# First, the grid-point decoding approach relies on definition of a cortical or subcortical grid. 
+# Data from individual grid points is then interpolated onto those common grid points. 
+# The approach was also explained in the :doc:`plot_4_example_gridPointProjection` notebook.
+# 
+# .. image:: ../_static/RMAP_figure.png
+#     :alt: R-Map and grid point approach for decoding without patient-individual training 
+# 
+# The R-Map decoding approach relies on the other hand on computation of whole brain connectivity. The electrode MNI space locations need to be known,
+# then the following steps can be performed for decoding without patient individual training:
+# 
+# #. Using the `wjn_toolbox <https://github.com/neuromodulation/wjn_toolbox>`_ *wjn_specrical_roi* function, the MNI coordinates can be transformed into NIFTI (.nii) files, containing the electrode contact region of interest (ROI):
+# 
+#    .. code-block:: python
+# 
+#      wjn_spherical_roi(roiname, mni, 4)
+# 
+# #. For the given *ROI.nii* files, the LeadDBS `LeadMapper <https://netstim.gitbook.io/leaddbs/connectomics/lead-mapper>`_ tool can be used for functional or structural connectivity estimation. 
+#
+# #. The py_neuromodulation :class:`~nm_RMAP.py` module can then compute the R-Map given the contact-individual connectivity fingerprints:
+# 
+#    .. code-block:: python
+# 
+#        nm_RMAP.calculate_RMap_numba(fingerprints, performances)
+# 
+# #. The fingerprints from test-set patients can then be correlated with the calculated R-Map:
+# 
+#    .. code-block:: python
+# 
+#       nm_RMAP.get_corr_numba(fp, fp_test)
+# 
+# #. The channel with highest correlation can then be selected for decoding without individual training. :class:`~nm_RMAP.py` contain already leave one channel and leave one patient out cross validation functions:
+# 
+#    .. code-block:: python
+# 
+#       nm_RMAP.leave_one_sub_out_cv(l_fps_names, l_fps_dat, l_per, sub_list)
+# 
+# #. The obtained R-Map correlations can then be estimated statistically and plotted against true correlates:
+# 
+#    .. code-block:: python
+# 
+#       nm_RMAP.plot_performance_prediction_correlation(per_left_out, per_predict, out_path_save)
+# 
+#

examples/plot_6_real_time_demo.py

@@ -0,0 +1,121 @@
+"""
+Real-time feature estimation
+============================
+
+"""
+
+# %%
+# Implementation of individual nm_streams
+# ---------------------------------------
+#
+# *py_neuromodulation* was optimized for computation of real-time data streams.
+# There are however center -and lab specific hardware acquisition systems. Therefore, each experiment requires modules to interact with hardware platforms
+# which periodically acquire data.
+#
+# Given the raw data, data can be analyzed using *py_neuromodulation*. Preprocessing methods, such as re-referencing and normalization,
+# feature computation and decoding can be performed then in real-time.
+#
+# For online as well as as offline analysis, the :class:`~nm_stream_abc` class needs to be instantiated.
+# Here the `nm_settings` and `nm_channels` are required to be defined.
+# Previously for the offline analysis, an offline :class:`~nm_generator` object was defined that periodically yielded data.
+# For online data, the :meth:`~nm_stream_abc.run` function therefore needs to be overwritten, which first acquires data and then calls
+# the :meth:`~nm_run_analysis.process` function.
+#
+# The following illustrates in pseudo-code how such a stream could be initialized:
+#
+# .. code-block:: python
+#
+#    from py_neuromodulation import nm_stream_abc
+#
+#    class MyStream(nm_stream_abc):
+#    def __init__(self, settings, channels):
+#        super().__init__(settings, channels)
+#
+#    def run(self):
+#       features_ = []
+#        while True:
+#           data = self.acquire_data()
+#           features_.append(self.run_analysis.process(data))
+#           # potentially use machine learning model for decoding
+#
+#
+# Computation time examples
+# -------------------------
+#
+# The following example calculates for six channels, CAR re-referencing, z-score normalization and FFT features results the following computation time:
+
+# %%
+import py_neuromodulation as nm
+import numpy as np
+import timeit
+
+
+def get_fast_compute_settings():
+    settings = nm.nm_settings.get_default_settings()
+    settings = nm.nm_settings.reset_settings(settings)
+    settings = nm.nm_settings.set_settings_fast_compute(settings)
+    settings["preprocessing"] = ["re_referencing", "notch_filter"]
+    settings["features"]["fft"] = True
+    settings["postprocessing"]["feature_normalization"] = True
+    return settings
+
+
+data = np.random.random([1, 1000])
+
+print("FFT Features, CAR re-referencing, z-score normalization")
+print()
+print("Computation time for single ECoG channel: ")
+stream = nm.Stream(
+    sfreq=1000,
+    data=data,
+    sampling_rate_features_hz=10,
+    verbose=False,
+    settings=get_fast_compute_settings(),
+)
+print(
+    f"{np.round(timeit.timeit(lambda: stream.run_analysis.process(data), number=100)/100, 3)} s"
+)
+
+print("Computation time for 6 ECoG channels: ")
+data = np.random.random([6, 1000])
+stream = nm.Stream(
+    sfreq=500,
+    data=data,
+    sampling_rate_features_hz=10,
+    verbose=False,
+    settings=get_fast_compute_settings(),
+)
+print(
+    f"{np.round(timeit.timeit(lambda: stream.run_analysis.process(data), number=100)/100, 3)} s"
+)
+
+print(
+    "\nFFT Features & Temporal Waveform Shape & Hjorth & Bursts, CAR re-referencing, z-score normalization"
+)
+print("Computation time for single ECoG channel: ")
+data = np.random.random([1, 1000])
+stream = nm.Stream(
+    sfreq=1000, data=data, sampling_rate_features_hz=10, verbose=False
+)
+print(
+    f"{np.round(timeit.timeit(lambda: stream.run_analysis.process(data), number=10)/10, 3)} s"
+)
+
+
+# %%
+# Those results show that the computation time for a typical pipeline (FFT, re-referencing, notch-filtering, feature normalization)
+# is well below 10 ms, which is fast enough for real-time analysis with feature sampling rates below 100 Hz.
+# Computation of more complex features could still result in feature sampling rates of more than 30 Hz.
+#
+# Real-time movement decoding using the TMSi-SAGA amplifier
+# ---------------------------------------------------------
+#
+# In the following example, we will show how we setup a real-time movement decoding experiment using the TMSi-SAGA amplifier.
+# First, we relied on different software modules for data streaming and visualization.
+# `LabStreamingLayer <https://labstreaminglayer.org>`_ allows for real-time data streaming and synchronization across multiple devices.
+# We used `timeflux <https://timeflux.io>`_ for real-time data visualization of features, decoded output.
+# For raw data visualization we used `Brain Streaming Layer <https://fcbg-hnp-meeg.github.io/bsl/dev/index.html>`_.
+#
+# The code for real-time movement decoding is added in the GitHub branch `realtime_decoding <https://github.com/neuromodulation/py_neuromodulation/tree/realtime_decoding>`_.
+# Here we relied on the `TMSI SAGA Python interface <https://gitlab.com/tmsi/tmsi-python-interface>`_.
+#

packages/realtime_decoding/build/lib/realtime_decoding/__init__.py

@@ -0,0 +1,4 @@
+from .decoder import Decoder
+from .features import Features
+from .helpers import clear_queue
+from .run_decoding import run