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

.. py:module:: coco_pipe.descriptors


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/coco_pipe/descriptors/configs/index
   /autoapi/coco_pipe/descriptors/core/index
   /autoapi/coco_pipe/descriptors/extractors/index
   /autoapi/coco_pipe/descriptors/validation/index


Classes
-------

.. autoapisummary::

   coco_pipe.descriptors.DescriptorConfig
   coco_pipe.descriptors.DescriptorPipeline


Package Contents
----------------

.. py:class:: DescriptorConfig(/, **data: Any)

   Bases: :py:obj:`_StrictConfigModel`


   Top-level descriptors configuration object.

   .. attribute:: input

      Runtime input requirements for explicit array extraction.

      :type: DescriptorInputConfig

   .. attribute:: families

      Enabled descriptor families and their typed configs.

      :type: DescriptorFamiliesConfig

   .. attribute:: precision

      Output dtype used for the final descriptor matrix.

      :type: {"float32", "float64"}

   .. attribute:: runtime

      Runtime execution and error-handling settings.

      :type: DescriptorRuntimeConfig

   .. rubric:: Notes

   This object is the stable config boundary for
   :class:`coco_pipe.descriptors.core.DescriptorPipeline`. Parsing this config
   validates local structure here, then the pipeline applies the remaining
   cross-family compatibility checks when it builds the execution plan.


   .. py:attribute:: input
      :type:  DescriptorInputConfig
      :value: None



   .. py:attribute:: families
      :type:  DescriptorFamiliesConfig
      :value: None



   .. py:attribute:: precision
      :type:  Literal['float32', 'float64']
      :value: 'float32'



   .. py:attribute:: runtime
      :type:  DescriptorRuntimeConfig
      :value: None



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