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: Any)[source]¶

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.

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: Any)[source]¶

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.

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¶

classmethod _coerce_bands(value: Any) → dict[str, tuple[float, float]][source]¶

classmethod _validate_outputs(value: list[str]) → list[str][source]¶

classmethod _coerce_ratio_pairs(value: Any) → list[tuple[str, str]][source]¶

_validate_model() → BandDescriptorConfig[source]¶

class coco_pipe.descriptors.configs.ParametricDescriptorConfig(/, **data: Any)[source]¶

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.

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¶

classmethod _validate_outputs(value: list[str]) → list[str][source]¶

_validate_model() → ParametricDescriptorConfig[source]¶

class coco_pipe.descriptors.configs.ComplexityDescriptorConfig(/, **data: Any)[source]¶

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.

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¶

classmethod _validate_measures(value: list[str]) → list[str][source]¶

class coco_pipe.descriptors.configs.DescriptorFamiliesConfig(/, **data: Any)[source]¶

Bases: _StrictConfigModel

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

bands¶

Configuration for PSD-based band summaries.

Type:: BandDescriptorConfig

parametric¶

Configuration for specparam-based summaries.

Type:: ParametricDescriptorConfig

complexity¶

Configuration for complexity measures.

Type:: ComplexityDescriptorConfig

bands: BandDescriptorConfig = None¶

parametric: ParametricDescriptorConfig = None¶

complexity: ComplexityDescriptorConfig = None¶

class coco_pipe.descriptors.configs.DescriptorRuntimeConfig(/, **data: Any)[source]¶

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.

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¶

classmethod _validate_n_jobs(value: int) → int[source]¶

class coco_pipe.descriptors.configs.DescriptorConfig(/, **data: Any)[source]¶

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¶