mousetrap (version 2.0.0)

mt_time_normalize: Time normalize trajectories.

Description

Compute time-normalized trajectories using a constant number of equally sized time steps. Time normalization is performed separately for all specified trajectory dimensions (by default, the x- and y-positions) using linear interpolation based on the timestamps. By default, 101 time steps are used (following Spivey et al., 2005).

Usage

mt_time_normalize(data, use = "trajectories", save_as = "tn_trajectories", dimensions = c("xpos", "ypos"), timestamps = "timestamps", nsteps = 101, verbose = FALSE, show_progress = NULL)

Arguments

data

a mousetrap data object created using one of the mt_import functions (see mt_example for details). Alternatively, a trajectory array can be provided directly (in this case use will be ignored).

use

a character string specifying which trajectory data should be used.

save_as

a character string specifying where the resulting trajectory data should be stored.

dimensions

a character vector specifying the dimensions in the trajectory array that should be time-normalized. If "all", all trajectory dimensions except the timestamps will be time-normalized.

timestamps

a character string specifying the trajectory dimension containing the timestamps.

nsteps

an integer specifying the number of equally sized time steps.

verbose

logical indicating whether function should report its progress.

show_progress

Deprecated. Please use verbose instead.

Value

A mousetrap data object (see mt_example) with an additional array (by default called tn_trajectories) containing the time-normalized trajectories. In this array, another dimension (called steps) has been added with increasing integer values indexing the time-normalized position. If a trajectory array was provided directly as data, only the time-normalized trajectories will be returned.

Details

Time-normalization is often performed if the number of recorded x- and y-positions varies across trajectories, which typically occurs when trajectories vary in their response time. After time-normalization, all trajectories have the same number of recorded positions (which is specified using nsteps) and the positions at different relative time points can be compared across trajectories.

For example, time normalized trajectories can be compared across conditions that differed in their overall response time, as the timestamps are now relative to the overall trial duration. This is also helpful for creating average trajectories, which are often used in plots.

References

Spivey, M. J., Grosjean, M., & Knoblich, G. (2005). Continuous attraction toward phonological competitors. Proceedings of the National Academy of Sciences of the United States of America, 102(29), 10393-10398.

See Also

approx for information about the function used for linear interpolation.

mt_resample for resampling trajectories using a constant time interval.

Examples

mt_example <- mt_time_normalize(mt_example,
  save_as="tn_trajectories", nsteps=101)