coco_pipe.descriptors.extractors.base#

Base interfaces for descriptor extraction backends.

This module defines the internal contracts shared by built-in descriptor extractors. The module exposes:

  • BaseDescriptorExtractor, shared by all families; families that read the raw signal (complexity) add extract()

  • BasePSDDescriptorExtractor for families that consume shared PSD batches

  • _DescriptorBlock as the private family output payload

  • make_failure_record as the shared normalized failure-record helper

The surrounding descriptors stack uses these interfaces to provide:

  • explicit runtime dispatch from DescriptorPipeline

  • deterministic sensor-level descriptor naming

  • family-wise metadata and failure collection

  • safe merging of family outputs into one stable result dictionary

Notes

BaseDescriptorExtractor is an internal extension point for descriptor families. Unlike dim-reduction reducers, descriptor extractors are stateless at runtime and do not expose fit, persistence, or model objects.

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

Classes#

BaseDescriptorExtractor

Base class for descriptor extraction families.

BasePSDDescriptorExtractor

Abstract base class for descriptor families that consume PSD batches.

Functions#

make_failure_record(family, obs_index[, obs_id, ...])

Create one normalized extractor failure record.

Module Contents#

coco_pipe.descriptors.extractors.base.make_failure_record(family, obs_index, obs_id=None, channel_index=None, channel_name=None, exception_type=None, message=None)#

Create one normalized extractor failure record.

Parameters:

  • family (str)

  • obs_index (int)

  • obs_id (Any)

  • channel_index (int | None)

  • channel_name (str | None)

  • exception_type (str | None)

  • message (str | None)

Return type:

dict[str, Any]

class coco_pipe.descriptors.extractors.base.BaseDescriptorExtractor(config)#

Base class for descriptor extraction families.

Subclasses receive already validated NumPy inputs and return one _DescriptorBlock aligned on the observation axis. Families that read the raw signal define extract(); PSD families derive from BasePSDDescriptorExtractor instead. The base class keeps the extractor API narrow and provides a shared helper for sensor-level finalization and deterministic descriptor naming.

Parameters:

config (Any) – Typed family configuration parsed by DescriptorConfig.

Variables:

  • config (Any) – Stored family-specific configuration object.

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

Notes

Extractors are stateless at runtime. They do not learn parameters across calls; all runtime state is passed explicitly.

Concrete extractors are expected to:

  1. compute family-specific values with shape (n_obs, n_channels) for each metric

  2. pass those values through _finalize_descriptor()

  3. return one _DescriptorBlock with aligned names, metadata, and failures

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

Return static extractor capability metadata.

Returns:

Static metadata describing optional dependencies and general execution properties for the extractor.

Return type:

dict[str, Any]

Notes

The descriptors pipeline currently uses this mapping only as lightweight backend metadata. It is intentionally much smaller than the reducer capability surface in dim_reduction.

class coco_pipe.descriptors.extractors.base.BasePSDDescriptorExtractor(config)#

Bases: BaseDescriptorExtractor, abc.ABC

Abstract base class for descriptor families that consume PSD batches.

PSD-consuming families still participate in the shared descriptor contract, but they expose one additional explicit entry point:

  • extract_psd(…) consumes precomputed psds, freqs

  • psd_request() tells the planner which PSD range and method is needed

This keeps the generic raw-signal interface narrow while still giving the planner one formal PSD-consumer contract shared by spectral and parametric families.

Parameters:

config (Any)

abstractmethod psd_request()#

Describe the PSD requirements for the shared planner.

Returns:

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

Return type:

dict[str, Any]

parametric_fit_requirements()#

Describe whether this PSD consumer needs a shared parametric fit.

Returns:

Shared-fit requirements with the keys:

  • needed

  • metrics

  • periodic_psds

  • config

Return type:

dict[str, Any]

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

Extract descriptors from explicit PSD intermediates.

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.

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

  • ids (np.ndarray, optional) – Observation identifiers aligned with the observation axis.

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

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

  • fit_batch (Any, optional) – Additional shared fit payload required by some PSD consumers.

Returns:

Family-specific descriptor block aligned with the input PSD batch.

Return type:

_DescriptorBlock