.. currentmodule:: pypillometry

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. :mod:`pypillometry`
implements the method described in Mittner & Groot (2025) to separate the
two:

.. autosummary::
   :nosignatures:

   EyeData.pupil.estimate_baseline
   EyeData.pupil.estimate_response

:meth:`~EyeData.pupil.estimate_baseline` estimates the baseline as the
lower envelope of the signal, fitted with B-splines through the troughs
between events. :meth:`~EyeData.pupil.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):

.. plot::
   :include-source: False

   fig, ax = plt.subplots(figsize=(6, 3.2))
   for npar, tmax in [(10.1, 930), (5, 930), (10.1, 600)]:
       k = pp.signal.pupil_kernel(duration=4000, fs=1000, npar=npar, tmax=tmax)
       ax.plot(np.arange(len(k)), k / k.max(), label=f"npar={npar}, tmax={tmax} ms")
   ax.set_xlabel("time after the event (ms)")
   ax.set_ylabel("response (scaled)")
   ax.legend(fontsize=8, frameon=False)
   fig.tight_layout()

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

.. image:: ../images/modeling_baseline_response.png
   :alt: pupil, estimated baseline, and baseline plus responses

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 :doc:`/getting_started/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 :doc:`/api/signal`.

See the tutorial :doc:`/notebooks/modeling`. 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