coco_pipe.decoding.foundation_models.extraction
===============================================

.. py:module:: coco_pipe.decoding.foundation_models.extraction

.. autoapi-nested-parse::

   Reusable extraction and preflight utilities for EEG foundation models.



Classes
-------

.. autoapisummary::

   coco_pipe.decoding.foundation_models.extraction.CapabilityResult
   coco_pipe.decoding.foundation_models.extraction.FoundationEmbeddingResult
   coco_pipe.decoding.foundation_models.extraction.FoundationEmbeddingExtractor


Functions
---------

.. autoapisummary::

   coco_pipe.decoding.foundation_models.extraction.check_capability
   coco_pipe.decoding.foundation_models.extraction.normalize_inclusive_endpoint


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

.. py:class:: CapabilityResult

   Preflight result for one model/training-mode/input combination.


   .. py:attribute:: train_mode
      :type:  str


   .. py:attribute:: status
      :type:  str


   .. py:attribute:: reason
      :type:  str
      :value: ''



   .. py:attribute:: details
      :type:  dict[str, Any]


   .. py:method:: to_dict()


.. py:function:: check_capability(model_key, train_mode, sfreq = None, ch_names = None, n_times = None, backend = 'auto', backend_kwargs = None)

   Check registry support and obvious signal incompatibilities without loading.


.. py:function:: normalize_inclusive_endpoint(container, *, segment_duration, expected_sfreq, model_key = 'model', on_mismatch = 'error')

   Drop MNE's inclusive-endpoint extra sample from epoched windows.

   MNE epochs span ``[tmin, tmax]`` inclusively, yielding ``expected_n_times +
   1`` samples; foundation backends want the half-open count. This trims the
   trailing sample (recording it in ``meta``) when the off-by-one is observed,
   so ``prepare`` does not raise on the mismatch.

   Returns ``(container, None)`` when the window is already correct or was
   normalized. On any other length mismatch, returns ``(None, reason)`` if
   ``on_mismatch == "skip"`` and otherwise raises ``ValueError``.


.. py:class:: FoundationEmbeddingResult

   Window- and recording-level embeddings plus extraction provenance.


   .. py:attribute:: window_embeddings
      :type:  numpy.ndarray


   .. py:attribute:: recording_embedding
      :type:  numpy.ndarray


   .. py:attribute:: window_start
      :type:  numpy.ndarray


   .. py:attribute:: window_stop
      :type:  numpy.ndarray


   .. py:attribute:: window_index
      :type:  numpy.ndarray


   .. py:attribute:: metadata
      :type:  dict[str, Any]


.. py:class:: FoundationEmbeddingExtractor(model_key, *, backend = 'auto', device = 'auto', pooling = 'mean', recording_pooling = 'mean', normalize_embeddings = True, resample = True, cache_embeddings = False, batch_size = None, backend_kwargs = None, model = None)

   Compose model loading, metadata binding, extraction, and pooling.


   .. py:attribute:: backend
      :value: 'auto'



   .. py:attribute:: device
      :value: 'auto'



   .. py:attribute:: pooling
      :value: 'mean'



   .. py:attribute:: recording_pooling
      :value: 'mean'



   .. py:attribute:: normalize_embeddings
      :value: True



   .. py:attribute:: resample
      :value: True



   .. py:attribute:: cache_embeddings
      :value: False



   .. py:attribute:: batch_size
      :value: None



   .. py:attribute:: backend_kwargs


   .. py:attribute:: model
      :value: None



   .. py:method:: clear_cache()

      Drop all memoized window embeddings.



   .. py:method:: extract(epochs, *, signal_metadata, window_start = None, window_stop = None, metadata = None)

      Extract one embedding per input window and one pooled recording vector.