Installation

pypillometry requires Python 3.11 or newer. Released versions are on PyPI:

pip install pypillometry

The dependencies are installed automatically.

Development version

The latest version from GitHub:

pip install git+https://github.com/ihrke/pypillometry.git

Editable install

To work on the code yourself (see Development), clone the repository and install it in editable mode, together with the test dependencies:

git clone https://github.com/ihrke/pypillometry.git
cd pypillometry
pip install -e ".[test]"

Conda environment

It is a good idea to install the package into its own environment, e.g., with conda:

conda create -n pypil python=3.13
conda activate pypil
pip install pypillometry

Python’s built-in virtual environments work as well.

To check that everything works, load one of the bundled example datasets:

import pypillometry as pp
d = pp.get_example_data("rlmw_002_short")
print(d)

Dependencies

All of these are installed with the package (see pyproject.toml):

• numpy, scipy, pandas and matplotlib for numerical work and plotting

• eyelinkio for reading Eyelink EDF files

• PyQt5 and vispy for the interactive viewer

• cmdstanpy for the baseline model (see below)

• loguru for logging

Saved files are compressed with zstd, which is part of the standard library from Python 3.14. On older Python versions, the backports.zstd package is installed instead.

Jupyter is not required, but most examples in this documentation are notebooks and the package works well in them (objects display as tables, plots appear inline).

CmdStan (optional)

The baseline estimation (estimate_baseline(), see Modeling the pupil signal) uses the probabilistic programming language Stan through cmdstanpy. Apart from the Python package, it needs the CmdStan command-line tools, which are not installed automatically. If you need them, install CmdStan as described in the CmdStanPy documentation, e.g.:

import cmdstanpy
cmdstanpy.install_cmdstan()

All other parts of pypillometry work without CmdStan.

Upgrading from version 1

Version 2 is a major rewrite and scripts written for version 1 will not run without changes. The main differences:

• The data class is now EyeData (see Data objects). It holds both eyes and several variables (pupil, x, y) at the same time.

• Most methods were renamed, e.g. blinks_detect() is now blinks_detect() and lowpass_filter() is lowpass_filter().

• ERPDs are created with get_epochs() and get_segments() (see Event-related pupil dilations).

Version 1 is still available on the v1 branch and its documentation is here. You can install it with pip install "pypillometry<2".