pupeyes 0.3.4

PupEyes: Your Buddy for Pupil Size and Eye Movement Data Analysis

PupEyes: Your Buddy for Pupil Size and Eye Movement Data Analysis

Overview

PupEyes is a Python package for preprocessing and visualizing eye movement data. It handles pupil size preprocessing and supports interactive visualization of pupil size and fixation data. It was designed to streamline data preparation so you can analyze your data with ease and confidence.

Tutorials and API Reference

Preprint

Higlights

Best practices

The pupil data preprocessing pipeline is desgined based on the best practices available.

Pandas integration

Raw data is cleaned and prepared as a pandas dataframe, allowing you to enjoy the vast data analysis and manipulation methods offered by the pandas ecosystem.

Interactive interface

Multiple interactive visualizations using Plotly Dash allow you understand your data better.

Pupil Viewer: Examining Pupil Preprocessing Steps

Fixation Viewer: Visualize Fixation Patterns

AOI Drawing Tool: Flexibly Define AOIs

Installation

pip install pupeyes

or install the latest development version from Github

pip install git+https://github.com/HanZhang-psych/pupeyes.git

Documentation

Tutorials and API reference are available at Read the Docs.

Docker Container

Try PupEyes in a virtual environment!

# Clone the repository
git clone https://github.com/HanZhang-psych/pupeyes.git
cd pupeyes

# Start the Docker container
./start-pupeyes.sh start

# Access Jupyter Lab at http://localhost:8888

For detailed Docker instructions, see DOCKER_README.md.

Compatibility

While some PupEyes features are specific to Eyelink eye-trackers, many tools are compatible with any eye movement data.

Contributing

Please report bugs if you notice any. See the Contributing Guidelines for details on how to submit pull requests, report issues, and contribute to the project.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE.md file for details.

Citation

If you use PupEyes in your research, please cite our preprint

@misc{zhang_pupeyes_2025,
	title = {{PupEyes}: An Interactive Python Library for Pupil Size and Eye Movement Data Processing},
	url = {https://osf.io/h95ma_v1},
	doi = {10.31234/osf.io/h95ma_v1},
	shorttitle = {{PupEyes}},
	publisher = {{OSF}},
	author = {Zhang, Han and Jonides, John},
	urldate = {2025-04-16},
	date = {2025-04-07}
}

Changelog

See CHANGELOG.md for a list of changes in each release.

---

The project began as an attempt to formalize the eye-tracking processing scripts used in my past research. It then evolved into a much bigger project (as is always the case).

I hope PupEyes will be useful to the eye-tracking community!