Imports eye tracking data from any eye tracker with special support for SMI, SR Research, and Tobii eye trackers. Standardizes columns and values to be used with other functions in this package. See https://dr-jt.github.io/pupillometry/ for more information.
pupil_read(
file,
eyetracker = "",
eye_use = NULL,
subj_prefix = NULL,
subj_suffix = NULL,
include_col = NULL,
start_tracking_message = "default",
start_tracking_match = NULL,
ms_conversion = NULL,
px_to_mm_conversion = NULL,
trial_exclude = c(NA),
quality_check_dir = NULL,
timing_file = NULL,
delim = NULL,
na = "NA",
subject = NULL,
trial = NULL,
time = NULL,
message_event = NULL,
pupil.mm = NULL,
pupil.px = NULL,
gaze.x = NULL,
gaze.y = NULL,
blink_event = NULL,
fixation_event = NULL,
saccade_event = NULL,
eye_event = NULL,
eye_event_blink = "Blink",
eye_event_fixation = "Fixation",
eye_event_saccade = "Saccade",
left_pupil.mm = NULL,
right_pupil.mm = NULL,
left_pupil.px = NULL,
right_pupil.px = NULL,
left_gaze.x = NULL,
left_gaze.y = NULL,
right_gaze.x = NULL,
right_gaze.y = NULL,
left_blink_event = NULL,
right_blink_event = NULL,
left_fixation_event = NULL,
right_fixation_event = NULL,
left_saccade_event = NULL,
right_saccade_event = NULL,
left_eye_event = NULL,
right_eye_event = NULL,
start_tracking.message = NULL,
start_tracking.match = NULL,
starttracking.message = NULL,
starttracking.match = NULL
)A file path to the raw data.
Which eye tracker system was used to record data? options: "smi", "eyelink", "tobii", NULL. Note that only tobii eye tracking data using E-Prime GazeData option is supported. Tobii ProLab and other experimental software (e.g., PsychoPy) have not been tested.
Which eye to use? options: "left", "right" or NULL (default to keep both).
The unique pattern prefix (letter(s) and/or symbol(s)) that comes before the subject number in the data file. Required for SMI, but likely not needed for other eye trackers.
The unique pattern suffix (letter(s) or symbol(s)) that comes after the subject number in the data file. Required for SMI, but likely not needed for other eye trackers.
Extra columns from the raw data file to include. c().
Message used in experiment software to mark the onset of "Start Tracking". Most eye trackers include a marker message corresponding to this event. Usually included at the start of every trial. Not required for SMI, SR Research, and Tobii Pro Fusion.
Should the message string be an "exact" match or a "pattern" match? default: "exact".
The conversion factor to get the timing column in milliseconds.
The conversion factor to go from px pupil diameter to mm pupil diameter.
Specify if there are any trials to exclude. Default: c(NA) - to remove any rows that having missing values in Trial. To preserve rows that have missing values in Trial, set to c().
Directory to save quality check file to.
File location and name that contains timing information for message markers. Required if no message markers are included in data.
File delimiter type. (needed if eyetracker is not specified)
How are missing values defined in the data files
Column name that contains subject IDs. (needed if eyetracker is not specified)
Column name that contains the trial number. (needed if eyetracker is not specified)
Column name that contains the timing variable. (needed if eyetracker is not specified)
Column name that contains the message markers. (needed if eyetracker is not specified)
Column name that contains the pupil data in millimeters. If the eye tracker data file has pupil data from only one eye use this argument.
Column name that contains the pupil data in pixels. If the eye tracker data file has pupil data from only one eye use this argument.
Column name that contains the gaze position on the x-axis. If the eye tracker data file has data from only one eye use this argument.
Column name that contains the gaze position on the y-axis. If the eye tracker data file has data from only one eye use this argument.
Column name that contains whether the eye event sample is in a blink or not in a blink. If the eye tracker data file has data from only one eye use this argument.
Column name that contains whether the eye event sample is in a fixation or not in a fixation. If the eye tracker data file has data from only one eye use this argument.
Column name that contains whether the eye event sample is in a saccade or not in a saccade. If the eye tracker data file has data from only one eye use this argument.
Column name that contains the eye event data (e.g., fixation, saccade, and blink). If the eye tracker data file has data from only one eye use this argument. Some eye trackers will store the event data in one column with values corresponding to fixation, blink, or saccades. You also need to specify what these values are with the eye_event_blink, eye_event_fixation, and eye_event_saccade arguments.
Values in the eye_event column that correspond to blinks.
Values in the eye_event column that correspond to fixations.
Values in the eye_event column that correspond to saccades.
Column name that contains the left pupil data in millimeters. If the eye tracker data file has pupil data from both eyes use this argument for the left pupil.
Column name that contains the right pupil data in millimeters. If the eye tracker data file has pupil data from both eyes use this argument for the right pupil.
Column name that contains the left pupil data in pixels. If the eye tracker data file has pupil data from both eyes use this argument for the left pupil.
Column name that contains the right pupil data in pixels. If the eye tracker data file has pupil data from both eyes use this argument for the right pupil.
Column name that contains the left eye gaze position on the x-axis. If the eye tracker data file has data from both eyes use this argument for the left eye.
Column name that contains the left eye gaze position on the y-axis. If the eye tracker data file has data from both eyes use this argument for the left eye.
Column name that contains the right eye gaze position on the x-axis. If the eye tracker data file has data from both eyes use this argument for the right eye.
Column name that contains the right eye gaze position on the y-axis. If the eye tracker data file has data from both eyes use this argument for the right eye.
Column name that contains whether the eye event sample is in a blink or not in a blink. If the eye tracker data file has data from both eyes use this argument for the left eye.
Column name that contains whether the eye event sample is in a blink or not in a blink. If the eye tracker data file has data from both eyes use this argument for the right eye.
Column name that contains whether the eye event sample is in a fixation or not in a fixation. If the eye tracker data file has data from both eyes use this argument for the left eye.
Column name that contains whether the eye event sample is in a fixation or not in a fixation. If the eye tracker data file has data from both eyes use this argument for the right eye.
Column name that contains whether the eye event sample is in a saccade or not in a saccade. If the eye tracker data file has data from both eyes use this argument for the left eye.
Column name that contains whether the eye event sample is in a saccade or not in a saccade. If the eye tracker data file has data from only one eye use this argument. If the eye tracker data file has data from both eyes use this argument for the right eye.
Column name that contains the left eye event data (e.g., fixation, saccade, and blink). If the eye tracker data file has data from both eyes use this argument for the left eye. Some eye trackers will store the event data in one column with values corresponding to fixation, blink, or saccades. You also need to specify what these values are with the eye_event_blink, eye_event_fixation, and eye_event_saccade arguments.
Column name that contains the right eye event data (e.g., fixation, saccade, and blink). If the eye tracker data file has data from both eyes use this argument for the right eye. Some eye trackers will store the event data in one column with values corresponding to fixation, blink, or saccades. You also need to specify what these values are with the eye_event_blink, eye_event_fixation, and eye_event_saccade arguments.
See start_tracking_message.
See start_tracking_match.
See start_tracking_message.
See start_tracking_match.
Standardized columns and values to be used with other functions in this package.
Ease of import is provided for certain eye trackers:
- SMI: Red250m and glasses: `pupil_read(eyetracker = "smi")` - SR Research: EyeLink 1000 Plus `pupil_read(eyetracker = "eyelink")` - Tobii: Pro Fusion `pupil_read(eyetracker = "tobii")`
Other eye trackers from these companies may or may not be supported but you are welcome to try.
All other eye trackers and data file types can be imported by specifying the column names.
There are several importing options to specify, some of them required, others are more optional. See the full argument list for all options.
- start_tracking_message (recommended): helps to correctly identify trials segments
- eye_use (optional): specify which eye you want to perform analyses on
- px_to_mm_conversion (optional): convert pupil pixel values to millimeters
- include_col (optional): other columns you may want to include (e.g., RT, accuracy, condition)
- trial_exclude (optional): remove certain trials from the data
- quality_check_dir (optional): a directory to save an import quality check file to
- subj_prefix: required for SMI eye trackers, might be useful to remove strings in subject column
- subj_suffix: required for SMI eye trackers, might be useful to remove strings in subject column