| Title: | Tools for Processing Webcam Eye Tracking Data |
|---|---|
| Description: | A companion package to gazeR. Functions for reading and pre-processing webcam eye tracking data. |
| Authors: | Jason Geller |
| Maintainer: | Jason Geller <[email protected]> |
| License: | GPL-3 |
| Version: | 0.1.0 |
| Built: | 2025-01-07 20:23:31 UTC |
| Source: | https://github.com/jgeller112/webgazeR |
This function calculates the sampling rate for each subject and trial in an eye-tracking dataset. It provides overall statistics, including the median and standard deviation of sampling rates, and also generates a histogram of median sampling rates by subject, with a density plot overlayed, and a vertical line showing the overall median sampling rate and the standard deviation displayed.
analyze_sampling_rate(eye_data)analyze_sampling_rate(eye_data)
eye_data |
A dataframe containing eye-tracking data with columns 'subject', 'trial', and 'time'. The column 'time' should represent the time in milliseconds for each trial. |
A list containing:
The overall median sampling rate (Hz).
The overall standard deviation of sampling rates.
A dataframe with the median sampling rate by subject.
A dataframe with the sampling rate by subject and trial.
## Not run: # Assuming eye_data is a dataframe with appropriate columns result <- analyze_sampling_rate(eye_data) print(result) ## End(Not run)## Not run: # Assuming eye_data is a dataframe with appropriate columns result <- analyze_sampling_rate(eye_data) print(result) ## End(Not run)
Takes a data frame of gaze positions (or other locations), plus screen size and aoi size (or location), and computes the area of interest (AOI) for each location. Defaults assume standard four-corner design.
assign_aoi( gaze, screen_size = c(1024, 768), aoi_size = c(400, 300), aoi_loc = NULL, X = "CURRENT_FIX_X", Y = "CURRENT_FIX_Y" )assign_aoi( gaze, screen_size = c(1024, 768), aoi_size = c(400, 300), aoi_loc = NULL, X = "CURRENT_FIX_X", Y = "CURRENT_FIX_Y" )
gaze |
data frame containing positions |
screen_size |
size of the screen in pixels. Defaults to c(1024, 768) and assumes reversed vertical (i.e., [0,0] is top left). |
aoi_size |
size of AOIs in pixels. Defaults to a c(400, 300) width-height pair and assumes AOIs are in screen corners. AOIs will be coded numerically 1 to 4 in reading order (left to right, top to bottom), with 0 as center location. |
aoi_loc |
location of rectangular AOIs. Use as alternative to aoi_size for non-corner AOIs. Each AOI location should be a separate row in a data frame that has variables xmin, xmax, ymin, and ymax. Assumes reversed vertical (i.e., [0,0] is top left). AOIs will be coded numerically in row order. |
X |
name of variable containing X coordinates. Defaults to "CURRENT_FIX_X" |
Y |
name of variable containing Y coordinates. Defaults to "CURRENT_FIX_Y" |
Original gaze data frame with AOI column added. Non-AOI and off-screen gazes are marked NA.
This function combines gaze samples into time bins and optionally aggregates the data.
downsample_gaze( dataframe, bin.length = 50, timevar = "time", aggvars = c("subject", "condition", "target", "trial", "object", "time_bin") )downsample_gaze( dataframe, bin.length = 50, timevar = "time", aggvars = c("subject", "condition", "target", "trial", "object", "time_bin") )
dataframe |
DataFrame containing gaze data. |
bin.length |
Length of time bins (in milliseconds). |
timevar |
Column name representing time. |
aggvars |
Vector of variable names to group by for aggregation. Use "none" to skip aggregation. |
DataFrame with time bins added and optionally aggregated data.
This function reads in multiple Gorilla webcam files, extracts the 'loc', 'x_normalised', 'y_normalised', 'width_normalised', and 'height_normalised' columns, and calculates the bounding box coordinates for the AOIs. It also rounds all numeric columns to 3 decimal places.
extract_aois(file_paths, zone_names = NULL)extract_aois(file_paths, zone_names = NULL)
file_paths |
A list of file paths to webcam files (in .xlsx format). |
A dataframe containing distinct rows with AOI-related columns and calculated coordinates.
# Example usage: # file_paths <- c("file1.xlsx", "file2.xlsx") # aoi_data <- extract_aois(file_paths)# Example usage: # file_paths <- c("file1.xlsx", "file2.xlsx") # aoi_data <- extract_aois(file_paths)
This function allows users to set a sampling rate threshold and choose to either remove the data that falls below the threshold or label it as "bad." Users can apply this threshold either at the subject level, the trial level, or both.
filter_sampling_rate( data, threshold = NA, action = c("remove", "label"), by = c("subject", "trial", "both") )filter_sampling_rate( data, threshold = NA, action = c("remove", "label"), by = c("subject", "trial", "both") )
data |
A dataframe that contains the data to be processed. The dataframe should include the columns:
|
threshold |
Numeric value specifying the sampling rate threshold. Data falling below this threshold will either be removed or labeled as "bad". |
action |
Character string specifying whether to "remove" data that falls below the threshold or "label" it as bad. Acceptable values are '"remove"' or '"label"'.
|
by |
Character string specifying whether the threshold should be applied at the "subject" level, the "trial" level, or "both". Acceptable values are '"subject"', '"trial"', or '"both"'.
|
A dataframe with either rows removed or new columns ('is_bad_subject', 'is_bad_trial') added to indicate whether the data is below the threshold. Additionally, messages will inform the user how many subjects and trials were removed or labeled as "bad."
The function will either return a dataset with rows removed based on the sampling rate threshold or add new columns, 'is_bad_subject' and/or 'is_bad_trial' to the dataset, which indicates whether the data is considered "bad" (i.e., below the sampling rate threshold).
## Not run: # Example usage of the filter_sampling_rate function result <- filter_sampling_rate(data = data_with_sr, threshold = 500, action = "remove", by = "both") # Example usage to label data as "bad" result <- filter_sampling_rate(data = data_with_sr, threshold = 500, action = "label", by = "trial") ## End(Not run)## Not run: # Example usage of the filter_sampling_rate function result <- filter_sampling_rate(data = data_with_sr, threshold = 500, action = "remove", by = "both") # Example usage to label data as "bad" result <- filter_sampling_rate(data = data_with_sr, threshold = 500, action = "label", by = "trial") ## End(Not run)
This function determines the location of an image within a set of locations. The function accepts a vector of locations (such as "TL", "TR", "BL", "BR") and an image identifier. It returns the corresponding location name if the image is found, or 'NA' if the image is not present or is 'NA'.
find_location(locations, image)find_location(locations, image)
locations |
A character vector representing the possible locations (e.g., 'c("TL", "TR", "BL", "BR")'). |
image |
A character value representing the image to find in the locations. |
A character string representing the location of the image, or 'NA' if the image is not found or is missing.
# Example usage of the find_location function locations <- c("apple", "banana", "cherry", "date") find_location(locations, "banana") # Returns "TR" if locations follow c("TL", "TR", "BL", "BR") find_location(locations, "orange") # Returns NA# Example usage of the find_location function locations <- c("apple", "banana", "cherry", "date") find_location(locations, "banana") # Returns "TR" if locations follow c("TL", "TR", "BL", "BR") find_location(locations, "orange") # Returns NA
This function calculates the number and percentage of points that fall outside a specified range (0, 1) for both X and Y coordinates, grouped by subject.
gaze_oob( data, subject_col = "subject", x_col = "x_pred_normalised", y_col = "y_pred_normalised" )gaze_oob( data, subject_col = "subject", x_col = "x_pred_normalised", y_col = "y_pred_normalised" )
data |
A data frame containing gaze data. |
subject_col |
A string specifying the name of the column that contains the subject identifier. Default is "subject". |
x_col |
A string specifying the name of the column that contains the X coordinate. Default is "x_pred_normalised". |
y_col |
A string specifying the name of the column that contains the Y coordinate. Default is "y_pred_normalised". |
A data frame with the following columns:
The subject identifier.
The total number of points for the subject.
The number of points outside the range for both X and Y coordinates.
The number of points outside the range for the X coordinate.
The number of points outside the range for the Y coordinate.
The percentage of points outside the range for the X coordinate.
The percentage of points outside the range for the Y coordinate.
## Not run: # Example data data <- data.frame( subject = rep(1:2, each = 100), x_pred_normalised = runif(200, -0.5, 1.5), y_pred_normalised = runif(200, -0.5, 1.5) ) # Calculate out-of-bounds proportion by subject results <- calculate_out_of_bounds_by_subject(data) print(results) ## End(Not run)## Not run: # Example data data <- data.frame( subject = rep(1:2, each = 100), x_pred_normalised = runif(200, -0.5, 1.5), y_pred_normalised = runif(200, -0.5, 1.5) ) # Calculate out-of-bounds proportion by subject results <- calculate_out_of_bounds_by_subject(data) print(results) ## End(Not run)
This function reads in multiple Gorilla webcam files, merges them, and optionally extracts area of interest (AOI) data. It cleans up column names, and allows filtering by screen index. If 'extract_aois' is TRUE, it extracts specific AOI-related columns ('zone_name', 'zone_x_normalized', 'zone_y_normalized', 'zone_width_normalized', and 'zone_height_normalized') and returns distinct rows for these columns.
merge_webcam_files(file_paths, screen_index = NULL)merge_webcam_files(file_paths, screen_index = NULL)
file_paths |
A list of file paths to webcam files (in .xlsx format). |
screen_index |
An optional screen index to filter the data by. If NULL, the filter will be ignored. |
extract_aois |
Logical. If TRUE, extracts AOI-related columns and returns distinct rows for them. |
A dataframe containing the merged and processed data from the webcam files. If 'extract_aois' is TRUE, it returns a dataframe with distinct AOI-related columns.
# Example usage: # file_paths <- c("file1.xlsx", "file2.xlsx") # merged_data <- extract_gorilla_aois(file_paths, screen_index = 4, extract_aois = FALSE) # aoi_data <- extract_gorilla_aois(file_paths, screen_index = 4, extract_aois = TRUE)# Example usage: # file_paths <- c("file1.xlsx", "file2.xlsx") # merged_data <- extract_gorilla_aois(file_paths, screen_index = 4, extract_aois = FALSE) # aoi_data <- extract_gorilla_aois(file_paths, screen_index = 4, extract_aois = TRUE)
This function creates a time-course plot of the proportion of looks to specified Interest Areas (IAs). Optionally, it can facet the plot by an experimental condition. Custom labels for each IA can be specified through the 'ia_mapping' argument to define the display order.
plot_IA_proportions( data, ia_column, time_column, proportion_column, condition_column = NULL, ia_mapping )plot_IA_proportions( data, ia_column, time_column, proportion_column, condition_column = NULL, ia_mapping )
data |
A data frame containing the data to plot. |
ia_column |
The name of the column containing Interest Area (IA) identifiers. |
time_column |
The name of the column representing time (e.g., milliseconds). |
proportion_column |
The name of the column with the proportion of looks for each IA. |
condition_column |
Optional. The name of the column representing experimental conditions. If not provided, the plot will not be faceted by condition. |
ia_mapping |
A named list specifying custom labels for each IA in the desired display order (e.g., 'list(IA1 = "Target", IA2 = "Cohort", IA3 = "Rhyme", IA4 = "Unrelated")'). |
A ggplot2 plot of the proportion of looks over time for each IA, optionally faceted by condition.
## Not run: # Example with a condition column plot_IA_proportions(gaze_data, ia_column = "condition", time_column = "time_ms", proportion_column = "proportion_looks", condition_column = "condition", ia_mapping = list(IA1 = "Target", IA2 = "Cohort", IA3 = "Rhyme", IA4 = "Unrelated")) # Example without a condition column plot_IA_proportions(gaze_data, ia_column = "condition", time_column = "time_ms", proportion_column = "proportion_looks", ia_mapping = list(IA1 = "Target", IA2 = "Cohort", IA3 = "Rhyme", IA4 = "Unrelated")) ## End(Not run)## Not run: # Example with a condition column plot_IA_proportions(gaze_data, ia_column = "condition", time_column = "time_ms", proportion_column = "proportion_looks", condition_column = "condition", ia_mapping = list(IA1 = "Target", IA2 = "Cohort", IA3 = "Rhyme", IA4 = "Unrelated")) # Example without a condition column plot_IA_proportions(gaze_data, ia_column = "condition", time_column = "time_ms", proportion_column = "proportion_looks", ia_mapping = list(IA1 = "Target", IA2 = "Cohort", IA3 = "Rhyme", IA4 = "Unrelated")) ## End(Not run)