coco_pipe.io.units
==================

.. py:module:: coco_pipe.io.units

.. autoapi-nested-parse::

   Analysis-unit enumeration for multi-mode EEG pipelines.

   An *analysis unit* is a (container-slice, metadata) pair that feeds one
   independent analysis run (dim-reduction, decoding, connectivity, …).
   The supported modes are:

   ``flat``
       One unit per scope — the entire container is used as-is.
   ``sensor``
       One unit per sensor/channel.  For raw inputs the channel dimension is
       sliced; for descriptor inputs each sensor's columns are selected and
       flattened.
   ``family``
       One unit per descriptor feature family (descriptor inputs only).
   ``subfamily``
       One unit per descriptor sub-family — the output type within a family, e.g.
       band ``log_abs`` / ``rel`` or param ``aperiodic`` / ``peaks`` (descriptor
       inputs only; requires a ``feature_subfamily`` coord).
   ``sensor_within_family``
       One unit per (sensor, family) combination (descriptor inputs only).
   ``sensor_within_subfamily``
       One unit per (sensor, sub-family) combination (descriptor inputs only;
       requires a ``feature_subfamily`` coord).
   ``feature``
       One unit per descriptor feature across all sensors.
   ``feature_within_family``
       One unit per (feature, family) combination across all sensors.
   ``descriptor``
       One unit per descriptor across all sensors — all aggregation-stat columns of
       a descriptor (e.g. mean + iqr of alpha) kept together (requires a
       ``feature_descriptor`` coord).
   ``descriptor_sensor``
       One unit per (descriptor, sensor) — one descriptor's stats at a single
       sensor (requires a ``feature_descriptor`` coord).



Functions
---------

.. autoapisummary::

   coco_pipe.io.units.iter_analysis_units


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

.. py:function:: iter_analysis_units(container, analysis_mode, input_mode, descriptor_families = None)

   Enumerate analysis units from *container* according to *analysis_mode*.

   Each returned dict has the keys:

   - ``unit_type`` — one of ``"global"``, ``"sensor"``, ``"family"``,
     ``"subfamily"``, ``"feature"``, or ``"descriptor"``
   - ``unit_name`` — human-readable identifier (e.g. ``"Fz"``, ``"band"``)
   - ``unit_key``  — filesystem-safe unique key (e.g. ``"band_Fz"``)
   - ``family``    — descriptor family name, or ``None``
   - ``subfamily`` — descriptor sub-family name, or ``None``
   - ``container`` — the sliced/flattened
     :class:`~coco_pipe.io.DataContainer` for this unit

   The container's ``meta`` dict is also updated in-place with the
   ``unit_type``/``unit_name``/``unit_key``/``family``/``subfamily`` fields so
   that downstream functions can read the unit context from the container
   without needing to carry the dict separately.

   :param container: Full data container for one analysis scope/condition.
   :param analysis_mode: The unit granularity. ``"flat"`` and ``"sensor"`` work for both input
                         modes; the remaining modes require descriptor inputs:

                         - ``"flat"`` — one unit for the whole container.
                         - ``"sensor"`` — one unit per sensor/channel.
                         - ``"family"`` — one unit per descriptor feature family.
                         - ``"subfamily"`` — one unit per sub-family (needs a
                           ``feature_subfamily`` coord).
                         - ``"sensor_within_family"`` — one unit per (sensor, family).
                         - ``"sensor_within_subfamily"`` — one unit per (sensor, sub-family)
                           (needs a ``feature_subfamily`` coord).
                         - ``"feature"`` — one unit per feature across all sensors.
                         - ``"feature_within_family"`` — one unit per (feature, family).
                         - ``"descriptor"`` — one unit per descriptor across all sensors
                           (needs a ``feature_descriptor`` coord).
                         - ``"descriptor_sensor"`` — one unit per (descriptor, sensor)
                           (needs a ``feature_descriptor`` coord).
   :param input_mode: ``"raw"`` or ``"descriptors"``.  Controls which container dimension is
                      sliced for the ``"sensor"`` mode.
   :param descriptor_families: Ordered list of feature families to include.  ``None`` means all
                               families present in the container.

   :returns: One entry per analysis unit in the order they should be processed.
   :rtype: list of dict

   :raises ValueError: On unsupported *analysis_mode* / *input_mode* combinations, or when
       no features match the requested families.
   :raises RuntimeError: When no features match in sensor mode.