Type:	Package
Title:	Flexible, Extensible, & Reproducible Pupillometry Preprocessing
Version:	2.1.0
Date:	2025-07-21
Description:	Pupillometry offers a non-invasive window into the mind and has been used extensively as a psychophysiological readout of arousal signals linked with cognitive processes like attention, stress, and emotional states [Clewett et al. (2020) <doi:10.1038/s41467-020-17851-9>; Kret & Sjak-Shie (2018) <doi:10.3758/s13428-018-1075-y>; Strauch (2024) <doi:10.1016/j.tins.2024.06.002>]. Yet, despite decades of pupillometry research, many established packages and workflows to date lack design patterns based on Findability, Accessibility, Interoperability, and Reusability (FAIR) principles [see Wilkinson et al. (2016) <doi:10.1038/sdata.2016.18>]. 'eyeris' provides a modular, performant, and extensible preprocessing framework for pupillometry data with BIDS-like organization and interactive output reports [Esteban et al. (2019) <doi:10.1038/s41592-018-0235-4>; Gorgolewski et al. (2016) <doi:10.1038/sdata.2016.44>]. Development was supported, in part, by the Stanford Wu Tsai Human Performance Alliance, Stanford Ric Weiland Graduate Fellowship, Stanford Center for Mind, Brain, Computation and Technology, NIH National Institute on Aging Grants (R01-AG065255, R01-AG079345), NSF GRFP (DGE-2146755), McKnight Brain Research Foundation Clinical Translational Research Scholarship in Cognitive Aging and Age-Related Memory Loss, American Brain Foundation, and the American Academy of Neurology.
Encoding:	UTF-8
Depends:	R (≥ 4.1)
Imports:	eyelinker, dplyr, gsignal, purrr, zoo, cli, rlang, stringr, utils, stats, graphics, grDevices, tidyr, progress, data.table, withr, lifecycle, MASS, viridis, fields, jsonlite, rmarkdown
RoxygenNote:	7.3.2
Suggests:	knitr, testthat (≥ 3.0.0), devtools
VignetteBuilder:	knitr
License:	MIT + file LICENSE
Config/testthat/edition:	3
URL:	https://shawnschwartz.com/eyeris/, https://github.com/shawntz/eyeris/
BugReports:	https://github.com/shawntz/eyeris/issues
NeedsCompilation:	no
Packaged:	2025-07-22 07:55:31 UTC; shawn
Author:	Shawn Schwartz [aut, cre], Mingjian He [ctb], Haopei Yang [ctb], Alice Xue [ctb], Gustavo Santiago-Reyes [ctb]
Maintainer:	Shawn Schwartz <shawn.t.schwartz@gmail.com>
Repository:	CRAN
Date/Publication:	2025-07-22 08:10:02 UTC

eyeris: Flexible, Extensible, & Reproducible Pupillometry Preprocessing

Description

Pupillometry offers a non-invasive window into the mind and has been used extensively as a psychophysiological readout of arousal signals linked with cognitive processes like attention, stress, and emotional states [Clewett et al. (2020) doi:10.1038/s41467-020-17851-9; Kret & Sjak-Shie (2018) doi:10.3758/s13428-018-1075-y; Strauch (2024) doi:10.1016/j.tins.2024.06.002]. Yet, despite decades of pupillometry research, many established packages and workflows to date lack design patterns based on Findability, Accessibility, Interoperability, and Reusability (FAIR) principles [see Wilkinson et al. (2016) doi:10.1038/sdata.2016.18]. 'eyeris' provides a modular, performant, and extensible preprocessing framework for pupillometry data with BIDS-like organization and interactive output reports [Esteban et al. (2019) doi:10.1038/s41592-018-0235-4; Gorgolewski et al. (2016) doi:10.1038/sdata.2016.44]. Development was supported, in part, by the Stanford Wu Tsai Human Performance Alliance, Stanford Ric Weiland Graduate Fellowship, Stanford Center for Mind, Brain, Computation and Technology, NIH National Institute on Aging Grants (R01-AG065255, R01-AG079345), NSF GRFP (DGE-2146755), McKnight Brain Research Foundation Clinical Translational Research Scholarship in Cognitive Aging and Age-Related Memory Loss, American Brain Foundation, and the American Academy of Neurology.

Author(s)

Maintainer: Shawn Schwartz shawn.t.schwartz@gmail.com (ORCID)

Other contributors:

• Mingjian He [contributor]

• Haopei Yang [contributor]

• Alice Xue [contributor]

• Gustavo Santiago-Reyes [contributor]

See Also

Useful links:

• https://shawnschwartz.com/eyeris/

• https://github.com/shawntz/eyeris/

• Report bugs at https://github.com/shawntz/eyeris/issues

Add unique event identifiers to handle duplicate event messages

Description

This function adds a new column text_unique to each events table that creates unique identifiers for each occurrence of the same event message by appending a count number. This prevents events like "GOAL" from being merged across all separate goals.

Usage

add_unique_event_identifiers(events_list)

Arguments

Details

This function is called by the exposed wrapper load_asc()

Value

Updated events list with text_unique column added to each data frame

Add unique identifiers to a single events data frame

Description

This function is called by the exposed wrapper load_asc()

Usage

add_unique_identifiers_to_df(events_df)

Arguments

Value

Updated events data frame with text_unique column

Display formatted alert messages

Description

A utility function to display formatted alert messages using the cli package. Supports warning, info, and success message types.

Usage

alert(type = c("warning", "info", "success"), msg, ...)

Arguments

Value

No return value; displays the formatted message to the console

Save out pupil timeseries data in a BIDS-like structure

Description

This method provides a structured way to save out pupil data in a BIDS-like structure. The method saves out epoched data as well as the raw pupil timeseries, and formats the directory and filename structures based on the metadata you provide.

Usage

bidsify(
  eyeris,
  save_all = TRUE,
  epochs_list = NULL,
  merge_epochs = FALSE,
  bids_dir = NULL,
  participant_id = NULL,
  session_num = NULL,
  task_name = NULL,
  run_num = NULL,
  merge_runs = FALSE,
  save_raw = TRUE,
  html_report = TRUE,
  report_seed = 0,
  report_epoch_grouping_var_col = "matched_event",
  verbose = TRUE,
  pdf_report = deprecated()
)

Arguments

Details

In the future, we intend for this function to save out the data in an official BIDS format for eyetracking data (see the proposal currently under review here). At this time, however, this function instead takes a more BIDS-inspired approach to organizing the output files for preprocessed pupil data.

Value

Invisibly returns NULL. Called for its side effects

See Also

lifecycle::deprecate_warn()

Examples

# Bleed around blink periods just long enough to remove majority of
#  deflections due to eyelid movements

demo_data <- eyelink_asc_demo_dataset()

# example with unepoched data
demo_data |>
  eyeris::glassbox() |>
  eyeris::bidsify(
    bids_dir = tempdir(), # <- MAKE SURE TO UPDATE TO YOUR DESIRED LOCAL PATH
    participant_id = "001",
    session_num = "01",
    task_name = "assocret",
    run_num = "01",
    save_raw = TRUE, # save out raw timeseries
    html_report = TRUE, # generate interactive report document
    report_seed = 0 # make randomly selected plot epochs reproducible
  )

# example with epoched data
demo_data |>
  eyeris::glassbox() |>
  eyeris::epoch(
    events = "PROBE_{startstop}_{trial}",
    limits = c(-1, 1), # grab 1 second prior to and 1 second post event
    label = "prePostProbe" # custom epoch label name
  ) |>
  eyeris::bidsify(
    bids_dir = tempdir(), # <- MAKE SURE TO UPDATE TO YOUR DESIRED LOCAL PATH
    participant_id = "001",
    session_num = "01",
    task_name = "assocret",
    run_num = "01"
  )

# example with run_num for single block data
demo_data <- eyelink_asc_demo_dataset()

demo_data |>
  eyeris::glassbox() |>
  eyeris::epoch(
    events = "PROBE_{startstop}_{trial}",
    limits = c(-1, 1),
    label = "prePostProbe"
  ) |>
  eyeris::bidsify(
    bids_dir = tempdir(),
    participant_id = "001",
    session_num = "01",
    task_name = "assocret",
    run_num = "03" # override default run-01 (block_1) to use run-03 instead
  )

