# Aligning Sample Data to a Specific Sample Message in SR Eyelink Data

#### Vincent Porretta

#### 2018-03-19

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 in 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.

## Before aligning

In order to perform the alignment, you must first load your sample report and complete the first two preprocessing steps using the functions `prep_data` and `relabel_na` provided in this package. These step 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.

## Aligning to a specific message

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.

    check_msg_time(data = aligndat, Msg = "VowelOnset")

    ## # A tibble: 320 x 3
    ##    Event    SAMPLE_MESSAGE TIMESTAMP
    ##    <fctr>   <fctr>             <dbl>
    ##  1 14001.1  VowelOnset       1047469
    ##  2 14001.2  VowelOnset       1054718
    ##  3 14001.3  VowelOnset       1062679
    ##  4 14001.4  VowelOnset       1069987
    ##  5 14001.5  VowelOnset       1077113
    ##  6 14001.6  VowelOnset       1084338
    ##  7 14001.7  VowelOnset       1091555
    ##  8 14001.8  VowelOnset       1099738
    ##  9 14001.9  VowelOnset       1107363
    ## 10 14001.10 VowelOnset       1114682
    ## # ... with 310 more rows

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.

    aligned1 <- align_msg(data = aligndat, Msg = "VowelOnset")

If we check the message time again, we now see that the message occurs at time 0 in the `Align` column.

    check_msg_time(data = aligned1, Msg = "VowelOnset")

    ## # A tibble: 320 x 3
    ##    Event    SAMPLE_MESSAGE Align
    ##    <fctr>   <fctr>         <dbl>
    ##  1 14001.1  VowelOnset         0
    ##  2 14001.2  VowelOnset         0
    ##  3 14001.3  VowelOnset         0
    ##  4 14001.4  VowelOnset         0
    ##  5 14001.5  VowelOnset         0
    ##  6 14001.6  VowelOnset         0
    ##  7 14001.7  VowelOnset         0
    ##  8 14001.8  VowelOnset         0
    ##  9 14001.9  VowelOnset         0
    ## 10 14001.10 VowelOnset         0
    ## # ... with 310 more rows

To fully examine all events, you can include the parameter `ReturnData=TRUE` and assign the output to an object in your environment.

    MSGTime <- check_msg_time(data = aligned1, Msg = "VowelOnset", ReturnData = TRUE)

## Creating the Time series column

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

    aligned2 <- create_time_series(data = aligned1, Adjust = 0)

    ## 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`.

    check_time_series(data = aligned2)

    ##   [1] -165 -280 -198 -176 -110 -384 -182 -163 -293 -445 -207 -362 -213 -157
    ##  [15] -249 -191 -204 -175 -184 -155 -185 -214 -248 -190 -164 -409 -174 -241
    ##  [29] -215 -361 -177 -242 -367 -197 -179 -178 -258 -289 -202 -257 -244 -111
    ##  [43] -108 -136 -250 -104 -484 -188 -116 -227 -195 -338 -181 -413 -117 -115
    ##  [57] -255 -318 -328 -263 -264 -118 -485 -412 -426 -172 -106 -114 -170 -211
    ##  [71] -319 -154 -171 -180 -296 -107 -402 -109 -408 -431 -254 -271 -432 -203
    ##  [85] -270 -317 -259 -267 -612 -135 -298 -368 -134 -158 -253 -152 -323 -260
    ##  [99] -139 -105 -235 -160 -210 -611 -268 -321 -315 -113 -112 -218 -446 -206
    ## [113] -322 -159 -219 -256 -243 -279 -217 -354 -272 -234 -146 -327 -187 -232
    ## [127] -330 -220 -245 -290 -142 -141 -189 -121 -122 -156

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.

    check_msg_time(data = aligned2, Msg = "VowelOnset")

    ## # A tibble: 320 x 3
    ##    Event   SAMPLE_MESSAGE  Time
    ##    <fctr>  <fctr>         <dbl>
    ##  1 14001.1 VowelOnset         0
    ##  2 14002.1 VowelOnset         0
    ##  3 14003.1 VowelOnset         0
    ##  4 14004.1 VowelOnset         0
    ##  5 14005.1 VowelOnset         0
    ##  6 14006.1 VowelOnset         0
    ##  7 14008.1 VowelOnset         0
    ##  8 14010.1 VowelOnset         0
    ##  9 14001.2 VowelOnset         0
    ## 10 14002.2 VowelOnset         0
    ## # ... with 310 more rows

## Proceed with preprocessing

At this point it is possible to proceed with preprocessing as usual. For details, please refer to the `Basic Preprocessing` vignette and continue by selecting a recording eye before binning the data.