eyefeatures 2.0.2

Preprocessing, visualization, statistical analysis, feature engineering, and machine learning of eye movement data.

EyeFeatures

EyeFeatures is an end-to-end Python library for eye-tracking data analysis, designed to make eye-tracking research accessible to developers and scientists alike. From raw gaze preprocessing to complex feature engineering and deep learning, eyefeatures provides a unified, production-ready framework.

Key Features

• Scikit-learn Integration: All transformers follow the fit/transform API and work seamlessly with sklearn.Pipeline.
• PyTorch-Ready: Native PyTorch Dataset classes and neural network modules (CNN, LSTM, GNN, ViT) for gaze-based classification.
• Scanpath Visualizations: Static and animated scanpath plots, heatmaps, and AOI overlays.
• 50+ Methods: Extensive library of preprocessing, statistical, complexity, and distance-based features.
• Group Analysis: Built-in support for individual normalization and group-level comparisons.

Installation

pip install eyefeatures

Check Contribution page in the documentation for installation with poetry.

Documentation & Tutorials

Check out our Full Documentation and the following interactive tutorials:

• 🚀 Quickstart Examples
• 📊 Simple Features
• 🧠 Feature Maps & Timeseries
• 🛠️ Preprocessing
• 🧿 AOI Definition
• 🎥 Visualization
• ⚡ Deep Learning

Datasets collection

All datasets in data/collection/ folder are available for download via Git LFS:

git lfs install
git lfs pull

The collection is also available at Google Drive.

Collection experiments

The collection_experiments folder contains reproducible pipelines that use the library on collection data (data/collection):

See experiments/collection_experiments/README.md for more details.

Supported Methods

Check a comprehensive list of all methods.

🔧 Preprocessing

Fixation Extraction

Method	Description	Docs
Velocity Threshold Identification (I-VT)	Velocity-based fixation detection. O(n) complexity.	IVT
Dispersion Threshold Identification (I-DT)	Dispersion-based fixation detection. O(n log n) avg.	IDT
Hidden Markov Model Identification (I-HMM)	Probabilistic fixation detection via Viterbi algorithm	IHMM

Smoothing Filters

Method	Description	Docs
Savitzky-Golay Filter	Polynomial smoothing filter	SavGolFilter
Finite Impulse Response Filter (FIR)	Convolution with FIR kernel	FIRFilter
Infinite Impulse Response Filter (IIR)	Convolution with IIR kernel	IIRFilter
Wiener Filter	Noise reduction filter using spectral estimation	WienerFilter

Blink Detection

Method	Description	Docs
Pupil Missing Detection	Blink detection via missing pupil data	detect_blinks_pupil_missing
Pupil Velocity Threshold	Blink detection via pupil size velocity	detect_blinks_pupil_vt
Eye Openness Detection	Blink detection via eye openness signal	detect_blinks_eo

Area of Interest (AOI) Extraction

Method	Description	Docs
Shape-Based AOI	Define AOI using predefined shapes (rect, circle, polygon)	ShapeBased
Threshold-Based AOI	Density-based AOI using local maxima and KMeans	ThresholdBased
Gradient-Based AOI	AOI extraction via gradient magnitude	GradientBased
Overlap Clustering AOI	AOI via overlapping fixation clusters	OverlapClustering
AOI Extractor	Meta-extractor selecting lowest entropy partition	AOIExtractor

📊 Feature Engineering

Statistical Features

Method	Description	Docs
Fixation Features	Duration, dispersion, VAD statistics	FixationFeatures
Saccade Features	Length, speed, direction/rotation angles	SaccadeFeatures
Regression Features	Features for regressive (backward) saccades	RegressionFeatures
Micro-Saccade Features	Statistics for small fixation-related saccades	MicroSaccadeFeatures

Measures

Method	Description	Docs
Hurst Exponent	Long-term memory measure via R/S analysis	HurstExponent
Shannon Entropy	Gaze distribution uncertainty over AOIs	ShannonEntropy
Spectral Entropy	Frequency-domain complexity via PSD	SpectralEntropy
Fuzzy Entropy	Robust entropy with fuzzy membership	FuzzyEntropy
Sample Entropy	Irregularity/complexity of scanpath	SampleEntropy
Incremental Entropy	Average entropy as exploration evolves	IncrementalEntropy
Gridded Distribution Entropy	Spatial entropy over a grid	GriddedDistributionEntropy
Phase Entropy	Phase space trajectory complexity	PhaseEntropy
Lyapunov Exponent	Chaos indicator via trajectory divergence	LyapunovExponent
Fractal Dimension	Box-counting dimension of scanpath	FractalDimension
Correlation Dimension	Attractor dimensionality measure	CorrelationDimension
RQA Measures	Recurrence Quantification (REC, DET, LAM, CORM)	RQAMeasures
Saccade Unlikelihood	Negative log-likelihood of saccade transitions	SaccadeUnlikelihood
Hilbert-Huang Transform	Features from Empirical Mode Decomposition	HHTFeatures

Scanpath Distance Metrics

Method	Description	Docs
Euclidean Distance	Point-to-point distance	EucDist
Hausdorff Distance	Max distance between point sets	HauDist
Dynamic Time Warping	Time-invariant scanpath similarity	DTWDist
Discrete Fréchet Distance	Shape-based curve similarity	DFDist
ScanMatch	String-based scanpath comparison	ScanMatchDist
MultiMatch	Multi-dimensional scanpath comparison	MultiMatchDist
Mannan Distance	Fixation position similarity	MannanDist
EyeAnalysis Distance	Fixation-based scanpath comparison	EyeAnalysisDist
Time Delay Embedding Distance	Phase-space reconstruction similarity	TDEDist

Feature Maps

Method	Description	Docs
Heatmap	Aggregated gaze density visualization	get_heatmap
Markov Transition Field	Temporal dynamics as transition probabilities	get_mtf
Gramian Angular Field	Polar encoding of time series	get_gaf
Recurrence Plot	Visual representation of dynamical systems	get_rqa
Hilbert Curve Mapping	Space-filling curve for 2D→1D mapping	get_hilbert_curve

Normalization

Method	Description	Docs
Individual Normalization	Group-relative feature scaling	IndividualNormalization

🤖 Deep Learning

Datasets

Method	Description	Docs
Gaze Dataset	PyTorch Dataset for gaze sequences	GazeDataset
Time Series Dataset	PyTorch Dataset for 2D time series	TimeSeriesDataset
Graph Dataset	PyTorch Geometric Dataset for scanpaths	GraphDataset

Models

Method	Description	Docs
CNN Model	Convolutional Neural Network for gaze classification	CNNModel
LSTM Model	Recurrent model for sequential gaze data	LSTMModel
GNN Model	Graph Neural Network for scanpath analysis	GNNModel
Vision Transformer	Attention-based model for gaze images	ViTModel

🎨 Visualization

Static Plots

Method	Description	Docs
Static Scanpath Plot	Static visualization of eye movements	static_scanpath_plot
Heatmap Visualization	Gaze density heatmap plot	heatmap_plot
AOI Visualization	Area of Interest overlay plot	aoi_plot

Animated Plots

Method	Description	Docs
Dynamic Scanpath Animation	Animated visualization of scanpaths	dynamic_scanpath_plot

📁 Data

Utilities to list and load benchmark datasets (Parquet), with column conventions for keys, labels, and meta. API