Skip to main content

pypillometry logo

pypillometry

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

PyPI version Python versions tests coverage documentation
JOSS paper DOI license

Documentation · Quickstart · Tutorials · API reference


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.

Raw and cleaned pupil data, and the average pupil response to 300 stimuli

Installation

pip install pypillometry

pypillometry requires Python 3.11 or newer. See the installation guide for the development version and conda environments.

Quick example

From raw data to an event-related pupil response, using one of the bundled example datasets:

import pypillometry as pp
from pypillometry import u

d = pp.get_example_data("rlmw_002")     # or: pp.EyeData.from_eyelink("recording.edf")
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

# pupil response from 500 ms before to 2.5 s after each stimulus
epochs = d.get_epochs("S_", (-500, 2500) * u.ms)
erpd = d.get_segments(epochs, "left_pupil").pupil.baseline_correct((-500, 0))
erpd.pupil.plot()

The quickstart walks through this example step by step.

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)

Interactive viewer and command-line tools

pp.view(d) opens a fast, zoomable viewer for long recordings; pp.tweak() lets you adjust preprocessing parameters while watching the result. The same viewer is available from the command line:

pypilview recording.edf            # view an Eyelink file or a saved object
edf2pypil recording.edf            # convert EDF once, load much faster later
pypilinfo data/*.pkl               # print a summary of one or more files
pypil-upgrade -i data/             # convert files saved with older versions

The pypilview viewer showing pupil size and gaze of both eyes

See interactive tools and command-line programs in the documentation.

Coming from version 1?

Version 2 is a major restructuring: it handles eye-tracking data in addition to pupillometry, and more than one eye at a time. Scripts written for version 1 need to be updated (see the changelog). Version 1 is still available on the v1 branch, with its documentation, and can be installed with pip install "pypillometry<2".

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, 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

Contributing

Bug reports and feature requests are welcome on the issue tracker. See the development guide for how to contribute code.

pypillometry is maintained by Matthias Mittner (matthias.mittner@uit.no) and released under the MIT license.

Metadata

Release files for pypillometry 2.2.1

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

Source distribution (sdist)

Source distribution for pypillometry 2.2.1
File Size Uploaded Provenance Actions
pypillometry-2.2.1.tar.gz 2.9 MB Without provenance Details for pypillometry-2.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pypillometry 2.2.1
File Interpreter ABI Platform Actions
pypillometry-2.2.1-py3-none-any.whl Python 3 none any Details for pypillometry-2.2.1-py3-none-any.whl

Total release size: 3.6 MB

Release files / pypillometry-2.2.1.tar.gz

Download URL pypillometry-2.2.1.tar.gz
Size 2.9 MB
Tags Source
SHA-256 checksum
How to use checksums
a46a462ca4029776367eadd3ccb984417802b9bab2780cad7ef4a6b6643ffe8f
BLAKE2b-256 checksum
How to use checksums
494fb2c61b91ec228b4184e779b45e0328d3593a4f372b82484f467b4a47111e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.18

Release files / pypillometry-2.2.1-py3-none-any.whl

Download URL pypillometry-2.2.1-py3-none-any.whl
Size 620.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a890b6897f697d61bbdc149e4c49454e1373b3426040f1d0a34b6d9d483e0024
BLAKE2b-256 checksum
How to use checksums
b4cc7728e0320c3b0151e5c31a299cdb74246e6e4b3beb0e4faa80ae215ddfa1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.18

Security for pypillometry 2.2.1

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page