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

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

.. _sphx_glr_auto_examples_descriptors_plot_01_basic_descriptors.py:


====================================
Basic Feature Descriptors Extraction
====================================

This example demonstrates how to use the ``DescriptorPipeline`` to extract
EEG features (bands, parametric, complexity) from a standard NumPy array.

.. GENERATED FROM PYTHON SOURCE LINES 11-13

Imports
-------

.. GENERATED FROM PYTHON SOURCE LINES 13-20

.. code-block:: Python


    from __future__ import annotations

    import numpy as np

    from coco_pipe.descriptors import DescriptorPipeline








.. GENERATED FROM PYTHON SOURCE LINES 21-25

1. Simulate EEG Data
--------------------
We will create a dummy dataset with 12 observations, 3 channels, and 256 timepoints.
We'll also inject some sine waves to simulate alpha (10Hz) and theta (6Hz) activity.

.. GENERATED FROM PYTHON SOURCE LINES 25-37

.. code-block:: Python


    rng = np.random.default_rng(42)
    X = rng.normal(size=(12, 3, 256))
    t = np.linspace(0, 1, 256, endpoint=False)

    # Inject 10Hz signal into the first channel
    X[:, 0, :] += np.sin(2 * np.pi * 10 * t)
    # Inject 6Hz signal into the second channel
    X[:, 1, :] += np.sin(2 * np.pi * 6 * t)

    ids = np.asarray([f"obs-{idx:02d}" for idx in range(12)])








.. GENERATED FROM PYTHON SOURCE LINES 38-43

2. Configure the Pipeline
-------------------------
The descriptor pipeline is configured via a simple dictionary. We can enable
specific families of descriptors (e.g., spectral bands, aperiodic components,
and signal complexity measures).

.. GENERATED FROM PYTHON SOURCE LINES 43-61

.. code-block:: Python


    config = {
        "families": {
            "bands": {
                "enabled": True,
                "outputs": ["absolute_power", "corrected_absolute_power"],
            },
            "parametric": {
                "enabled": True,
                "outputs": ["aperiodic"],
            },
            "complexity": {
                "enabled": True,
                "measures": ["sample_entropy", "hjorth_mobility"],
            },
        },
    }








.. GENERATED FROM PYTHON SOURCE LINES 62-65

3. Extract Features
-------------------
We pass our data, configs, sampling frequency, and channel names to the pipeline.

.. GENERATED FROM PYTHON SOURCE LINES 65-76

.. code-block:: Python


    channels = ["Fz", "Cz", "Pz"]
    pipe = DescriptorPipeline(config)

    result = pipe.extract(
        X=X,
        ids=ids,
        sfreq=256.0,
        channel_names=channels,
    )








.. GENERATED FROM PYTHON SOURCE LINES 77-82

4. Pooling and Results
----------------------
After extraction, we can pool the channel features together (e.g., averaging
all frontal or parietal channels). Here, we create an "all" region pool.
The pipeline natively outputs a ``DataContainer``, which holds all of our labels.

.. GENERATED FROM PYTHON SOURCE LINES 82-88

.. code-block:: Python


    result = pipe.pool_channels(result, {"all": channels})

    print("Descriptor matrix shape:", result.X.shape)
    print("First five names:\n", result.coords["feature"][:5])





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

 .. code-block:: none

    Descriptor matrix shape: (12, 14)
    First five names:
     ['band_abs_delta_chgrp-all' 'band_abs_theta_chgrp-all'
     'band_abs_alpha_chgrp-all' 'band_abs_beta_chgrp-all'
     'band_abs_gamma_chgrp-all']




.. GENERATED FROM PYTHON SOURCE LINES 89-94

5. Data Aggregation
-------------------
Since the output is already a ``DataContainer``, it is perfectly formatted for
downstream analysis without any extra wrapping. We can easily aggregate the
descriptors by subject or condition.

.. GENERATED FROM PYTHON SOURCE LINES 94-104

.. code-block:: Python


    # Let's simulate aggregating the descriptors by subjects (assuming 6 epochs per subject)
    grouped = result.aggregate(
        by=["sub-01"] * 6 + ["sub-02"] * 6,
        stats=["mean", "std"],
    )

    print(f"Grouped descriptor shape: {grouped.X.shape}")
    print(f"Grouped dims: {grouped.dims}")
    print(f"Grouped stats: {grouped.coords['stat'].tolist()}")




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

 .. code-block:: none

    Grouped descriptor shape: (2, 2, 14)
    Grouped dims: ('obs', 'stat', 'feature')
    Grouped stats: ['mean', 'std']





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

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


.. _sphx_glr_download_auto_examples_descriptors_plot_01_basic_descriptors.py:

.. only:: html

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

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

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

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

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

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

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


.. only:: html

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

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