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 outputs are derived from the periodic-only PSDs of the parametric fit batch that DescriptorPipeline shares between families. A band counts as periodic only where the fit placed a peak centre inside it; elsewhere every corrected output of that band is NaN (not measured), not zero.

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

Classes#

BandDescriptorExtractor

Spectral band descriptor extractor.

Module Contents#

class coco_pipe.descriptors.extractors.spectral.BandDescriptorExtractor(config, fit_config)#

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.

Variables:

  • config (BandDescriptorConfig) – Stored typed configuration for the spectral band 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 to extract_psd(), and the shared parametric fit batch when corrected outputs are requested.

family_name = 'bands'#
fit_config#
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()#

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()#

Whether corrected spectral outputs require a shared parametric fit.

Return type:

bool

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 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.

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

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.

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.