coco_pipe.descriptors.configs ============================= .. py:module:: coco_pipe.descriptors.configs .. autoapi-nested-parse:: Descriptor Configuration ======================== 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 :class:`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 ------- .. autoapisummary:: coco_pipe.descriptors.configs.DescriptorInputConfig coco_pipe.descriptors.configs.BandDescriptorConfig coco_pipe.descriptors.configs.ParametricDescriptorConfig coco_pipe.descriptors.configs.ComplexityDescriptorConfig coco_pipe.descriptors.configs.DescriptorFamiliesConfig coco_pipe.descriptors.configs.DescriptorRuntimeConfig coco_pipe.descriptors.configs.DescriptorConfig Module Contents --------------- .. py:class:: DescriptorInputConfig(/, **data: Any) Bases: :py:obj:`_StrictConfigModel` Explicit runtime input requirements for descriptor extraction. :param require_sfreq: Whether extraction requires an explicit sampling frequency input. :type require_sfreq: bool, default=True :param require_channel_names: Whether extraction requires explicit channel names at runtime. :type require_channel_names: bool, default=False .. rubric:: 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. .. py:attribute:: require_sfreq :type: bool :value: True .. py:attribute:: require_channel_names :type: bool :value: False .. py:class:: BandDescriptorConfig(/, **data: Any) Bases: :py:obj:`_StrictConfigModel` Configuration for PSD-based band summary descriptors. :param enabled: Whether the band family is enabled. :type enabled: bool, default=False :param psd_method: PSD estimator used before computing band summaries. :type psd_method: {"welch", "multitaper"}, default="welch" :param fmin: Global frequency window within which PSDs and bands are evaluated. :type fmin: float :param fmax: Global frequency window within which PSDs and bands are evaluated. :type fmax: float :param bands: Mapping from band name to ``(low, high)`` boundaries. :type bands: dict of str to tuple of float, default=canonical EEG bands :param outputs: Band descriptors to emit. :type outputs: list of {"absolute_power", "log_absolute_power", "relative_power", "ratios", "corrected_absolute_power", "corrected_log_absolute_power", "corrected_relative_power", "corrected_ratios"} :param ratio_pairs: Explicit numerator and denominator band names for ratio outputs. :type ratio_pairs: list of tuple of str, default=[] :param min_denominator_power: 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. :type min_denominator_power: float, default=0.0 .. rubric:: 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. .. py:attribute:: enabled :type: bool :value: False .. py:attribute:: psd_method :type: Literal['welch', 'multitaper'] :value: 'welch' .. py:attribute:: fmin :type: float :value: None .. py:attribute:: fmax :type: float :value: None .. py:attribute:: bands :type: dict[str, tuple[float, float]] :value: None .. py:attribute:: outputs :type: list[Literal['absolute_power', 'log_absolute_power', 'relative_power', 'ratios', 'corrected_absolute_power', 'corrected_log_absolute_power', 'corrected_relative_power', 'corrected_ratios']] :value: None .. py:attribute:: ratio_pairs :type: list[tuple[str, str]] :value: None .. py:attribute:: min_denominator_power :type: float :value: None .. py:method:: _coerce_bands(value: Any) -> dict[str, tuple[float, float]] :classmethod: .. py:method:: _validate_outputs(value: list[str]) -> list[str] :classmethod: .. py:method:: _coerce_ratio_pairs(value: Any) -> list[tuple[str, str]] :classmethod: .. py:method:: _validate_model() -> BandDescriptorConfig .. py:class:: ParametricDescriptorConfig(/, **data: Any) Bases: :py:obj:`_StrictConfigModel` Configuration for specparam-based spectral summary descriptors. :param enabled: Whether the parametric family is enabled. :type enabled: bool, default=False :param backend: Parametric modeling backend. :type backend: {"specparam"}, default="specparam" :param psd_method: PSD estimator used before fitting the parametric model. :type psd_method: {"welch", "multitaper"}, default="welch" :param freq_range: Frequency range passed to the parametric model. :type freq_range: tuple of float, default=(1.0, 45.0) :param peak_width_limits: Peak width bounds forwarded to the model backend. :type peak_width_limits: tuple of float, default=(1.0, 12.0) :param max_n_peaks: Maximum number of periodic peaks to fit. :type max_n_peaks: int, default=6 :param aperiodic_mode: Aperiodic model form used by specparam. :type aperiodic_mode: {"fixed", "knee"}, default="fixed" :param outputs: Parametric descriptor groups to emit. :type outputs: list of {"aperiodic", "fit_quality", "peak_summary"} .. rubric:: 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. .. py:attribute:: enabled :type: bool :value: False .. py:attribute:: backend :type: Literal['specparam'] :value: 'specparam' .. py:attribute:: psd_method :type: Literal['welch', 'multitaper'] :value: 'welch' .. py:attribute:: freq_range :type: tuple[float, float] :value: (1.0, 45.0) .. py:attribute:: peak_width_limits :type: tuple[float, float] :value: (1.0, 12.0) .. py:attribute:: max_n_peaks :type: int :value: None .. py:attribute:: aperiodic_mode :type: Literal['fixed', 'knee'] :value: 'fixed' .. py:attribute:: outputs :type: list[Literal['aperiodic', 'fit_quality', 'peak_summary']] :value: None .. py:method:: _validate_outputs(value: list[str]) -> list[str] :classmethod: .. py:method:: _validate_model() -> ParametricDescriptorConfig .. py:class:: ComplexityDescriptorConfig(/, **data: Any) Bases: :py:obj:`_StrictConfigModel` Configuration for signal-complexity descriptors. :param enabled: Whether the complexity family is enabled. :type enabled: bool, default=False :param backend: Complexity backend used for supported measures. :type backend: {"antropy", "neurokit2", "auto"}, default="antropy" :param measures: Complexity measures to compute. :type measures: list of str :param measure_kwargs: Per-measure keyword arguments forwarded to the backend implementation. :type measure_kwargs: dict of str to dict, default={} .. rubric:: Notes Complexity measures are signal-domain descriptors. Unlike the PSD-based families, they do not participate in shared PSD planning. .. py:attribute:: enabled :type: bool :value: False .. py:attribute:: backend :type: Literal['antropy', 'neurokit2', 'auto'] :value: 'antropy' .. py:attribute:: measures :type: list[str] :value: None .. py:attribute:: measure_kwargs :type: dict[str, dict[str, Any]] :value: None .. py:method:: _validate_measures(value: list[str]) -> list[str] :classmethod: .. py:class:: DescriptorFamiliesConfig(/, **data: Any) Bases: :py:obj:`_StrictConfigModel` Group descriptor-family configuration under one top-level field. .. attribute:: bands Configuration for PSD-based band summaries. :type: BandDescriptorConfig .. attribute:: parametric Configuration for specparam-based summaries. :type: ParametricDescriptorConfig .. attribute:: complexity Configuration for complexity measures. :type: ComplexityDescriptorConfig .. py:attribute:: bands :type: BandDescriptorConfig :value: None .. py:attribute:: parametric :type: ParametricDescriptorConfig :value: None .. py:attribute:: complexity :type: ComplexityDescriptorConfig :value: None .. py:class:: DescriptorRuntimeConfig(/, **data: Any) Bases: :py:obj:`_StrictConfigModel` Runtime execution controls for descriptor extraction. :param execution_backend: Execution backend used by the pipeline. :type execution_backend: {"joblib", "sequential"}, default="joblib" :param n_jobs: 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. :type n_jobs: int, default=1 :param obs_chunk: Number of observations processed per batch. :type obs_chunk: int, default=128 :param on_error: Failure policy applied during extraction. :type on_error: {"raise", "warn", "collect"}, default="collect" .. rubric:: Notes Runtime config controls execution only. It does not add provenance, reporting, or persistence metadata to the returned descriptor result. .. py:attribute:: execution_backend :type: Literal['joblib', 'sequential'] :value: 'joblib' .. py:attribute:: n_jobs :type: int :value: 1 .. py:attribute:: obs_chunk :type: int :value: None .. py:attribute:: on_error :type: Literal['raise', 'warn', 'collect'] :value: None .. py:method:: _validate_n_jobs(value: int) -> int :classmethod: .. py:class:: DescriptorConfig(/, **data: Any) Bases: :py:obj:`_StrictConfigModel` Top-level descriptors configuration object. .. attribute:: input Runtime input requirements for explicit array extraction. :type: DescriptorInputConfig .. attribute:: families Enabled descriptor families and their typed configs. :type: DescriptorFamiliesConfig .. attribute:: precision Output dtype used for the final descriptor matrix. :type: {"float32", "float64"} .. attribute:: runtime Runtime execution and error-handling settings. :type: DescriptorRuntimeConfig .. rubric:: Notes This object is the stable config boundary for :class:`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. .. py:attribute:: input :type: DescriptorInputConfig :value: None .. py:attribute:: families :type: DescriptorFamiliesConfig :value: None .. py:attribute:: precision :type: Literal['float32', 'float64'] :value: 'float32' .. py:attribute:: runtime :type: DescriptorRuntimeConfig :value: None