eyetools: Analyse Eye Data

Description

Enables the automation of actions across the pipeline, including initial steps of transforming binocular data and gap repair to event-based processing such as fixations, saccades, and entry/duration in Areas of Interest (AOIs). It also offers visualisation of eye movement and AOI entries. These tools take relatively raw (trial, time, x, and y form) data and can be used to return fixations, saccades, and AOI entries and time spent in AOIs. As the tools rely on this basic data format, the functions can work with data from any eye tracking device. Implements fixation and saccade detection using methods proposed by Salvucci and Goldberg (2000) doi:10.1145/355017.355028.

Author(s)

Maintainer: Tom Beesley t.beesley@lancaster.ac.uk

Authors:

• Matthew Ivory matthew.ivory@lancaster.ac.uk

See Also

Useful links:

• https://tombeesley.github.io/eyetools/

• Report bugs at https://github.com/tombeesley/eyetools/issues

Sequence analysis of area of interest entries

Description

Analyses the sequence of entries into defined AOI regions across trials. Can only be used with fixation data with a "fix_n" column denoting fixation events. Assumes that AOIs are non-overlapping and hasn't been tested with overlapping AOIs. Consecutive fixations within an AOI are grouped together as a single entry. Non-consecutive fixations in the same AOI (i.e., with an intervening fixation in no AOI) are treated as two separate entries.

Usage

AOI_seq(data, AOIs, AOI_names = NULL, progress = TRUE)

Arguments

Value

a dataframe containing the sequence of entries into AOIs on each trial, entry/exit/duration time into AOI

Examples

data <- combine_eyes(HCL)
fix_d <- fixation_dispersion(data)

AOI_seq(fix_d, AOIs = HCL_AOIs)

Analysis of time spent in areas of interest

Description

Analyses total time on defined AOI regions across trials. Works with fixation and raw data as the input (must use one or the other, not both).

Usage

AOI_time(
  data,
  data_type = NULL,
  AOIs,
  AOI_names = NULL,
  sample_rate = NULL,
  as_prop = FALSE,
  trial_time = NULL
)

Arguments

Details

Analyses data separately for each unique combination of values in pID and trial. Returned values can be absolute time or proportion of time over the period.

Value

a dataframe containing the time on the passed AOIs for each trial. One column for each AOI separated by trial.

Examples

data <- combine_eyes(HCL)
fix_d <- fixation_dispersion(data)

# fixation data
AOI_time(data = fix_d, data_type = "fix", AOIs = HCL_AOIs)

#raw data
AOI_time(data = data, data_type = "raw", AOIs = HCL_AOIs)

#as proportional data
AOI_time(data = fix_d, data_type = "fix", AOIs = HCL_AOIs,
         as_prop = TRUE, trial_time = HCL_behavioural$RT)

Binned time analysis of area of interest entries

Description

Analyses total time on defined AOI regions across trials separated into bins. Works with raw data as the input. Data can be separated into bins of a given length of time and the number of bins per trial is calculated automatically, keeping the bin length consistent across varying lengths of trial. Any data that cannot fill a bin (typically the last few milliseconds of the trial) are dropped to ensure that bins are of a consistent length

Usage

AOI_time_binned(
  data,
  AOIs,
  AOI_names = NULL,
  sample_rate = NULL,
  bin_length = NULL,
  max_time = NULL,
  as_prop = FALSE
)

Arguments

Details

AOI_time_binned can take either single participant data or multiple participants, where participants are demarcated by values in the "pID" column.

Value

a dataframe containing the time on the passed AOIs for each trial. One column for each AOI separated by trial.

Examples

data <- combine_eyes(HCL)


#with bins of 100ms each and only for the first 2000ms
AOI_time_binned(data = data, AOIs = HCL_AOIs, 
    bin_length = 100, max_time = 2000)

Example dataset from that contains binocular eye data from two participants from a simple contingency learning task (the data are from Beesley, Nguyen, Pearson, & Le Pelley, 2015). In this task there are two stimuli that appear simultaneously on each trial (to the left and right of the screen). Participants look at these cues and then make a decision by selecting an "outcome response" button.

Description

The dataset contains data from two participants and the first six trials of the study.

Usage

HCL

Format

A dataframe of 31,041 observations and seven variables

pID

participant ID

time

timestamp of the sample (milliseconds)

left_x

x coordinate of the left eye

left_y

y coordinate of the left eye

