.. 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-14

.. code-block:: Python


    import numpy as np
    from matplotlib import pyplot as plt

    import py_neuromodulation as nm








.. GENERATED FROM PYTHON SOURCE LINES 15-18

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 18-45

.. 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 46-93

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 *channels.tsv* and the *default_settings.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 93-98

.. code-block:: Python


    nm_channels = nm.utils.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 99-105

Using this function default channel names and a common average re-referencing scheme is specified.
Alternatively the *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 105-109

.. code-block:: Python


    settings = nm.NMSettings.get_fast_compute()









.. GENERATED FROM PYTHON SOURCE LINES 110-128

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 128-134

.. code-block:: Python


    settings.features.fooof = True
    settings.features.fft = True
    settings.features.bursts = True
    settings.features.sharpwave_analysis = True








.. GENERATED FROM PYTHON SOURCE LINES 135-136

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

.. GENERATED FROM PYTHON SOURCE LINES 136-147

.. code-block:: Python


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

    features = stream.run(data, save_csv=True)





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

 .. code-block:: none

    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)
    /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/fooof/core/funcs.py:62: RuntimeWarning: invalid value encountered in log10
      ys = offset - np.log10(knee + xs**exp)




.. GENERATED FROM PYTHON SOURCE LINES 148-153

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 153-158

.. code-block:: Python


    analyzer = nm.FeatureReader(
        feature_dir=stream.out_dir_root, feature_file=stream.experiment_name
    )








.. GENERATED FROM PYTHON SOURCE LINES 159-160

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

.. GENERATED FROM PYTHON SOURCE LINES 160-163

.. 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>ch1_avgref_fft_theta_mean</th>
          <th>ch2_avgref_fft_theta_mean</th>
          <th>ch3_avgref_fft_theta_mean</th>
          <th>ch4_avgref_fft_theta_mean</th>
          <th>ch5_avgref_fft_theta_mean</th>
          <th>ch0_avgref_fft_alpha_mean</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>3.173335</td>
          <td>2.599706</td>
          <td>2.717248</td>
          <td>3.058939</td>
          <td>2.982307</td>
          <td>2.943506</td>
          <td>2.837150</td>
        </tr>
        <tr>
          <th>1</th>
          <td>-1.000000</td>
          <td>1.000000</td>
          <td>1.000000</td>
          <td>-1.000000</td>
          <td>-1.000000</td>
          <td>-1.000000</td>
          <td>1.000000</td>
        </tr>
        <tr>
          <th>2</th>
          <td>-1.346376</td>
          <td>-0.503323</td>
          <td>-1.382572</td>
          <td>-1.033234</td>
          <td>0.067698</td>
          <td>0.884309</td>
          <td>-1.404595</td>
        </tr>
        <tr>
          <th>3</th>
          <td>-0.826819</td>
          <td>0.393170</td>
          <td>-0.938964</td>
          <td>1.091164</td>
          <td>-0.872061</td>
          <td>0.277494</td>
          <td>-1.452470</td>
        </tr>
        <tr>
          <th>4</th>
          <td>-1.460201</td>
          <td>1.524250</td>
          <td>-0.405598</td>
          <td>0.348553</td>
          <td>1.648792</td>
          <td>-1.002571</td>
          <td>-1.272433</td>
        </tr>
        <tr>
          <th>5</th>
          <td>-0.455732</td>
          <td>0.924325</td>
          <td>-1.610885</td>
          <td>1.489735</td>
          <td>1.546969</td>
          <td>0.614548</td>
          <td>-0.491364</td>
        </tr>
        <tr>
          <th>6</th>
          <td>0.862754</td>
          <td>0.031796</td>
          <td>1.833354</td>
          <td>0.553278</td>
          <td>0.175344</td>
          <td>0.366158</td>
          <td>-1.083103</td>
        </tr>
        <tr>
          <th>7</th>
          <td>0.979889</td>
          <td>-0.922244</td>
          <td>-1.538273</td>
          <td>-1.483128</td>
          <td>1.360713</td>
          <td>0.343133</td>
          <td>1.145800</td>
        </tr>
        <tr>
          <th>8</th>
          <td>0.897504</td>
          <td>-0.130931</td>
          <td>-0.693593</td>
          <td>-0.919179</td>
          <td>1.166493</td>
          <td>-0.721426</td>
          <td>1.590803</td>
        </tr>
        <tr>
          <th>9</th>
          <td>1.243882</td>
          <td>0.574644</td>
          <td>0.040646</td>
          <td>-0.870387</td>
          <td>-0.247241</td>
          <td>-0.098972</td>
          <td>1.599101</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 164-173

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 173-176

.. 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 177-183

.. code-block:: Python

    nm.analysis.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 184-186

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 5.492 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>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_0_first_demo.zip <plot_0_first_demo.zip>`


.. only:: html

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

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