mousetrap (version 1.0.0)

mt_calculate_derivatives: Calculate distance, velocity, and acceleration.

Description

Calculate distance traveled, velocity, and acceleration for each logged position. Distance is calculated as the Euclidean distance between successive coordinates, and velocity as distance covered per time interval. The acceleration denotes the difference in velocity, again normalized per time.

Usage

mt_calculate_derivatives(data, use = "trajectories", save_as = use,
  dimension = "xypos", acc_on_abs_vel = FALSE, show_progress = TRUE)

Arguments

data

a mousetrap data object created using one of the mt_import functions (see mt_example for details).

use

a character string specifying which trajectory data should be used (defaults to 'trajectories')

save_as

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

dimension

a character string specifying across which dimension(s) distances, velocity, and acceleration are calculated. By default ("xypos"), they are calculated across both x and y dimensions. Alternatively, only the x- ("xpos") or the y- ("ypos") dimension ca

acc_on_abs_vel

logical indicating if acceleration should be calculated based on absolute velocity values (ignoring direction). Only relevant if velocity can be negative (see Details).

show_progress

logical indicating whether function should report its progress.

Value

• A mousetrap data object (see mt_example) with Euclidian distance, velocity, and acceleration added as additional columns to the trajectory array.

Details

Distances, velocities and acceleration are computed as follows: The first entry in each respective vector is always zero. Each subsequent entry thus represents the Euclidean distance traveled since the previous recorded set of coordinates and the velocity with which the movement between both samples took place. Thus, both distance and velocity represent the intervening period between the previous sample and the one with which the numeric value is saved. The acceleration, by contrast, denotes the change in velocity between two adjacent periods. Because of this, it is shifted forward to best match the actual time point at which the acceleration was measured. Because there will always be one less value computed for acceleration than for velocity, the final value in the acceleration vector has been padded with an NA. To reconstruct the velocity from the acceleration, multiply the acceleration vector with the sampling interval, compute the cumulative sum of the result, and add a zero at the beginning. If the distance is calculated across both horizontal and vertical (x and y) dimensions, velocity is always positive (or 0). If only one dimension is used, increases in x (or y) values result in positive velocity, decreases in negative velocity.

See Also

mt_average for averaging trajectories across constant time intervals. mt_calculate_measures for calculating per-trial mouse-tracking measures.

Examples

# Calculate derivatives looking at movement
# across both dimensions
mt_example <- mt_calculate_derivatives(mt_example)

# Calculate derivatives ony looking at movement
# in x dimension
mt_example <- mt_calculate_derivatives(mt_example,
  dimension="xpos")