right_x

x coordinate of the right eye

right_y

y coordinate of the right eye

trial

trial number

...

Example AOIs for use with HCL

Description

This dataframe contains three rectangular areas of interest (AOIs), set out for use with the HCL dataset. Values are in pixels.

Usage

HCL_AOIs

Format

A data frame with 3 rows and 4 variables:

x

centred x coordinate of the AOI

y

centred y coordinate of the AOI

width_radius

either the width of the AOI, or the radius for circular AOIs

height

the height of the AOI; should be NA for circular AOIs

...

Example dataset of behavioural data to complement dataset HCL.

Description

This contains information on stimuli (such as the side the predictive cue was presented on) as well as response data, including accuracy and response times

Usage

HCL_behavioural

Format

A dataframe of 12 observations and eight variables

pID

participant ID

trial

trial number

P_cue

Are these necessary columns?

NP_cue

Are these necessary columns?

cue_order

whether the predictive cue os presented on the left (1) or the right (2)

correct_out

NAre these necessary columns?

accuracy

response accuracy

RT

response time in milliseconds

...

Combine binocular data into single X/Y coordinate pairs

Description

Combines the data from binocular samples into X/Y coordinate pairs. Two methods can be used: "average" or "best_eye". For "average", the result is based on the average of the two eyes for each sample, or for samples where there is data from only a single eye, that eye is used. For "best_eye", a summary of the proportion of missing samples is computed, and the eye with the fewest missing samples is used.

Usage

combine_eyes(data, method = "average")

Arguments

Value

a dataframe of x-2 variables (with left_x and right_x condensed to x, and left_y and right_y condensed to y) and the same number of observations as the input data

Examples

combine_eyes(HCL, method = "average")

A battery of metrics and plots to compare the two algorithms (dispersion and VTI)

Description

A tool for comparing the two different algorithms present in this package. This function is useful for assessing the data as well as exploring which algorithm is likely to fit data more appropriately. The raw data is run through both algorithms (using the same specified dispersion tolerances, etc.) before making comparisons of the underlying data. Can only be used for single participant data.

Usage

compare_algorithms(
  data,
  plot_fixations = TRUE,
  print_summary = TRUE,
  sample_rate = NULL,
  threshold = 100,
  min_dur = 150,
  min_dur_sac = 20,
  disp_tol = 100,
  NA_tol = 0.25,
  smooth = FALSE
)

Arguments

Value

a list of the fixation data, correlation output, and data used for plotting

Examples

data <- combine_eyes(HCL)
data <- interpolate(data)
compare_algorithms(data[data$pID == 119,])

conditional_transform

Description

A function to perform conditional transformations of the x/y raw data. The function takes the dataframe and performs a single axis flip based on the values specified in the cond_column. The primary use of this function is to correct or normalise the data when counterbalancing stimulus placement within experiments (e.g., having a target stimulus appear on the left and right equally often)

Usage

conditional_transform(
  data,
  flip = c("x", "y"),
  cond_column,
  cond_values,
  resolution_x = 1920,
  resolution_y = 1080,
  message = TRUE
)

Arguments

Value

a dataframe of the equivalent format as the input data

Examples

data <- combine_eyes(HCL)
data <- merge(data, HCL_behavioural)
conditional_transform(data, flip = "x",
                      cond_column = "cue_order",
                      cond_values = 2)

Create a blank data frame for populating with AOIs

Description

Create a blank data frame for populating with AOIs

Usage

create_AOI_df(num_AOIs = 3, shape = "rect", AOI_data = NULL)

Arguments

Value

a dataframe in the standard format required for eyetools

Examples

# create an empty data frame with 3 rectangular shaped AOIs
create_AOI_df(3, shape = "rect")

# create an AOI dataframe with data
create_AOI_df(3, shape = "rect",
              AOI_data = list(c(460,840,400,300), c(1460,840,400,300), c(960,270,300,500)))
# creating data for circular AOIs
create_AOI_df(3, shape = "circ",
              AOI_data = list(c(460,840,400), c(1460,840,400), c(960,270,300)))

Compute visual angle from distance metrics

Description

Takes a single value or vector of distances and returns the visual angle equivalent.

Usage

dist_to_visual_angle(
  vector,
  dist_type = "cm",
  view_dist_cm = 60,
  screen_width_cm = 51,
  screen_width_pixels = 1920
)

Arguments

Value

an equivalent-sized object to the input

