coco_pipe.descriptors.extractors.spectral ========================================= .. py:module:: coco_pipe.descriptors.extractors.spectral .. autoapi-nested-parse:: 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. .. rubric:: 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 :meth:`extract_psd`. Author: Hamza Abdelhedi (hamza.abdelhedi@umontreal.ca) Classes ------- .. autoapisummary:: coco_pipe.descriptors.extractors.spectral.BandDescriptorExtractor Module Contents --------------- .. py:class:: BandDescriptorExtractor(config: coco_pipe.descriptors.configs.BandDescriptorConfig, fit_config=None) Bases: :py:obj:`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. :param config: Parsed family configuration controlling the PSD method, frequency window, band definitions, and requested spectral outputs. :type config: BandDescriptorConfig .. attribute:: config Stored typed configuration for the spectral band family. :type: BandDescriptorConfig .. attribute:: family_name Stable family identifier used in metadata and failure records. :type: str .. rubric:: Notes The extractor always computes descriptor values per sensor first. Public sensor-level naming is applied afterward through :meth:`BaseDescriptorExtractor._finalize_descriptor`. When the pipeline provides a precomputed PSD batch through :meth:`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`. .. py:attribute:: family_name :value: 'bands' .. py:attribute:: config .. py:attribute:: fit_config :value: None .. py:property:: capabilities :type: 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. :rtype: dict[str, Any] .. rubric:: Notes Spectral band extraction always requires an explicit sampling rate because the PSD frequency axis depends on it. .. py:method:: psd_request() -> dict[str, Any] Describe the PSD requirements for the shared planner. :returns: Minimal PSD request containing the PSD method and the required frequency range for this family. :rtype: dict[str, Any] .. rubric:: Notes `DescriptorPipeline` uses this request to group compatible PSD consumers and decide when one batch-scoped PSD can be reused across families. .. py:method:: needs_parametric_fit() -> bool Whether corrected spectral outputs require a shared parametric fit. .. py:method:: parametric_fit_requirements() -> dict[str, Any] Describe whether this family needs shared parametric-fit outputs. .. py:method:: 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 Extract band descriptors from a precomputed PSD batch. :param psds: Power spectral density array with shape ``(n_obs, n_channels, n_freqs)``. :type psds: np.ndarray :param freqs: Frequency grid aligned with the last axis of ``psds``. :type freqs: np.ndarray :param channel_names: Explicit channel labels aligned with axis 1 of ``psds``. If omitted, fallback names ``"ch-0"``, ``"ch-1"``, ... are used internally. :type channel_names: list of str, optional :param ids: Observation identifiers aligned with axis 0 of ``psds``. :type ids: np.ndarray, optional :param runtime: Runtime execution controls shared across descriptor families. :type runtime: DescriptorRuntimeConfig :param obs_offset: Global observation offset added to any collected failure records when this extractor is called on one observation batch. :type obs_offset: int, default=0 :returns: Spectral-family descriptor block aligned with the input observation axis. :rtype: _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``. .. rubric:: 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. .. rubric:: 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``. .. py:method:: 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 Extract band descriptors from segmented multi-channel data. :param X: Input array with shape ``(n_obs, n_channels, n_times)``. Each row already represents one observation segment produced upstream. :type X: np.ndarray :param sfreq: Sampling frequency in Hertz. :type sfreq: float, optional :param channel_names: Explicit channel labels aligned with axis 1 of ``X``. :type channel_names: list of str, optional :param ids: Observation identifiers aligned with axis 0 of ``X``. :type ids: np.ndarray, optional :param runtime: Runtime execution controls shared across descriptor families. :type runtime: DescriptorRuntimeConfig :param obs_offset: Global observation offset added to any collected failure records. :type obs_offset: int, default=0 :returns: Spectral-family descriptor block aligned with the input observation axis. :rtype: _DescriptorBlock .. rubric:: Notes This is the standalone extraction path for raw spectral outputs. It computes a PSD for the provided batch and then delegates to :meth:`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.