coco_pipe.descriptors.configs

Strict Pydantic configuration models for the descriptors module.

This module defines the static, typed configuration surface for descriptor extraction:

• explicit runtime input requirements

• family-specific configs for bands, parametric fitting, and complexity

• final output precision control

• runtime execution controls

These models validate local field structure and family-local constraints. The remaining cross-family compatibility rule for corrected spectral outputs is enforced by coco_pipe.descriptors.core.DescriptorPipeline after config parsing, because it depends on how multiple family configs interact.

Author: Hamza Abdelhedi (hamza.abdelhedi@umontreal.ca)

Classes

DescriptorInputConfig	Explicit runtime input requirements for descriptor extraction.
BandDescriptorConfig	Configuration for PSD-based band summary descriptors.
ParametricDescriptorConfig	Configuration for specparam-based spectral summary descriptors.
ComplexityDescriptorConfig	Configuration for signal-complexity descriptors.
DescriptorFamiliesConfig	Group descriptor-family configuration under one top-level field.
DescriptorRuntimeConfig	Runtime execution controls for descriptor extraction.
DescriptorConfig	Top-level descriptors configuration object.

Module Contents

class coco_pipe.descriptors.configs.DescriptorInputConfig(/, **data)

Bases: _StrictConfigModel

Explicit runtime input requirements for descriptor extraction.

Parameters:

• require_sfreq (bool, default=True) – Whether extraction requires an explicit sampling frequency input.

• require_channel_names (bool, default=False) – Whether extraction requires explicit channel names at runtime.

• data (Any)

Notes

The descriptors module accepts only explicit NumPy-like arrays with shape (n_obs, n_channels, n_times) in observation-channel-time order. That structural contract is fixed by the module and enforced at runtime; this config only controls which additional runtime inputs must also be passed.

require_sfreq: bool = True

require_channel_names: bool = False

class coco_pipe.descriptors.configs.BandDescriptorConfig(/, **data)

Bases: _StrictConfigModel

Configuration for PSD-based band summary descriptors.

Parameters:

• enabled (bool, default=False) – Whether the band family is enabled.

• psd_method ({"welch", "multitaper"}, default="welch") – PSD estimator used before computing band summaries.

• fmin (float) – Global frequency window within which PSDs and bands are evaluated.

• fmax (float) – Global frequency window within which PSDs and bands are evaluated.

• bands (dict of str to tuple of float, default=canonical EEG bands) – Mapping from band name to (low, high) boundaries.

• outputs (list of {"absolute_power", "log_absolute_power", "relative_power", "ratios", "corrected_absolute_power", "corrected_log_absolute_power", "corrected_relative_power", "corrected_ratios"}) – Band descriptors to emit.

• ratio_pairs (list of tuple of str, default=[]) – Explicit numerator and denominator band names for ratio outputs.

• min_denominator_power (float, default=0.0) – Minimum denominator power required for relative-power and ratio outputs. Any denominator at or below this threshold is treated as undefined and yields NaN instead of an unstable division result.

• data (Any)

Notes

Corrected band outputs are configured here, but their cross-family compatibility with the parametric fit range is checked later by the descriptor pipeline because that rule depends on both the band and parametric family configs together.

enabled: bool = False

psd_method: Literal['welch', 'multitaper'] = 'welch'

fmin: float = None

fmax: float = None

bands: dict[str, tuple[float, float]] = None

outputs: list[Literal['absolute_power', 'log_absolute_power', 'relative_power', 'ratios', 'corrected_absolute_power', 'corrected_log_absolute_power', 'corrected_relative_power', 'corrected_ratios']] = None

ratio_pairs: list[tuple[str, str]] = None

min_denominator_power: float = None

class coco_pipe.descriptors.configs.ParametricDescriptorConfig(/, **data)

Bases: _StrictConfigModel

Configuration for specparam-based spectral summary descriptors.

Parameters:

• enabled (bool, default=False) – Whether the parametric family is enabled.

• backend ({"specparam"}, default="specparam") – Parametric modeling backend.

• psd_method ({"welch", "multitaper"}, default="welch") – PSD estimator used before fitting the parametric model.

