Type:	Package
Title:	Flexible, Extensible, & Reproducible Pupillometry Preprocessing
Version:	3.0.0
Date:	2025-09-16
Language:	en-US
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, DBI, glue, base64enc, arrow
RoxygenNote:	7.3.3
Suggests:	duckdb, 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-09-16 23:14:51 UTC; shawn.schwartz
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-09-17 07:50: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

Save out pupil time series 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 time series, and formats the directory and filename structures based on the metadata you provide.

Usage

bidsify(
  eyeris,
  save_all = TRUE,
  epochs_list = NULL,
  bids_dir = NULL,
  participant_id = NULL,
  session_num = NULL,
  task_name = NULL,
  run_num = NULL,
  save_raw = TRUE,
  html_report = TRUE,
  report_seed = 0,
  report_epoch_grouping_var_col = "matched_event",
  verbose = TRUE,
  csv_enabled = TRUE,
  db_enabled = FALSE,
  db_path = "my-project",
  parallel_processing = FALSE,
  merge_epochs = deprecated(),
  merge_runs = deprecated(),
  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 time series
    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
  )

# example with database storage enabled
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",
    db_enabled = TRUE,  # enable eyerisdb database storage
    db_path = "my-project"  # custom project database name
  )

# example for large-scale cloud compute (database only, no CSV files)
demo_data |>
  eyeris::glassbox() |>
  eyeris::bidsify(
    bids_dir = tempdir(),
    participant_id = "001",
    session_num = "01",
    task_name = "assocret",
    csv_enabled = FALSE,  # disable CSV files
    db_enabled = TRUE     # database storage only
  )

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 time series 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 data frame

Description

Validates that a specified column exists in a data frame.

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 for DuckDB availability

Description

This internal helper checks whether the duckdb package is installed. If it is not available, a status message is displayed with platform-specific installation instructions (macOS, Linux, Windows). Functions that depend on DuckDB call this check before proceeding.

Usage

check_duckdb()

Value

TRUE if duckdb is installed, otherwise FALSE (with an informative status message).

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 data frames.

Usage

check_epoch_manual_input_data(ts_list)

Arguments

Value

No return value; throws error if structure is invalid

Check epoch manual input data frame format

Description

Validates that start and end timestamp data frames 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 data frames 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

Clean up individual image files in run directories after HTML generation

Description

Removes PNG and JPG files from the root of source/figures/run-xx directories after all HTML reports have been generated. This cleans up loose image files that may have been created during report generation.

Usage

cleanup_run_dir_images(report_path, eye_suffix = NULL, verbose = FALSE)

Arguments

Value

Invisibly returns TRUE if cleanup was successful, FALSE otherwise

Clean up source figures after report generation

Description

Removes the entire source/figures directory after the main HTML report has been generated since all images are now embedded in the HTML as data URLs.

Usage

cleanup_source_figures_post_render(
  report_path,
  eye_suffix = NULL,
  verbose = FALSE
)

Arguments

Value

Invisibly returns TRUE if cleanup was successful, FALSE otherwise

Cleanup temporary database

Description

Safely disconnects and removes temporary database files after successful merge.

Usage

cleanup_temp_database(temp_db_info, verbose = FALSE)

Arguments

Value

Logical indicating success

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

Create or connect to eyeris project database

Description

Creates a new DuckDB database for the eyeris project or connects to an existing one. The database will be created in the BIDS derivatives directory. When parallel processing is enabled, creates temporary databases to avoid concurrency issues.

Usage

connect_eyeris_database(
  bids_dir,
  db_path = "my-project",
  verbose = FALSE,
  parallel = FALSE
)

Arguments

Value

DBI database connection object or temp database info list (when parallel=TRUE)

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

Create zip file from epoch images

Description

Creates a zip file containing epoch images instead of saving individual files. This function collects all the image data in memory and then creates a single zip file, which can be more efficient for the HTML gallery display.

Usage

create_epoch_images_zip(
  epochs_to_save,
  epoch_index,
  block_name,
  run_dir_num,
  epochs_out,
  pupil_steps,
  eyeris_object,
  eye_suffix = NULL,
  report_epoch_grouping_var_col = "matched_event",
  verbose = FALSE
)

