coco_pipe.io.units#

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#

iter_analysis_units(container, analysis_mode, input_mode)

Enumerate analysis units from container according to analysis_mode.

Module Contents#

coco_pipe.io.units.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 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.

Parameters:

  • container (coco_pipe.io.structures.DataContainer) – Full data container for one analysis scope/condition.

  • analysis_mode (str) –

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

  • input_mode (str) – "raw" or "descriptors". Controls which container dimension is sliced for the "sensor" mode.

  • descriptor_families (list[str] | None) – 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.

Return type:

list of dict

Raises:

  • ValueError – On unsupported analysis_mode / input_mode combinations, or when no features match the requested families.

  • RuntimeError – When no features match in sensor mode.