coco_pipe.descriptors.extractors._parametric_fit

Shared specparam fitting for PSD-consuming descriptor paths.

This module holds the reusable fitting step used by the descriptors planner and by extractors that consume explicit parametric-fit intermediates. It does not define descriptor names or output pooling. It only:

  • fit specparam models on PSD batches

  • collect scalar fit metrics in aligned arrays

  • optionally reconstruct periodic-only PSDs for corrected band outputs

  • return one batch-scoped payload that downstream extractors can consume

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

Attributes

_ALPHA_BAND

Classes

_ParametricFitBatch

Batch-scoped parametric fit payload shared across PSD consumers.

Functions

fit_single_spectrum(→ tuple[dict[str, float], ...)

Fit one specparam model to one PSD spectrum.

fit_parametric_batch(→ _ParametricFitBatch)

Fit parametric models over one PSD batch.

Module Contents

coco_pipe.descriptors.extractors._parametric_fit._ALPHA_BAND = (8.0, 13.0)
class coco_pipe.descriptors.extractors._parametric_fit._ParametricFitBatch[source]

Batch-scoped parametric fit payload shared across PSD consumers.

freqs

Frequency grid used for the fitted spectra.

Type:

np.ndarray

metrics

Scalar metric arrays aligned to (n_obs, n_channels) for each requested parametric metric.

Type:

dict of str to np.ndarray

errors

Collected fit failures as (obs_index, channel_index, exception_type, message).

Type:

list of tuple

periodic_psds

Periodic-only PSDs aligned to (n_obs, n_channels, n_freqs) when corrected spectral outputs request them.

Type:

np.ndarray | None

meta

Lightweight fit metadata propagated into downstream descriptor blocks.

Type:

dict

freqs: numpy.ndarray
metrics: dict[str, numpy.ndarray]
errors: list[tuple[int, int, str, str]] = []
periodic_psds: numpy.ndarray | None = None
meta: dict[str, Any]
coco_pipe.descriptors.extractors._parametric_fit.fit_single_spectrum(freqs: numpy.ndarray, spectrum: numpy.ndarray, config: coco_pipe.descriptors.configs.ParametricDescriptorConfig, need_periodic_psd: bool = False) → tuple[dict[str, float], numpy.ndarray | None][source]

Fit one specparam model to one PSD spectrum.

Parameters:

  • freqs (np.ndarray) – Frequency grid for the input spectrum.

  • spectrum (np.ndarray) – One PSD spectrum aligned with freqs.

  • config (ParametricDescriptorConfig) – Parsed parametric fit configuration.

  • need_periodic_psd (bool, default=False) – Whether to reconstruct the periodic-only PSD from the fitted model.

Returns:

Scalar fit metrics and, when requested, the periodic-only PSD on the same frequency grid.

Return type:

tuple[dict[str, float], np.ndarray | None]

Raises:

  • ValueError – If the spectrum is constant or entirely non-finite.

  • RuntimeError – If specparam fails to produce a usable model or if reconstructed model components become non-finite.

coco_pipe.descriptors.extractors._parametric_fit.fit_parametric_batch(psds: numpy.ndarray, freqs: numpy.ndarray, config: coco_pipe.descriptors.configs.ParametricDescriptorConfig, runtime, need_periodic_psd: bool = False, include_metrics: bool = True) → _ParametricFitBatch[source]

Fit parametric models over one PSD batch.

Parameters:

  • psds (np.ndarray) – PSD batch with shape (n_obs, n_channels, n_freqs).

  • freqs (np.ndarray) – Frequency grid aligned with the last axis of psds.

  • config (ParametricDescriptorConfig) – Parsed parametric fit configuration.

  • runtime (DescriptorRuntimeConfig) – Runtime execution controls. Only the inner fitting parallelism path uses this object here.

  • need_periodic_psd (bool, default=False) – Whether to reconstruct periodic-only PSDs for each fitted spectrum.

  • include_metrics (bool, default=True) – Whether to materialize scalar metric arrays in the returned payload.

Returns:

Batch-scoped fit payload aligned to the input observation and channel axes after restricting the PSD to config.freq_range.

Return type:

_ParametricFitBatch