Arguments

Value

Path to the created zip file

Create table name for eyeris data

Description

Generates a standardized table name for eyeris data based on the data type and subject information.

Usage

create_table_name(
  data_type,
  sub,
  ses,
  task,
  run = NULL,
  eye_suffix = NULL,
  epoch_label = NULL
)

Arguments

Value

Character string with table name

Create temporary database for parallel processing

Description

Creates a unique temporary database for use in parallel jobs to avoid concurrency issues. The temporary database is named using process ID and timestamp to ensure uniqueness.

Usage

create_temp_eyeris_database(
  bids_dir,
  base_db_path = "my-project",
  verbose = FALSE
)

Arguments

Value

List containing database connection and temp database path

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 ⁠time series⁠: ⁠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 ⁠time series⁠: 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

Disconnect from eyeris database

Description

Safely disconnects from the eyeris project database.

Usage

disconnect_eyeris_database(con, verbose = FALSE)

Arguments

Value

Logical indicating success

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 time series data for preview plotting.

Usage

draw_random_epochs(x, n, d, hz)

Arguments

Value

A list of data frames, 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 time series 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 data frames of timestamps

Description

This function manually epochs data using provided start/end data frames 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 and/or database

Description

Exports each block's confounds data to a separate CSV file and/or database table. 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,
  csv_enabled = TRUE,
  db_con = NULL,
  sub = NULL,
  ses = NULL,
  task = NULL,
  eye_suffix = NULL,
  epoch_label = NULL
)

Arguments

Value

Invisibly returns a vector of created file paths

Extract baseline epochs from time series data

Description

Extracts baseline periods from time series 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 data frames

Extract event identifiers from event messages

Description

Extracts identifiers (like image names or trial numbers) from event messages to enable matching between start and end events.

Usage

extract_event_ids(events)

Arguments

Value

A vector of extracted identifiers

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)

Extract and aggregate eyeris data across subjects from database

Description

A comprehensive wrapper function that simplifies extracting eyeris data from the database. Provides easy one-liner access to aggregate data across multiple subjects for each data type, without requiring SQL knowledge.

Usage

eyeris_db_collect(
  bids_dir,
  db_path = "my-project",
  subjects = NULL,
  data_types = NULL,
  sessions = NULL,
  tasks = NULL,
  epoch_labels = NULL,
  eye_suffixes = NULL,
  verbose = TRUE
)

Arguments

Value

A named list of data frames, one per data type

Examples

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
  db_enabled = TRUE # enable database storage
)

# extract all data for all subjects (returns list of data frames)
all_data <- eyeris_db_collect(tempdir())

# view available data types
names(all_data)

# access specific data type
blinks_data <- all_data$blinks
epochs_data <- all_data$epochs

# extract specific subjects and data types
subset_data <- eyeris_db_collect(
  bids_dir = tempdir(),
  subjects = c("001"),
  data_types = c("blinks", "epochs", "timeseries")
)

# extract epoch data for specific epoch label
epoch_data <- eyeris_db_collect(
  bids_dir = tempdir(),
  data_types = "epochs",
  epoch_labels = "prepostprobe"
)

Connect to eyeris project database (user-facing)

Description

User-friendly function to connect to an existing eyeris project database. This function provides easy access for users to query their eyeris data.

Usage

eyeris_db_connect(bids_dir, db_path = "my-project")

Arguments

Value

Database connection object for use with other eyeris database functions

Examples

# step 1: create a database using bidsify with db_enabled = TRUE
# (This example assumes you have already run bidsify to create a database)

# temp dir for testing
temp_dir <- tempdir()

# step 2: connect to eyeris DB (will fail gracefully if no DB exists)
tryCatch({
  con <- eyeris_db_connect(temp_dir)

  tables <- eyeris_db_list_tables(con)

  # read timeseries data for a specific subject
  data <- eyeris_db_read(con, data_type = "timeseries", subject = "001")

  # close connection when done
  eyeris_db_disconnect(con)
}, error = function(e) {
  message("No eyeris DB found - create one first with bidsify(db_enabled = TRUE)")
})

