.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/plot_0_first_demo.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_plot_0_first_demo.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_plot_0_first_demo.py:


First Demo
==========

This Demo will showcase the feature estimation and
exemplar analysis using simulated data.

.. GENERATED FROM PYTHON SOURCE LINES 8-16

.. code-block:: Python


    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








.. GENERATED FROM PYTHON SOURCE LINES 17-20

Data Simulation
---------------
We will now generate some exemplar data with 10 second duration for 6 channels with a sample rate of 1 kHz.

.. GENERATED FROM PYTHON SOURCE LINES 20-47

.. code-block:: Python



    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")




.. image-sg:: /auto_examples/images/sphx_glr_plot_0_first_demo_001.png
   :alt: Example random walk data
   :srcset: /auto_examples/images/sphx_glr_plot_0_first_demo_001.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    Text(0.5, 1.0, 'Example random walk data')



.. GENERATED FROM PYTHON SOURCE LINES 48-95

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:

.. GENERATED FROM PYTHON SOURCE LINES 95-102

.. code-block:: Python


    nm_channels = nm_define_nmchannels.get_default_channels_from_data(
        data, car_rereferencing=True
    )

    nm_channels






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>name</th>
          <th>rereference</th>
          <th>used</th>
          <th>target</th>
          <th>type</th>
          <th>status</th>
          <th>new_name</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>ch0</td>
          <td>average</td>
          <td>1</td>
          <td>0</td>
          <td>ecog</td>
          <td>good</td>
          <td>ch0-avgref</td>
        </tr>
        <tr>
          <th>1</th>
          <td>ch1</td>
          <td>average</td>
          <td>1</td>
          <td>0</td>
          <td>ecog</td>
          <td>good</td>
          <td>ch1-avgref</td>
        </tr>
        <tr>
          <th>2</th>
          <td>ch2</td>
          <td>average</td>
          <td>1</td>
          <td>0</td>
          <td>ecog</td>
          <td>good</td>
          <td>ch2-avgref</td>
        </tr>
        <tr>
          <th>3</th>
          <td>ch3</td>
          <td>average</td>
          <td>1</td>
          <td>0</td>
          <td>ecog</td>
          <td>good</td>
          <td>ch3-avgref</td>
        </tr>
        <tr>
          <th>4</th>
          <td>ch4</td>
          <td>average</td>
          <td>1</td>
          <td>0</td>
          <td>ecog</td>
          <td>good</td>
          <td>ch4-avgref</td>
        </tr>
        <tr>
          <th>5</th>
          <td>ch5</td>
          <td>average</td>
          <td>1</td>
          <td>0</td>
          <td>ecog</td>
          <td>good</td>
          <td>ch5-avgref</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 103-109

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:

.. GENERATED FROM PYTHON SOURCE LINES 109-114

.. code-block:: Python


    settings = nm.nm_settings.get_default_settings()
    settings = nm.nm_settings.reset_settings(settings)









.. GENERATED FROM PYTHON SOURCE LINES 115-133

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.

.. GENERATED FROM PYTHON SOURCE LINES 133-138

.. code-block:: Python


    settings["features"]["fft"] = True
    settings["features"]["bursts"] = True
    settings["features"]["sharpwave_analysis"] = True








.. GENERATED FROM PYTHON SOURCE LINES 139-140

We are now ready to go to instantiate the *Stream* and call the *run* method for feature estimation:

.. GENERATED FROM PYTHON SOURCE LINES 140-151

