pyeeg.features.FeaturePipeline.extract

FeaturePipeline.extract(text: str, textgrid: TextGrid | None = None, signal_length: int | None = None) → Tuple[Dict[str, ndarray], Dict]

Extract features from text and optionally align to signal.

Runs every configured extractor over text and collects the resulting features. If no alignment is available (no textgrid and no configured alignment handler), the features are returned as word-position arrays; otherwise they are aligned to signal samples using the word intervals of the textgrid.

When syntactic extractors return per-word dicts, their entries are converted to word-position arrays of length len(text.split()).

Parameters:

• text (str) – Input text to process.

• textgrid (TextGrid, optional) – Optional Praat TextGrid providing word intervals for aligning features to the signal. If None and no alignment handler is configured, features are returned unaligned. If None but an alignment handler exists, a warning is logged and an empty TextGrid is used (yielding an empty aligned array).

• signal_length (int, optional) – Length of the neural signal in samples. If None, it is derived from the TextGrid end time and the alignment sampling rate.

Returns:

• result (dict of str -> ndarray) – Feature name to array mapping. Keys are "{extractor_name}_{feature}". When unaligned, each array has one entry per word (or per token for LLM token-level features). When aligned, each array has one entry per signal sample.

• metadata (dict) – Metadata describing the extraction: text (input text), text_length (character count), feature_specs (configured spec names), aligned (whether the features were aligned to a signal), and, when aligned, n_samples (number of aligned samples) and sampling_rate (sampling rate used).