Disconnect from eyeris database (user-facing)

Description

User-friendly function to disconnect from the eyeris project database.

Usage

eyeris_db_disconnect(con)

Arguments

Value

Logical indicating success

List available tables in eyeris database

Description

Lists all tables in the eyeris project database with optional filtering.

Usage

eyeris_db_list_tables(con, data_type = NULL, subject = NULL)

Arguments

Value

Character vector of table names

Read eyeris data from database

Description

Reads eyeris data from the project database with dplyr-style interface.

Usage

eyeris_db_read(
  con,
  data_type = NULL,
  subject = NULL,
  session = NULL,
  task = NULL,
  run = NULL,
  eye_suffix = NULL,
  epoch_label = NULL,
  table_name = NULL
)

Arguments

Value

Data frame with requested data

Reconstruct eyerisdb from chunked files

Description

Merges multiple chunked eyerisdb files back into a single database file. Uses the reconstruction metadata file created by eyeris_db_split_for_sharing() to ensure proper reconstruction.

Usage

eyeris_db_reconstruct_from_chunks(
  chunked_dir,
  output_path,
  reconstruction_file = NULL,
  verbose = TRUE
)

Arguments

Value

List containing information about the reconstruction process

Examples

## Not run: 
# Reconstruct database from chunked files
reconstruction_info <- eyeris_db_reconstruct_from_chunks(
  chunked_dir = "/path/to/chunked_db/project-name",
  output_path = "/path/to/reconstructed-project.eyerisdb"
)

# Specify custom reconstruction file location
reconstruction_info <- eyeris_db_reconstruct_from_chunks(
  chunked_dir = "/path/to/chunked_db/project-name",
  output_path = "/path/to/reconstructed-project.eyerisdb",
  reconstruction_file = "/path/to/custom_reconstruction_info.json"
)

## End(Not run)

Split eyerisdb for data sharing and distribution

Description

Creates multiple smaller eyerisdb files from a single large database for easier distribution via platforms with file size limits (GitHub, OSF, data repositories, etc.). Data can be chunked by data type, by number of chunks, or by maximum file size. Includes metadata to facilitate reconstruction of the original database.

Usage

eyeris_db_split_for_sharing(
  bids_dir,
  db_path = "my-project",
  output_dir = NULL,
  chunk_strategy = "by_data_type",
  n_chunks = 4,
  max_chunk_size_mb = 100,
  data_types = NULL,
  group_by_epoch_label = TRUE,
  include_metadata = TRUE,
  verbose = TRUE
)

Arguments

Value

List containing information about created chunked databases and reconstruction instructions

Examples

## Not run: 
# These examples require an existing eyeris database

# Chunk by data type (each data type gets its own database file)
chunk_info <- eyeris_db_split_for_sharing(
  bids_dir = "/path/to/bids",
  db_path = "large-project",
  chunk_strategy = "by_data_type"
)

# Chunk into 6 files by count
chunk_info <- eyeris_db_split_for_sharing(
  bids_dir = "/path/to/bids",
  db_path = "large-project",
  chunk_strategy = "by_count",
  n_chunks = 6
)

# Chunk by size (max 50MB per file)
chunk_info <- eyeris_db_split_for_sharing(
  bids_dir = "/path/to/bids",
  db_path = "large-project",
  chunk_strategy = "by_size",
  max_chunk_size_mb = 50
)

## End(Not run)

Get summary statistics for eyeris database

Description

Provides a quick overview of the contents of an eyeris database, including available subjects, sessions, tasks, and data types.

Usage

eyeris_db_summary(bids_dir, db_path = "my-project", verbose = TRUE)

Arguments

Value

A named list containing summary information about the database contents

Examples

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 = file.path(tempdir(), "my-cool-memory-project"),
    participant_id = "001",
    session_num = "01",
    task_name = "assocret",
    run_num = "03", # override default run-01 (block_1) to use run-03 instead
    db_enabled = TRUE,
    db_path = "my-cool-memory-study",
  )

