itrak: Tools for processing eye-tracking data

Description Usage Arguments Value Examples

tsAB is for time series containing a mixture of two trial types, as would arise from a within-individual A/B experiment (for example, responses over time to images that are either happy or sad). It is typically used on data grouped by individual time series, created by group_by. The output will have one row per time series.

1	tsAB(data, type, value, pos_thresh = 0, neg_thresh = 0)

`data`	A data frame of at least two columns: one indicating the trial `type`, which must be dichotomous (e.g., A/B), and one giving the response `value`. Rows must be ordered by trial sequence. The data frame may contain multiple time series, but in this case a `grouped_df` must be created by calling the `group_by` method on the variable or variables (usually the participant ID) nesting the individual time series.
`type`	Name of the column in `data` giving the trial type. Must be passed as a string (inside quotation marks).
`value`	Name of the column in `data` giving the observed value for each trial. Must be passed as a string (inside quotation marks).
`pos_thresh`	a `value` greater than this threshold will be counted as a positive response. Default is `0`.
`neg_thresh`	a `value` smaller than this threshold will be counted as a negative response. Default is `0`.

An object of the same class as data reducing each time series to the following summary metrics. Note "A" and "B" will be replaced by the labels given by the type column.

trials_total_A: Total number of trials detected of type A. Useful as a validity check.
trials_total_B: Total number of trials detected of type B. Useful as a validity check.
trials_missed_A: Number of trials of type A with missing data.
trials_missed_B: Number of trials of type B with missing data.
mean_A: Mean of all non-neutral trials of type A.
mean_B: Mean of all non-neutral trials of type B.
sd_A: Standard deviation of all non-neutral trials of type A.
sd_B: Standard deviation of all non-neutral trials of type B.
pos_response_to_A: Count of positive type-A trials above threshold set by pos_thresh.
pos_response_to_B: Count of positive type-B trials above threshold set by pos_thresh.
neg_response_to_A: Count of negative type-A trials below threshold set by neg_thresh.
neg_response_to_B: Count of negative type-B trials below threshold set by neg_thresh.
neu_response_to_A: Count of neutral type-A trials between thresholds set by neg_thresh and pos_thresh.
neu_response_to_B: Count of neutral type-B trials between thresholds set by neg_thresh and pos_thresh.
mean_A_after_A: Mean of all non-neutral trials of type A that follow another trial of type A.
mean_B_after_B: Mean of all non-neutral trials of type B that follow another trial of type B.
mean_A_after_B: Mean of all non-neutral trials of type A that immediately follow a trial of type B.
mean_B_after_A: Mean of all non-neutral trials of type B that immediately follow a trial of type A.
diff_A_from_B: Mean difference of all non-neutral trials of type A from an immediately preceding trial of type B.
diff_B_from_A: Mean difference of all non-neutral trials of type B from an immediately preceding trial of type A.
drift_over_A: Mean linear slope over consecutive trials of type A.
drift_over_B: Mean linear slope over consecutive trials of type B.

# Create example data frame containing 10 time series of 100 reaction times
# from a dot-probe experiment with trial types (`valence`) of "happy" vs.
# "sad".
data <- data.frame(id = rep(1:10, each = 100),
                   trial = rep(1:100, 10),
                   valence = rep(sample(c("happy", "sad"), 1000,
                                 replace = TRUE)),
                   rt = sample(100:1000, 1000, replace = TRUE),
                   congru = sample(c(TRUE,FALSE), 1000, replace = TRUE))

# Compute a trial-level bias score for each individual (`group_by(id)`) using
# reaction time (`rt`) and logical vectors indicating whether or not the dot
# probe was congruent with the target stimulus (`congru`).
data <- data %>% group_by(id) %>% mutate(tlbs = get_tlbs(rt, congru)) %>%
  ungroup()

# Obtain A/B summary features for each individual time series
ts_summary <- data %>%
  group_by(id) %>%
  tsAB(type = "valence", value = "tlbs")