Modeling the pupil signal

The pupil signal can be seen as the sum of a slowly changing (tonic) baseline and fast (phasic) responses to events. pypillometry implements the method described in Mittner & Groot (2025) to separate the two:

EyeData.pupil.estimate_baseline	Apply one of the baseline-estimation methods.
EyeData.pupil.estimate_response	Estimate pupil-response based on event-onsets, see pupil_response().

estimate_baseline() estimates the baseline as the lower envelope of the signal, fitted with B-splines through the troughs between events. estimate_response() then fits a pupil response function (Hoeks & Levelt, 1993) to every event in the signal that remains. Both store their results as new variables (baseline and response) next to the pupil data.

The response to one event, for a few values of its parameters (npar sets its shape, tmax the time of its peak):

A recording split into its baseline and the responses to the events:

The data must not contain missing samples, so blinks have to be interpolated first. The baseline is fitted with a model written in Stan and needs CmdStan (see Installation). The response model is fitted with non-negative least squares.

The underlying functions work on plain arrays and are listed in the API reference under Signal processing.

See the tutorial Modeling the pupillometric signal. The algorithm and simulation studies comparing it to the usual window-averaging approach are described in Mittner & Groot (2025). Please cite this paper if you use these methods.

References

• 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

• Hoeks, B., & Levelt, W. J. (1993). Pupillary dilation as a measure of attention: A quantitative system analysis. Behavior Research Methods, Instruments, & Computers, 25(1), 16–26. https://doi.org/10.3758/BF03204445