Chapter 1 eyeTrackR

Welcome! So, eyeTrackR is an R package of functions geared towards analysing eye-tracking datasets. For now, it can handle output from SR Research’s Eyelink eye trackers.

This guide is written to allow you to read through the text in chapter order, and assumes familiarity with the Eyelink system and how to output data from SR Research DataViewer. The software that you use for data collection can be Experiment Builder, but could also be including E-prime, Matlab, OpenSesame and others.

1.1 What can eyeTrackR do?

EyeTrackR has a wide array of functions available but the core goals for it are speed and accuracy. For speed, it uses the popular data.table R package. For accuracy… well, in some senses that is up to you. Many things can go wrong with complex datasets that are hundreds of thousands of rows in length (indeed, the errors may be sufficiently subtle that it’s hard to detect them). The solution to dealing with that, adopted by eyeTrackR, is to implement a number of ways of checking, double-checking and triple-checking your data to make sure that as little as possible slips through the cracks. Many of these checks have been inspired by errors I’ve caught in my own code, but have also been inspired by requests from editors and reviewers when writing papers.

1.2 Is eyeTrackR for you?

I hope so! I mean, at least, I hope it is useful to you. Every software package or tool is only as useful as it’s intended purposes, so I’ve listed below some different experimental paradigms and whether you might find eyeTrackR useful.

Table 1.1: Paradigms and recommendations
Paradigm Recommendation
Visual Search eyeTrackR is for you
Scene Perception eyeTrackR is for you
Visual World eyeTrackR can be helpful for organising your data, and you may also want to use the Gazer R package for this.
Oculomotor Control (e.g., antisaccade tasks) eyeTrackR is for you
Pupillometry You will want to use the Gazer R package for this.
Reading - single line You will want to use the popEYE R package for this.
Reading - mutli-line You will want to use popEYE for this as well, but I have used eyeTrackR to examine multi-line text experiments as well.

1.3 Citing eyeTrackR

If you have used eyeTrackR and would like to cite it, please use the following citation:

Godwin, H. J. & Muhl-Richardson, A. (2019). eyeTrackR: Organising and Analysing Eye-Tracking Data. R package version 1.0.0.

1.4 Some History

I started working on what would become this R package back in 2011 and 2012. Around that time, I was a post-doc, surviving on scraps from different research projects. In order to survive, and because I enjoy coding, I ended up helping out various other people with their R code and eye-tracking datasets. I kept using the same basic scripts repeatedly, as you do, then the scripts became functions, and eventually the functions became eyeTrackR.

The first version was released around that time - the first commit on github for the package was April 2nd, 2012. I used it extensively since that time, and, because I wasn’t sure what it would involve, I never really got around to formalising it and uploading it to CRAN.

In more recent times, I’ve developed my working practices, and, in the spirit of open science, I wanted to share eyeTrackR in a state that others could use. It seems to me that consistency of data processing, filtering and cleaning methods - all of which are offered by eyeTrackR - could be beneficial to a wider audience. I’ve seen so many times, and in so many papers, people making mistakes where they’ve missed things that eyeTrackR can check for them very easily. I’m hoping that it can help to avoid those mistakes in the future. Indeed, I’m sure I’ve made plenty myself…

1.5 Contributors

I’d like to thank the kind individuals who have taken their time out to contribute to the development and testing of eyeTrackR and/or the development and testing of this guide. At present, the local team of testers and feedback providers are listed below.

Hayward Godwin, who is currently a Lecturer at the University of Southampton.

Alexander Muhl-Richardson, who is currently a post-doc at Cambridge. Alex has contributed code to eyeTrackR and also made edits to this guide.

Andreea Butnaru, who is currently a PhD student at the University of Southampton. Andreea has made edits and suggestions to this guide.

Philippa Broadbent, who is currently a PhD student at the University of Southampton. Philippa has made edits and suggestions to this guide.

If you would like to contribute, please do get in touch - more information on this in the next section!

1.6 Get in Touch

Probably the best way to talk to the eyeTrackR team is via the eyeTrack R Slack channel. If you’ve not heard of Slack, it’s a bit like the web forums of antiquity but with a lot more functionality.