View source: R/pipeline-epoch.R
epoch | R Documentation |
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.
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()
)
eyeris |
An object of class |
events |
Either (1) a single string representing the event message to
perform trial extraction around, using specified 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 For event-modes |
limits |
A vector of 2 values (start, end) in seconds, indicating where
trial extraction should occur centered around any given |
label |
An (optional) string you can provide to customize the name of
the resulting |
baseline |
(New) A single parameter that controls baseline
correction. Set to |
baseline_type |
Whether to perform subtractive ( |
baseline_events |
Similar to |
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 |
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 |
call_info |
A list of call information and parameters. If not provided, it will be generated from the function call |
calc_baseline |
(Deprecated) Use |
apply_baseline |
(Deprecated) Use |
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.
lifecycle::deprecate_warn()
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"
)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.