Detect likely blink or pupil-dropout samples — detect_gazepoint

Detects likely blink or pupil-dropout samples in Gazepoint pupil columns using transparent, rule-based criteria. The function flags non-finite values, values outside a plausible pupil range, and optionally large sample-to-sample changes. It does not infer attention, cognition, arousal, emotion, or visual processing from the pupil signal.

Usage

detect_gazepoint_blinks(
  data,
  pupil_cols = NULL,
  id_cols = NULL,
  min_pupil = 0,
  max_pupil = Inf,
  change_threshold = NULL,
  extend_samples = 0L,
  mask = TRUE,
  flag_suffix = "_blink_flag",
  clean_suffix = "_blink_clean"
)

Arguments

data: A data frame containing Gazepoint pupil data.
pupil_cols: Character vector naming pupil columns. If NULL, numeric columns whose names contain "pupil" are used.
id_cols: Optional character vector naming grouping columns. Blink detection based on sample-to-sample change is applied within groups.
min_pupil: Minimum plausible pupil value. Values less than or equal to this threshold are flagged. Use NULL to disable the lower-bound rule.
max_pupil: Maximum plausible pupil value. Values greater than or equal to this threshold are flagged. Use NULL to disable the upper-bound rule.
change_threshold: Optional maximum plausible absolute sample-to-sample change. Use NULL to disable the change rule.
extend_samples: Non-negative integer. Number of neighbouring samples on each side of a detected blink/dropout to also flag.
mask: Logical. If TRUE, add cleaned pupil columns with detected blink/dropout samples set to NA.
flag_suffix: Suffix appended to pupil-column names for logical flag columns.
clean_suffix: Suffix appended to pupil-column names for cleaned columns when mask = TRUE.

Value

A list with the processed data, a summary table, rule settings, and warnings. The object has class "gazepoint_blink_audit".

Examples

d <- data.frame(
  participant = rep("P01", 8),
  time = seq_len(8),
  pupil_left = c(3.1, 3.2, 0, 3.2, 8.5, 3.1, NA, 3.0)
)
detect_gazepoint_blinks(d, pupil_cols = "pupil_left")
#> Gazepoint blink/dropout audit
#>   pupil_col n_samples n_flagged prop_flagged
#>  pupil_left         8         2         0.25