Examples

# calculate visual angle for stimulus of 5cm
dist_to_visual_angle(5)

# calculate visual angle of stimuli 2 and 10cm width at 50 cm viewing angle
dist_to_visual_angle(c(2,10), view_dist_cm = 50)

# calculate visual angle of 150 pixel wide
dist_to_visual_angle(150, dist_type = "pixels")

Fixation detection using a velocity threshold identification method

Description

Determine fixations by assessing the velocity of eye-movements, using a method that is similar to that proposed by Salvucci & Goldberg (2000). Applies the algorithm used in VTI_saccade and removes the identified saccades before assessing whether separated fixations are outside of the dispersion tolerance. If they are outside of this tolerance, the fixation is treated as a new fixation regardless of the length of saccade separating them. Compared to fixation_dispersion(), fixation_VTI() is more conservative in determining a fixation as smaller saccades are discounted and the resulting data is treated as a continued fixation (assuming it is within the pixel tolerance set by disp_tol). Returns a summary of the fixations found per trial, including start and end coordinates, timing, duration, mean velocity, and peak velocity.

Usage

fixation_VTI(
  data,
  sample_rate = NULL,
  threshold = 100,
  min_dur = 150,
  min_dur_sac = 20,
  disp_tol = 100,
  smooth = FALSE,
  progress = TRUE
)

Arguments

Details

Analyses data separately for each unique combination of values in pID and trial.

Value

a dataframe containing each detected fixation by trial, with mean x/y position in pixel, start and end times, and duration.

References

Salvucci, D. D., & Goldberg, J. H. (2000). Identifying fixations and saccades in eye-tracking protocols. Proceedings of the Symposium on Eye Tracking Research & Applications - ETRA '00, 71–78.

Examples

data <- combine_eyes(HCL)
data <- interpolate(data)
fixation_VTI(data)

Fixation detection using a dispersion method

Description

Detects fixations by assessing dispersion of the eye position, using a method that is similar to that proposed by Salvucci & Goldberg (2000). Evaluates the maximum dispersion (distance) between x/y coordinates across a window of data. Looks for sufficient periods in which this maximum dispersion is below the specified dispersion tolerance. NAs are considered breaks in the data and are not permitted within a valid fixation period.

Usage

fixation_dispersion(
  data,
  min_dur = 150,
  disp_tol = 100,
  NA_tol = 0.25,
  progress = TRUE
)

Arguments

Details

It can take either single participant data or multiple participants, where participants are demarcated by values in the "pID" column.

Value

a dataframe containing each detected fixation by trial, with mean x/y position in pixel, start and end times, and duration.

References

Salvucci, D. D., & Goldberg, J. H. (2000). Identifying fixations and saccades in eye-tracking protocols. Proceedings of the Symposium on Eye Tracking Research & Applications - ETRA '00, 71–78.

Examples

data <- combine_eyes(HCL)
fixation_dispersion(data)

Get messgaes stored in TOBII-generated HDF5 files

Description

A function to get the message event files from a TOBII-generated hdf5 file to dataframe. Used when a Psychopy experiment uses the io.sendMessageEvent() to record events

Usage

hdf5_get_event(filename)

Arguments

Value

A dataframe of message events as recorded by TOBII eye trackers

Examples

## Not run: 
raw_data <- hdf5_get_event("example_TOBII.hdf5")

## End(Not run)

Convert TOBII-generated HDF5 files to dataframe

Description

A function to convert TOBII-generated hdf5 files to a dataframe

Usage

hdf5_to_df(filename)

Arguments

Value

A list of dataframes collected from the eyetracker content, if only one eyetracking event is present, return this as a single dataframe

Examples

## Not run: 
raw_data <- hdf5_to_df("example_TOBII.hdf5")

## End(Not run)

Interpolation of missing data (NAs)

Description

Extends the zoo::na.approx and zoo::na.spline functions to include a report which provides the proportion of missing data before and after the interpolation process. This is handy for evaluating the effectiveness of the repair.

Usage

interpolate(
  data,
  maxgap = 150,
  method = "approx",
  sample_rate = NULL,
  report = FALSE
)

Arguments

Details

Analyses data separately for each unique combination of values in pID and trial.

Value

a dataframe of the same shape of the input data

Examples

data <- combine_eyes(HCL)
interpolate(data, maxgap = 150)

Plots absolute or proportional time spent in AOIs over time

Description

