Features module

Stimulus Feature Extraction Module

This module provides tools for extracting features from various types of stimuli: - Text: LLM-based features (surprisal, entropy, KL divergence) - Text: Syntactic features (depth, closing nodes, etc.) - Audio: Acoustic features (envelope, filterbank, gammatone) - Audio: Alignment with transcripts

Main Classes: - LLMFeatureExtractor: Extract word-level features using language models - SyntacticFeatureExtractor: Extract features from constituency trees - AcousticFeatureExtractor: Extract envelope, filterbank, gammatone features - AlignmentHandler: Handle alignment between stimuli and neural data - FeaturePipeline: Compose multiple feature extractors - StimulusEncoder: High-level interface for feature extraction - FeatureReducer: PCA/ICA dimensionality reduction

Classes

SyntacticFeatureExtractor([config])

Extract syntactic features from text using constituency parsing.

AlignmentHandler([signal_sampling_rate])

Handle alignment between word-level features and neural signals.

TextGridParser()

Parser for Praat TextGrid files.

FeaturePipeline(config)

Pipeline for extracting and aligning multiple features from stimuli.

FeatureReducer(config)

Reduce the dimensionality of feature sets.

Note

LLMFeatureExtractor (and its LLMFeatureConfig) live in pyeeg.features.llm_features, which requires torch. Install the optional [features] extra (pip install natmeeg[features]) to use and auto-document the LLM feature extraction classes. They are omitted from the autosummary below so the docs build succeeds in environments without torch.

The following dataclasses are defined in the pyeeg.features.alignment submodule:

Interval(start, end, label, tier)

Represents an interval (tier item) in a TextGrid file.

TextGrid(intervals, ...)

Represents a TextGrid file with multiple tiers.

The following dataclasses are defined in the pyeeg.features.pipeline submodule:

FeatureSpec(name, extractor_type, features, ...)

Specification for a feature to be extracted.

PipelineConfig(feature_specs, ...)

Configuration for the feature extraction pipeline.

The following dataclasses are defined in the pyeeg.features.reduction submodule:

ReductionConfig([method, n_components, ...])

Configuration for feature reduction.

The following dataclasses are defined in the pyeeg.features.syntactic_features submodule:

ParserConfig([parser_name, parser_path, ...])

Configuration for the external constituency parser.