coco_pipe.descriptors.extractors.parametric#

Parametric spectral descriptor extraction backend.

This module implements the built-in parametric spectral family for coco_pipe.descriptors. The extractor operates on already segmented NumPy inputs with shape (n_obs, n_channels, n_times) and computes one or more specparam-derived summary descriptors per sensor, per observation.

Notes

The parametric family is a PSD consumer. When used through DescriptorPipeline.extract(), it can share one batch-scoped PSD computation with other compatible PSD consumers such as the spectral band family. The actual descriptor outputs are then derived from that shared psds, freqs pair.

Model fitting itself still happens one spectrum at a time. When runtime parallelism is enabled and the planner allows it, those per-spectrum fits can run in parallel across observation-channel units.

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

Classes#

ParametricDescriptorExtractor

Parametric spectral descriptor extractor.

Module Contents#

class coco_pipe.descriptors.extractors.parametric.ParametricDescriptorExtractor(config)#

Bases: coco_pipe.descriptors.extractors.base.BasePSDDescriptorExtractor

Parametric spectral descriptor extractor.

This extractor fits one specparam model per observation and sensor in a validated descriptor input array, then exposes scalar summaries such as aperiodic parameters, fit quality, and dominant peak statistics.

Parameters:

config (ParametricDescriptorConfig) – Parsed family configuration controlling the PSD method, fit range, specparam settings, and requested output groups.

Variables:

  • config (ParametricDescriptorConfig) – Stored typed configuration for the parametric family.

  • family_name (str) – Stable family identifier used in metadata and failure records.

Notes

The extractor always computes descriptor values per sensor first. Public sensor-level naming is applied afterward through BaseDescriptorExtractor._finalize_descriptor().

DescriptorPipeline passes the shared PSD batch and the shared parametric fit batch to extract_psd().

family_name = 'parametric'#
property capabilities: dict[str, Any]#

Return static parametric extractor capability metadata.

Returns:

Capability metadata describing sampling-rate requirements and the optional backends used by the parametric family.

Return type:

dict[str, Any]

psd_request()#

Describe the PSD requirements for the shared planner.

Return type:

dict[str, Any]

parametric_fit_requirements()#

Describe whether this family needs shared parametric-fit outputs.

Return type:

dict[str, Any]

extract_psd(psds, freqs, channel_names, ids, runtime, obs_offset=0, fit_batch=None)#

Extract parametric descriptors from a precomputed PSD batch.

Parameters:

  • psds (np.ndarray) – Power spectral density array with shape (n_obs, n_channels, n_freqs).

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

  • channel_names (list of str, optional) – Explicit channel labels aligned with axis 1 of psds. If omitted, fallback names "ch-0", "ch-1", … are used internally.

  • ids (np.ndarray, optional) – Observation identifiers aligned with axis 0 of psds.

  • runtime (DescriptorRuntimeConfig) – Runtime execution controls shared across descriptor families.

  • obs_offset (int, default=0) – Global observation offset added to any collected failure records when this extractor is called on one observation batch.

  • fit_batch (coco_pipe.descriptors.extractors._parametric_fit._ParametricFitBatch | None)

Returns:

Parametric-family descriptor block aligned with the input observation axis.

Return type:

_DescriptorBlock

Notes

This method consumes explicit shared intermediates. It does not compute PSDs or fit models on its own.