trim_to_bin_width: Truncate times to fit bin width

In tjmahr/littlelisteners: Helper Functions for Hand-coded Eyetracking Data

Truncate times to fit bin width

Description

Samples of eyetracking data are excluded so that the number of frames is evenly divisible by a given bin width. For example, given a bin width of 3 frames, a trial with 181 frames would lose 1 frame. The frames aligned so that a key time value have a specific position in a bin. For example, setting time 0 to position 1 will truncate the times so that time 0 will be the first frame inside of its bin.

Usage

trim_to_bin_width(
  data,
  bin_width = 3,
  key_time = NULL,
  key_position = 1,
  time_var,
  ...,
  min_time = NULL,
  max_time = NULL
)

Arguments

data	a dataframe of looking data
bin_width	the number of items to put in each bin. Default is 3.
key_time, key_position	arguments controlling the trimming. The given time value (key_time) will have a specific position within a bin (key_position). For example, given a value of 0 and position of 2, the trimming will force the frame with time 0 to fall in the second frame of its bin.
time_var	the name of the column representing time
...	grouping variables
min_time, max_time	optional arguments controlling the trimming. If used, the time values are filtered to exclude whole bins of frames before min_time and after max_time.

Value

the original dataframe with its time column trimmed to make it easier to bin time values into groups of bin_width.

Examples

data1 <- tibble::tibble(
  task = "testing",
  id = "test1",
  time = -4:6,
  frame = seq_along(time)
)

data2 <- tibble::tibble(
  task = "testing",
  id = "test2",
  time = -5:5,
  frame = seq_along(time)
)

# Number of rows per id is divisible by bin width
# and time 0 is center of its bin
dplyr::bind_rows(data1, data2) |>
  trim_to_bin_width(3, key_time = 0, key_position = 2, time, id) |>
  assign_bins(3, time, id) |>
  dplyr::group_by(id, .bin) |>
  dplyr::mutate(center_time = median(time))

# And exclude times in bins before some minimum time
dplyr::bind_rows(data1, data2) |>
  trim_to_bin_width(
    bin_width = 3,
    key_time = 0,
    key_position = 2,
    time,
    id,
    min_time = -1
) |>
  assign_bins(3, time, id)

# And exclude times in bins after some maximum time
dplyr::bind_rows(data1, data2) |>
  trim_to_bin_width(
    bin_width = 3,
    key_time = 0,
    key_position = 2,
    time, id,
    min_time = -1,
    max_time = 4
  ) |>
  assign_bins(3, time, id)

tjmahr/littlelisteners documentation built on July 31, 2024, 6:02 a.m.