A visualisation tool for plotting the changes in defined AOI regions across a single trial time.

Usage

plot_AOI_growth(
  data = NULL,
  pID_values = NULL,
  trial_values = NULL,
  AOIs = NULL,
  AOI_names = NULL,
  type = "abs",
  plot_time_not_in_AOI = FALSE
)

Arguments

Value

a plot of the raw data

Examples

data <- combine_eyes(HCL)
data <- interpolate(data)
# plot absolute and then proportional
plot_AOI_growth(data = data, AOIs = HCL_AOIs, type = "abs")
plot_AOI_growth(data = data, AOIs = HCL_AOIs, type = "prop")

Plot heatmap of raw data

Description

Plots a heatmap of raw data.

Usage

plot_heatmap(
  data = NULL,
  pID_values = NULL,
  trial_values = NULL,
  bg_image = NULL,
  res = c(0, 1920, 0, 1080),
  flip_y = FALSE,
  plot_type = "density",
  alpha_range = c(0.1, 0.8),
  plot_header = FALSE
)

Arguments

Value

a plot of the raw data

Examples

data <- combine_eyes(HCL)
# plot all trials data
plot_heatmap(data, pID_values = 118, alpha_range = c(0.3,0.8))

#plot one trial
plot_heatmap(data, trial_values = 1)

Plot of raw data over time

Description

A tool for visualising the timecourse of raw data over a single trial. Participant and trial values can be selected from the data. If values for these parameters are not provided then a single participant and a single trial will be sampled at random. Data can be split into bins by time or by the number of bins.

Usage

plot_seq(
  data = NULL,
  AOIs = NULL,
  trial_values = NULL,
  pID_values = NULL,
  bg_image = NULL,
  res = c(0, 1920, 0, 1080),
  flip_y = FALSE,
  plot_header = FALSE,
  bin_time = NULL,
  bin_range = NULL
)

Arguments

Value

a plot of the raw data representing changes over time

Examples

data <- combine_eyes(HCL)

# plot the raw data
plot_seq(data)

# with AOIs
plot_seq(data, AOIs = HCL_AOIs)

# plot raw data with bins
plot_seq(data, bin_time = 500)

Plot raw data and fixations

Description

A tool for visualising raw eye-data, processed fixations, and saccades. Can use all three data types together and independently. Fixations can be labeled in the order they were made. Can overlay areas of interest (AOIs) and customise the resolution.

Usage

plot_spatial(
  raw_data = NULL,
  fix_data = NULL,
  sac_data = NULL,
  AOIs = NULL,
  pID_values = NULL,
  trial_values = NULL,
  bg_image = NULL,
  res = c(0, 1920, 0, 1080),
  flip_y = FALSE,
  show_fix_order = TRUE,
  plot_header = FALSE
)

Arguments

Value

a plot of the raw data

Examples

data <- combine_eyes(HCL)
# plot the raw data
plot_spatial(raw_data = data, pID_values = 118)

# plot both raw and fixation data together
plot_spatial(raw_data = data, fix_data = fixation_dispersion(data), pID_values = 118)

#plot one trial
plot_spatial(raw_data = data, fix_data = fixation_dispersion(data), trial_values = 6)

Velocity threshold identification of saccades

Description

Use the velocity threshold algorithm from Salvucci & Goldberg (2000) to determine saccadic eye movements. Returns a summary of the saccades found per trial, including start and end coordinates, timing, duration, mean velocity, and peak velocity.

Usage

saccade_VTI(data, sample_rate = NULL, threshold = 150, min_dur = 20)

Arguments

Details

Analyses data separately for each unique combination of values in pID and trial.

Value

a data frame giving the saccades found by trial

References

Salvucci, D. D., & Goldberg, J. H. (2000). Identifying fixations and saccades in eye-tracking protocols. Proceedings of the Symposium on Eye Tracking Research & Applications - ETRA '00, 71–78.

Examples

data <- combine_eyes(HCL)
saccade_VTI(data)

Smoothing of raw data

Description

A wrapper for the stats::loess function, with default parameters suitable for smoothing raw eye data

Usage

smoother(data, span = 0.05, plot = FALSE)

Arguments

Details

Analyses data separately for each unique combination of values in pID and trial.

Value

a dataframe of the same shape as the input data

Examples

data <- combine_eyes(HCL)

smoother(data)

#with an inspection plot
smoother(data, span = .02, plot = TRUE)