coco_pipe.descriptors.extractors._psd
=====================================

.. py:module:: coco_pipe.descriptors.extractors._psd

.. autoapi-nested-parse::

   Shared PSD computation for PSD-consuming descriptor paths.

   This module holds the reusable PSD step used by the descriptors planner and by
   PSD-consuming extractors when they need a standalone spectral input. It does
   not define descriptor semantics. It only:

   - prepare a writable runtime environment for MNE-backed PSD helpers
   - lazily import the MNE PSD functions used by descriptors
   - compute Welch or multitaper PSD batches on explicit NumPy inputs

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



Functions
---------

.. autoapisummary::

   coco_pipe.descriptors.extractors._psd.load_mne_psd_functions
   coco_pipe.descriptors.extractors._psd.compute_psd


Module Contents
---------------

.. py:function:: load_mne_psd_functions()

   Lazily import MNE PSD helpers with writable runtime cache locations.

   :returns: ``(psd_array_welch, psd_array_multitaper)`` imported from
             `mne.time_frequency`.
   :rtype: tuple

   .. rubric:: Notes

   MNE may write cache or config files during import/use. The descriptors
   module keeps those paths inside the system temp directory so PSD
   computation remains sandbox-friendly.


.. py:function:: compute_psd(X: numpy.ndarray, sfreq: float, method: str, fmin: float, fmax: float, n_jobs: int | None = None) -> tuple[numpy.ndarray, numpy.ndarray]

   Compute PSD values for one batch of segmented signals.

   :param X: Input array with shape ``(n_obs, n_channels, n_times)``.
   :type X: np.ndarray
   :param sfreq: Sampling frequency in Hertz.
   :type sfreq: float
   :param method: PSD estimator to use.
   :type method: {"welch", "multitaper"}
   :param fmin: Lower frequency bound passed to the PSD backend.
   :type fmin: float
   :param fmax: Upper frequency bound passed to the PSD backend.
   :type fmax: float
   :param n_jobs: Parallel worker count forwarded to the MNE PSD backend when the caller
                  enables PSD-level parallelism. `None` leaves the backend default in
                  place.
   :type n_jobs: int, optional

   :returns: PSD values with shape ``(n_obs, n_channels, n_freqs)`` and the aligned
             frequency grid with shape ``(n_freqs,)``.
   :rtype: tuple[np.ndarray, np.ndarray]

   .. rubric:: Notes

   For Welch PSDs, the descriptors module uses:

   - ``n_fft = min(n_times, 256)``
   - ``n_per_seg = n_fft``

   while enforcing a minimum of `8` for both values. This keeps Welch
   behavior bounded and deterministic across the current descriptor tests and
   examples.