eyeris (version 2.1.1)

epoch: 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()
)

Value

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

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

Arguments

eyeris

An object of class eyeris derived from load_asc()

events

Either (1) a single string representing the event message to perform trial extraction around, using specified limits to center the epoch around or no limits (which then just grabs the data epochs between each subsequent event string of the same type); (2) a vector containing both start and end event message strings -- here, limits will be ignored and the duration of each trial epoch will be the number of samples between each matched start and end event message pair; or (3) a list of 2 dataframes that manually specify start/end event timestamp-message pairs to pull out of the raw timeseries data -- here, it is required that each raw timestamp and event message be provided in the following format:

list( data.frame(time = c(...), msg = c(...)), # start events data.frame(time = c(...), msg = c(...)), # end events 1 # block number )

where the first data.frame indicates the start event timestamp and message string pairs, and the second data.frame indicates the end event timestamp and message string pairs. Additionally, manual epoching only words with 1 block at a time for event-modes 2 and 3; thus, please be sure to explicitly indicate the block number in your input list (for examples, see above as well as example #9 below for more details)

For event-modes 1 and 2, the way in which you pass in the event message string must conform to a standardized protocol so that eyeris knows how to find your events and (optionally) parse any included metadata into the tidy epoch data outputs. You have two primary choices: either (a) specify a string followed by a * wildcard expression (e.g., "PROBE_START*), which will match any messages that have "PROBE_START ..." (... referring to potential metadata, such as trial number, stim file, etc.); or (b) specify a string using the eyeris syntax: (e.g., "PROBE_{type}_{trial}"), which will match the messages that follow a structure like this "PROBE_START_1" and "PROBE_STOP_1", and generate two additional metadata columns: type and trial, which would contain the following values based on these two example strings: type: ('START', 'STOP'), and trial: (1, 1)

limits

A vector of 2 values (start, end) in seconds, indicating where trial extraction should occur centered around any given start message string in the events parameter

label

An (optional) string you can provide to customize the name of the resulting eyeris class object containing the epoched data frame. If left as NULL (default), then list item will be called epoch_xyz, where xyz will be a sanitized version of the original start event string you provided for matching. If you choose to specify a label here, then the resulting list object name will take the form: epoch_label. Warning: if no label is specified and there are no event message strings to sanitize, then you may obtain a strange-looking epoch list element in your output object (e.g., $epoch_, or $epoch_nana, etc.). The data should still be accessible within this nested lists, however, to avoid ambiguous list objects, we recommend you provide an epoch label here to be safe

baseline

(New) A single parameter that controls baseline correction. Set to TRUE to both calculate and apply baseline correction, or FALSE to skip it. This replaces the deprecated calc_baseline and apply_baseline parameters

baseline_type

Whether to perform subtractive (sub) or divisive (div) baseline correction. Defaults to sub

baseline_events

Similar to events, baseline_events, you can supply either (1) a single string representing the event message to center the baseline calculation around, as indicated by baseline_period; or (2) a single vector containing both a start and an end event message string -- here, baseline_period will be ignored and the duration of each baseline period that the mean will be calculated on will be the number of samples between each matched start and end event message pair, as opposed to a specified fixed duration (as described in 1). Please note, providing a list of trial-level start/end message pairs (like in the events parameter) to manually indicate unique start/end chunks for baselining is currently unsupported. Though, we intend to add this feature in a later version of eyeris, given it likely won't be a heavily utilized / in demand feature.

baseline_period

A vector of 2 values (start, end) in seconds, indicating the window of data that will be used to perform the baseline correction, which will be centered around the single string "start" message string provided in baseline_events. Again, baseline_period will be ignored if both a "start" and "end" message string are provided to the baseline_events argument

hz

Data sampling rate. If not specified, will use the value contained within the tracker's metadata

verbose

A flag to indicate whether to print detailed logging messages Defaults to TRUE. Set to False to suppress messages about the current processing step and run silently

call_info

A list of call information and parameters. If not provided, it will be generated from the function call

calc_baseline

(Deprecated) Use baseline instead

apply_baseline

(Deprecated) Use baseline instead

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"
  )