coco_pipe.descriptors.core
==========================

.. py:module:: coco_pipe.descriptors.core

.. autoapi-nested-parse::

   Descriptor extraction planner and execution pipeline.

   This module owns the config-bound runtime orchestration for descriptor
   extraction. It does not implement family-specific descriptor math; instead it:

   - validates the explicit runtime inputs accepted by the module
   - instantiates enabled descriptor families from typed config
   - plans shared PSD computation for compatible PSD consumers
   - executes one observation batch at a time with controlled parallelism
   - merges aligned family outputs into one flat descriptor matrix

   Author: Hamza Abdelhedi (hamza.abdelhedi@umontreal.ca)



Classes
-------

.. autoapisummary::

   coco_pipe.descriptors.core.DescriptorPipeline


Module Contents
---------------

.. py:class:: DescriptorPipeline(config)

   Run config-driven descriptor extraction on explicit arrays.

   :param config: Typed descriptors configuration or a mapping accepted by
                  :class:`DescriptorConfig`.
   :type config: DescriptorConfig or Mapping[str, Any]

   :ivar config: Parsed descriptors configuration.
   :vartype config: DescriptorConfig
   :ivar extractors: Enabled family extractors in deterministic family order.
   :vartype extractors: list of BaseDescriptorExtractor
   :ivar signal_extractors: Enabled non-PSD extractors that consume raw signal batches directly.
   :vartype signal_extractors: list of BaseDescriptorExtractor
   :ivar psd_groups: Planned PSD reuse groups derived once from the enabled extractors.
   :vartype psd_groups: list of _PSDGroup
   :ivar family_order: Deterministic family order used when merging batch-local outputs.

   :vartype family_order: list of str

   .. rubric:: Notes

   The pipeline is config-bound but runtime-stateless. Construction performs
   config parsing, corrected-band compatibility checks, and planner setup once.
   Each call to :meth:`extract` then validates the explicit runtime inputs,
   executes the planned families, and returns one flat descriptor matrix plus
   any collected failures.


   .. py:attribute:: config


   .. py:attribute:: extractors
      :type:  list[coco_pipe.descriptors.extractors.base.BaseDescriptorExtractor]
      :value: []



   .. py:attribute:: signal_extractors


   .. py:attribute:: psd_groups
      :value: []



   .. py:attribute:: family_order


   .. py:method:: extract(X, ids = None, sfreq = None, channel_names = None)

      Extract descriptors from explicit NumPy inputs.

      :param X: Signal array with shape ``(n_obs, n_channels, n_times)``.
      :type X: np.ndarray
      :param ids: Observation identifiers aligned with ``X``.
      :type ids: sequence or np.ndarray, optional
      :param sfreq: Sampling frequency in Hertz. Required when enabled families depend
                    on spectral estimates or spectral entropy.
      :type sfreq: float, optional
      :param channel_names: Channel labels. Required for channel-resolved outputs.
      :type channel_names: sequence of str or np.ndarray, optional

      :returns: Flat ``("obs", "feature")`` container: ``X`` is the descriptor
                matrix, ``coords["feature"]`` the column names, and
                ``coords["feature_family"]`` the per-column family token (carried
                from the extractors, not parsed). ``ids`` are the observation ids and
                ``meta`` holds ``failures`` and ``sfreq``.
      :rtype: DataContainer

      :raises ValueError: If the explicit input contract is not satisfied.
      :raises ImportError: If an optional backend required by the enabled families is missing.

      .. rubric:: Notes

      When ``runtime.on_error="warn"``, extraction still completes and stores
      the failures in ``meta["failures"]`` before emitting one aggregate
      warning at the pipeline level.

      The returned row order always matches the input observation order.



   .. py:method:: pool_channels(container, channel_groups)

      Pool sensor-level descriptor columns into grouped channel outputs.

      :param container: Flat descriptor container produced by :meth:`extract`.
      :type container: DataContainer
      :param channel_groups: Channel groups used to replace sensor-level descriptor columns with
                             grouped ``"chgrp-..."`` outputs.
      :type channel_groups: mapping of str to sequence of str

      :returns: New container with grouped channel features. ``ids`` and ``meta``
                (including ``failures``) are preserved; ``coords["feature"]`` and
                ``coords["feature_family"]`` reflect the pooled columns.
      :rtype: DataContainer

      :raises ValueError: If the container is malformed or if any requested group cannot be
          formed from the sensor-level descriptor columns.