.. code-block:: Python


    stream = nm.Stream(
        settings=settings,
        nm_channels=nm_channels,
        verbose=True,
        sfreq=sfreq,
        line_noise=50,
    )

    features = stream.run(data)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Last batch took: 0.04 seconds
    1.0 seconds of data processed
    Last batch took: 0.04 seconds
    1.1 seconds of data processed
    Last batch took: 0.04 seconds
    1.2 seconds of data processed
    Last batch took: 0.03 seconds
    1.3 seconds of data processed
    Last batch took: 0.04 seconds
    1.4 seconds of data processed
    Last batch took: 0.04 seconds
    1.5 seconds of data processed
    Last batch took: 0.04 seconds
    1.6 seconds of data processed
    Last batch took: 0.04 seconds
    1.7 seconds of data processed
    Last batch took: 0.04 seconds
    1.8 seconds of data processed
    Last batch took: 0.04 seconds
    1.9 seconds of data processed
    Last batch took: 0.04 seconds
    2.0 seconds of data processed
    Last batch took: 0.04 seconds
    2.1 seconds of data processed
    Last batch took: 0.04 seconds
    2.2 seconds of data processed
    Last batch took: 0.04 seconds
    2.3 seconds of data processed
    Last batch took: 0.04 seconds
    2.4 seconds of data processed
    Last batch took: 0.04 seconds
    2.5 seconds of data processed
    Last batch took: 0.04 seconds
    2.6 seconds of data processed
    Last batch took: 0.04 seconds
    2.7 seconds of data processed
    Last batch took: 0.04 seconds
    2.8 seconds of data processed
    Last batch took: 0.04 seconds
    2.9 seconds of data processed
    Last batch took: 0.04 seconds
    3.0 seconds of data processed
    Last batch took: 0.04 seconds
    3.1 seconds of data processed
    Last batch took: 0.04 seconds
    3.2 seconds of data processed
    Last batch took: 0.04 seconds
    3.3 seconds of data processed
    Last batch took: 0.04 seconds
    3.4 seconds of data processed
    Last batch took: 0.04 seconds
    3.5 seconds of data processed
    Last batch took: 0.04 seconds
    3.6 seconds of data processed
    Last batch took: 0.04 seconds
    3.7 seconds of data processed
    Last batch took: 0.04 seconds
    3.8 seconds of data processed
    Last batch took: 0.04 seconds
    3.9 seconds of data processed
    Last batch took: 0.04 seconds
    4.0 seconds of data processed
    Last batch took: 0.04 seconds
    4.1 seconds of data processed
    Last batch took: 0.04 seconds
    4.2 seconds of data processed
    Last batch took: 0.04 seconds
    4.3 seconds of data processed
    Last batch took: 0.04 seconds
    4.4 seconds of data processed
    Last batch took: 0.04 seconds
    4.5 seconds of data processed
    Last batch took: 0.04 seconds
    4.6 seconds of data processed
    Last batch took: 0.04 seconds
    4.7 seconds of data processed
    Last batch took: 0.04 seconds
    4.8 seconds of data processed
    Last batch took: 0.04 seconds
    4.9 seconds of data processed
    Last batch took: 0.04 seconds
    5.0 seconds of data processed
    Last batch took: 0.04 seconds
    5.1 seconds of data processed
    Last batch took: 0.04 seconds
    5.2 seconds of data processed
    Last batch took: 0.04 seconds
    5.3 seconds of data processed
    Last batch took: 0.04 seconds
    5.4 seconds of data processed
    Last batch took: 0.04 seconds
    5.5 seconds of data processed
    Last batch took: 0.04 seconds
    5.6 seconds of data processed
    Last batch took: 0.04 seconds
    5.7 seconds of data processed
    Last batch took: 0.04 seconds
    5.8 seconds of data processed
    Last batch took: 0.04 seconds
    5.9 seconds of data processed
    Last batch took: 0.04 seconds
    6.0 seconds of data processed
    Last batch took: 0.04 seconds
    6.1 seconds of data processed
    Last batch took: 0.04 seconds
    6.2 seconds of data processed
    Last batch took: 0.04 seconds
    6.3 seconds of data processed
    Last batch took: 0.04 seconds
    6.4 seconds of data processed
    Last batch took: 0.04 seconds
    6.5 seconds of data processed
    Last batch took: 0.04 seconds
    6.6 seconds of data processed
    Last batch took: 0.04 seconds
    6.7 seconds of data processed
    Last batch took: 0.04 seconds
    6.8 seconds of data processed
    Last batch took: 0.04 seconds
    6.9 seconds of data processed
    Last batch took: 0.04 seconds
    7.0 seconds of data processed
    Last batch took: 0.04 seconds
    7.1 seconds of data processed
    Last batch took: 0.04 seconds
    7.2 seconds of data processed
    Last batch took: 0.04 seconds
    7.3 seconds of data processed
    Last batch took: 0.05 seconds
    7.4 seconds of data processed
    Last batch took: 0.05 seconds
    7.5 seconds of data processed
    Last batch took: 0.05 seconds
    7.6 seconds of data processed
    Last batch took: 0.05 seconds
    7.7 seconds of data processed
    Last batch took: 0.04 seconds
    7.8 seconds of data processed
    Last batch took: 0.04 seconds
    7.9 seconds of data processed
    Last batch took: 0.04 seconds
    8.0 seconds of data processed
    Last batch took: 0.04 seconds
    8.1 seconds of data processed
    Last batch took: 0.04 seconds
    8.2 seconds of data processed
    Last batch took: 0.04 seconds
    8.3 seconds of data processed
    Last batch took: 0.04 seconds
    8.4 seconds of data processed
    Last batch took: 0.04 seconds
    8.5 seconds of data processed
    Last batch took: 0.04 seconds
    8.6 seconds of data processed
    Last batch took: 0.04 seconds
    8.7 seconds of data processed
    Last batch took: 0.04 seconds
    8.8 seconds of data processed
    Last batch took: 0.04 seconds
    8.9 seconds of data processed
    Last batch took: 0.04 seconds
    9.0 seconds of data processed
    Last batch took: 0.04 seconds
    9.1 seconds of data processed
    Last batch took: 0.04 seconds
    9.2 seconds of data processed
    Last batch took: 0.04 seconds
    9.3 seconds of data processed
    Last batch took: 0.04 seconds
    9.4 seconds of data processed
    Last batch took: 0.04 seconds
    9.5 seconds of data processed
    Last batch took: 0.04 seconds
    9.6 seconds of data processed
    Last batch took: 0.04 seconds
    9.7 seconds of data processed
    Last batch took: 0.04 seconds
    9.8 seconds of data processed
    Last batch took: 0.04 seconds
    9.9 seconds of data processed
    Last batch took: 0.04 seconds
    10.0 seconds of data processed
    _SIDECAR.json saved to /home/docs/checkouts/readthedocs.org/user_builds/py-neuromodulation/checkouts/latest/examples/sub/sub_SIDECAR.json
    FEATURES.csv saved to /home/docs/checkouts/readthedocs.org/user_builds/py-neuromodulation/checkouts/latest/examples/sub/sub_FEATURES.csv
    settings.json saved to /home/docs/checkouts/readthedocs.org/user_builds/py-neuromodulation/checkouts/latest/examples/sub/sub_SETTINGS.json
    nm_channels.csv saved to /home/docs/checkouts/readthedocs.org/user_builds/py-neuromodulation/checkouts/latest/examples/sub/sub_nm_channels.csv