Bin pupil time series by averaging within time bins

Description

This function bins pupillometry data by dividing time into equal intervals and averaging the data within each bin. Unlike downsampling, binning averages data points within each time bin.

Usage

bin(eyeris, bins_per_second, method = "mean", call_info = NULL)

Arguments

Details

Binning divides one second of pupillary data into X bins and averages pupillometry data around each bin center. The resulting time points will be: 1/2X, 3/2X, 5/2X, ..., etc. where X is the number of bins per second.

This approach is commonly used in pupillometry research to study temporal dynamics of pupil dilatory response; however, it should be used with caution (as averaging within bins can distort the pupillary dynamics).

Value

An eyeris object with binned data and updated sampling rate

Note

This function is part of the glassbox() preprocessing pipeline and is not intended for direct use in most cases. Provide parameters via bin = list(...).

Advanced users may call it directly if needed.

See Also

glassbox() for the recommended way to run this step as part of the full eyeris glassbox preprocessing pipeline downsample() for downsampling functionality

Examples

demo_data <- eyelink_asc_demo_dataset()

# bin data into 10 bins per second using the (default) "mean" method
demo_data |>
  eyeris::glassbox(bin = list(bins_per_second = 10, method = "mean")) |>
  plot(seed = 0)

Bin pupil data into specified time bins

Description

This function bins pupil data into specified time bins using either mean or median aggregation. It creates evenly spaced bins across the time series and aggregates pupil values within each bin.

Usage

bin_pupil(x, prev_op, bins_per_second, method, current_fs)

Arguments

Details

This function is called by the exposed wrapper bin().

Value

A data frame with binned pupil data containing columns:

• time_secs: Bin center timestamps

• ⁠pupil_binned_{method}_{bins_per_second}hz⁠: Binned pupil values

Calculate Euclidean distance between points

Description

Calculate Euclidean distance between points

Usage

calc_euclidean_dist(x1, y1, x2 = 0, y2 = 0)

Arguments

Value

A numeric vector of Euclidean distances

Calculate confounds for epoched data

Description

Helper function to calculate confounds for epoched timeseries data. This function is used internally by both summarize_confounds() and epoch().

Usage

calculate_epoched_confounds(eyeris, epoch_names, hz, verbose = TRUE)

Arguments

Value

An updated eyeris object with epoched confounds

Check and create directory if it doesn't exist

Description

Checks if a directory exists and creates it if it doesn't. Provides informative messages about the process.

Usage

check_and_create_dir(basedir, dir = NULL, verbose = TRUE)

Arguments

Value

No return value; creates directory if needed

Check baseline and epoch counts match

Description

Validates that the number of baseline epochs matches the number of epochs.

Usage

check_baseline_epoch_counts(epochs, baselines)

Arguments

Value

No return value; throws error if counts don't match

Check baseline input arguments

Description

Validates that baseline inputs are properly specified.

Usage

check_baseline_inputs(events, limits)

Arguments

Value

No return value; throws error if inputs are invalid

Check if baseline mean is zero

Description

Validates that baseline mean is not zero for divisive baseline correction.

Usage

check_baseline_mean(x)

Arguments

Value

No return value; throws error if baseline mean is zero

Check if column exists in dataframe

Description

Validates that a specified column exists in a dataframe.

Usage

check_column(df, col_name)

Arguments

Value

No return value; throws error if column doesn't exist

Check if object is of class eyeris

Description

Validates that an object is of class eyeris.

Usage

check_data(eyeris, fun)

Arguments

Value

No return value; throws error if object is not eyeris class

Check epoch input for plotting

Description

Validates that exactly one epoch is specified for plotting.

Usage

check_epoch_input(epochs)

Arguments

Value

No return value; throws error if more than one epoch is specified

Check epoch manual input data structure

Description

Validates that the events argument is a list of two dataframes.

Usage

check_epoch_manual_input_data(ts_list)

Arguments

Value

No return value; throws error if structure is invalid

Check epoch manual input dataframe format

Description

Validates that start and end timestamp dataframes have required columns.

Usage

check_epoch_manual_input_dfs(ts_list)

Arguments

Value

No return value; throws error if format is invalid

Check epoch message values against available events

Description

Validates that specified event messages exist in the eyeris object.

Usage

check_epoch_msg_values(eyeris, events)

Arguments

Value

No return value; throws error if invalid messages are found

Check if input argument is provided

Description

Validates that a required argument is not NULL and throws an error if missing.

Usage

check_input(arg)

Arguments

Value

No return value; throws error if argument is NULL

Check limits in wildcard mode

Description

Validates that limits are provided when using wildcard mode.

Usage

check_limits(limits)

Arguments

Value

No return value; throws error if limits are missing in wildcard mode

Check if pupil_raw column exists

Description

Validates that the pupil_raw column exists in the eyeris object.

Usage

check_pupil_cols(eyeris, fun)

Arguments

Value

No return value; throws error if pupil_raw column is missing

Check start and end timestamps are balanced

Description

Validates that start and end timestamp dataframes have the same number of rows.

Usage

check_start_end_timestamps(start, end)

Arguments

Value

No return value; throws error if timestamps are unbalanced

Check time series monotonicity

Description

Validates that a time vector is monotonically increasing.

Usage

check_time_monotonic(time_vector, time_col_name = "time_secs")

Arguments

Value

No return value; throws error if time series is not monotonic

Clean string by removing non-alphanumeric characters

Description

Removes all non-alphanumeric and non-whitespace characters from a string.

Usage

clean_string(str)

Arguments

Value

A cleaned string with only alphanumeric characters and spaces

Compute baseline correction for epoch data

Description

Applies baseline correction to epoch data using either subtractive or divisive methods.

Usage

compute_baseline(
  x,
  epochs,
  baseline_epochs,
  mode,
  epoch_events = NULL,
  baseline_events = NULL
)

Arguments

Value

A list containing baseline correction results and metadata

Convert nested data.table objects to tibbles

Description

Recursively converts data.table objects within nested lists to tibbles.

Usage

convert_nested_dt(nested_dt)

Arguments

Value

A nested list with data.table objects converted to tibbles

Count epochs and validate data is epoched

Description

Counts the number of epochs and validates that data has been epoched.

Usage

count_epochs(epochs)

Arguments

Value

No return value; throws error if no epochs found

Create a counter progress bar

Description

Creates a simple counter progress bar that shows current/total progress.

Usage

counter_bar(total, msg = "Progress", width = 80)

Arguments

Value

A progress bar object from the progress package

NA-pad blink events / missing data

Description

Deblinking (a.k.a. NA-padding) of time series data. The intended use of this method is to remove blink-related artifacts surrounding periods of missing data. For instance, when an individual blinks, there are usually rapid decreases followed by increases in pupil size, with a chunk of data missing in-between these 'spike'-looking events. The deblinking procedure here will NA-pad each missing data point by your specified number of ms.

Usage

deblink(eyeris, extend = 50, call_info = NULL)

Arguments

Details

This function is automatically called by glassbox() by default. If needed, customize the parameters for deblink by providing a parameter list. Use glassbox(deblink = FALSE) to disable this step as needed.

Users should prefer using glassbox() rather than invoking this function directly unless they have a specific reason to customize the pipeline manually.

Value

An eyeris object with a new column: ⁠pupil_raw_{...}_deblink⁠

Note

This function is part of the glassbox() preprocessing pipeline and is not intended for direct use in most cases. Provide parameters via deblink = list(...).

Advanced users may call it directly if needed.

See Also

glassbox() for the recommended way to run this step as part of the full eyeris glassbox preprocessing pipeline

Examples

demo_data <- eyelink_asc_demo_dataset()

# 50 ms in both directions (the default)
demo_data |>
  eyeris::glassbox(deblink = list(extend = 50)) |>
  plot(seed = 0)

# 40 ms backward, 50 ms forward
demo_data |>
  # set deblink to FALSE (instead of a list of params)
  #  to skip step (not recommended)
  eyeris::glassbox(deblink = list(extend = c(40, 50))) |>
  plot(seed = 0)

Internal function to remove blink artifacts from pupil data

