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).
This notebook goes through pre-processing data from an EyeLink 1000 running EyeTrack.
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
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.
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
Taken directly from Cohen (2013):
start_ptsis 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_filesis a vector of .asc file names and/or folders containing .asc files.
xy_boundsare considered out of bounds and are removed from the analysis before the regression lines are determined.
xy_boundsprovides a way to remove points from analysis a priori.
xy_boundsare considered out of bounds and are removed from analysis before the regression lines are determined.
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).
keep_y_varis 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.
use_run_ruleis set as
TRUE, ambiguous fixations are potentially reclassified by their surrounding fixations as described above; otherwise, they remain ambiguous.
trial_plotsis set as
TRUE, trial-by-trial plots of the original and reformatted fixations are shown.
save_trial_plotsis set as
TRUE, the trial plots are saved as .tiff files, in a subdirectory called “Trial_Plots” in the directory defined by
summary_fileis set as
TRUE, a .fas (fix align summary) file is created
show_imageis set as
TRUE, the trial plots are shown on top of background images.
fa_diris the name of the directory used to store the reformatted .asc files, .fas files, and trial plots.
FA_Dirthus should be set to the name of the actual directory.
start_flagis the text that marks the start of data collection in the .asc file, which will typically be either “TRIALID” or “SYNCTIME.”
den_sd_cutoffdefines the number of standard deviations from a regression line that determines an outlier.
den_ratio_cutoffdefines the ratio (in density) that determines ambiguous fixations.
s_boundsare 1×2 vectors that define the minimum and maximum values that the regression line slope, vertical offset, and standard deviation, respectively, can take.