pupil_response#

pypillometry.signal.pupil_response(tx, sy, event_onsets, fs, npar='free', tmax='free', verbose=10, bounds={'npar': (1, 20), 'tmax': (100, 2000)}, display_progress=True, valid=None, min_valid=0)[source]#

Estimate pupil-response based on event-onsets.

The amplitudes of one PRF per event (see pupil_kernel()) are estimated with non-negative least-squares (NNLS). If npar and/or tmax are “free”, they are optimized (minimizing the sum of squared residuals) within bounds. Only the valid samples (see valid) are used for the fit; the prediction is computed for all samples. Events whose response falls mostly on invalid samples (see min_valid) are left out of the fit; their coefficient is NaN.

Parameters:

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

  • sy (np.ndarray) – (baseline-corrected) pupil signal; NaN samples are not used

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

  • fs (float) – sampling rate in Hz

  • npar (float or "free") – npar-parameter for the canonical response-function or “free”; in case of “free”, the function optimizes for this parameter

  • tmax (float or "free") – tmax-parameter (in ms) for the canonical response-function or “free”; in case of “free”, the function optimizes for this parameter

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

  • bounds (dict) – in case that one or both parameters are estimated, give the lower and upper bounds for the parameters (keys “npar” and “tmax”, tmax in ms)

  • display_progress (bool) – show the progress of the optimization (if both parameters are free, each iteration is logged; otherwise passed as disp option to scipy.optimize.minimize_scalar())

  • valid (np.ndarray or None) – boolean array (same length as sy), True for the samples that are used for the fit (e.g., False in long gaps); None: all samples that are not NaN

  • min_valid (float) – events whose share of the response on valid samples (see pupil_response_coverage()) is below this are left out of the fit (their amplitude cannot be estimated reliably); default 0 (all events are used)

Returns:

  • pred (np.ndarray) – predicted signal (same length as sy)

  • coef (np.ndarray) – non-negative amplitude of each event’s PRF (NaN for events left out, see min_valid)

  • npar (float) – npar used (estimated if “free”)

  • tmax (float) – tmax used in ms (estimated if “free”)

  • x1 (np.ndarray) – design matrix (nevents x len(tx)), see pupil_build_design_matrix()