coco_pipe.descriptors

Submodules

• coco_pipe.descriptors.configs
• coco_pipe.descriptors.core
• coco_pipe.descriptors.extractors
• coco_pipe.descriptors.validation

Classes

DescriptorConfig	Top-level descriptors configuration object.
DescriptorPipeline	Run config-driven descriptor extraction on explicit arrays.

Package Contents

class coco_pipe.descriptors.DescriptorConfig(/, **data: Any)

Bases: _StrictConfigModel

Top-level descriptors configuration object.

input

Runtime input requirements for explicit array extraction.

Type:

DescriptorInputConfig

families

Enabled descriptor families and their typed configs.

Type:

DescriptorFamiliesConfig

precision

Output dtype used for the final descriptor matrix.

Type:

{“float32”, “float64”}

runtime

Runtime execution and error-handling settings.

Type:

DescriptorRuntimeConfig

Notes

This object is the stable config boundary for 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.

input: DescriptorInputConfig = None

families: DescriptorFamiliesConfig = None

precision: Literal['float32', 'float64'] = 'float32'

runtime: DescriptorRuntimeConfig = None

class coco_pipe.descriptors.DescriptorPipeline(config: coco_pipe.descriptors.configs.DescriptorConfig | collections.abc.Mapping[str, Any])

Run config-driven descriptor extraction on explicit arrays.

Parameters:

config (DescriptorConfig or Mapping[str, Any]) – Typed descriptors configuration or a mapping accepted by DescriptorConfig.

config

Parsed descriptors configuration.

Type:

DescriptorConfig

extractors

Enabled family extractors in deterministic family order.

Type:

list of BaseDescriptorExtractor

signal_extractors

Enabled non-PSD extractors that consume raw signal batches directly.

Type:

list of BaseDescriptorExtractor

psd_groups

Planned PSD reuse groups derived once from the enabled extractors.

Type:

list of _PSDGroup

family_order

Deterministic family order used when merging batch-local outputs.

Type:

list of str

Notes

The pipeline is config-bound but runtime-stateless. Construction performs config parsing, corrected-band compatibility checks, and planner setup once. Each call to extract() then validates the explicit runtime inputs, executes the planned families, and returns one flat descriptor matrix plus any collected failures.

config

extractors: list[coco_pipe.descriptors.extractors.base.BaseDescriptorExtractor] = []

signal_extractors

psd_groups = []

family_order

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.

Parameters:

• X (np.ndarray) – Signal array with shape (n_obs, n_channels, n_times).

• ids (sequence or np.ndarray, optional) – Observation identifiers aligned with X.

• sfreq (float, optional) – Sampling frequency in Hertz. Required when enabled families depend on spectral estimates or spectral entropy.

• channel_names (sequence of str or np.ndarray, optional) – Channel labels. Required for channel-resolved outputs.

Returns:

Dictionary with keys X, descriptor_names, and failures.

Return type:

dict[str, Any]

Raises:

• ValueError – If the explicit input contract is not satisfied.

• ImportError – If an optional backend required by the enabled families is missing.

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.

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.

Parameters:

• result (mapping) – Standard descriptor result produced by extract().

• channel_groups (mapping of str to sequence of str) – Channel groups used to replace sensor-level descriptor columns with grouped "chgrp-..." outputs.

Returns:

Descriptor result with grouped channel features and unchanged failures.

Return type:

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.