coco_pipe.descriptors.naming#

Descriptor column-name contract.

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

Functions#

descriptor_identity(measure)

Return a measure's descriptor identity (aggregation-stat prefix removed).

descriptor_subfamily(family, measure)

Map a (family, measure) pair to its descriptor sub-family.

split_family_token(text, known_families)

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

parse_descriptor_feature_column(column, known_families)

Strictly parse one descriptor column into its constituent parts.

build_descriptor_feature_metadata(columns, *[, ...])

Build decoding feature metadata from descriptor feature-column names.

Module Contents#

coco_pipe.descriptors.naming.descriptor_identity(measure)#

Return a measure’s descriptor identity (aggregation-stat prefix removed).

Collapses the per-stat columns of one descriptor — e.g. mean_log_abs_alpha and iqr_log_abs_alpha both map to log_abs_alpha — so location and spread stay together as one unit.

Parameters:

measure (str)

Return type:

str

coco_pipe.descriptors.naming.descriptor_subfamily(family, measure)#

Map a (family, measure) pair to its descriptor sub-family.

A sub-family is the output type within a family — finer than family but coarser than measure:

  • band → log_abs / rel / corr_log_abs / corr_rel / abs / corr_abs / ratio (band name stripped)

  • param → aperiodic / peaks / fit_quality

  • complexity → entropy / fractal_complexity / signal_dynamics

Robust to subject-level aggregation-stat prefixes (median_…). Unknown families/measures fall back to "<family>_other" (or "unknown").

Parameters:

  • family (str | None)

  • measure (str)

Return type:

str

coco_pipe.descriptors.naming.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 parse_descriptor_feature_column() and the family classifier so the token-matching rule lives in one place.

Parameters:
Return type:

tuple[str | None, str]

coco_pipe.descriptors.naming.parse_descriptor_feature_column(column, known_families)#

Strictly parse one descriptor column into its constituent parts.

Parameters:

  • column (str) – Descriptor column name, e.g. "band_abs_alpha_ch-Fz".

  • known_families (tuple[str, ...]) – Recognised family prefix tokens (e.g. KNOWN_FAMILY_TOKENS).

Returns:

Keys column, family, feature, scope ("sensor" / "sensor_group"), and sensor.

Return type:

dict[str, str]

Raises:

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

coco_pipe.descriptors.naming.build_descriptor_feature_metadata(columns, *, known_families=KNOWN_FAMILY_TOKENS, feature_names=None)#

Build decoding feature metadata from descriptor feature-column names.

Parameters:
Return type:

pandas.DataFrame