pypillometry

Preprocessing, analysis and visualization of pupillometric and eye-tracking data in Python.

pip install pypillometry

pypillometry reads recordings from eye trackers (e.g., Eyelink EDF files), cleans them (blinks, artifacts, filtering), cuts them into event-related segments and plots the results. Pupil size and gaze position of one or both eyes are kept together in a single object, and every processing step is recorded in the object’s history.

Version 2 is a major rewrite and not compatible with version 1; the documentation of version 1 is still available. What is new in each version is listed in the changelog.

import pypillometry as pp
from pypillometry import u

d = pp.EyeData.from_eyelink("recording.edf")   # read an Eyelink file
d = (d | pp.pupil.blinks_detect()                # detect and mask blinks
       | pp.pupil.blinks_interpolate()           # interpolate them
       | pp.pupil.lowpass_filter(cutoff=4))      # 4 Hz low-pass filter

# average pupil response from 200 ms before to 1 s after each stimulus
epochs = d.get_epochs("stim", (-200, 1000) * u.ms)
erpd = d.get_segments(epochs, "left_pupil").pupil.baseline_correct((-200, 0))
erpd.pupil.plot()                                    # event-related pupil dilation
Getting started

Install the package and work through a ten-minute example from raw data to an event-related pupil response.

Getting started
User guide

The concepts behind the package: data objects, eyes and variables, units, events and intervals, preprocessing and plotting.

User guide
Tutorials

Worked examples as Jupyter notebooks that you can run in your browser.

Tutorials
API reference

Every class and function, with parameters, return values and examples.

API reference
Experimental features

Correction of pupil foreshortening, spatial calibration and regions of interest. Usable, but the API may change.

Experimental features
Development

Report bugs, contribute code and read the changelog.

Development

Features#

  • Reading data from Eyelink EDF and ASC files, saved pickle files, and whole studies from a local folder or OSF

  • Binocular data: pupil size and gaze of both eyes in one object

  • Blinks: detection, merging and interpolation (Mathôt, 2013)

  • Filtering: low-pass filtering, smoothing, downsampling, scaling

  • Events and intervals with flexible selection by label, function or time

  • Event-related pupil dilation for single subjects and groups

  • Units everywhere: 3 * u.min, "200 ms", 60 * u.cm

  • Interactive viewer for long recordings and command-line tools

  • Modeling of tonic baseline and phasic pupil responses (Mittner & Groot, 2025)

Citing pypillometry#

If you use pypillometry in your research, please cite

Mittner, M. (2020). pypillometry: A Python package for pupillometric analyses. Journal of Open Source Software, 5(51), 2348. https://doi.org/10.21105/joss.02348

If you use the estimation of tonic and phasic pupil components (Modeling the pupil signal), please also cite

Mittner, M., & Groot, J. M. (2025). A novel method for modeling tonic and phasic pupil dynamics in humans. Behavior Research Methods, 57(9), 233. https://doi.org/10.3758/s13428-025-02755-7