coco_pipe.descriptors.extractors.parametric =========================================== .. py:module:: coco_pipe.descriptors.extractors.parametric .. autoapi-nested-parse:: Parametric spectral descriptor extraction backend. This module implements the built-in parametric spectral 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 specparam-derived summary descriptors per sensor, per observation. .. rubric:: Notes The parametric 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 spectral band family. The actual descriptor outputs are then derived from that shared `psds, freqs` pair. Model fitting itself still happens one spectrum at a time. When runtime parallelism is enabled and the planner allows it, those per-spectrum fits can run in parallel across observation-channel units. Author: Hamza Abdelhedi (hamza.abdelhedi@umontreal.ca) Classes ------- .. autoapisummary:: coco_pipe.descriptors.extractors.parametric.ParametricDescriptorExtractor Module Contents --------------- .. py:class:: ParametricDescriptorExtractor(config: coco_pipe.descriptors.configs.ParametricDescriptorConfig) Bases: :py:obj:`coco_pipe.descriptors.extractors.base.BasePSDDescriptorExtractor` Parametric spectral descriptor extractor. This extractor fits one specparam model per observation and sensor in a validated descriptor input array, then exposes scalar summaries such as aperiodic parameters, fit quality, and dominant peak statistics. :param config: Parsed family configuration controlling the PSD method, fit range, specparam settings, and requested output groups. :type config: ParametricDescriptorConfig .. attribute:: config Stored typed configuration for the parametric family. :type: ParametricDescriptorConfig .. 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 and expects an explicit shared `fit_batch`. Standalone :meth:`extract` remains available for family-local PSD and fit computation. .. py:attribute:: family_name :value: 'parametric' .. py:attribute:: config .. py:property:: capabilities :type: dict[str, Any] Return static parametric extractor capability metadata. :returns: Capability metadata describing sampling-rate requirements and the optional backends used by the parametric family. :rtype: dict[str, Any] .. py:method:: psd_request() -> dict[str, Any] Describe the PSD requirements for the shared planner. .. 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 parametric 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: Parametric-family descriptor block aligned with the input observation axis. :rtype: _DescriptorBlock :raises ValueError: If ``fit_batch`` is not supplied. .. rubric:: Notes This method consumes explicit shared intermediates. It does not compute PSDs or fit models on its own. .. 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 parametric 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: Parametric-family descriptor block aligned with the input observation axis. :rtype: _DescriptorBlock :raises ImportError: If the optional `mne` or `specparam` backend is unavailable. :raises ValueError: If PSD computation encounters an invalid runtime condition. :raises RuntimeError: If shared fit materialization encounters a runtime failure and ``runtime.on_error == "raise"``. .. rubric:: Notes This standalone path computes a PSD for the current batch, fits one explicit parametric batch payload for this family, and then delegates to :meth:`extract_psd`. When the family is executed through `DescriptorPipeline`, the shared planner supplies the PSD and fit payload instead.