.. GENERATED FROM PYTHON SOURCE LINES 152-157

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:

.. GENERATED FROM PYTHON SOURCE LINES 157-162

.. code-block:: Python


    analyzer = nm_analysis.Feature_Reader(
        feature_dir=stream.PATH_OUT, feature_file=stream.PATH_OUT_folder_name
    )








.. GENERATED FROM PYTHON SOURCE LINES 163-164

Let's have a look at the resulting "feature_arr" DataFrame:

.. GENERATED FROM PYTHON SOURCE LINES 164-167

.. code-block:: Python


    analyzer.feature_arr.iloc[:10, :7]






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>ch0-avgref_fft_theta_mean</th>
          <th>ch0-avgref_fft_alpha_mean</th>
          <th>ch0-avgref_fft_low beta_mean</th>
          <th>ch0-avgref_fft_high beta_mean</th>
          <th>ch0-avgref_fft_low gamma_mean</th>
          <th>ch0-avgref_fft_high gamma_mean</th>
          <th>ch0-avgref_fft_HFA_mean</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>2.849872</td>
          <td>2.514739</td>
          <td>2.285799</td>
          <td>2.058928</td>
          <td>1.592914</td>
          <td>1.339337</td>
          <td>1.100760</td>
        </tr>
        <tr>
          <th>1</th>
          <td>2.830329</td>
          <td>2.546446</td>
          <td>2.369743</td>
          <td>2.088122</td>
          <td>1.596852</td>
          <td>1.354243</td>
          <td>1.081805</td>
        </tr>
        <tr>
          <th>2</th>
          <td>2.757690</td>
          <td>2.537966</td>
          <td>2.416848</td>
          <td>2.018576</td>
          <td>1.599164</td>
          <td>1.348615</td>
          <td>1.075573</td>
        </tr>
        <tr>
          <th>3</th>
          <td>2.812961</td>
          <td>2.548513</td>
          <td>2.362202</td>
          <td>2.026213</td>
          <td>1.585782</td>
          <td>1.389733</td>
          <td>1.091364</td>
        </tr>
        <tr>
          <th>4</th>
          <td>2.743448</td>
          <td>2.735562</td>
          <td>2.326806</td>
          <td>2.042691</td>
          <td>1.776755</td>
          <td>1.455006</td>
          <td>1.147841</td>
        </tr>
        <tr>
          <th>5</th>
          <td>2.607056</td>
          <td>2.591237</td>
          <td>2.362328</td>
          <td>2.019262</td>
          <td>1.638703</td>
          <td>1.379498</td>
          <td>1.063767</td>
        </tr>
        <tr>
          <th>6</th>
          <td>2.716326</td>
          <td>2.546269</td>
          <td>2.351909</td>
          <td>2.181473</td>
          <td>1.690273</td>
          <td>1.406453</td>
          <td>1.071060</td>
        </tr>
        <tr>
          <th>7</th>
          <td>2.636727</td>
          <td>2.501564</td>
          <td>2.287193</td>
          <td>2.043828</td>
          <td>1.640759</td>
          <td>1.385958</td>
          <td>1.074094</td>
        </tr>
        <tr>
          <th>8</th>
          <td>2.573047</td>
          <td>2.467366</td>
          <td>2.179603</td>
          <td>2.074842</td>
          <td>1.667849</td>
          <td>1.384829</td>
          <td>1.078987</td>
        </tr>
        <tr>
          <th>9</th>
          <td>2.835159</td>
          <td>2.457356</td>
          <td>2.207807</td>
          <td>2.158214</td>
          <td>1.731634</td>
          <td>1.417998</td>
          <td>1.139323</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 168-177

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.



.. GENERATED FROM PYTHON SOURCE LINES 177-180

.. code-block:: Python


    analyzer.plot_all_features(ch_used="ch1")




.. image-sg:: /auto_examples/images/sphx_glr_plot_0_first_demo_002.png
   :alt: Feature Plot sub
   :srcset: /auto_examples/images/sphx_glr_plot_0_first_demo_002.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 181-187

.. code-block:: Python

    nm_plots.plot_corr_matrix(
        figsize=(25, 25),
        show_plot=True,
        feature=analyzer.feature_arr,
    )




.. image-sg:: /auto_examples/images/sphx_glr_plot_0_first_demo_003.png
   :alt: Correlation matrix
   :srcset: /auto_examples/images/sphx_glr_plot_0_first_demo_003.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <Axes: title={'center': 'Correlation matrix'}>



.. GENERATED FROM PYTHON SOURCE LINES 188-190

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.


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 8.199 seconds)


.. _sphx_glr_download_auto_examples_plot_0_first_demo.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_0_first_demo.ipynb <plot_0_first_demo.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_0_first_demo.py <plot_0_first_demo.py>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_