blink_onsets_mahot

pypillometry.signal.blink_onsets_mahot(sy, blinks, smooth_winsize, vel_onset, vel_offset, margin, blinkwindow, min_onset_len=1, min_offset_len=1)

Method for finding the on- and offset for each blink (excluding transient). See https://figshare.com/articles/A_simple_way_to_reconstruct_pupil_size_during_eye_blinks/688001.

Uses asymmetric Savitzky-Golay velocity estimation: - Backward-looking velocity for onset detection (so future zeros/NaN don’t affect the estimate) - Forward-looking velocity for offset detection (so past zeros/NaN don’t affect the estimate)

The asymmetric approach naturally handles blink regions (zeros/NaN) because: - At blink onset: backward velocity only sees valid data before the blink → detects the drop - At blink offset: forward velocity only sees valid data after the blink → detects the rise

Parameters:

• sy (np.ndarray) – pupil data (can contain NaN or zeros for missing values)

• blinks (np.ndarray or Intervals) – blink onset/offset sample indices (nblinks x 2), e.g. from detect_blinks_zero() or an Intervals object in index units; anything that iterates over (start, end) pairs works

• smooth_winsize (int) – size of the Savitzky-Golay window in samples (odd)

• vel_onset (float) – velocity-threshold to detect the onset of the blink; in units per sample (negative value)

• vel_offset (float) – velocity-threshold to detect the offset of the blink; in units per sample (positive value)

• margin (tuple of int) – (before, after) margin that is subtracted/added to onset and offset (in samples)

• blinkwindow (int) – how much time before and after each blink to search for the on-/offset (in samples)

• min_onset_len (int) – minimum number of consecutive samples in an onset run to be considered valid

• min_offset_len (int) – minimum number of consecutive samples in an offset run to be considered valid

Return type:

np.ndarray

Returns:

array (n x 2) of refined onset/offset sample indices, one row per input blink; if no valid velocity-threshold crossing is found before (after) a blink, its detected start (end) is used