coco_pipe.descriptors.extractors.complexity#

Complexity descriptor extraction backend.

This module implements the built-in complexity 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 complexity measures per sensor, per observation.

Notes

The complexity family prefers batched backend calls when the selected library supports them. In the current implementation:

  • spectral_entropy, hjorth_mobility, and hjorth_complexity use batched antropy calls over flattened observation-channel units

  • sample_entropy, perm_entropy, approx_entropy, svd_entropy, petrosian_fd, katz_fd, higuchi_fd, and lziv_complexity are still evaluated one 1D signal at a time

  • shannon_entropy, fuzzy_entropy, dispersion_entropy, and hurst_exponent use scalar neurokit2 calls

  • zero_crossings, kurtosis, and rms are computed as simple scalar channelwise signal descriptors

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

Classes#

ComplexityDescriptorExtractor

Complexity descriptor extractor.

Module Contents#

class coco_pipe.descriptors.extractors.complexity.ComplexityDescriptorExtractor(config)#

Bases: coco_pipe.descriptors.extractors.base.BaseDescriptorExtractor

Complexity descriptor extractor.

This extractor computes scalar complexity measures 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 (ComplexityDescriptorConfig) – Parsed family configuration controlling the selected measures, backend, and any per-measure keyword arguments.

Variables:

  • config (ComplexityDescriptorConfig) – Stored typed configuration for the complexity family.

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

Notes

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

When backend=”auto” is selected, the extractor resolves each measure to the preferred available implementation:

  • antropy for the existing antropy-backed measures

  • neurokit2 for measures that are only supported there

  • built-in NumPy/SciPy implementations for simple scalar signal summaries

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

Return static complexity extractor capability metadata.

Returns:

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

Return type:

dict[str, Any]

Notes

spectral_entropy requires an explicit sampling rate, while the other currently supported measures do not.

extract(X, sfreq, channel_names, ids, runtime, obs_offset=0)#

Extract complexity 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. Required when spectral_entropy is requested.

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

  • 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 when this extractor is called on one observation batch.

Returns:

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

Return type:

_DescriptorBlock

Raises:

  • ImportError – If the configured optional backend is unavailable.

  • ValueError – If a requested measure is unsupported by the selected backend, or if runtime error handling is configured to raise on a numerical or backend failure.

Notes

The extractor uses a mixed execution strategy:

  • batched antropy calls for spectral_entropy, hjorth_mobility, and hjorth_complexity

  • scalar antropy calls for the remaining antropy-backed measures

  • scalar neurokit2 calls for shannon_entropy, fuzzy_entropy, dispersion_entropy, and hurst_exponent

Non-finite outputs are converted to NaN and recorded under failures unless runtime.on_error == “raise”, in which case the extractor fails immediately.

Example

With channel_names=["Fz", "Cz"], a requested measure such as perm_entropy yields channel-resolved names like complexity_perm_entropy_ch-Fz and complexity_perm_entropy_ch-Cz.