time_lock_stats {forceplate}

Calculate Statistics for Time Locked Bins

Description

Processing segmented force-plate data by calculating descriptive statistics like mean, standard deviation, and range for defined time bins around time-locked events, such as stimulus onset or response onset etc.

Usage

time_lock_stats(
  fp.dt,
  vars,
  time.lock.trigger,
  bins,
  bin.width = NULL,
  n.bins = NULL,
  FUN = list(mean = mean, sd = sd, range = function(x) diff(range(x)))
)

Arguments

fp.dt

A data.table of the class "fp.segm" produced by segment_fp_data().

vars

A (vector of) character(s) giving the variable names in fp.dt$forceplate, for which the statistics (see FUN below) should be calculated for each bin (see arguments below). For example Fx, Fy, Mx, My etc.

time.lock.trigger

A (vector of) number(s) containing the trigger(s) marking the onset of the time locking (the event of interest like stimulus onset or response onset). The onset of this trigger will be treated as reference (point zero) for the bins to be defined in the next argument(s).

bins

Either a vector of length 2 or a list of vectors of length 2 providing the lower and upper boundaries of the bins (in milliseconds). If only one vector is used either one of the next two arguments can be used to make (equaly sized) bins. If a list is used the next two arguments are ignored.

bin.width

If bins is a vector of 2 then this argument can be used to divide the bin into smaller bins of the size bin.width in milliseconds.

n.bins

If bins is a vector of 2 then this argument can be used to divide the bin into n.bins number of bins of equal size. If bin.width is provided as well, n.bins will be ignored.

FUN

A list of functions. These functions should be statistics that take as input a vector and return a scalar. See usage for an example (mean, standard deviation, range).

Value

A data.table of the class fp.tl. The following variables are included in the data.table:

• subj: subject number,

• block: block number,

• trial: trial number,

• forceplate: force-plate data of each trial as data.table. Use, for example, fp.dt$forceplate[[1]] to open the force-plate data of the first trial, first block, and first subject (if sort in the segment_fp_data was set to TRUE.

• For each combination of variable vars and bin a new variable is created by the function(s) provided by FUN.

Author(s)

Raphael Hartmann & Anton Koger

References

Johannsen, L., Stephan, D. N., Straub, E., Döhring, F., Kiesel, A., Koch, I., & Müller, H. (2023). Assessing the influence of cognitive response conflict on balance control: An event-related approach using response-aligned force-plate time series data. Psychological Research, 87, 2297–2315.

Examples

# Using example data from github which requires internet
 # takes longer than 5 seconds
if (curl::has_internet()) {
  url <- paste0("https://raw.githubusercontent.com/RaphaelHartmann/forceplate/",
                "main/data/subj013_block001.txt")
  
  # Safe download, handling potential errors
  tryCatch({
    filenames <- tempfile(pattern = c("subj013_block001_"), 
                          tmpdir = tempdir(), fileext = ".txt")
    download.file(url, filenames)
    fp.dt <- segment_fp_data(filenames = filenames, n.trials = 80, baseline.trigger = 128,
                             baseline.intv = c(0, 215), start.trigger = 128, start.prepend = 0,
                             stimulus.trigger.list = c(1, 2, 4, 8),
                             response.trigger.list = c(32, 64),
                             cond.trigger.list = list(stimulus = c(1, 2, 4, 8), 
                                                      correctness = c(32, 64)))
    
    # Response-locking with 2 bins before and 2 bins after response onset. Each bin is 100 ms.
    tl.dt <- time_lock_stats(fp.dt = fp.dt, vars = c("Mx", "My"), 
                             time.lock.trigger = c(1,2,4,8), bins = c(-150, 150), n.bins = 2, 
                             FUN = list(mean = mean, sd = sd, range = function(x) diff(range(x))))
    
    # Clean up
    unlink(filenames)
  }, error = function(e) {
    message("Failed to download data: ", e$message)
  })
}