• freq_range (tuple of float, default=(1.0, 45.0)) – Frequency range passed to the parametric model.

• peak_width_limits (tuple of float, default=(1.0, 12.0)) – Peak width bounds forwarded to the model backend.

• max_n_peaks (int, default=6) – Maximum number of periodic peaks to fit.

• aperiodic_mode ({"fixed", "knee"}, default="fixed") – Aperiodic model form used by specparam.

• outputs (list of {"aperiodic", "fit_quality", "peak_summary"}) – Parametric descriptor groups to emit.

• data (Any)

Notes

This config describes how the shared parametric fit is produced. The same fit can be reused by the parametric family itself and by corrected spectral outputs when the planner detects compatible requests.

enabled: bool = False

backend: Literal['specparam'] = 'specparam'

psd_method: Literal['welch', 'multitaper'] = 'welch'

freq_range: tuple[float, float] = (1.0, 45.0)

peak_width_limits: tuple[float, float] = (1.0, 12.0)

max_n_peaks: int = None

aperiodic_mode: Literal['fixed', 'knee'] = 'fixed'

outputs: list[Literal['aperiodic', 'fit_quality', 'peak_summary']] = None

class coco_pipe.descriptors.configs.ComplexityDescriptorConfig(/, **data)

Bases: _StrictConfigModel

Configuration for signal-complexity descriptors.

Parameters:

• enabled (bool, default=False) – Whether the complexity family is enabled.

• backend ({"antropy", "neurokit2", "auto"}, default="antropy") – Complexity backend used for supported measures.

• measures (list of str) – Complexity measures to compute.

• measure_kwargs (dict of str to dict, default={}) – Per-measure keyword arguments forwarded to the backend implementation.

• data (Any)

Notes

Complexity measures are signal-domain descriptors. Unlike the PSD-based families, they do not participate in shared PSD planning.

enabled: bool = False

backend: Literal['antropy', 'neurokit2', 'auto'] = 'antropy'

measures: list[str] = None

measure_kwargs: dict[str, dict[str, Any]] = None

class coco_pipe.descriptors.configs.DescriptorFamiliesConfig(/, **data)

Bases: _StrictConfigModel

Group descriptor-family configuration under one top-level field.

Variables:

• bands (BandDescriptorConfig) – Configuration for PSD-based band summaries.

• parametric (ParametricDescriptorConfig) – Configuration for specparam-based summaries.

• complexity (ComplexityDescriptorConfig) – Configuration for complexity measures.

Parameters:

data (Any)

bands: BandDescriptorConfig = None

parametric: ParametricDescriptorConfig = None

complexity: ComplexityDescriptorConfig = None

class coco_pipe.descriptors.configs.DescriptorRuntimeConfig(/, **data)

Bases: _StrictConfigModel

Runtime execution controls for descriptor extraction.

Parameters:

• execution_backend ({"joblib", "sequential"}, default="joblib") – Execution backend used by the pipeline.

• n_jobs (int, default=1) – Number of worker slots requested for supported parallel paths. -1 means “use as much useful parallelism as the current stage can use”, while positive integers request an explicit worker count.

• obs_chunk (int, default=128) – Number of observations processed per batch.

• on_error ({"raise", "warn", "collect"}, default="collect") – Failure policy applied during extraction.

• data (Any)

Notes

Runtime config controls execution only. It does not add provenance, reporting, or persistence metadata to the returned descriptor result.

execution_backend: Literal['joblib', 'sequential'] = 'joblib'

n_jobs: int = 1

obs_chunk: int = None

on_error: Literal['raise', 'warn', 'collect'] = None

class coco_pipe.descriptors.configs.DescriptorConfig(/, **data)

Bases: _StrictConfigModel

Top-level descriptors configuration object.

Variables:

• input (DescriptorInputConfig) – Runtime input requirements for explicit array extraction.

• families (DescriptorFamiliesConfig) – Enabled descriptor families and their typed configs.

• precision ({"float32", "float64"}) – Output dtype used for the final descriptor matrix.

• runtime (DescriptorRuntimeConfig) – Runtime execution and error-handling settings.

Parameters:

data (Any)

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