Truncate times to fit bin width

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))
#> # A tibble: 18 × 6
#> # Groups:   id, .bin [6]
#>    task    id     time frame  .bin center_time
#>    <chr>   <chr> <int> <int> <int>       <int>
#>  1 testing test1    -4     1     1          -3
#>  2 testing test1    -3     2     1          -3
#>  3 testing test1    -2     3     1          -3
#>  4 testing test1    -1     4     2           0
#>  5 testing test1     0     5     2           0
#>  6 testing test1     1     6     2           0
#>  7 testing test1     2     7     3           3
#>  8 testing test1     3     8     3           3
#>  9 testing test1     4     9     3           3
#> 10 testing test2    -4     2     1          -3
#> 11 testing test2    -3     3     1          -3
#> 12 testing test2    -2     4     1          -3
#> 13 testing test2    -1     5     2           0
#> 14 testing test2     0     6     2           0
#> 15 testing test2     1     7     2           0
#> 16 testing test2     2     8     3           3
#> 17 testing test2     3     9     3           3
#> 18 testing test2     4    10     3           3

# 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)
#> # A tibble: 12 × 5
#>    task    id     time frame  .bin
#>    <chr>   <chr> <int> <int> <int>
#>  1 testing test1    -1     4     1
#>  2 testing test1     0     5     1
#>  3 testing test1     1     6     1
#>  4 testing test1     2     7     2
#>  5 testing test1     3     8     2
#>  6 testing test1     4     9     2
#>  7 testing test2    -1     5     1
#>  8 testing test2     0     6     1
#>  9 testing test2     1     7     1
#> 10 testing test2     2     8     2
#> 11 testing test2     3     9     2
#> 12 testing test2     4    10     2

# 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)
#> # A tibble: 12 × 5
#>    task    id     time frame  .bin
#>    <chr>   <chr> <int> <int> <int>
#>  1 testing test1    -1     4     1
#>  2 testing test1     0     5     1
#>  3 testing test1     1     6     1
#>  4 testing test1     2     7     2
#>  5 testing test1     3     8     2
#>  6 testing test1     4     9     2
#>  7 testing test2    -1     5     1
#>  8 testing test2     0     6     1
#>  9 testing test2     1     7     1
#> 10 testing test2     2     8     2
#> 11 testing test2     3     9     2
#> 12 testing test2     4    10     2