coco_pipe.decoding.foundation_models.extraction#

Reusable extraction and preflight utilities for EEG foundation models.

Classes#

CapabilityResult

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

FoundationEmbeddingResult

Window- and recording-level embeddings plus extraction provenance.

FoundationEmbeddingExtractor

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

Functions#

check_capability(model_key, train_mode[, sfreq, ...])

Check registry support and obvious signal incompatibilities without loading.

normalize_inclusive_endpoint(container, *, ...[, ...])

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

Module Contents#

class coco_pipe.decoding.foundation_models.extraction.CapabilityResult#

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

train_mode: str#
status: str#
reason: str = ''#
details: dict[str, Any]#
to_dict()#
Return type:

dict[str, Any]

coco_pipe.decoding.foundation_models.extraction.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.

Parameters:
Return type:

CapabilityResult

coco_pipe.decoding.foundation_models.extraction.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.

Parameters:
Return type:

tuple[coco_pipe.io.DataContainer | None, str | None]

class coco_pipe.decoding.foundation_models.extraction.FoundationEmbeddingResult#

Window- and recording-level embeddings plus extraction provenance.

window_embeddings: numpy.ndarray#
recording_embedding: numpy.ndarray#
window_start: numpy.ndarray#
window_stop: numpy.ndarray#
window_index: numpy.ndarray#
metadata: dict[str, Any]#
class coco_pipe.decoding.foundation_models.extraction.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.

Parameters:
backend = 'auto'#
device = 'auto'#
pooling = 'mean'#
recording_pooling = 'mean'#
normalize_embeddings = True#
resample = True#
cache_embeddings = False#
batch_size = None#
backend_kwargs#
model = None#
clear_cache()#

Drop all memoized window embeddings.

Return type:

None

extract(epochs, *, signal_metadata, window_start=None, window_stop=None, metadata=None)#

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

Parameters:
Return type:

FoundationEmbeddingResult