Getting Started: Getting Started with EyeLink Data Analysis in R

[Sam]

R is a programming language for statistical computing and graphics, and it's a powerful tool for processing and analyzing gaze and pupillometry data.

EyeLink data can be imported into R in several ways:

1. Use a Data Viewer Report
   Data Viewer outputs reports as tab-delimited ASCII files. These reports can be generated at the trial, interest area, fixation, saccade, and sample level (e.g., one row per trial, interest area, sample, etc.). Time-series (binning) reports allow data to be aggregated over short time windows (e.g., 20 or 50 ms bins).
   
   Each report can contain many different variables (columns). For example, Sample Reports are particularly useful because they can include:
   • Timestamp and Gaze X/Y coordinates
     
   • Columns indicating if the sample is in a saccade or blink
     
   • The index of the fixation or saccade the sample belongs to
     
   • The label of any Interest Area the sample is in
     
   • User-generated trial variables (such as the trial condition)
     
   As such, Sample Reports are often a richer and more convenient way to analyze ASCII data than a simple EDF-to-ASCII file conversion. Data Viewer reports can be easily read into R, and some of the packages listed below are designed to use them as input.
   
   Here is one example of how to import a report into R:
   
   Code:

   data <- read.table('ALL_SampleReport.xls', sep = "\t", na.strings = ".", header = TRUE)
   
   Note: Whether the report has a .txt or .xls extension makes no difference to its format or content. In both cases, the files are tab-delimited ASCII.
   
   
2. Use an EDF to ASCII Conversion Tool
   You can also convert EDF files to ASCII using a dedicated conversion tool. For more details, please see the article: Converting EDF Files to ASCII.
   
   While some R packages (like gazeR) have functions to parse the output from these converters, a Data Viewer Sample Report generally provides richer data and is easier to work with.
   
   
3. Directly Import EDF Files
   EyeLink Data Files (EDF files) are encoded in a binary format. However, our EDF-API, which is installed with the EyeLink Developer's Kit, provides tools to extract this data. Several tools use the EDF-API to read EDF files directly into R.
   
   The eyelinkReader package by Alexander Pastukhov works well, producing a rich data structure that is very easy to use. For details and installation instructions, see the following links:
   • eyelinkReader Documentation
     
   • CRAN Package
     
   Additionally, a version of the Engbert & Kliegl microsaccade detection algorithm that uses eyelinkReader can be downloaded here:
   • Microsaccade Analysis for EyeLink Data (Modified Engbert & Kliegl MS_Toolbox_R code)

---

Recommended R Packages

Researchers have developed several packages for processing EyeLink data in R. The following list includes examples that appear stable and actively maintained.

Disclaimer: These packages were developed by third parties, not SR Research, and have not been tested extensively by our support team. Please direct any support issues to the respective package developers.

• eyelinkReader:: A useful tool for reading EDF files directly into R. An example of its use can be found in the EyeLink_MS_Toolbox_eyelinkReader.R code for microsaccade detection mentioned above.
  
• eyetrackingR:: A comprehensive package with tools for preparing and analyzing gaze data. It accepts data in a sample-report format and is particularly suited for visual world and time-series analyses.
  
• GazeR:: Another comprehensive package with several useful functions for processing gaze and pupil data. It can read EDF files directly or parse EDF files that have been converted to ASCII.
  
• popEye:: A set of R functions designed for processing reading data, which takes ASCII data as input.
  
• pupillometryR:: A full CRAN package for working with pupil data that takes ASCII data as input.
  

If you find other R packages useful, please let us know by emailing support@sr-research.com and referencing this information.