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

.. py:module:: coco_pipe.descriptors.naming

.. autoapi-nested-parse::

   Descriptor column-name contract.

   The descriptor extractors emit column names of the form
   ``{family}_{feature}_{ch|chgrp}-{sensor}`` (see
   :class:`~coco_pipe.descriptors.core.DescriptorPipeline`). Parsing that contract
   is descriptor-domain knowledge, so it lives here next to the family QC that
   consumes it (:mod:`coco_pipe.descriptors.qc`) and shares the single
   :data:`~coco_pipe.descriptors._constants.DESCRIPTOR_SCOPE_RE`.



Functions
---------

.. autoapisummary::

   coco_pipe.descriptors.naming.split_family_token
   coco_pipe.descriptors.naming.parse_descriptor_feature_column


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

.. py:function:: split_family_token(text, known_families)

   Split ``text`` into ``(family, remainder)`` on the first known family token.

   The family token may appear as a leading prefix (``"band_..."``) or embedded
   (``"mean_band_..."``). Returns ``(None, text)`` when no known family token is
   present. Shared by :func:`parse_descriptor_feature_column` and the family
   classifier so the token-matching rule lives in one place.


.. py:function:: parse_descriptor_feature_column(column, known_families)

   Strictly parse one descriptor column into its constituent parts.

   :param column: Descriptor column name, e.g. ``"band_abs_alpha_ch-Fz"``.
   :param known_families: Recognised family prefix tokens (e.g.
                          :data:`~coco_pipe.descriptors._constants.KNOWN_FAMILY_TOKENS`).

   :returns: Keys ``column``, ``family``, ``feature``, ``scope``
             (``"sensor"`` / ``"sensor_group"``), and ``sensor``.
   :rtype: dict[str, str]

   :raises ValueError: If the column does not match the scope contract or contains no known
       family token.