Relabeling or Defining Interest Areas

Check interest area coding

First, ensure that you have loaded your data appropriately and that you have already carried out initial preprocessing using the functions prep_data and relabel_NA. The subsequent preprocessing requires that the interest area IDs are numerically, ranging from 0 (i.e., outside all interest areas) up to a maximum of 8. So, it’s important to check that the IDs present in the data set, conform to this. The check_ia functions does just this and indicates how those IDs are mapped to the interest area labels.

check_ia(data = checkdat)

##  RIGHT_IA_ID RIGHT_IA_LABEL
##            0        Outside
##           11        Object1
##          234        Object2
##          399        Object3
##          444        Object4

##  LEFT_IA_ID LEFT_IA_LABEL
##           0       Outside

## Interest Area IDs for the left eye are coded appropriately between 0 and 8.
## Interest Area ID and label mapping combinations for the right eye are consistent.
## Interest Area ID and label mapping combinations for the left eye are consistent.

## Error in check_ia(data = checkdat): Interest Area IDs for the right eye are not between 0 and 8. Please recode before proceeding with data processing.

Providing new labels and IDs for existing interest areas

The function recode_ia can be used to relabel interest area IDs (if they do not conform) or interest area labels (if you desire different ones). New IDs and/or labels can be specified using a named character vector. The following code serves as an example. Note that if your interest area labels contain spaces you must also put the old names in quotes.

newdat <- recode_ia(data=checkdat, IDs=c("0"="0", "11"="1", "234"="2", "399"="3",
                                         "444"="4"), 
                        Labels=c(Outside="Outside", Object1="Target", 
                                 Object2="RhymeCompetitor", Object3="OnsetCompetitor",
                                 Object4="Distractor"))

## Right interest area IDs recoded.

## Left interest area IDs recoded.

## Right interest area labels recoded.

## Left interest area labels recoded.

check_ia(data = newdat)

##  RIGHT_IA_ID  RIGHT_IA_LABEL
##            0         Outside
##            1          Target
##            2 RhymeCompetitor
##            3 OnsetCompetitor
##            4      Distractor

##  LEFT_IA_ID LEFT_IA_LABEL
##           0       Outside

## Interest Area IDs for the right eye are coded appropriately between 0 and 8.
## Interest Area IDs for the left eye are coded appropriately between 0 and 8.
## Interest Area ID and label mapping combinations for the right eye are consistent.
## Interest Area ID and label mapping combinations for the left eye are consistent.

Creating the look-up table

The look-up table requires specific information. In particular, in needs the event (participant specific trial) for which the interest areas are defined, the label of the interest area, the numeric ID of the interest area, and the top, bottom, left, and right pixel boundaries of the interest area. The reason these need to be specified for each event is that it is common for interest areas to move depending on the item/trial. Creating this sounds like a lot of work, but can actually be accomplished straightforwardly from an interest area report output by Data Viewer (especially if you have included the locations in your data source).

So, first export an interest area report for your data as a tab-delimited text file, including all available columns (to ensure you get all the necessary columns as well as the ones you output from your data source). Import that into R.

library(VWPre)
IAdat <- read.table("IAreport.txt", header = T, sep = "\t", na.strings = c(".", "NA"))

You will notice that the data are organized so that there is one row per interest area for each trial.

Next, create the Event column. Typically this is done using the Subject Identifier and Trial Index.

IAdat$Event <- interaction(IAdat$RECORDING_SESSION_LABEL, IAdat$TRIAL_INDEX, drop = T)

Next you need to create a column which indicates the location of each interest area for a specific trial. If you defined this in your data source and output all columns to the eye-tracking file, these should already be included in your interest area report. In the example below, the columns (NAME_reg) indicate a numeric index (in this case Cartesian quadrants) of where the target and other objects were located per trial. This information must be unified into a single column so that it can be used later to merge in other information.

dat1 <- IAdat %>% mutate(ScreenLoc = ifelse(IA_LABEL=="Target", target_reg,
                        ifelse(IA_LABEL=="RhymeComp", rhymecomp_reg,
                               ifelse(IA_LABEL=="OnsetComp", onsetcomp_reg,
                                      ifelse(IA_LABEL=="Distractor", distractor_reg, NA))))
                  )

To create the bounding boxes of the region locations, make a dataframe that includes the top, bottom, left, and right pixel boundaries. These will, of course, be dependent on the resolution of the screen used in the experiment.

Loc_Table <- data_frame(ScreenLoc = c(1, 2, 3, 4), 
                        Top = c(40, 40, 740, 740),
                        Bottom = c(340, 340, 1040, 1040),
                        Left = c(1160, 460, 460, 1160),
                        Right = c(1460, 760, 760, 1460))

The dataframe should look similar to the following.

This table will be merged with the interest area report, matching by ScreenLoc column.

dat2 <- inner_join(dat1, Loc_Table, by="ScreenLoc")

The look-up table (as with other functions in VWPre) requires a numeric interest area ID column. This can be created directly from the IA_LABEL column, as follows by corresponding the Labels to the IDs.

dat2$IA_ID <- case_when(
  dat2$IA_LABEL == "Target" ~ 1,
  dat2$IA_LABEL == "RhymeComp" ~ 2,
  dat2$IA_LABEL == "OnsetComp" ~ 3,
  dat2$IA_LABEL == "Distractor" ~ 4
)

Lastly, select only the required columns for the look-up table.

LookUpTable <- dat2 %>% select(Event, IA_LABEL, IA_ID, Top, Bottom, Left, Right)

The table should now look similar to the following.

Performing the gaze remapping

Make sure your sample report has been loaded appropriately and that you have carried out the function prep_data. This will ensure that the necessary columns are coded appropriately and that the Event column has been created. Then simply feed that data frame, along with the lookup table, to the function custom_ia.

remapped <- custom_ia(data = sampledata, iaLookup = LookUpTable)

This function examines the gaze coordinates of each sample for each event and evaluates which interest area it falls in, based on the information contained in the lookup table. Because this works row-wise, it can take a bit of time for large datasets.

After the remapping is complete, you are then ready to continue preprocessing your data. Please refer to the Basic Preprocessing vignette for further details.