Description

This function implements blink artifact removal by extending the duration of detected blinks (missing samples) by a specified number of milliseconds both forward and backward in time. This helps to remove deflections in pupil size that occur due to eyelid movements during and around actual blink periods.

This function is called by the exposed wrapper deblink().

Usage

deblink_pupil(x, prev_op, extend)

Arguments

Details

The function works by:

• Identifying missing samples as blink periods

• Extending these periods by the specified number of milliseconds

• Setting all samples within the extended blink periods to NA

• Preserving all other samples unchanged

This implementation is based on the approach described in the pupillometry package by dr-JT (https://github.com/dr-JT/pupillometry/blob/main/R/pupil_deblink.R).

Value

A numeric vector of the same length as the input data with blink artifacts removed (set to NA)

Remove pupil samples that are physiologically unlikely

Description

The intended use of this method is for removing pupil samples that emerge more quickly than would be physiologically expected. This is accomplished by rejecting samples that exceed a "speed"-based threshold (i.e., median absolute deviation from sample-to-sample). This threshold is computed based on the constant n, which defaults to the value 16.

Usage

detransient(eyeris, n = 16, mad_thresh = NULL, call_info = NULL)

Arguments

Details

This function is automatically called by glassbox() by default. If needed, customize the parameters for detransient by providing a parameter list. Use glassbox(detransient = FALSE) to disable this step as needed.

Users should prefer using glassbox() rather than invoking this function directly unless they have a specific reason to customize the pipeline manually.

Computed properties:

• pupil_speed: Compute speed of pupil by approximating the derivative of x (pupil) with respect to y (time) using finite differences.

  • Let x = (x_1, x_2, \dots, x_n) and y = (y_1, y_2, \dots, y_n) be two numeric vectors with n \ge 2; then, the finite differences are computed as:

    \delta_i = \frac{x_{i+1} - x_i}{y_{i+1} - y_i}, \quad i = 1, 2, \dots, n-1.

  • This produces an output vector p = (p_1, p_2, \dots, p_n) defined by:

    • For the first element:

      p_1 = |\delta_1|,

    • For the last element:

      p_n = |\delta_{n-1}|,

    • For the intermediate elements (i = 2, 3, \dots, n-1):

      p_i = \max\{|\delta_{i-1}|,\,|\delta_i|\}.

• median_speed: The median of the computed pupil_speed:

  median\_speed = median(p)

• mad_val: The median absolute deviation (MAD) of pupil_speed from the median:

  mad\_val = median(|p - median\_speed|)

• mad_thresh: A threshold computed from the median speed and the MAD, using a constant multiplier n (default value: 16):

  mad\_thresh = median\_speed + (n \times mad\_val)

Value

An eyeris object with a new column in timeseries: ⁠pupil_raw_{...}_detransient⁠

Note

This function is part of the glassbox() preprocessing pipeline and is not intended for direct use in most cases. Provide parameters via detransient = list(...).

Advanced users may call it directly if needed.

See Also

glassbox() for the recommended way to run this step as part of the full eyeris glassbox preprocessing pipeline.

Examples

demo_data <- eyelink_asc_demo_dataset()

demo_data |>
  eyeris::glassbox(
    detransient = list(n = 16) # set to FALSE to skip step (not recommended)
  ) |>
  plot(seed = 0)

Internal function to remove transient artifacts from pupil data

Description

This function implements transient artifact removal by identifying and removing samples that exceed a speed-based threshold. The threshold is computed based on the constant n, which defaults to the value 16.

This function is called by the exposed wrapper detransient().

Usage

detransient_pupil(x, prev_op, n, mad_thresh)

Arguments

Details

The function works by:

• Calculating the speed of pupil changes using finite differences

• Identifying samples that exceed a speed-based threshold

• Removing these samples from the pupil data

Value

A numeric vector of the same length as the input data with transient artifacts removed (set to NA)

Detrend the pupil time series

Description

Linearly detrend_pupil data by fitting a linear model of pupil_data ~ time, and return the fitted betas and the residuals (pupil_data - fitted_values).

Usage

detrend(eyeris, call_info = NULL)

Arguments

Details

This function is automatically called by glassbox() if detrend = TRUE.

Users should prefer using glassbox() rather than invoking this function directly unless they have a specific reason to customize the pipeline manually.

Value

An eyeris object with two new columns in timeseries: detrend_fitted_betas, and ⁠pupil_raw_{...}_detrend⁠

Note

This function is part of the glassbox() preprocessing pipeline and is not intended for direct use in most cases. Use glassbox(detrend = TRUE).

Advanced users may call it directly if needed.

See Also

glassbox() for the recommended way to run this step as part of the full eyeris glassbox preprocessing pipeline

Examples

demo_data <- eyelink_asc_demo_dataset()

demo_data |>
  eyeris::glassbox(detrend = TRUE) |>  # set to FALSE to skip step (default)
  plot(seed = 0)

Internal function to detrend pupil data

Description

This function detrends pupil data by fitting a linear model of pupil_data ~ time, and returning the fitted betas and the residuals (pupil_data - fitted_values).

This function is called by the exposed wrapper detrend().

Usage

detrend_pupil(x, prev_op)

Arguments

Value

A list containing the fitted values, coefficients, and residuals

Downsample pupil time series with anti-aliasing filtering

Description

This function downsamples pupillometry data by applying an anti-aliasing filter before decimation. Unlike binning, downsampling preserves the original temporal dynamics without averaging within bins.

Usage

downsample(
  eyeris,
  target_fs,
  plot_freqz = FALSE,
  rp = 1,
  rs = 35,
  call_info = NULL
)

Arguments

Details

Downsampling reduces the sampling frequency by decimating data points. The function automatically designs an anti-aliasing filter using the lpfilt() function with carefully chosen parameters:

• ws (stopband frequency) = Fs_new / 2 (Nyquist freq of new sampling rate)

• wp (passband frequency) = ws - max(5, Fs_nq * 0.2)

• An error is raised if wp < 4 to prevent loss of pupillary responses

The resulting time points will be: 0, 1/X, 2/X, 3/X, ..., etc. where X is the new sampling frequency.

Value

An eyeris object with downsampled data and updated sampling rate.

Note

This function is part of the glassbox() preprocessing pipeline and is not intended for direct use in most cases. Provide parameters via downsample = list(...).

Advanced users may call it directly if needed.

See Also

glassbox() for the recommended way to run this step as part of the full eyeris glassbox preprocessing pipeline. bin() for binning functionality.

Examples

demo_data <- eyelink_asc_demo_dataset()

# downsample pupil data recorded at 1000 Hz to 100 Hz with the default params
demo_data |>
  eyeris::glassbox(downsample = list(target_fs = 100)) |>
  plot(seed = 0)

Internal function to downsample pupil data

Description

This function downsamples pupil data by applying an anti-aliasing filter before decimation. Unlike binning, downsampling preserves the original temporal dynamics without averaging within bins.

This function is called by the exposed wrapper downsample().

Usage

downsample_pupil(x, prev_op, target_fs, plot_freqz, current_fs, rp, rs)

Arguments

Value

A list containing the downsampled data and the decimated sample rate

Draw vertical lines at NA positions

Description

Adds vertical dashed lines at positions where y values are NA.

Usage

draw_na_lines(x, y, ...)

Arguments

Value

No return value; adds lines to the current plot

Draw random epochs for plotting

Description

Generates random time segments from the timeseries data for preview plotting.

Usage

draw_random_epochs(x, n, d, hz)

Arguments

Value

A list of dataframes, each containing a random epoch segment

Epoch (and baseline) pupil data based on custom event message structure

Description

Intended to be used as the final preprocessing step. This function creates data epochs of either fixed or dynamic durations with respect to provided events and time limits, and also includes an intuitive metadata parsing feature where additional trial data embedded within event messages can easily be identified and joined into the resulting epoched data frames.

Usage

epoch(
  eyeris,
  events,
  limits = NULL,
  label = NULL,
  baseline = FALSE,
  baseline_type = c("sub", "div"),
  baseline_events = NULL,
  baseline_period = NULL,
  hz = NULL,
  verbose = TRUE,
  call_info = NULL,
  calc_baseline = deprecated(),
  apply_baseline = deprecated()
)

Arguments

Value

An eyeris object with a new nested list of data frames: ⁠$epoch_*⁠. The epochs are organized hierarchically by block and preprocessing step. Each epoch contains the pupil timeseries data for the specified time window around each event message, along with metadata about the event.

When using bidsify() to export the data, filenames will include both epoch and baseline event information for clarity.

See Also

lifecycle::deprecate_warn()

Examples

demo_data <- eyelink_asc_demo_dataset()
eye_preproc <- eyeris::glassbox(demo_data)

# example 1: select 1 second before/after matched event message "PROBE*"
eye_preproc |>
  eyeris::epoch(events = "PROBE*", limits = c(-1, 1))

# example 2: select all samples between each trial
eye_preproc |>
  eyeris::epoch(events = "TRIALID {trial}")

# example 3: grab the 1 second following probe onset
eye_preproc |>
  eyeris::epoch(
    events = "PROBE_START_{trial}",
    limits = c(0, 1)
  )

# example 4: 1 second prior to and 1 second after probe onset
eye_preproc |>
  eyeris::epoch(
    events = "PROBE_START_{trial}",
    limits = c(-1, 1),
    label = "prePostProbe" # custom epoch label name
  )

# example 5: manual start/end event pairs
# note: here, the `msg` column of each data frame is optional
eye_preproc |>
  eyeris::epoch(
    events = list(
      data.frame(time = c(11334491), msg = c("TRIALID 22")), # start events
      data.frame(time = c(11337158), msg = c("RESPONSE_22")), # end events
      1 # block number
    ),
    label = "example5"
  )

# example 6: manual start/end event pairs
# note: set `msg` to NA if you only want to pass in start/end timestamps
eye_preproc |>
  eyeris::epoch(
    events = list(
      data.frame(time = c(11334491), msg = NA), # start events
      data.frame(time = c(11337158), msg = NA), # end events
      1 # block number
    ),
    label = "example6"
  )

## examples with baseline arguments enabled

# example 7: use mean of 1-s preceding "PROBE_START" (i.e. "DELAY_STOP")
# to perform subtractive baselining of the 1-s PROBE epochs.
eye_preproc |>
  eyeris::epoch(
    events = "PROBE_START_{trial}",
    limits = c(0, 1), # grab 0 seconds prior to and 1 second post PROBE event
    label = "prePostProbe", # custom epoch label name
    baseline = TRUE, # Calculate and apply baseline correction
    baseline_type = "sub", # "sub"tractive baseline calculation is default
    baseline_events = "DELAY_STOP_*",
    baseline_period = c(-1, 0)
  )

# example 8: use mean of time period between set start/end event messages
# (i.e. between "DELAY_START" and "DELAY_STOP"). In this case, the
# `baseline_period` argument will be ignored since both a "start" and "end"
# message string are provided to the `baseline_events` argument.
eye_preproc |>
  eyeris::epoch(
    events = "PROBE_START_{trial}",
    limits = c(0, 1), # grab 0 seconds prior to and 1 second post PROBE event
    label = "prePostProbe", # custom epoch label name
    baseline = TRUE, # Calculate and apply baseline correction
    baseline_type = "sub", # "sub"tractive baseline calculation is default
    baseline_events = c(
      "DELAY_START_*",
      "DELAY_STOP_*"
    )
  )

# example 9: additional (potentially helpful) example
start_events <- data.frame(
  time = c(11334491, 11338691),
  msg = c("TRIALID 22", "TRIALID 23")
)
end_events <- data.frame(
  time = c(11337158, 11341292),
  msg = c("RESPONSE_22", "RESPONSE_23")
)
block_number <- 1

eye_preproc |>
  eyeris::epoch(
    events = list(start_events, end_events, block_number),
    label  = "example9"
  )

Block-by-block epoch and baseline handler

Description

This function processes a single block of pupil data to extract epochs and optionally compute and apply baseline corrections. It handles the core epoching and baselining logic for a single block of data.

Usage

epoch_and_baseline_block(
  x,
  blk,
  lab,
  evs,
  lims,
  msg_s,
  msg_e,
  c_bline,
  a_bline,
  bline_type,
  bline_evs,
  bline_per,
  hz,
  verbose
)

Arguments

Details

This function is called by the internal epoch_pupil() function.

Value

A list containing epoch and baseline results

Manually epoch using provided start/end dataframes of timestamps

Description

This function manually epochs data using provided start/end dataframes of timestamps.

Usage

epoch_manually(eyeris, ts_list, hz, verbose)

Arguments

Details

This function is called by the internal process_epoch_and_baselines() function.

Value

A list containing epoch results

Epoch based on a single event message (without explicit limits)

Description

This function epochs data based on a single event message (i.e., without explicit limits).

Usage

epoch_only_start_msg(eyeris, start, hz, verbose)

Arguments

Details

This function is called by the internal epoch_only_start_msg() function.

Value

A list containing epoch results

Main epoching and baselining logic

Description

This function handles the core epoching and baselining operations for pupil data. It processes time series data to extract epochs based on specified events and optionally computes and applies baseline corrections.

Usage

epoch_pupil(
  x,
  prev_op,
  evs,
  lims,
  label,
  c_bline,
  a_bline,
  bline_type = c("sub", "div"),
  bline_evs,
  bline_per,
  hz,
  verbose
)

Arguments

Details

This function is called by the exposed wrapper epoch().

Value

A list containing epoch and baseline results

Epoch using a start and an end message (explicit timestamps)

Description

This function epochs data using a start and an end message (i.e., explicit timestamps).

Usage

epoch_start_end_msg(eyeris, start, end, hz, verbose)

Arguments

Details

This function is called by the internal epoch_start_end_msg() function.

Value

A list containing epoch results

Epoch using a start message with fixed limits around it

Description

This function epochs data using a start message with fixed limits around it.

Usage

epoch_start_msg_and_limits(eyeris, start, lims, hz, verbose)

Arguments

Details

This function is called by the internal epoch_start_msg_and_limits() function.

Value

A list containing epoch results

Handle errors with custom error classes

Description

A utility function to handle errors with specific error classes and provide appropriate error messages using the cli package.

Usage

error_handler(e, e_class)

Arguments

Value

No return value; either displays an error message via cli or stops execution with the original error

Evaluate pipeline step parameters

Description

Converts pipeline step parameters to logical values for evaluation.

Usage

evaluate_pipeline_step_params(params)

Arguments

Value

A logical vector indicating which steps should be executed

Export confounds data to CSV files

Description

Exports each block's confounds data to a separate CSV file. Each file will contain all pupil steps (e.g., pupil_raw, pupil_clean) as rows, with confound metrics as columns.

Usage

export_confounds_to_csv(
  confounds_list,
  output_dir,
  filename_prefix,
  verbose,
  run_num = NULL
)

Arguments

Value

Invisibly returns a vector of created file paths

Extract baseline epochs from timeseries data

Description

Extracts baseline periods from timeseries data based on event messages and time ranges or start/end messages.

Usage

extract_baseline_epochs(x, df, evs, time_range, matched_epochs, hz)

Arguments

Value

A list of baseline epoch dataframes

Access example EyeLink .asc binocular mock dataset file provided by the eyeris package.

Description

Returns the file path to the demo binocular .asc EyeLink pupil data file included in the eyeris package.

Usage

eyelink_asc_binocular_demo_dataset()

Details

This dataset is a mock dataset trimmed from a larger data file. The original data file was obtained from: https://github.com/scott-huberty/eyelinkio/blob/main/src/eyelinkio/tests/data/test_raw_binocular.edf

Value

A character string giving the full file path to the demo .asc EyeLink pupil data file

Examples

path_to_binocular_demo_dataset <- eyelink_asc_binocular_demo_dataset()
print(path_to_binocular_demo_dataset)

Access example EyeLink .asc demo dataset file provided by the eyeris package.

Description

Returns the file path to the demo .asc EyeLink pupil data file included in the eyeris package.

Usage

eyelink_asc_demo_dataset()

Value

A character string giving the full file path to the demo .asc EyeLink pupil data file

Examples

path_to_demo_dataset <- eyelink_asc_demo_dataset()
print(path_to_demo_dataset)

Run eyeris commands with automatic logging of R console's stdout and stderr

Description

This utility function evaluates eyeris commands while automatically capturing and recording both standard output (stdout) and standard error (stderr) to timestamped log files in your desired log directory.

Usage

eyelogger(
  eyeris_cmd,
  log_dir = file.path(tempdir(), "eyeris_logs"),
  timestamp_format = "%Y%m%d_%H%M%S"
)

Arguments

Details

Each run produces two log files:

• ⁠<timestamp>.out⁠: records all console output

• ⁠<timestamp>.err⁠: records all warnings and errors

Value

The result of the evaluated eyeris command (invisibly)

Examples

eyelogger({
  message("eyeris `glassbox()` completed successfully.")
  warning("eyeris `glassbox()` completed with warnings.")
  print("some eyeris-related information.")
})

eyelogger({
  glassbox(eyelink_asc_demo_dataset(), interactive_preview = FALSE)
}, log_dir = file.path(tempdir(), "eyeris_logs"))

Default color palette for eyeris plotting functions

Description

A custom color palette designed for visualizing pupil data preprocessing steps. This palette is based on the RColorBrewer Set1 palette and provides distinct, visually appealing colors for different preprocessing stages.

Usage

eyeris_color_palette()

Details

The palette includes 7 colors optimized for:

• High contrast and visibility

• Colorblind-friendly design

• Consistent visual hierarchy across preprocessing steps

• Professional appearance in reports and publications

Colors are designed to work well with both light and dark backgrounds and maintain readability when overlaid in time series plots.

Value

A character vector of 7 hex color codes representing the default eyeris color palette

Examples

# get the default color palette
colors <- eyeris_color_palette()
print(colors)

# use in a plot
plot(1:7, 1:7, col = colors, pch = 19, cex = 3)

Filter epoch names from eyeris object

Description

Extracts names of epoch-related elements from an eyeris object.

Usage

filter_epochs(eyeris, epochs)

Arguments

Value

A character vector of epoch names that start with "epoch_"

Find baseline structure name for a given epoch

Description

Helper function to find the correct baseline structure name that matches the complex baseline naming scheme used by eyeris.

Usage

find_baseline_structure(eyeris, epoch_label)

Arguments

Value

The baseline structure name or NULL if not found

Format call stack information for display

Description

Converts call stack information into a formatted data frame for display.

Usage

format_call_stack(callstack)

Arguments

Value

A data frame with formatted call stack information

Extract block numbers from eyeris object or character vector

Description

Extracts numeric block numbers from block names or an eyeris object.

Usage

get_block_numbers(x)

Arguments

Value

A numeric vector of block numbers, or NULL if no blocks found

Calculate confounds for a single pupil data step

Description

Computes various metrics from pupil data including:

• Blink detection

• Gaze on/off screen detection

• Gap analysis

• Gaze distance from screen center

• Gaze variance

• Blink rate

• Blink duration

• Blink time

Usage

get_confounds_for_step(pupil_df, pupil_vec, screen_width, screen_height, hz)

Arguments

Value

A data frame containing confounds metrics for the current step

Obtain timestamps from events data

Description

Extracts start and end timestamps from events data based on message patterns.

Usage

get_timestamps(
  evs,
  timestamped_events,
  msg_s,
  msg_e,
  limits,
  baseline_mode = FALSE
)

Arguments

Value

A list containing start and end timestamps

The opinionated "glass box" eyeris pipeline

Description

This glassbox function (in contrast to a "black box" function where you run it and get a result but have no (or little) idea as to how you got from input to output) has a few primary benefits over calling each exported function from eyeris separately.

Usage

glassbox(
  file,
  interactive_preview = FALSE,
  preview_n = 3,
  preview_duration = 5,
  preview_window = NULL,
  verbose = TRUE,
  ...,
  confirm = deprecated(),
  num_previews = deprecated(),
  detrend_data = deprecated(),
  skip_detransient = deprecated()
)

Arguments

Details

First, this glassbox function provides a highly opinionated prescription of steps and starting parameters we believe any pupillometry researcher should use as their defaults when preprocessing pupillometry data.

Second, and not mutually exclusive from the first point, using this function should ideally reduce the probability of accidental mishaps when "reimplementing" the steps from the preprocessing pipeline both within and across projects. We hope to streamline the process in such a way that you could collect a pupillometry dataset and within a few minutes assess the quality of those data while simultaneously running a full preprocessing pipeline in 1-ish line of code!

Third, glassbox provides an "interactive" framework where you can evaluate the consequences of the parameters within each step on your data in real time, facilitating a fairly easy-to-use workflow for parameter optimization on your particular dataset. This process essentially takes each of the opinionated steps and provides a pre-/post-plot of the timeseries data for each step so you can adjust parameters and re-run the pipeline until you are satisfied with the choices of your paramters and their consequences on your pupil timeseries data.

Value

Preprocessed pupil data contained within an object of class eyeris

See Also

lifecycle::deprecate_warn()

Examples

demo_data <- eyelink_asc_demo_dataset()

# (1) examples using the default prescribed parameters and pipeline recipe

## (a) run an automated pipeline with no real-time inspection of parameters
output <- eyeris::glassbox(demo_data)

start_time <- min(output$timeseries$block_1$time_secs)
end_time <- max(output$timeseries$block_1$time_secs)

# by default, verbose = TRUE. To suppress messages, set verbose = FALSE.
plot(
  output,
  steps = c(1, 5),
  preview_window = c(start_time, end_time),
  seed = 0
)

## (b) run a interactive workflow (with confirmation prompts after each step)

output <- eyeris::glassbox(demo_data, interactive_preview = TRUE, seed = 0)


# (2) examples of overriding the default parameters
output <- eyeris::glassbox(
  demo_data,
  interactive_preview = FALSE, # TRUE to visualize each step in real-time
  deblink = list(extend = 40),
  lpfilt = list(plot_freqz = TRUE) # overrides verbose parameter
)

# to suppress messages, set verbose = FALSE in plot():
plot(output, seed = 0, verbose = FALSE)

# (3) examples of disabling certain steps
output <- eyeris::glassbox(
  demo_data,
  detransient = FALSE,
  detrend = FALSE,
  zscore = FALSE
)

plot(output, seed = 0)

Internal glassbox function for processing individual eyes

Description

Internal glassbox function for processing individual eyes

Usage

glassbox_internal(
  file,
  interactive_preview = FALSE,
  preview_n = 3,
  preview_duration = 5,
  preview_window = NULL,
  verbose = TRUE,
  params,
  original_call,
  seed
)

Arguments

Value

An eyeris object with the processed data lists

Index metadata from dataframe

Description

Extracts a single row of metadata from a dataframe.

Usage

index_metadata(x, i)

Arguments

Value

A single row from the dataframe

Interpolate missing pupil samples

Description

Linear interpolation of time series data. The intended use of this method is for filling in missing pupil samples (NAs) in the time series. This method uses "na.approx()" function from the zoo package, which implements linear interpolation using the "approx()" function from the stats package. Currently, NAs at the beginning and the end of the data are replaced with values on either end, respectively, using the "rule = 2" argument in the approx() function.

Usage

interpolate(eyeris, verbose = TRUE, call_info = NULL)

Arguments

Details

This function is automatically called by glassbox() by default. Use glassbox(interpolate = FALSE) to disable this step as needed.

Users should prefer using glassbox() rather than invoking this function directly unless they have a specific reason to customize the pipeline manually.

Value

An eyeris object with a new column in timeseries: ⁠pupil_raw_{...}_interpolate⁠

Note

This function is part of the glassbox() preprocessing pipeline and is not intended for direct use in most cases. Use glassbox(interpolate = TRUE).

Advanced users may call it directly if needed.

See Also

glassbox() for the recommended way to run this step as part of the full eyeris glassbox preprocessing pipeline.

Examples

demo_data <- eyelink_asc_demo_dataset()

demo_data |>
  # set to FALSE to skip (not recommended)
  eyeris::glassbox(interpolate = TRUE) |>
  plot(seed = 0)

Interpolate missing pupil data using linear interpolation

Description

This function fills missing values (NAs) in pupil data using linear interpolation. It uses the zoo::na.approx() function with settings optimized for pupillometry data.

Usage

interpolate_pupil(x, prev_op, verbose)

Arguments

Details

This function is called by the exposed wrapper interpolate().

Value

A vector of interpolated pupil values with the same length as the input

Check if object is a binocular eyeris object

Description

Detects whether an object is a binocular eyeris object created with binocular_mode = "both".

Usage

is_binocular_object(x)

Arguments

Value

Logical indicating whether the object is a binocular eyeris object

Load and parse SR Research EyeLink .asc files

Description

This function builds upon the eyelinker::read.asc() function to parse the messages and metadata within the EyeLink .asc file. After loading and additional processing, this function returns an S3 eyeris class for use in all subsequent eyeris pipeline steps and functions.

Usage

load_asc(
  file,
  block = "auto",
  binocular_mode = c("average", "left", "right", "both")
)

Arguments

Details

This function is automatically called by glassbox() by default. If needed, customize the parameters for load_asc by providing a parameter list.

Users should prefer using glassbox() rather than invoking this function directly unless they have a specific reason to customize the pipeline manually.

Value

An object of S3 class eyeris with the following attributes:

1. file: Path to the original .asc file.

2. timeseries: Data frame of all raw time series data from the tracker.

3. events: Data frame of all event messages and their time stamps.

4. blinks: Data frame of all blink events.

5. info: Data frame of various metadata parsed from the file header.

6. latest: eyeris variable for tracking pipeline run history.

For binocular data with binocular_mode = "both", returns a list containing:

1. left: An eyeris object for the left eye data.

2. right: An eyeris object for the right eye data.

3. original_file: Path to the original .asc file.

Note

This function is part of the glassbox() preprocessing pipeline and is not intended for direct use in most cases. Provide parameters via load_asc = list(...).

Advanced users may call it directly if needed.

See Also

eyelinker::read.asc() which this function wraps.

glassbox() for the recommended way to run this step as part of the full eyeris glassbox preprocessing pipeline.

Examples

demo_data <- eyelink_asc_demo_dataset()

demo_data |>
  eyeris::glassbox(load_asc = list(block = 1))

# Other useful parameter configurations
## (1) Basic usage (no block column specified)
demo_data |>
  eyeris::load_asc()

## (2) Manual specification of block number
demo_data |>
  eyeris::load_asc(block = 3)

## (3) Auto-detect multiple recording segments embedded within the same
##  file (i.e., the default behavior)
demo_data |>
  eyeris::load_asc(block = "auto")

## (4) Omit block column
demo_data |>
  eyeris::load_asc(block = NULL)

Lowpass filtering of time series data

Description

The intended use of this method is for smoothing, although by specifying wp and ws differently one can achieve highpass or bandpass filtering as well. However, only lowpass filtering should be done on pupillometry data.

Usage

lpfilt(
  eyeris,
  wp = 4,
  ws = 8,
  rp = 1,
  rs = 35,
  plot_freqz = FALSE,
  call_info = NULL
)

Arguments

Details

This function is automatically called by glassbox() by default. If needed, customize the parameters for lpfilt by providing a parameter list. Use glassbox(lpfilt = FALSE) to disable this step as needed.

Users should prefer using glassbox() rather than invoking this function directly unless they have a specific reason to customize the pipeline manually.

Value

An eyeris object with a new column in timeseries: ⁠pupil_raw_{...}_lpfilt⁠

Note

This function is part of the glassbox() preprocessing pipeline and is not intended for direct use in most cases. Provide parameters via lpfilt = list(...).

Advanced users may call it directly if needed.

See Also

glassbox() for the recommended way to run this step as part of the full eyeris glassbox preprocessing pipeline

Examples

demo_data <- eyelink_asc_demo_dataset()

demo_data |>
  # set lpfilt to FALSE (instead of a list of params) to skip step
  eyeris::glassbox(lpfilt = list(plot_freqz = TRUE)) |>
  plot(seed = 0)

Internal function to lowpass filter pupil data

Description

This function lowpass filters pupil data using a Butterworth filter.

This function is called by the exposed wrapper lpfilt()

Usage

lpfilt_pupil(x, prev_op, wp, ws, rp, rs, fs, plot_freqz)

Arguments

Value

A vector of filtered pupil data

Create baseline label for epoch data

Description

Generates a standardized label for baseline-corrected epoch data.

Usage

make_baseline_label(baselined_data, epoch_id)

Arguments

Value

A character string with the baseline label

Make a BIDS-compatible filename

Description

Helper function to generate a BIDS-compatible filename based on the provided parameters.

Usage

make_bids_fname(
  sub_id,
  task_name,
  run_num,
  desc = "",
  ses_id = NULL,
  epoch_name = NULL,
  epoch_events = NULL,
  baseline_events = NULL,
  baseline_type = NULL,
  eye_suffix = NULL
)

Arguments

Value

A BIDS-compatible filename

Generate epoch label from events and data

Description

Creates a standardized label for epoch data based on events or user-provided label.

Usage

make_epoch_label(evs, label, epoched_data)

Arguments

Value

A character string with the epoch label

Create interactive epoch gallery report

Description

Generates an interactive HTML gallery report for epoch data with lightbox functionality.

Usage

make_gallery(eyeris, epochs, out, epoch_name, ...)

Arguments

Value

No return value; creates and renders an HTML gallery report

Create markdown table from dataframe

Description

Converts a dataframe into a markdown table.

Usage

make_md_table(df)

Arguments

Value

A character string containing the markdown table content

Create multiline markdown table from dataframe

Description

Converts a dataframe into a multiline markdown table.

Usage

make_md_table_multiline(df)

Arguments

Value

A character string containing the markdown table content

Create progressive preprocessing summary plot

Description

Internal function to create a comprehensive visualization showing the progressive effects of preprocessing steps on pupil data. This plot displays multiple preprocessing stages overlaid on the same time series, allowing users to see how each step modifies the pupil signal.

Usage

make_prog_summary_plot(
  pupil_data,
  pupil_steps,
  preview_n = 3,
  plot_params = list(),
  run_id = "run-01",
  cex = 2,
  eye_suffix = NULL
)

Arguments

Details

This function creates a two-panel visualization:

• Top panel: Overlaid time series showing progressive preprocessing effects with different colors for each step

• Bottom panel: Legend identifying each preprocessing step

The plot excludes z-scored data (columns ending with "_z") and only includes steps with sufficient valid data points (>100). Each preprocessing step is displayed with a distinct color, making it easy to see how the signal changes through the pipeline.

Value

NULL (invisibly). Creates a plot showing progressive preprocessing effects with multiple layers overlaid on the same time series

See Also

plot.eyeris

Create eyeris report

Description

Generates a comprehensive HTML report for eyeris preprocessing results.

Usage

make_report(eyeris, out, plots, eye_suffix = NULL, ...)

Arguments

Value

Path to the generated R Markdown file

Process event messages and merge with timeseries

Description

Matches event messages against templates and extracts metadata, supporting both exact matches and pattern matching with wildcards.

Usage

merge_events_with_timeseries(events, metadata_template, merge = TRUE)

Arguments

Value

A dataframe with matched events and extracted metadata

Normalize gaze coordinates to screen-relative units

Description

Transforms raw gaze coordinates (in pixels) to normalized coordinates where:

• (0,0) represents the center of the screen

• Coordinates are scaled to [-1,1] range

• Also calculates the normalized distance from screen center

Usage

normalize_gaze_coords(pupil_df, screen_width, screen_height)

Arguments

Value

A data frame with added columns:

• eye_x_norm: Normalized x coordinate [-1,1]

• eye_y_norm: Normalized y coordinate [-1,1]

• gaze_dist_from_center: Normalized distance from screen center

Parse call stack information

Description

Extracts function name and arguments from a call string.

Usage

parse_call_stack(call_str)

Arguments

Value

A list containing the function name and full call string

Parse EyeLink version and model information

Description

Extracts and cleans version and model information from EyeLink metadata.

Usage

parse_eyelink_info(version_str, model = NA)

Arguments

Value

A list containing cleaned version and model strings

Build a generic operation (extension) for the eyeris pipeline

Description

pipeline_handler enables flexible integration of custom data processing functions into the eyeris pipeline. Under the hood, each preprocessing function in eyeris is a wrapper around a core operation that gets tracked, versioned, and stored using this pipeline_handler method. As such, custom pipeline steps must conform to the eyeris protocol for maximum compatibility with the downstream functions we provide.

Usage

pipeline_handler(eyeris, operation, new_suffix, ...)

Arguments

Details

Following the eyeris protocol also ensures:

• all operations follow a predictable structure, and

• that new pupil data columns based on previous operations in the chain are able to be dynamically constructed within the core timeseries data frame.

Value

An updated eyeris object with the new column added to the timeseries dataframe and the latest pointer updated to the name of the most recently added column plus all previous columns (ie, the history "trace" of preprocessing steps from start-to-present)

See Also

For more details, please check out the following vignettes:

• Anatomy of an eyeris Object

vignette("anatomy", package = "eyeris")

• Building Your Own Custom Pipeline Extensions

vignette("custom-extensions", package = "eyeris")

Examples

# first, define your custom data preprocessing function
winsorize_pupil <- function(x, prev_op, lower = 0.01, upper = 0.99) {
  vec <- x[[prev_op]]
  q <- quantile(vec, probs = c(lower, upper), na.rm = TRUE)
  vec[vec < q[1]] <- q[1]
  vec[vec > q[2]] <- q[2]
  vec
}

# second, construct your `pipeline_handler` method wrapper
winsorize <- function(eyeris, lower = 0.01, upper = 0.99, call_info = NULL) {
  # create call_info if not provided
  call_info <- if (is.null(call_info)) {
    list(
      call_stack = match.call(),
      parameters = list(lower = lower, upper = upper)
    )
  } else {
    call_info
  }

  # handle binocular objects
  if (eyeris:::is_binocular_object(eyeris)) {
    # process left and right eyes independently
    left_result <- eyeris$left |>
      pipeline_handler(
        winsorize_pupil,
        "winsorize",
        lower = lower,
        upper = upper,
        call_info = call_info
      )

    right_result <- eyeris$right |>
      pipeline_handler(
        winsorize_pupil,
        "winsorize",
        lower = lower,
        upper = upper,
        call_info = call_info
    )

    # return combined structure
    list_out <- list(
      left = left_result,
      right = right_result,
      original_file = eyeris$original_file,
      raw_binocular_object = eyeris$raw_binocular_object
    )

    class(list_out) <- "eyeris"

    return(list_out)
  } else {
    # regular eyeris object, process normally
    eyeris |>
      pipeline_handler(
        winsorize_pupil,
        "winsorize",
        lower = lower,
        upper = upper,
        call_info = call_info
      )
  }
}

# and voilà, you can now connect your custom extension
# directly into your custom `eyeris` pipeline definition!
custom_eye <- system.file("extdata", "memory.asc", package = "eyeris") |>
  eyeris::load_asc(block = "auto") |>
  eyeris::deblink(extend = 50) |>
  winsorize()

plot(custom_eye, seed = 1)

Plot pre-processed pupil data from eyeris

Description

S3 plotting method for objects of class eyeris. Plots a single-panel timeseries for a subset of the pupil timeseries at each preprocessing step. The intended use of this function is to provide a simple method for qualitatively assessing the consequences of the preprocessing recipe and parameters on the raw pupillary signal.

Usage

## S3 method for class 'eyeris'
plot(
  x,
  ...,
  steps = NULL,
  preview_n = NULL,
  preview_duration = NULL,
  preview_window = NULL,
  seed = NULL,
  block = 1,
  plot_distributions = FALSE,
  suppress_prompt = TRUE,
  verbose = TRUE,
  add_progressive_summary = FALSE,
  eye = c("left", "right", "both"),
  num_previews = deprecated()
)

Arguments

Value

No return value; iteratively plots a subset of the pupil timeseries from each preprocessing step run

See Also

lifecycle::deprecate_warn()

Examples

# first, generate the preprocessed pupil data
my_eyeris_data <- system.file("extdata", "memory.asc", package = "eyeris") |>
  eyeris::load_asc() |>
  eyeris::deblink(extend = 50) |>
  eyeris::detransient() |>
  eyeris::interpolate() |>
  eyeris::lpfilt(plot_freqz = TRUE) |>
  eyeris::zscore()

# controlling the timeseries range (i.e., preview window) in your plots:

## example 1: using the default 10000 to 20000 ms time subset
plot(my_eyeris_data, seed = 0, add_progressive_summary = TRUE)

## example 2: using a custom time subset (i.e., 1 to 500 ms)
plot(
  my_eyeris_data,
  preview_window = c(0.01, 0.5),
  seed = 0,
  add_progressive_summary = TRUE
)

# controlling which block of data you would like to plot:

## example 1: plots first block (default)
plot(my_eyeris_data, seed = 0)

## example 2: plots a specific block
plot(my_eyeris_data, block = 1, seed = 0)

## example 3: plots a specific block along with a custom preview window
##   (i.e., 1000 to 2000 ms)
plot(
  my_eyeris_data,
  block = 1,
  preview_window = c(1, 2),
  seed = 0
)

Plot binocular correlation between left and right eye data

Description

Creates correlation plots showing the relationship between left and right eye measurements for pupil size, x-coordinates, and y-coordinates. This function is useful for validating binocular data quality and assessing the correlation between the two eyes.

Usage

plot_binocular_correlation(
  eyeris,
  block = 1,
  variables = c("pupil", "x", "y"),
  main = "",
  col_palette = "viridis",
  sample_rate = NULL,
  verbose = TRUE
)

Arguments

Value

No return value; creates correlation plots

Examples

# For binocular data loaded with binocular_mode = "both"
binocular_data <- load_asc(eyelink_asc_binocular_demo_dataset(), binocular_mode = "both")
plot_binocular_correlation(binocular_data)

# For binocular data loaded with binocular_mode = "average"
# (correlation plot will show original left vs right before averaging)
avg_data <- load_asc(eyelink_asc_binocular_demo_dataset(), binocular_mode = "average")
plot_binocular_correlation(avg_data$raw_binocular_object)

Internal helper to plot detrending overlay

Description

This function replicates the exact detrending visualization from the glassbox() interactive preview mode. It uses robust_plot() to show the most recent detrended pupil signal overlaid with the fitted linear trend.

Usage

plot_detrend_overlay(
  pupil_data,
  pupil_steps,
  preview_n = preview_n,
  plot_params = list(),
  suppress_prompt = TRUE
)

Arguments

Value

Logical indicating whether detrend overlay was plotted successfully

Create gaze heatmap of eye coordinates

Description

Creates a heatmap showing the distribution of eye_x and eye_y coordinates across the entire screen area. The heatmap shows where the participant looked most frequently during the recording period.

Usage

plot_gaze_heatmap(
  eyeris,
  block = 1,
  screen_width = NULL,
  screen_height = NULL,
  n_bins = 50,
  col_palette = "viridis",
  main = "Gaze Heatmap",
  xlab = "Screen X (pixels)",
  ylab = "Screen Y (pixels)",
  sample_rate = NULL,
  eye_suffix = NULL
)

Arguments

Value

No return value; creates a heatmap plot

Examples

demo_data <- eyelink_asc_demo_dataset()
eyeris_preproc <- glassbox(demo_data)
plot_gaze_heatmap(eyeris = eyeris_preproc, block = 1)

Plot pupil distribution histogram

Description

Creates a histogram of pupil size distribution with customizable parameters.

Usage

plot_pupil_distribution(data, color, main, xlab, backuplab = NULL)

Arguments

Value

No return value; creates a histogram plot

Plot with seed handling for glassbox pipeline

Description

Internal function to handle plotting with consistent seed management for the glassbox pipeline interactive previews.

Usage

plot_with_seed(
  file,
  step_counter,
  seed,
  preview_n,
  preview_duration,
  preview_window,
  only_linear_trend,
  next_step,
  block_name = NULL,
  verbose = TRUE
)

Arguments

Print lightbox image HTML

Description

Generates HTML code for lightbox image gallery functionality.

Usage

print_lightbox_img_html(images)

Arguments

Value

A character string containing HTML code for the lightbox gallery

Print plots in markdown format

Description

Generates markdown code to display plots in the report.

Usage

print_plots(plots, eye_suffix = NULL)

Arguments

Value

A character string containing markdown plot references

Epoch and baseline processor

Description

This function processes a single block of pupil data to extract epochs and optionally compute and apply baseline corrections. It handles the core epoching and baselining logic for a single block of data.

Usage

process_epoch_and_baselines(eyeris, timestamps, evs, lims, hz, verbose)

Arguments

Details

This function is called by the internal epoch_and_baseline_block() function.

Value

A list containing epoch and baseline results

Process eyeris data and create eyeris object

Description

Process eyeris data and create eyeris object

Usage

process_eyeris_data(x, block, eye, hz, pupil_type, file, binoc, binoc_mode)

Arguments

Value

An eyeris object

Create a progress bar for tracking operations

Description

Creates a progress bar using the progress package with customizable formatting.

Usage

progress_bar(
  total,
  msg = "Processing",
  width = 80,
  show_percent = TRUE,
  show_eta = TRUE,
  clear = FALSE
)

Arguments

Value

A progress bar object from the progress package

Prompt user for continuation

Description

Prompts the user to continue or cancel the current operation.

Usage

prompt_user()

Value

A logical flag indicating whether the user chose to continue

Render R Markdown report

Description

Renders an R Markdown file to HTML and cleans up the temporary file.

Usage

render_report(rmd_f)

Arguments

Value

No return value; renders HTML report and removes temporary file

Robust plotting function with error handling

Description

A wrapper around base plotting functions that handles errors and missing data gracefully.

Usage

robust_plot(y, x = NULL, ...)

Arguments

Value

No return value; creates a plot or displays warning messages

Internal function to run bidsify on a single eye

Description

Internal function to run bidsify on a single eye

Usage

run_bidsify(
  eyeris,
  save_all = TRUE,
  epochs_list = NULL,
  merge_epochs = FALSE,
  bids_dir = NULL,
  participant_id = NULL,
  session_num = NULL,
  task_name = NULL,
  run_num = NULL,
  merge_runs = FALSE,
  save_raw = TRUE,
  html_report = TRUE,
  report_seed = 0,
  report_epoch_grouping_var_col = "matched_event",
  eye_suffix = NULL,
  verbose = TRUE,
  raw_binocular_object = NULL
)

Arguments

Value

A eyeris object

Sanitize event tag string into canonical epoch label

Description

Converts event tag strings into standardized epoch labels by removing special characters and converting to camel case.

Usage

sanitize_event_tag(string, prefix = "epoch_")

Arguments

Value

A sanitized epoch label string

Save detrend plots for each block

Description

Generates and saves detrend diagnostic plots for each block in the eyeris object.

Usage

save_detrend_plots(
  eyeris,
  out_dir,
  preview_n = 3,
  plot_params = list(),
  eye_suffix = NULL
)

Arguments

Value

No return value; saves detrend plots to the specified directory

Save progressive summary plots for each block

Description

Generates and saves progressive summary plots for each block in the eyeris object.

Usage

save_progressive_summary_plots(
  eyeris,
  out_dir,
  preview_n = 3,
  plot_params = list(),
  eye_suffix = NULL
)

Arguments

Value

A character string containing markdown references to the saved plots

Check if binocular correlations should be plotted

Description

Validates that binocular correlations should be plotted.

Usage

should_plot_binoc_cors(x)

Arguments

Value

Logical indicating whether binocular correlations should be plotted

Slice epoch from raw timeseries data

Description

Extracts a time segment from raw timeseries data based on start and end times.

Usage

slice_epoch(x_raw, s, e)

Arguments

Value

A dataframe containing the epoch data

Slice epochs with no explicit limits

Description

Creates epochs using adjacent timestamps without explicit time limits.

Usage

slice_epochs_no_limits(x_raw, all_ts)

Arguments

Value

A list of epoch dataframes

Slice epochs with explicit limits

Description

Creates epochs using explicit time limits around a central timestamp.

Usage

slice_epochs_with_limits(x_raw, cur_ts, lims, hz)

Arguments

Value

A dataframe containing the epoch data

Calculate pupil speed using finite differences

Description

Computes the speed of pupil changes using finite differences between consecutive time points. This is a helper function for the detransient step.

Usage

speed(x, y)

Arguments

Value

A vector of pupil speeds at each time point

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 timeseries in the eyeris object.

Usage

summarize_confounds(eyeris)

Arguments

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:

• Blink rate and duration statistics

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

• Pupil size mean, standard deviation, and range

• Missing data percentage

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 timeseries for a specific block and step
confounds$confounds$unepoched_timeseries

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

Tag blinks in pupil data

Description

Identifies when pupil data corresponds to eye blinks based on missing values in the pupil vector.

Usage

tag_blinks(pupil_df, pupil_vec)

Arguments

Value

A data frame with added column:

• is_blink: Logical indicating if pupil data corresponds to a blink (NA values)

Tag gaze coordinates as on/off screen

Description

Identifies when gaze coordinates fall outside the screen boundaries, with an optional buffer zone to account for potential overshoot in eye tracking.

Usage

tag_gaze_coords(pupil_df, screen_width, screen_height, overshoot_buffer = 0.05)

Arguments

Value

A data frame with added column:

• is_offscreen: Logical indicating if gaze is outside screen boundaries

Tick a progress bar

Description

Advances a progress bar by the specified amount.

Usage

tick(pb, by = 1)

Arguments

Value

No return value; advances the progress bar

Z-score pupil timeseries data

Description

The intended use of this method is to scale the arbitrary units of the pupil size timeseries to have a mean of 0 and a standard deviation of 1. This is accomplished by mean centering the data points and then dividing them by their standard deviation (i.e., z-scoring the data, similar to base::scale()). Opting to z-score your pupil data helps with trial-level and between-subjects analyses where arbitrary units of pupil size recorded by the tracker do not scale across participants, and therefore make analyses that depend on data from more than one participant difficult to interpret.

Usage

zscore(eyeris, call_info = NULL)

Arguments

Details

This function is automatically called by glassbox() by default. Use glassbox(zscore = FALSE) to disable this step as needed.

Users should prefer using glassbox() rather than invoking this function directly unless they have a specific reason to customize the pipeline manually.

In general, it is common to z-score pupil data within any given participant, and furthermore, z-score that participant's data as a function of block number (for tasks/experiments where participants complete more than one block of trials) to account for potential time-on-task effects across task/experiment blocks.

As such, if you use the eyeris package as intended, you should NOT need to specify any groups for the participant/block-level situations described above. This is because eyeris is designed to preprocess a single block of pupil data for a single participant, one at a time. Therefore, when you later merge all of the preprocessed data from eyeris, each individual, preprocessed block of data for each participant will have already been independently scaled from the others.

Additionally, if you intend to compare mean z-scored pupil size across task conditions, such as that for memory successes vs. memory failures, then do NOT set your behavioral outcome (i.e., success/failure) variable as a grouping variable within your analysis. If you do, you will consequently obtain a mean pupil size of 0 and standard deviation of 1 within each group (since the scaled pupil size would be calculated on the timeseries from each outcome variable group, separately). Instead, you should compute the z-score on the entire pupil timeseries (before epoching the data), and then split and take the mean of the z-scored timeseries as a function of condition variable.

Value

An eyeris object with a new column in timeseries: ⁠pupil_raw_{...}_z⁠

Note

This function is part of the glassbox() preprocessing pipeline and is not intended for direct use in most cases. Use glassbox(zscore = TRUE).

Advanced users may call it directly if needed.

See Also

glassbox() for the recommended way to run this step as part of the full eyeris glassbox preprocessing pipeline

Examples

demo_data <- eyelink_asc_demo_dataset()

demo_data |>
  eyeris::glassbox(zscore = TRUE) |> # set to FALSE to skip (not recommended)
  plot(seed = 0)

Internal function to z-score pupil data

Description

This function z-scores pupil data by subtracting the mean and dividing by the standard deviation.

This function is called by the exposed wrapper zscore()

Usage

zscore_pupil(x, prev_op)

Arguments

Value

A vector of z-scored pupil data