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: coco_pipe.descriptors.configs.DescriptorConfig | collections.abc.Mapping[str, Any])

   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]

   .. attribute:: config

      Parsed descriptors configuration.

      :type: DescriptorConfig

   .. attribute:: extractors

      Enabled family extractors in deterministic family order.

      :type: list of BaseDescriptorExtractor

   .. attribute:: signal_extractors

      Enabled non-PSD extractors that consume raw signal batches directly.

      :type: list of BaseDescriptorExtractor

   .. attribute:: psd_groups

      Planned PSD reuse groups derived once from the enabled extractors.

      :type: list of _PSDGroup

   .. attribute:: family_order

      Deterministic family order used when merging batch-local outputs.

      :type: 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: numpy.ndarray, ids: collections.abc.Sequence[Any] | numpy.ndarray | None = None, sfreq: float | None = None, channel_names: collections.abc.Sequence[str] | numpy.ndarray | None = None) -> dict[str, Any]

      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: Dictionary with keys ``X``, ``descriptor_names``, and ``failures``.
      :rtype: dict[str, Any]

      :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
      failures in ``result["failures"]`` before emitting one aggregate
      warning at the pipeline level.

      The returned row order always matches the input observation order.



   .. py:method:: pool_channels(result: collections.abc.Mapping[str, Any], channel_groups: collections.abc.Mapping[str, collections.abc.Sequence[str]]) -> dict[str, Any]

      Pool sensor-level descriptor columns into grouped channel outputs.

      :param result: Standard descriptor result produced by :meth:`extract`.
      :type result: mapping
      :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: Descriptor result with grouped channel features and unchanged
                failures.
      :rtype: dict[str, Any]

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