An R Package to preprocess pupil data
The package contains various functions for different steps in the preprocessing pipeline, such as interpolation, smoothing, and baseline correction.
The pre-processing steps are based on what has commonly been used in the literature and influenced by sensible preprocessing methods suggested by
Mathôt, S., Fabius, J., Van Heusden, E., & Van der Stigchel, S. (2018). Safe and sensible preprocessing and baseline correction of pupil-size data. Behavior research methods, 50(1), 94-106.
The main goal of this package is to provide:
1) ease of use for pupillometry researchers
2) flexibility in choosing which preprocessing methods and parameters are used.
The format and organization of the raw data file will depend on the type of Eyetracker used. The
pupil_read() function imports the “messy” raw data file and it’s output is a “tidy” raw data file with standardized column and value labels to be used by the other functions.
pupil_read() only supports data exported from BeGaze using an SMI eye-tracker or glasses. Support for other eye-trackers will be included in future updates.
pupil_preprocess() is a wrapper around the other functions to allow full preprocessing of pupil data using a single function.
As such, you will need to pass many arguments to the
pupil_preprocess() function that specifies all the details and preprocessing options.
pupil_preprocess() will be performed on an entire
import.dir directory of raw data files that match a certain
pattern. The preprocessed data will be saved to a specified
The overall workflow of
Read in raw data files
tracking.fileis supplied will also add message markers to the data
Clean up raw data files and more
Smooth (if specified).
Interpolate (if specified).
Baseline Correct (if specified).
Remove trials with too much Missing Data.
Merges files into a single merged file (if specified).
A final preprocessed data file will be saved for every original raw data file.
output.steps == TRUE a data file will be saved after steps 3, 4, and 5. Before saving the data file at each of these steps, the final two steps 6 and 7 are performed. This results in baseline corrected and missing data removed files before each major preprocessing step. This is obviously not necessary and so
output.steps = FALSE is the default and will only save one final preprocessed data file per subject.
You will need to supply message markers to correctly preprocess your data. This image is a representation of what the message markers
bconset.message correspond to. For further detail see Example Data Set and Message Markers Articles.
You can copy and paste the following code into a script and use it as a template.
## Preprocessing parameters # File Import Information import.dir <- "data/Raw" pattern <- ".txt" taskname <- "Pitch_Discrimination" timing.file <- NULL # Eyetrackers save the subject number information in different ways and is not # always easy to obtain. For SMI eyetrackers we need to extract it from the # datafile name. You need to identify a unique subj.prefix pattern and # subj.suffix pattern that surrounds the subject # in the datafile name. subj.prefix <- "n_" ## For SMI Red50m eyetrackers subj.suffix <- "-" ## For SMI Red250m eyetrackers # File Output Information output.dir <- "data/Preprocessed" output.steps <- FALSE files.merge <- FALSE # Eyetracker Information eyetracker <- "smi" hz <- 250 eye.use <- "left" # Message Marker Information starttracking.message <- "default" starttracking.match <- "exact" trialonset.message <- "Tone 1" trialonset.match <- "exact" pretrial.duration <- 1000 bconset.message <- "Tone 1" bconset.match <- "exact" # Preprocessing Options deblink.extend <- 100 smooth <- "hann" smooth.window <- 500 interpolate <- "linear" interpolate.maxgap <- 750 method.first <- "smooth" bc <- "subtractive" prebc.duration <- 200 missing.allowed <- .30 # Misc. subset <- "default" trial.exclude <- c() ############################ pupil_preprocess(import.dir = import.dir, pattern = pattern, taskname = taskname, subj.prefix = subj.prefix, subj.suffix = subj.suffix, timing.file = timing.file, output.dir = output.dir, output.steps = output.steps, files.merge = files.merge, eyetracker = eyetracker, hz = hz, eye.use = eye.use, starttracking.message = starttracking.message, starttracking.match = starttracking.match, trialonset.message = trialonset.message, trialonset.match = trialonset.match, pretrial.duration = pretrial.duration, bconset.message = bconset.message, bconset.match = bconset.match, deblink.extend = deblink.extend, smooth = smooth, smooth.window = smooth.window, interpolate = interpolate, interpolate.maxgap = interpolate.maxgap, method.first = method.first, bc = bc, prebc.duration = prebc.duration, missing.allowed = missing.allowed, subset = subset, trial.exclude = trial.exclude)
For more detailed information on how to use
pupil_preprocess() and other functions see the Articles tab above.
Add data preprocessing visualizations?
Add hampel filter option (maybe?)
Add greater support for SR Research EyeLink Eyetrackers
Add support for Tobii Eyetrackers
Add support for GazePoint Eyetrackers
Tsukahara, J.S. (2018). pupillometry: An R Package to Preprocess Pupil Data. Retrieved from https://dr-jt.github.io/pupillometry