Skip to contents

Load a .gazedata file for an experiment

read_gazedata.Rd

Loads .gazedata file created by an Eprime experiment running on a Tobii eyetracker, and performs typical data reduction on that file.

Usage

read_gazedata(
  gazedata_path,
  eyes = "both",
  means_need_both = FALSE,
  apply_corrections = TRUE
)

Arguments

gazedata_path

path to the .gazedata file that is to be parsed.

eyes

string describing which eye(s) should be selected for the Mean columns. Valid options are "both", "left", and "right". Defaults to "both". If "left" is selected, then only the left eye is used to calculate the XMean, YMean, etc. columns.

means_need_both

logical value indicating if both eyes are required to compute Mean columns. Defaults to FALSE. If FALSE, NA values are ignored, so for example, XMean could be computed from an XLeft of .25 and an XRight of NA.

apply_corrections

whether to do low-level adjustments like coding offscreen looks as NA, negative pupil diameters to NA, negative distances to NA, and flip y-axis so the origin is the lower-left corner. Defaults to TRUE. Only used as FALSE in case "raw" data is needed.

Value

A dataframe containing the parsed gazedata. Each row of the dataframe contains the eye-tracking data for a single frame of time recorded during the experiment.

Details

We extract the columns the following columns: TrialId, RTTime, XGazePosLeftEye, XGazePosRightEye, YGazePosLeftEye, YGazePosRightEye, DistanceLeftEye, DistanceRightEye, DiameterPupilLeftEye and DiameterPupilRightEye.

Once these column values are loaded, we make three modifications to the gazedata (when apply_corrections is TRUE).

  1. Gaze measurements with Validity codes greater than or equal to 1 are replaced with NA values.

  2. X,Y gaze values are defined in screen proportions. Values that fall outside [0,1] are outside of the boundaries of the screen and therefore are nonsensical. Replace them with NA. We perform a similar correction on pupil diameters and eye-distances by replacing negative values with NA.

  3. The origin of the screen is the upper-left-hand corner of the screen. Flip the y-values so that the origin is in a more familiar position in the lower-left-hand corner of the screen. This way, low y values are closer to the bottom of the screen.

  4. Compute the mean x, y, distance and diameter values for the left and right eyes. NA values are ignored when computing the mean, so the pair (XLeft = NA, XRight = .5) yields XMean = .5.

References

Tobii Toolbox for Matlab: Product Description & User Guide

Examples

gazedata_path <- example_files(1)[1]
read_gazedata(gazedata_path)
#> # A tibble: 12,573 × 17
#>    Basename TrialNo TobiiTime  Time Origin XLeft XRight XMean YLeft YRight YMean
#>    <chr>      <int>     <dbl> <int> <chr>  <dbl>  <dbl> <dbl> <dbl>  <dbl> <dbl>
#>  1 Coartic…       1   1.36e12 37312 Lower… 0.355  0.367 0.361 0.561  0.551 0.556
#>  2 Coartic…       1   1.36e12 37329 Lower… 0.352  0.372 0.362 0.559  0.562 0.561
#>  3 Coartic…       1   1.36e12 37345 Lower… 0.359  0.366 0.362 0.564  0.566 0.565
#>  4 Coartic…       1   1.36e12 37362 Lower… 0.353  0.366 0.360 0.565  0.573 0.569
#>  5 Coartic…       1   1.36e12 37378 Lower… 0.350  0.367 0.359 0.558  0.579 0.568
#>  6 Coartic…       1   1.36e12 37395 Lower… 0.352  0.363 0.358 0.559  0.574 0.567
#>  7 Coartic…       1   1.36e12 37412 Lower… 0.357  0.360 0.358 0.566  0.565 0.565
#>  8 Coartic…       1   1.36e12 37428 Lower… 0.352  0.367 0.359 0.563  0.559 0.561
#>  9 Coartic…       1   1.36e12 37445 Lower… 0.348  0.374 0.361 0.554  0.558 0.556
#> 10 Coartic…       1   1.36e12 37461 Lower… 0.351  0.364 0.357 0.569  0.565 0.567
#> # ℹ 12,563 more rows
#> # ℹ 6 more variables: ZLeft <dbl>, ZRight <dbl>, ZMean <dbl>,
#> #   DiameterLeft <dbl>, DiameterRight <dbl>, DiameterMean <dbl>