Skip to contents

Corrects eye-tracking coordinate data

eye_scroll_correct.Rd

The core function that corrects the eye-tracking coordinate data to fit in a webpage scrolled vertically by the participant

Usage

eye_scroll_correct(
  eyes_data,
  timestamp_start,
  timestamp_stop,
  image_width,
  image_height,
  calibration,
  time_shift = 0,
  starting_scroll = 0,
  output_file = "",
  fixed_areas = list(),
  rules = list(),
  scroll_lag = 0,
  outside_image_is_na = TRUE,
  progression_bar = TRUE
)

Arguments

eyes_data

The dataset. Please note that it MUST include correctly named columns (see below)

timestamp_start

The starting timestamp from the dataset at which the participant was watching the webpage (INCLUDING the time_shift, if applicable)

timestamp_stop

The final timestamp from the dataset at which the participant was watching the webpage (INCLUDING the time_shift, if applicable)

image_width

The total width of the webpage image (in pixels)

image_height

The total height of the webpage image (in pixels)

calibration

A calibration list (see the scroll_calibration_auto or the scroll_calibration_manual functions)

time_shift

[Optional] A time shift parameter to synchronize the dataset with another source (e.g. if a screen recording started after timestamp 0 of the .csv). Default: 0

starting_scroll

[Optional] If the participant did not start watching the webpage from the top, you can indicate the y coordinate at which he started here (in pixels). Default: 0

output_file

[Optional] The name of the output .csv file. If an empty string, will just return the data without creating a file. Default: empty string

fixed_areas

[Optional] A list of potentially immovable areas inside the webpage (e.g. fixed menus in a website) - see the Fixed Areas article for more information. Default: empty list

rules

[Optional] A list of functions that can act as rules to activate/deactivate immovables areas in the webpage (e.g. a menu that disappears after X pixels have been scrolled) - See the Fixed Areas article for more information. Default: empty list

scroll_lag

[Optional] Determines the lag (in milliseconds) between the scroll message and the scroll correction, to account for input lag. See the related publication for more information. Default: 0

outside_image_is_na

[Optional] Indicates if values outside the AOI (e.g. the windows bar) should be set to NA or kept in the file/dataset. If set to FALSE, coordinates above/before the AOI will become negative. Default: TRUE

progression_bar

[Optional] Indicates if the function should display a progression bar. Default: TRUE

Value

Returns the same dataset with added columns for corrected coordinates ("Corrected.Gaze.X", "Corrected.Gaze.Y", "Corrected.Fixation.X" and "Corrected.Fixation.Y"), shifted timestamps ("Timestamp.Shifted"), and the amount of pixels scrolled down ("Scroll")

Details

The Dataset

The dataset must include correctly named columns, which are:

  • A "Data" column, with user-generated events (such as keystrokes or browser changes)

  • A "Timestamp" column with the timestamps for each fixation point and event

  • A "Gaze.X" column with the x coordinate of gaze

  • A "Gaze.Y" column with the y coordinate of gaze

  • A "Fixation.X" column with the x coordinate of fixation points

  • A "Fixation.Y" column with the y coordinate of fixation points

Data and Timestamp columns are mandatory, but you may choose to only include Gaze data or Fixation data (or both)

Examples

if (FALSE) {
library(eyeScrollR)
calibration <- scroll_calibration_auto(calibration_image = calibration_image,
                                       scroll_pixels = 100)
data <- eye_scroll_correct(eyes_data = dataset, timestamp_start = 2000,
                                    timstamp_stop = 50000, image_width = 1920,
                                    image_height = 10000, calibration = calibration)
generate_heatmap(data = data, heatmap_image = heatmap_image)
}