Sometimes, depending on the design of the experiment, you may decide not to define an interest period in Data Viewer prior to exporting the data. If this is the case, there are some functions (which technically belong to the dependency VWPre) which can help to align the data to your critical stimulus. Specifically, these functions search for a specific Eyelink message which was read out during the recording sequence. They will align the samples to this message, and, if necessary, also apply a variable adjustment forward or backward in time. This depends on whether the message signals the onset of the stimulus itself, or rather, serves as a reference point for the onset of the stimulus.
In order to perform the alignment, you must first load your sample
report and complete the first two preprocessing steps using the
functions ppl_prep_data
provided in this package. These
steps will ensure that an Event column (unique index of each recording
sequence - typically the combination of Subject and Trial) is created. A
description of these can be found in the Basic Preprocessing
vignette.
The messages in the data can be determined using the function
check_all_msgs
. This will output all the messages that
exist in the data set.
## # A tibble: 2 × 1
## SAMPLE_MESSAGE
## <fct>
## 1 TIMER_1
## 2 PLAY_target
## Set ReturnData to TRUE to output full, event-specific information.
Using the function check_msg_time
you can see that the
TIMESTAMP values associated with the message are not the same for each
event. This indicates that alignment is required. Note that a regular
expression (regex) can be used here as the message string.
## # A tibble: 75 × 2
## SAMPLE_MESSAGE TIMESTAMP
## <fct> <dbl>
## 1 TIMER_1 3658426
## 2 TIMER_1 3714594
## 3 TIMER_1 3725422
## 4 TIMER_1 3736366
## 5 TIMER_1 3794430
## 6 TIMER_1 3805278
## 7 TIMER_1 3859118
## 8 TIMER_1 3882002
## 9 TIMER_1 3903726
## 10 TIMER_1 3960078
## # ℹ 65 more rows
## Set ReturnData to TRUE to output full, event-specific information.
The function align_msg
is used to perform the alignment.
To do this you must specify the message text as a string to the
parameter Msg
. Again, this string can contain a regular
expression (regex) on which to locate the message. The function finds
the instance of the message for each event and sets that sample as the
zero point. Consequently, this creates a new column called
Align
, which represents the time sequence relative to the
message.
If we check the message time again, we now see that the message
occurs at time 0 in the Align
column.
## # A tibble: 1 × 2
## SAMPLE_MESSAGE Align
## <fct> <dbl>
## 1 TIMER_1 0
## Set ReturnData to TRUE to output full, event-specific information.
To fully examine all events, you can include the parameter
ReturnData=TRUE
and assign the output to an object in your
environment.
Once you have aligned the time sequence relative to the message, you
need to create the Time
column using the function
create_time_series
. This function returns the time series
column called Time
which is required for subsequent
processing, plotting, and modeling of the data. In the example here, our
message relates specifically to the time at which the vowel in the word
was played (because we programmed Experiment Builder to output a message
for that). So, we do not need to specify an adjustment to the time
series. If, however, your critical stimulus did not occur exactly at the
message, but rather, before or after, an adjustment (i.e., negative or
positive value in milliseconds) can be applied to the time series, to
shift the zero point. This is done by specifying the Adjust
parameter. If, on the other hand, this adjustment differed trial by
trial, you can input a column name (present in your dataset) in
Adjust
, which will apply the recording event specific
adjustment.
A positive value (3 in the example below) provided to
Adjust
shifts the zero point to after the
reference point (i.e., Message), effectively moving the zero point
forward along the number line and causing the reference point to have a
negative time value.
Smp1 | Smp2 | Smp3 | Smp4 | Smp5 | Smp6 | Smp7 | Smp8 | Smp9 | Smp10 | Smp11 | |
---|---|---|---|---|---|---|---|---|---|---|---|
Before | -4 | -3 | -2 | -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 |
Old 0 | New 0 | ||||||||||
After | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 | 1 | 2 | 3 |
A negative value (-3 in the example below) provided to
Adjust
shifts the zero point to before the
reference point (i.e., Message), effectively moving the zero point
backward along the number line and causing the reference point to have a
postive time value.
Smp1 | Smp2 | Smp3 | Smp4 | Smp5 | Smp6 | Smp7 | Smp8 | Smp9 | Smp10 | Smp11 | |
---|---|---|---|---|---|---|---|---|---|---|---|
Before | -4 | -3 | -2 | -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 |
New 0 | Old 0 | ||||||||||
After | -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
## No adjustment applied.
The function check_time_series
can be used to verify
that the time series was created. The function outputs a list of the
unique start values present in the data. In this example, we do not
expect all events to start with the same Time value, given that we
performed our own alignment without a relative interest period defined
in Data Viewer. As with check_msg_time
, the list of Events
and Start Times can be returned as a data frame using the parameter
ReturnData
.
## # A tibble: 2 × 1
## Start_Time
## <dbl>
## 1 -480
## 2 -484
## Set ReturnData to TRUE to output full, event-specific information.
Perhaps more meaningfully, we can check the message time again. We can see that our message is still the zero point in the Time series column.
## # A tibble: 1 × 2
## SAMPLE_MESSAGE Time
## <fct> <dbl>
## 1 TIMER_1 0
## Set ReturnData to TRUE to output full, event-specific information.
At this point it is possible to proceed with preprocessing as usual. Please refer back to the Basic Preprocessing vignette and continue by creating the time series and selecting a recording eye.