# get database summary
summary <- eyeris_db_summary(
             file.path(
               tempdir(),
               "my-cool-memory-project"
             ),
             db_path = "my-cool-memory-study"
           )

# view available subjects
summary$subjects

# view available data types
summary$data_types

# view table counts
summary$table_counts

Export eyeris database to chunked files

Description

High-level wrapper function to export large eyeris databases to chunked CSV or Parquet files by data type. Uses chunked processing to handle very large datasets without memory issues.

Usage

eyeris_db_to_chunked_files(
  bids_dir,
  db_path = "my-project",
  output_dir = NULL,
  chunk_size = 1e+06,
  file_format = "csv",
  data_types = NULL,
  subjects = NULL,
  max_file_size_mb = 50,
  group_by_epoch_label = TRUE,
  verbose = TRUE
)

Arguments

Value

List containing information about exported files

Examples

## Not run: 
# These examples require an existing eyeris database

# Export entire database to CSV files
if (file.exists(file.path(tempdir(), "derivatives", "large-project.eyerisdb"))) {
  export_info <- eyeris_db_to_chunked_files(
    bids_dir = tempdir(),
    db_path = "large-project",
    chunk_size = 50000,
    file_format = "csv"
  )
}

# Export specific data types to Parquet
if (file.exists(file.path(tempdir(), "derivatives", "large-project.eyerisdb"))) {
  export_info <- eyeris_db_to_chunked_files(
    bids_dir = tempdir(),
    db_path = "large-project",
    data_types = c("timeseries", "events"),
    file_format = "parquet",
    chunk_size = 75000
  )
}

## End(Not run)

Split eyeris database into N parquet files by data type

Description

Utility function that takes an eyerisdb DuckDB database and splits it into N reasonably sized parquet files for easy management with GitHub, downloading, and distribution. Data is first grouped by table type (timeseries, epochs, events, etc.) since each has different columnar structures, then each group is split into the specified number of files. Files are organized in folders matching the database name for easy identification.

Usage

eyeris_db_to_parquet(
  bids_dir,
  db_path = "my-project",
  n_files_per_type = 1,
  output_dir = NULL,
  max_file_size = 512,
  data_types = NULL,
  verbose = TRUE,
  include_metadata = TRUE,
  epoch_labels = NULL,
  group_by_epoch_label = TRUE
)

Arguments

Value

List containing information about created parquet files

Database Safety

This function creates temporary tables during parquet export when the arrow package is not available. All temporary tables are automatically cleaned up, but if the process crashes, leftover tables may remain. The function checks for and warns about existing temporary tables before starting.

Examples

# create demo database
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 = "memory",
    db_enabled = TRUE,
    db_path = "memory-task"
  )

# split into 3 parquet files per data type - creates memory-task/ folder
split_info <- eyeris_db_to_parquet(
  bids_dir = tempdir(),
  db_path = "memory-task",
  n_files_per_type = 3
)

# split with size constraint and specific data types using the same database
split_info <- eyeris_db_to_parquet(
  bids_dir = tempdir(),
  db_path = "memory-task",
  n_files_per_type = 5,
  max_file_size = 50,  # max 50MB per file
  data_types = c("timeseries", "epochs", "events")
)

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, verbose = TRUE)

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, defaults to 1 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

Get formatted timestamp for logging

Description

Get formatted timestamp for logging

Usage

get_log_timestamp()

Value

Character string with current timestamp

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 time series data for each step so you can adjust parameters and re-run the pipeline until you are satisfied with the choices of your parameters and their consequences on your pupil time series 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 data frame

Description

Extracts a single row of metadata from a data frame.

Usage

index_metadata(x, i)

Arguments

Value

A single row from the data frame

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"),
  verbose = TRUE
)

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)

Log an error message and abort

Description

Log an error message and abort

Usage

log_error(..., wrap = TRUE, .envir = parent.frame())

Arguments

Examples

## Not run: 
log_error("Critical error occurred")
file_path <- "missing.csv"
log_error("File not found: {file_path}")

