🔙 Home

All work associated with the Centre for Behaviour and Evolution, including this documentation, is supported by a Wellcome Trust Capital Award to Newcastle (grant ref: 092504).

Purpose

This notebook goes through pre-processing data from an EyeLink 1000 running EyeTrack.

Technical Specifications

fix_align_v0p92.R

This section takes the prose information from Cohen (2013) and puts in it lists for quick accessibility.

Cohen, Andrew L. (2013). Software for the automatic correction of recorded eye fixation locations in reading experiments. Behavior research methods, 45(3), 679–683. Accessed from: https://people.umass.edu/eyelab/CohenBRM.pdf

Understanding the function

In order to use fix_align properly, it’s good to understand what arguments it takes and what it does with those arguments. I present information condensed from Cohen (2013) and my own interpretations and experiences with using it.

library(knitr)
source('fix_align_v0p92.R')
fix_align <- function(start_pts,                      # where does each line start
                      asc_files         = '.',        # where are the files
                      xy_bounds         = NULL,       # remove points before calculating regression
                      keep_y_var        = FALSE,      # TRUE: residual for its regression is kept
                      use_run_rule      = TRUE,       # 
                      trial_plots       = TRUE,       # 
                      save_trial_plots  = FALSE,      # .tiff plots saved in directory “Trial_Plots”
                      summary_file      = TRUE,       # TRUE: a .fas is saved in fa_dir
                      show_image        = FALSE,      # TRUE: trials on top of background images
                      fa_dir            = 'FA_Dir',   # where are the .asc files?
                      start_flag        = 'TRIALID',  # what do trials start with?
                      den_sd_cutoff     = Inf,        # remove outliers
                      den_ratio_cutoff  = 1,          # remove outliers
                      k_bounds          = c(-.1, .1), # NULL = 0; min/max of regression slope
                      o_bounds          = c(-50, 50), # NULL = 0; min/max of vertical offset
                      s_bounds          = c(1, 20))   # min/max of sd

Input

Taken directly from Cohen (2013):

  • start_pts is an n × 2 matrix that defines the x and y locations of the start of each text line, where n is the number of text lines.
  • asc_files is a vector of .asc file names and/or folders containing .asc files.
  • Any points outside the rectangles provided by xy_bounds are considered out of bounds and are removed from the analysis before the regression lines are determined.
  • xy_bounds provides a way to remove points from analysis a priori.
    • Any points outside the rectangles provided by xy_bounds are considered out of bounds and are removed from analysis before the regression lines are determined.
    • All other points are included in the creation of the regression lines.
    • The bounds can be set to no bounds (NULL), a single rectangle for the entire experiment (a 1 × 4 vector: x-min, x-max, ymin, and y-max), or one rectangle per trial (an n × 4 matrix of rectangles).
  • If keep_y_var is set as TRUE, the residual of each fixation around its assigned regression line is kept when the y location is changed; otherwise, it is removed.
  • If use_run_rule is set as TRUE, ambiguous fixations are potentially reclassified by their surrounding fixations as described above; otherwise, they remain ambiguous.
  • If trial_plots is set as TRUE, trial-by-trial plots of the original and reformatted fixations are shown.
  • If save_trial_plots is set as TRUE, the trial plots are saved as .tiff files, in a subdirectory called “Trial_Plots” in the directory defined by fa_dir
    • In this case, the plots will only be saved—that is, they will not be shown on the screen.
    • These files are massive, so do not use this option unless you are processing a small amount of data or have a lot of storage space.
  • If summary_file is set as TRUE, a .fas (fix align summary) file is created
    • It saves the slope, vertical offset, standard deviation, regression fit, and the numbers of total, kept, out-of-bounds, ambiguous, outlier, and other fixations for each participant and each trial.
  • If show_image is set as TRUE, the trial plots are shown on top of background images.
    • These background images are .tiff files located in the same directory as the data files.
    • One image can be used per .asc file, or one image per trial per .asc file, and images must be saved as .tiff files with the same name as the .asc file and the .tiff ending.
    • If one image is used per trial, the end of the name must have an underscore followed by a trial number (e.g., “_1” for Trial 1).
  • fa_dir is the name of the directory used to store the reformatted .asc files, .fas files, and trial plots.
    • The .asc files are marked by having “_fa” (fix align) at the ends of their names.
    • This is hard-coded as FA_Dir thus should be set to the name of the actual directory.
  • start_flag is the text that marks the start of data collection in the .asc file, which will typically be either “TRIALID” or “SYNCTIME.”
  • den_sd_cutoff defines the number of standard deviations from a regression line that determines an outlier.
  • den_ratio_cutoff defines the ratio (in density) that determines ambiguous fixations.
  • k_bounds, o_bounds, and s_bounds are 1×2 vectors that define the minimum and maximum values that the regression line slope, vertical offset, and standard deviation, respectively, can take.
    • If set to NULL, k_bounds and o_bounds h