summarize_bias: Summary of attention bias metrics
In jashu/itrak: Tools for processing eye-tracking data

Description Usage Arguments Value Departures from Zvielli et al. IMPORTANT SUPER IMPORTANT References See Also Examples

summarize_bias combines the get_bs and get_tlbs functions to generate a traditional attention bias metric as well as summary metrics of trial-level attention bias as described by Zvielli et al. (2015).

summarize_bias(
  data,
  RT,
  congruent,
  prior_weights,
  method = "weighted",
  search_limit = 5,
  fill_gaps = FALSE
)

`data`	A data frame or table.
`RT`	The name of the column in `data` that contains chronologically ordered observations of numeric type.
`congruent`	The name of the column in `data` that contains logical indicators of whether the corresponding entry of `RT` is a congruent (`TRUE`) or incongruent (`FALSE`) trial, i.e., whether the probe location matches the location of the stimulus expected to elicit attention bias.
`prior_weights`	Optional name of column in `data` that contains prior weights indicating the relative influence that each trial should have on the calculation of TLBS and summary metrics. If not provided, all trials are assumed to carry equal weight.
`method`	String indicating method to be used to calculate TLBS. The default method "`weighted`" compares each trial to the distance-weighted mean of all trials of opposite type. If `method = "nearest"`, the method described by Zvielli et al. (2015) is implemented, and each trial is compared to the single nearest trial of opposite type. See `get_tlbs` for details.
`search_limit`	If using `method = "nearest"`, an integer indicating how many trials to look forward or backward to find a trial of opposite type. Default value is 5. If no match is found within the `search_limit` of a trial, `NA` will be returned for that trial.
`fill_gaps`	Logical indicating whether missing values in the TLBS time series should be imputed based on neighboring trials. Default is `FALSE`.

An object of the same class as data with the following summary metrics:

mean_bias: Traditional bias score obtained by taking the mean of congruent trials and subtracting it from the mean of incongruent trials.
mean_toward: Mean bias toward the target stimulus obtained by calculating the mean of the positive trial-level bias scores.
mean_away: Mean bias away from the target stimulus obtained by calculating the absolute value of the mean of the negative trial-level bias scores.
peak_toward: Maximum bias toward the target stimulus obtained by calculating the maximum trial-level bias score.
peak_away: Maximum bias away from the target stimulus obtained by calculating the absolute value of the minimum (most negative) trial-level bias score.
variability: Variability in bias obtained by calculating the mean of the absolute value of the lag-1 differences in trial-level bias scores.
trials_toward: Number of trials during which bias was directed toward the target.
trials_away: Number of trials during which bias was directed away from the target.
trials_NA: Number of trials for which a trial-level bias score could not be computed, i.e., trial data is missing or a trial of opposite type could not be found within the search_limit
trials_total: Total number of trials detected. Useful as a validity check.

The names of the trial-level bias score (TL-BS) parameters and the methods for calculating them adhere closely to those used and described by Zvielli et al. (2015). There are two exceptions.

Zvielli et al.'s Mean TL-BS POSITIVE and Peak TL-BS POSITIVE are labeled here as mean_toward and peak_toward, respectively. In their discussion of these parameters, Zvielli et al. also refer to them as "the toward parameters." This terminology is favored because it is more descriptive and disambiguates the direction of attention from the target of attention. (For example, "bias toward negative stimuli" is clearer than "positive bias for negative stimuli.") For the same reason, Zvielli et al.'s Mean TL-BS NEGATIVE and Peak TL-BS NEGATIVE are labeled here as mean_away and peak_away, respectively.
Calculation of the TL-BS parameters is implemented precisely as described by Zvielli et al. with one minor modification: after taking the mean and min of the negative trial-level bias scores to obtain the mean_away and peak_away parameters, respectively, the results are multiplied by -1 to remove the negative sign. The rationale for this modification is as follows. First, leaving the negative sign in place is redundant since the direction of the bias is given by the name of the parameter. Second, and more problematic, scales that only have a negative vector (i.e., increasing effects are represented by decreasing numbers) are prone to misinterpretation. This is because statistical models will not know that increasing attention bias is scaled in a negative direction–increases are always defined as moving to the right on the x axis, i.e., becoming more positive–so one must remember that an increase on the bias-away scale is actually a decrease in attention bias in order to interpret results correctly. For example, if one finds a positive correlation between bias-away and some other (positively scaled) variable, then one must perform the mental gymnastics of a) realizing that a positive correlation means that an increase on the bias-away scale (becoming less negative) is associated with an increase in the other variable and b) recalling that an increase on the bias-away scale actually reflects a decrease in attention bias before c) coming to the correct, but counterintuitive conclusion, that a positive correlation in this case reflects a negative relationship. Converting mean_away and peak_away to a positive scale spares the user from this future headache.

Before calling this function, ensure that the data being passed have been grouped into sets of trials, with each set containing a single series of measurements belonging to a single individual. group_by is recommended for this purpose. If you receive an output that has less or more rows of observations than you were expecting, incorrect grouping is likely to blame.

You must also ensure that each set of trials is in chronological order. Otherwise, the trial-level bias calculation will be wrong, and there will be no obvious sign that this has happened. To ensure proper grouping and ordering, it is recommended that prior to calling this function you sort your data using arrange(data, g1, ..., trial) where g1 is your primary grouping variable (most likely 'subject' or 'id') followed by any secondary grouping variables (e.g., 'session', 'category') and ending with the variable that gives the trial number. This should then be piped to group_by(g1, ...), where g1, ... corresponds precisely to the same grouping variables used in the call to arrange. (Do NOT include trial in the call to group_by.) The result is then ready to be piped to the summarize_bias function.

Zvielli A, Bernstein A, Koster EHW. 2015. Temporal dynamics of attentional bias. Clinical Psychological Science. 3(5):772-788.

get_bs, get_tlbs, mutate, summarize

# Create example data frame containing 10 time series of 10 reaction times
# and trial types of congruent ('con') vs. incongruent ('incon'):
data <- data.frame(id = rep(1:10, each = 10),
                   rt = sample(100:1000, 10),
                   congru = sample(c(TRUE,FALSE), 100, replace = TRUE),
                   trial = rep(1:10, 10))

# Use dplyr to sort by trial and group by id and then generate bias summary:
library(dplyr)
data %>%
arrange(id, trial) %>%
group_by(id) %>%
summarize_bias(RT = rt, congruent = congru)