## End(Not run)

Log an informational message

Description

Log an informational message

Usage

log_info(..., verbose = TRUE, wrap = TRUE, .envir = parent.frame())

Arguments

Examples

## Not run: 
log_info("Processing file:", "data.csv")
subject_id <- "001"
log_info("Processing subject {subject_id}")
log_info("Found {nrow(data)} rows", "in dataset")

## End(Not run)

Core logging function with timestamp and glue support

Description

Core logging function with timestamp and glue support

Usage

log_message(level, ..., verbose = TRUE, wrap = TRUE, .envir = parent.frame())

Arguments

Log a success message

Description

Log a success message

Usage

log_success(..., verbose = TRUE, wrap = TRUE, .envir = parent.frame())

Arguments

Examples

## Not run: 
log_success("Processing completed successfully")
n_files <- 5
log_success("Processed {n_files} files successfully")

## End(Not run)

Log a warning message

Description

Log a warning message

Usage

log_warn(..., verbose = TRUE, wrap = TRUE, .envir = parent.frame())

Arguments

Examples

## Not run: 
log_warn("Missing data detected")
missing_count <- 10
log_warn("Found {missing_count} missing values")

## End(Not run)

Standardized logging functions for eyeris

Description

These functions provide a consistent logging interface with automatic timestamping, glue-style string interpolation, and support for multiple string arguments.

Arguments

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 ⁠time series⁠: ⁠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 data frame

Description

Converts a data frame into a markdown table.

Usage

make_md_table(df)

Arguments

Value

A character string containing the markdown table content

Create multiline markdown table from data frame

Description

Converts a data frame 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 time series

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 data frame with matched events and extracted metadata

Merge temporary database into main database

Description

Safely merges data from a temporary database into the main project database using file locking to prevent concurrent access issues. This function handles the transactional copying of all tables from the temporary database.

Usage

merge_temp_database(
  temp_db_info,
  verbose = FALSE,
  max_retries = 10,
  retry_delay = 1
)

Arguments

Value

Logical indicating success

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 time series data frame.

Value

An updated eyeris object with the new column added to the timeseries data frame 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 time series 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 time series 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 time series 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 for zip-based gallery

Description

Generates HTML code for lightbox image gallery functionality that loads images from zip files using zip.js.

Usage

print_lightbox_img_html(zip_path, image_filenames = NULL, verbose = TRUE)

Arguments

Value

A character string containing HTML code for the lightbox gallery

Print lightbox image HTML (legacy)

Description

Generates HTML code for lightbox image gallery functionality using individual image files (legacy behavior).

Usage

