baseline_envelope_iter_bspline#

pypillometry.signal.baseline_envelope_iter_bspline(tx, sy, event_onsets, fs, fsd=10, lp=2, lam_sig=1, lam_min=1, lam_max=100, verbose=0, seed=None)[source]#

Extract baseline based on (re-)estimating the lower envelope using B-splines. The signal is downsampled (to fsd Hz) for speed.

The B-spline fits are done with a Stan model (baseline_model_asym_laplac.stan, variational inference via cmdstanpy); in between, the event-related responses are estimated with pupil_response() (fixed npar=10, tmax=917) and removed before the second round of peak detection.

Parameters:

  • tx (np.ndarray) – time-vector in milliseconds

  • sy (np.ndarray) – raw pupil signal (must not contain NaN)

  • event_onsets (np.ndarray) – onsets of events (stimuli/responses) in milliseconds

  • fs (float) – sampling rate in Hz

  • fsd (float) – downsampled sampling rate in Hz (if too slow, decrease)

  • lp (float) – lowpass-filter cutoff in Hz (applied before downsampling)

  • lam_sig (float) – parameter steering how much the baseline is shaped by the non-peaks of the signal

  • lam_min (float) – weight given to the lowest-prominence peaks; peak prominences are mapped linearly to [lam_min, lam_max]

  • lam_max (float) – weight given to the highest-prominence peaks

  • verbose (int) – not used (progress is reported via the logger)

  • seed (int or None) – random seed for the variational inference (for reproducible results)

Returns:

  • txd (np.ndarray) – downsampled time-vector (ms)

  • syd (np.ndarray) – downsampled and lowpass-filtered pupil signal

  • base2 (np.ndarray) – final baseline estimate (after the second round), sampled at txd

  • base1 (np.ndarray) – baseline estimate after the first round, sampled at txd

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