.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/plot_2_example_add_feature.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_2_example_add_feature.py>`
        to download the full example code.

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

.. _sphx_glr_auto_examples_plot_2_example_add_feature.py:


===================
Adding New Features
===================

.. GENERATED FROM PYTHON SOURCE LINES 8-12

.. code-block:: Python

    import py_neuromodulation as nm
    import numpy as np
    from typing import Iterable








.. GENERATED FROM PYTHON SOURCE LINES 13-16

In this example we will demonstrate how a new feature can be added to the existing feature pipeline.
This can be done by creating a new feature class that implements the protocol class :class:`~features.NMFeature`
and registering it with the :func:`~features.AddCustomFeature` function.

.. GENERATED FROM PYTHON SOURCE LINES 19-24

Let's create a new feature class called `ChannelMean` that calculates the mean signal for each channel.
We can optinally make it inherit from :class:`~features.NMFeature` but as long as it has an adequate constructor
and a `calc_feature` method with the appropriate signatures it will work.
The :func:`__init__` method should take the settings, channel names and sampling frequency as arguments.
The `calc_feature` method should take the data and a dictionary of features as arguments and return the updated dictionary.

.. GENERATED FROM PYTHON SOURCE LINES 24-59

.. code-block:: Python

    class ChannelMean:
        def __init__(
            self, settings: nm.NMSettings, ch_names: Iterable[str], sfreq: float
        ) -> None:
            # If required for feature calculation, store the settings,
            # channel names and sampling frequency (optional)
            self.settings = settings
            self.ch_names = ch_names
            self.sfreq = sfreq

            # Here you can add any additional initialization code
            # For example, you could store parameters for the functions\
            # used in the calc_feature method
        
            self.feature_name = "channel_mean"

        def calc_feature(self, data: np.ndarray) -> dict:
            # First, create an empty dictionary to store the calculated features
            feature_results = {}

            # Here you can add any feature calculation code
            # This example simply calculates the mean signal for each channel
            ch_means = np.mean(data, axis=1)

            # Store the calculated features in the feature_results dictionary
            # Be careful to use a unique keyfor each channel and metric you compute
            for ch_idx, ch in enumerate(self.ch_names):
                feature_results[f"{self.feature_name}_{ch}"] = ch_means[ch_idx]

            # Return the updated feature_results dictionary to the stream
            return feature_results


    nm.add_custom_feature("channel_mean", ChannelMean)








.. GENERATED FROM PYTHON SOURCE LINES 60-61

Now we can instantiate settings and observe that the new feature has been added to the list of features

.. GENERATED FROM PYTHON SOURCE LINES 61-65

.. code-block:: Python

    settings = nm.NMSettings() # Get default settings

    settings.features





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

 .. code-block:: none


    {'bandpass_filter': False,
     'bispectrum': False,
     'bursts': True,
     'channel_mean': True,
     'coherence': False,
     'fft': True,
     'fooof': False,
     'linelength': True,
     'mne_connectivity': False,
     'nolds': False,
     'raw_hjorth': True,
     'return_raw': True,
     'sharpwave_analysis': True,
     'stft': False,
     'welch': True}



.. GENERATED FROM PYTHON SOURCE LINES 66-67

Let's create some artificial data to demonstrate the feature calculation.

.. GENERATED FROM PYTHON SOURCE LINES 67-85

.. code-block:: Python

    N_CHANNELS = 5
    N_SAMPLES = 10000 # 10 seconds of random data at 1000 Hz sampling frequency

    data = np.random.random([N_CHANNELS, N_SAMPLES]) 
    stream = nm.Stream(
        sfreq=1000,
        data=data,
        settings = settings,
        sampling_rate_features_hz=10,
        verbose=False,
    )

    feature_df = stream.run()
    columns = [col for col in feature_df.columns if "channel_mean" in col]

    feature_df[columns]







.. 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>channel_mean_ch0_avgref</th>
          <th>channel_mean_ch1_avgref</th>
          <th>channel_mean_ch2_avgref</th>
          <th>channel_mean_ch3_avgref</th>
          <th>channel_mean_ch4_avgref</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>-0.003151</td>
          <td>0.003845</td>
          <td>0.009986</td>
          <td>-0.008624</td>
          <td>-0.002056</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>
        </tr>
        <tr>
          <th>2</th>
          <td>-1.183055</td>
          <td>0.067441</td>
          <td>0.127422</td>
          <td>-1.388348</td>
          <td>1.386479</td>
        </tr>
        <tr>
          <th>3</th>
          <td>0.971766</td>
          <td>0.420605</td>
          <td>-1.230613</td>
          <td>-0.665998</td>
          <td>0.684274</td>
        </tr>
        <tr>
          <th>4</th>
          <td>1.602812</td>
          <td>-1.861613</td>
          <td>1.262754</td>
          <td>-1.847107</td>
          <td>1.170723</td>
        </tr>
        <tr>
          <th>...</th>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
        </tr>
        <tr>
          <th>86</th>
          <td>-0.223974</td>
          <td>0.650751</td>
          <td>0.052932</td>
          <td>-0.559971</td>
          <td>0.342396</td>
        </tr>
        <tr>
          <th>87</th>
          <td>-0.469088</td>
          <td>0.560148</td>
          <td>-0.411298</td>
          <td>0.418785</td>
          <td>0.369015</td>
        </tr>
        <tr>
          <th>88</th>
          <td>-0.284326</td>
          <td>0.633788</td>
          <td>-0.878672</td>
          <td>1.154053</td>
          <td>-0.013363</td>
        </tr>
        <tr>
          <th>89</th>
          <td>-1.228100</td>
          <td>0.222809</td>
          <td>0.037242</td>
          <td>1.437820</td>
          <td>-0.544140</td>
        </tr>
        <tr>
          <th>90</th>
          <td>-0.826018</td>
          <td>-0.044380</td>
          <td>0.340241</td>
          <td>0.805401</td>
          <td>-0.586588</td>
        </tr>
      </tbody>
    </table>
    <p>91 rows × 5 columns</p>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 86-87

Remove feature so that it does not interfere with other examples

.. GENERATED FROM PYTHON SOURCE LINES 87-91

.. code-block:: Python

    nm.remove_custom_feature("channel_mean") 











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

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


.. _sphx_glr_download_auto_examples_plot_2_example_add_feature.py:

.. only:: html

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

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

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

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

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

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

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


.. only:: html

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

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