Categorization for Eyetracking in Python

This repository was developed for Peter König's Neurobiopsychology Lab at the Institute of Cognitive Science, Osnabrück. Its aim is to provide easy access to different automated gaze classification algorithms and to generate a unified, simplistic, and elegant way of handling Eyetracking data.

Currently available gaze classification algorithms are:

  • NSLR-HMM: Pekkanen, J., & Lappi, O. (2017). A new and general approach to signal denoising and eye movement classification based on segmented linear regression. Scientific reports, 7(1), 1-13.
  • REMoDNaV: Dar *, A. H., Wagner *, A. S. & Hanke, M. (2019). REMoDNaV: Robust Eye Movement Detection for Natural Viewing. bioRxiv. DOI: 10.1101/619254
  • I-DT dispersion-based algorithm: Salvucci, D. D., & Goldberg, J. H. (2000). Identifying fixations and saccades in eye-tracking protocols. In Proceedings of the 2000 symposium on Eye tracking research & applications.
  • I-VT velocity-based algorithm: Salvucci, D. D., & Goldberg, J. H. (2000). Identifying fixations and saccades in eye-tracking protocols. In Proceedings of the 2000 symposium on Eye tracking research & applications.

Of course we will aim to include more gaze classification algorithms in the future. Suggestions and links to implementations are always welcome.

Installation

Currently, the way to install the package is:

pip install git+https://github.com/DiGyt/cateye.git

However, proper PyPI support might follow.

Examples

CatEye is intended to work on a simple and intuitive level. This includes reducing all the overhead from external classification algorithms and relying on fundamental Python objects that can be used with whatever data format and workflow you are working.

classification = cateye.classify_nslr_hmm(times, gaze_x, gaze_y)

CatEye also provides simple but flexible plotting functions which can be used to visualize classified gaze data and can be further customized with matplotlib.pyplot.

fig, axes = plt.subplots(2, figsize=(15, 6), sharex=True) cateye.plot_segmentation(gaze_x, times, classification, events, ax=axes[0], show_event_text=False, show_legend=False) cateye.plot_segmentation(gaze_y, times, classification, events, ax=axes[1]) axes[0].set_ylabel("Theta (in degree)") axes[1].set_ylabel("Phi (in degree)") axes[1].set_xlabel("Time in seconds");

CatEye segmentation plot

To get started, we recommend going through our example notebooks. You can simply run them via your internet browser (on Google Colab's hosted runtime) by clicking on the "open in Colab" button.


Minimal use example

This minimal example applies the NSLR-HMM algorithm to a simple 2D gaze array and plots the results using the cateye plotting functions.

Open in Colab

Pandas workflow example

This notebook gives a more extensive example on CatEye, including data organisation and manipulation with pandas (including e.g. resampling, interpolating, median-boxcar-filtering). The NSLR-HMM and REMoDNaV classification algorithms are applied and visualized using different internal and external plotting functions.

Open in Colab

Documentation

CatEye's documentation is created using pdoc3 and GitHub Pages. Click on the link below to view the documentation.

Documentation

GitHub

GitHub - DiGyt/cateye: Unified Categorization for Eyetracking
Unified Categorization for Eyetracking. Contribute to DiGyt/cateye development by creating an account on GitHub.