print_lightbox_img_html_legacy(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

Process large database query in chunks

Description

Handles really large databases by processing queries in reasonably sized chunks to avoid memory issues. Data can be written to CSV or Parquet files as it's processed.

Usage

process_chunked_query(
  con,
  query,
  chunk_size = 1e+06,
  output_file = NULL,
  process_chunk = NULL,
  verbose = TRUE
)

Arguments

Value

List containing summary information about the chunked processing

Examples

## Not run: 
# These examples require an existing eyeris database

con <- eyeris_db_connect("/path/to/bids", "my-project")

# Process large query and write to CSV
process_chunked_query(
  con,
  "SELECT * FROM large_table WHERE condition = 'something'",
  chunk_size = 50000,
  output_file = "large_export.csv"
)

# Process large query with custom chunk processing
process_chunked_query(
  con,
  "SELECT * FROM large_table",
  chunk_size = 25000,
  process_chunk = function(chunk) {
    # Custom processing here
    processed_data <- some_analysis(chunk)
    return(TRUE)
  }
)

eyeris_db_disconnect(con)

## End(Not run)

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

Read parquet files back into R

Description

Convenience function to read the parquet files created by eyeris_db_to_parquet back into a single data frame or list of data frames by data type.

Usage

read_eyeris_parquet(
  parquet_dir,
  db_name = NULL,
  data_type = NULL,
  return_list = FALSE,
  pattern = "*.parquet",
  verbose = TRUE
)

Arguments

Value

Combined data frame from all parquet files, or list of data frames by data type

Examples

# Minimal self-contained example that avoids database creation
if (requireNamespace("arrow", quietly = TRUE)) {
  # create a temporary folder structure: parquet/<db_name>
  base_dir <- file.path(tempdir(), "derivatives", "parquet")
  db_name <- "example-db"
  dir.create(file.path(base_dir, db_name), recursive = TRUE, showWarnings = FALSE)

  # write two small parquet parts for a single data type
  part1 <- data.frame(time = 1:5, value = 1:5)
  part2 <- data.frame(time = 6:10, value = 6:10)
  arrow::write_parquet(
    part1,
    file.path(
      base_dir, db_name, paste0(db_name, "_timeseries_part-01-of-02.parquet")
    )
  )
  arrow::write_parquet(
    part2,
    file.path(
      base_dir, db_name, paste0(db_name, "_timeseries_part-02-of-02.parquet")
    )
  )

  # read them back as combined data frame
  data <- read_eyeris_parquet(base_dir, db_name = db_name)

  # read as list by data type
  data_by_type <- read_eyeris_parquet(base_dir, db_name = db_name, return_list = TRUE)

  # read specific data type only
  timeseries_data <- read_eyeris_parquet(base_dir, db_name = db_name, data_type = "timeseries")
}

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,
  bids_dir = NULL,
  participant_id = NULL,
  session_num = NULL,
  task_name = NULL,
  run_num = NULL,
  save_raw = TRUE,
  html_report = TRUE,
  report_seed = 0,
  report_epoch_grouping_var_col = "matched_event",
  eye_suffix = NULL,
  verbose = TRUE,
  csv_enabled = TRUE,
  db_enabled = FALSE,
  db_path = "my-project",
  parallel_processing = FALSE,
  raw_binocular_object = NULL,
  skip_db_cleanup = FALSE
)

Arguments

Value

An 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,
  verbose = TRUE
)

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,
  verbose = TRUE
)

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 time series data

Description

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

Usage

slice_epoch(x_raw, s, e)

Arguments

Value

A data frame containing the epoch data

Slice epochs with no explicit limits

Description

Creates epochs using adjacent time stamps without explicit time limits.

Usage

slice_epochs_no_limits(x_raw, all_ts)

Arguments

Value

A list of epoch data frames

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 data frame 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 time series 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 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

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

Write data to CSV and/or database (helper function)

Description

This helper function writes data to CSV files and/or database based on the configuration. Useful for large-scale cloud compute where CSV files may be unnecessary when using database storage.

Usage

write_csv_and_db(
  data,
  csv_path,
  csv_enabled = TRUE,
  db_con = NULL,
  data_type = NULL,
  sub = NULL,
  ses = NULL,
  task = NULL,
  run = NULL,
  eye_suffix = NULL,
  epoch_label = NULL,
  verbose = FALSE
)

Arguments

Value

Logical indicating success

Write eyeris data to database

Description

Writes eyeris data to the project database as an alternative to CSV files. Creates or updates tables as needed.

Usage

write_eyeris_data_to_db(
  data,
  con,
  data_type,
  sub,
  ses,
  task,
  run = NULL,
  eye_suffix = NULL,
  epoch_label = NULL,
  append = TRUE,
  verbose = FALSE
)

Arguments

Value

Logical indicating success

Zip and cleanup source figure files

Description

Creates zip files for all PNG and JPG files in each run directory under source/figures/, then deletes the individual image files. This reduces file count while preserving all figure data in compressed format.

Usage

zip_and_cleanup_source_figures(report_path, eye_suffix = NULL, verbose = FALSE)

Arguments

Value

List of created zip file paths

Z-score pupil time series data

Description

The intended use of this method is to scale the arbitrary units of the pupil size time series 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 time series from each outcome variable group, separately). Instead, you should compute the z-score on the entire pupil time series (before epoching the data), and then split and take the mean of the z-scored time series as a function of condition variable.

Value

An eyeris object with a new column in ⁠time series⁠: ⁠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