DataQuality: R6 class for calculating Data Quality from a gaze data...

In ETDQualitizer: Automated Eye Tracking Data Quality Determination for Screen-Based Eye Trackers

R6 class for calculating Data Quality from a gaze data segment

Description

Provides methods for assessing the quality of gaze data, including accuracy, precision, data loss, and effective sampling frequency.

Public fields

timestamps

Vector of timestamps in seconds. Samples with missing data should not be removed, or the RMS calculation would be incorrect.

azi

Vector of azimuth angles in degrees (Fick angles). Missing data should be coded as NA, not using some special value such as (0,0) or (-xres,-yres).

ele

Vector of elevation angles in degrees (Fick angles). Missing data should be coded as NA, not using some special value such as (0,0) or (-xres,-yres).

Methods

Public methods

• DataQuality$new()

• DataQuality$accuracy()

• DataQuality$precision_RMS_S2S()

• DataQuality$precision_STD()

• DataQuality$precision_BCEA()

• DataQuality$data_loss_from_invalid()

• DataQuality$data_loss_from_expected()

• DataQuality$effective_frequency()

• DataQuality$get_duration()

• DataQuality$precision_using_moving_window()

• DataQuality$clone()

---

Method new()

Creates a new DataQuality object from gaze data and timestamps.

Usage

DataQuality$new(gaze_x, gaze_y, timestamps, unit, screen = NULL)

Arguments

gaze_x

Horizontal gaze positions (pixels or degrees).

gaze_y

Vertical gaze positions (pixels or degrees).

timestamps

Vector of timestamps in seconds.

unit

Unit of gaze data: either "pixels" or "degrees".

screen

Optional ScreenConfiguration object, required if unit is "pixels".

Returns

A new DataQuality object.

Examples

dq <- DataQuality$new(gaze_x, gaze_y, timestamps, unit = "pixels", screen = sc)

---

Method accuracy()

Calculates the accuracy of gaze data relative to a known target location.

Usage

DataQuality$accuracy(target_azi, target_ele, central_tendency_fun = mean)

Arguments

target_azi

Target azimuth in degrees.

target_ele

Target elevation in degrees.

central_tendency_fun

Function to compute central tendency (e.g., mean, median).

Returns

Accuracy in degrees.

Examples

dq$accuracy(0, 0)

---

Method precision_RMS_S2S()

Calculates precision as root mean square of sample-to-sample distances

Usage

DataQuality$precision_RMS_S2S(central_tendency_fun = mean)

Arguments

central_tendency_fun

Function to compute central tendency (e.g., mean, median).

Returns

Precision in degrees.

Examples

dq$precision_RMS_S2S()

---

Method precision_STD()

Calculates precision as standard deviation of gaze positions.

Usage

DataQuality$precision_STD()

Returns

Standard deviation in degrees.

Examples

dq$precision_STD()

---

Method precision_BCEA()

Calculates the Bivariate Contour Ellipse Area (BCEA) and ellipse parameters for gaze precision.

Usage

DataQuality$precision_BCEA(P = 0.68)

Arguments

P

Proportion of data to include in the ellipse (default is 0.68).

Returns

BCEA in degrees-squared.

Examples

dq$precision_BCEA()

---

Method data_loss_from_invalid()

Calculates the proportion of missing data (coded as NA).

Usage

DataQuality$data_loss_from_invalid()

Returns

Proportion of missing samples.

Examples

dq$data_loss_from_invalid()

---

Method data_loss_from_expected()

Estimates data loss based on expected number of samples given the duration and sampling frequency.

Usage

DataQuality$data_loss_from_expected(frequency)

Arguments

frequency

Expected sampling frequency in Hz.

Returns

Proportion of missing samples.

Examples

dq$data_loss_from_expected(500)

---

Method effective_frequency()

Calculates the effective sampling frequency based on timestamps.

Usage

DataQuality$effective_frequency()

Returns

Effective frequency in Hz.

Examples

dq$effective_frequency()

---

Method get_duration()

Computes the total duration of the gaze recording, including the last sample.

Usage

DataQuality$get_duration()

Returns

Duration in seconds.

Examples

dq$get_duration()

---

Method precision_using_moving_window()

Calculates precision using a moving window approach.

Usage

DataQuality$precision_using_moving_window(
  window_length,
  metric,
  aggregation_fun = median,
  ...
)

Arguments

window_length

Length of the moving window in number of samples.

metric

Precision metric to use ("RMS-S2S", "STD", or "BCEA").

aggregation_fun

Function to aggregate windowed precision values (e.g., median).

...

Additional arguments passed to the precision metric function.

Returns

Precision value.

Examples

dq$precision_using_moving_window(0.2, "RMS-S2S")

---

Method clone()

The objects of this class are cloneable with this method.

Usage

DataQuality$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

sc <- ScreenConfiguration$new(500, 300, 1920, 1080, 600)
gaze_x <- c(0, 1, -1)
gaze_y <- c(0, 1, -1)
timestamps <- c(0, 1, 2)
dq <- DataQuality$new(gaze_x, gaze_y, timestamps, unit = "pixels", screen = sc)
dq$accuracy(0, 0)
dq$precision_RMS_S2S()
dq$data_loss_from_invalid()


## ------------------------------------------------
## Method `DataQuality$new`
## ------------------------------------------------

dq <- DataQuality$new(gaze_x, gaze_y, timestamps, unit = "pixels", screen = sc)

## ------------------------------------------------
## Method `DataQuality$accuracy`
## ------------------------------------------------

dq$accuracy(0, 0)

## ------------------------------------------------
## Method `DataQuality$precision_RMS_S2S`
## ------------------------------------------------

dq$precision_RMS_S2S()

## ------------------------------------------------
## Method `DataQuality$precision_STD`
## ------------------------------------------------

dq$precision_STD()

## ------------------------------------------------
## Method `DataQuality$precision_BCEA`
## ------------------------------------------------

dq$precision_BCEA()

## ------------------------------------------------
## Method `DataQuality$data_loss_from_invalid`
## ------------------------------------------------

dq$data_loss_from_invalid()

## ------------------------------------------------
## Method `DataQuality$data_loss_from_expected`
## ------------------------------------------------

dq$data_loss_from_expected(500)

## ------------------------------------------------
## Method `DataQuality$effective_frequency`
## ------------------------------------------------

dq$effective_frequency()

## ------------------------------------------------
## Method `DataQuality$get_duration`
## ------------------------------------------------

dq$get_duration()

## ------------------------------------------------
## Method `DataQuality$precision_using_moving_window`
## ------------------------------------------------

dq$precision_using_moving_window(0.2, "RMS-S2S")

ETDQualitizer documentation built on Sept. 9, 2025, 5:40 p.m.