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: coco_pipe.descriptors.configs.ParametricDescriptorConfig)[source]

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.

config

Stored typed configuration for the parametric family.

Type:

ParametricDescriptorConfig

family_name

Stable family identifier used in metadata and failure records.

Type:

str

Notes

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

When the pipeline provides a precomputed PSD batch through extract_psd(), the extractor reuses that shared spectral input and expects an explicit shared fit_batch. Standalone extract() remains available for family-local PSD and fit computation.

family_name = 'parametric'
config
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() → dict[str, Any][source]

Describe the PSD requirements for the shared planner.

parametric_fit_requirements() → dict[str, Any][source]

Describe whether this family needs shared parametric-fit outputs.

extract_psd(psds: numpy.ndarray, freqs: numpy.ndarray, channel_names: list[str] | None, ids: numpy.ndarray | None, runtime, obs_offset: int = 0, fit_batch: coco_pipe.descriptors.extractors._parametric_fit._ParametricFitBatch | None = None) → coco_pipe.descriptors.extractors.base._DescriptorBlock[source]

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.

Returns:

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

Return type:

_DescriptorBlock

Raises:

ValueError – If fit_batch is not supplied.

Notes

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

extract(X: numpy.ndarray, sfreq: float | None, channel_names: list[str] | None, ids: numpy.ndarray | None, runtime, obs_offset: int = 0) → coco_pipe.descriptors.extractors.base._DescriptorBlock[source]

Extract parametric descriptors from segmented multi-channel data.

Parameters:

  • X (np.ndarray) – Input array with shape (n_obs, n_channels, n_times). Each row already represents one observation segment produced upstream.

  • sfreq (float, optional) – Sampling frequency in Hertz.

  • channel_names (list of str, optional) – Explicit channel labels aligned with axis 1 of X.

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

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

  • obs_offset (int, default=0) – Global observation offset added to any collected failure records.

Returns:

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

Return type:

_DescriptorBlock

Raises:

  • ImportError – If the optional mne or specparam backend is unavailable.

  • ValueError – If PSD computation encounters an invalid runtime condition.

  • RuntimeError – If shared fit materialization encounters a runtime failure and runtime.on_error == "raise".

Notes

This standalone path computes a PSD for the current batch, fits one explicit parametric batch payload for this family, and then delegates to extract_psd(). When the family is executed through DescriptorPipeline, the shared planner supplies the PSD and fit payload instead.