EyeFeatures Logo

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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Metadata

Release files for eyefeatures 2.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for eyefeatures 2.0.2
File	Size	Uploaded	Provenance
eyefeatures-2.0.2.tar.gz	87.3 kB	Mar 18, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for eyefeatures 2.0.2
File	Interpreter	ABI	Platform	Reset
eyefeatures-2.0.2-py3-none-any.whl 92.6 kB Mar 18, 2026 Without provenance	Python 3	none	any	Details

Total release size: 179.9 kB

Release files / eyefeatures-2.0.2.tar.gz

Download URL	eyefeatures-2.0.2.tar.gz
Size	87.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`31f070f7d491691757bb1977f5a2d77dfa134cf835109d6678e2d55eeaaccd79`
BLAKE2b-256 checksum How to use checksums	`e01232b504a37b0c68b49bd7a196fe17a44797feb6558d0d9e923961b6032683`
Upload date	Mar 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.8.3 CPython/3.9.5 Linux/6.17.0-19-generic`

Release files / eyefeatures-2.0.2-py3-none-any.whl

Download URL	eyefeatures-2.0.2-py3-none-any.whl
Size	92.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`429cf99b732293f7592605cd4785bc0390842dd140e97c4ef05718094ba92b14`
BLAKE2b-256 checksum How to use checksums	`87bf2ae54375b670cf5aaf3c170c9acc9a11c4c1210364e9248218fbaf1ecf17`
Upload date	Mar 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.8.3 CPython/3.9.5 Linux/6.17.0-19-generic`

Security for eyefeatures 2.0.2

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.