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

docs/source/_build/html/_downloads/b8b06cacc17969d3725a0b6f1d7741c5/plot_example_sharpwave_analysis.py

@@ -0,0 +1,219 @@
+"""
+Analyzing sharpwave 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()

docs/source/_build/html/_downloads/c2db0bf2b334d541b00662b991682256/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>`_.
+#

docs/source/_build/html/_downloads/c31a86c0b68cb4167d968091ace8080d/plot_example_add_feature.py

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

docs/source/_build/html/_downloads/ce3914826f782cbd1ea8fd024eaf0ac3/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)
+# 
+#

docs/source/_build/html/_downloads/da36848a41e6a3235d91fb7cfb6d59b4/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.