summarize_confounds: Extract confounding variables calculated separately for each...

In eyeris: Flexible, Extensible, & Reproducible Pupillometry Preprocessing

Extract confounding variables calculated separately for each pupil data file

Description

Calculates various confounding variables for pupil data, including blink statistics, gaze position metrics, and pupil size characteristics. These confounds are calculated separately for each preprocessing step, recording block, and epoched time series in the eyeris object.

Usage

summarize_confounds(eyeris)

Arguments

eyeris

An object of class eyeris derived from load_asc()

Value

An eyeris object with a new nested list of data frames: ⁠$confounds⁠ The confounds are organized hierarchically by block and preprocessing step. Each step contains metrics such as:

• Missing data (n_missing and prop_missing)

• Blink rate and duration statistics

• Gaze position (x,y) mean and standard deviation

• Pupil size mean, standard deviation, and range

Missing data is reported as both a count (n_missing) and a proportion (prop_missing, 0 to 1; multiply by 100 for a percentage) of NA samples. It is computed at two levels so you can choose the granularity appropriate to your design:

• Block level: confounds$unepoched_timeseries[[block]][[step]] reports prop_missing across the entire recording block.

• Epoch/trial level: confounds$epoched_timeseries[[epoch]][[block]] reports prop_missing for each epoched event (e.g., per trial).

eyeris intentionally does not enforce a fixed missing-data exclusion cutoff. Instead, prop_missing is exposed so you can define your own exclusion thresholds at whichever level (trial, epoch, or block) is appropriate for your study.

Examples

# load demo dataset
demo_data <- eyelink_asc_demo_dataset()

# calculate confounds for all blocks and preprocessing steps
confounds <- demo_data |>
  eyeris::glassbox() |>
  eyeris::epoch(
    events = "PROBE_{type}_{trial}",
    limits = c(-1, 1), # grab 1 second prior to and 1 second post event
    label = "prePostProbe" # custom epoch label name
  ) |>
  eyeris::summarize_confounds()

# access confounds for entire time series for a specific block and step
confounds$confounds$unepoched_timeseries

# access confounds for a specific epoched time series
# for a specific block and step
confounds$confounds$epoched_timeseries
confounds$confounds$epoched_epoch_wide

eyeris documentation built on June 19, 2026, 9:08 a.m.