coco_pipe.descriptors.extractors.spectral

Band summary descriptor extraction backend.

This module implements the built-in spectral band family for coco_pipe.descriptors. The extractor operates on already segmented NumPy inputs with shape (n_obs, n_channels, n_times) and computes PSD-derived band summaries per sensor, per observation.

Notes

The spectral 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 parametric family. The actual descriptor outputs are then derived from that shared psds, freqs pair.

Within one extracted PSD batch, the family computes band integrals once and reuses them for all requested outputs:

  • absolute power

  • log absolute power

  • relative power

  • band ratios

  • corrected absolute power

  • corrected log absolute power

  • corrected relative power

  • corrected band ratios

Corrected outputs are derived from periodic-only PSDs produced by a shared parametric fit batch. They are therefore only available through the shared planner path or an explicit fit_batch passed to extract_psd().

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

Classes

BandDescriptorExtractor

Spectral band descriptor extractor.

Module Contents

class coco_pipe.descriptors.extractors.spectral.BandDescriptorExtractor(config: coco_pipe.descriptors.configs.BandDescriptorConfig, fit_config=None)[source]

Bases: coco_pipe.descriptors.extractors.base.BasePSDDescriptorExtractor

Spectral band descriptor extractor.

This extractor computes PSD-derived band summaries for each observation and sensor in a validated descriptor input array. It is intended for signals that are already segmented upstream, such as epochs, windows, or trial blocks.

Parameters:

config (BandDescriptorConfig) – Parsed family configuration controlling the PSD method, frequency window, band definitions, and requested spectral outputs.

config

Stored typed configuration for the spectral band family.

Type:

BandDescriptorConfig

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 instead of computing its own PSD. Corrected spectral outputs additionally require a shared parametric fit batch and are therefore only available through the shared planner path or an explicit fit_batch.

family_name = 'bands'
config
fit_config = None
property capabilities: dict[str, Any]

Return static spectral extractor capability metadata.

Returns:

Capability metadata describing sampling-rate requirements and the optional backend used by the spectral family.

Return type:

dict[str, Any]

Notes

Spectral band extraction always requires an explicit sampling rate because the PSD frequency axis depends on it.

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

Describe the PSD requirements for the shared planner.

Returns:

Minimal PSD request containing the PSD method and the required frequency range for this family.

Return type:

dict[str, Any]

Notes

DescriptorPipeline uses this request to group compatible PSD consumers and decide when one batch-scoped PSD can be reused across families.

needs_parametric_fit() → bool[source]

Whether corrected spectral outputs require a shared parametric fit.

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 band 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:

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

Return type:

_DescriptorBlock

Raises:

ValueError – If a configured band has no overlap with the computed PSD range and runtime error handling is configured to raise. Also raised when corrected outputs are requested without a supplied parametric fit_batch.

Notes

The extractor first restricts the incoming PSD to the configured frequency window, then integrates one power value per configured band and sensor. Those band integrals are reused for all enabled outputs, such as absolute power, log absolute power, relative power, and ratios. Ratios are always derived from absolute band powers, not from relative or log-transformed outputs.

Example

With channel_names=["Fz", "Cz"], an absolute alpha-band request yields names such as band_abs_alpha_ch-Fz and band_abs_alpha_ch-Cz.

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 band 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:

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

Return type:

_DescriptorBlock

Notes

This is the standalone extraction path for raw spectral outputs. It computes a PSD for the provided batch and then delegates to extract_psd(). Corrected spectral outputs are not supported here because they depend on an explicit shared parametric fit batch. When the family is executed through DescriptorPipeline, the shared planner provides that batch automatically.