plot.eyeris: Plot pre-processed pupil data from 'eyeris'

In eyeris: Flexible, Extensible, & Reproducible Processing of Pupil Data

Plot pre-processed pupil data from eyeris

Description

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

Usage

## S3 method for class 'eyeris'
plot(
  x,
  ...,
  steps = NULL,
  num_previews = NULL,
  preview_duration = NULL,
  preview_window = NULL,
  seed = NULL,
  block = 1,
  plot_distributions = TRUE
)

Arguments

x	An object of class eyeris derived from load().
...	Additional arguments to be passed to plot.
steps	Which steps to plot; defaults to all (i.e., plot all steps). Otherwise, pass in a vector containing the index of the step(s) you want to plot, with index 1 being the original raw pupil timeseries.
num_previews	Number of random example "epochs" to generate for previewing the effect of each preprocessing step on the pupil timeseries.
preview_duration	Time in seconds of each randomly selected preview.
preview_window	The start and stop raw timestamps used to subset the preprocessed data from each step of the eyeris workflow for visualization. Defaults to NULL, meaning random epochs as defined by num_examples and example_duration will be plotted. To override the random epochs, set example_timelim here to a vector with relative start and stop times (e.g., c(5000, 6000) to indicate the raw data from 5-6 seconds on data that were recorded at 1000 Hz). Note, the start/stop time values indicated here relate to the raw index position of each pupil sample from 1 to n (which will need to be specified manually by the user depending on the sampling rate of the recording; i.e., 5000-6000 for the epoch positioned from 5-6 seconds after the start of the timeseries, sampled at 1000 Hz).
seed	Random seed for current plotting session. Leave NULL to select num_previews number of random preview "epochs" (of preview_duration) each time. Otherwise, choose any seed-integer as you would normally select for base::set.seed(), and you will be able to continue re-plotting the same random example pupil epochs each time – which is helpful when adjusting parameters within and across eyeris workflow steps.
block	For multi-block recordings, specifies which block to plot. Defaults to 1. When a single .asc data file contains multiple recording blocks, this parameter determines which block's timeseries to visualize. Must be a positive integer not exceeding the total number of blocks in the recording.
plot_distributions	Logical flag to indicate whether to plot both diagnostic pupil timeseries and accompanying histograms of the pupil samples at each processing step. Defaults to TRUE.

Value

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

Examples

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

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

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

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

# 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
plot(
  my_eyeris_data,
  block = 1,
  preview_window = c(1000, 2000),
  seed = 0
)

eyeris documentation built on April 12, 2025, 2:05 a.m.