mousetrap (version 2.0.0)

mt_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_derivatives(data, use = "trajectories", save_as = use, dimensions = c("xpos", "ypos"), timestamps = "timestamps", prefix = "", acc_on_abs_vel = FALSE, verbose = FALSE, show_progress = NULL, dimension = NULL)
mt_calculate_derivatives(data, use = "trajectories", save_as = use, dimensions = c("xpos", "ypos"), timestamps = "timestamps", prefix = "", acc_on_abs_vel = FALSE, verbose = FALSE, show_progress = NULL, dimension = 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 across which dimension(s) distances, velocity, and acceleration are calculated. By default (c("xpos","ypos")), they are calculated across both x and y dimensions. Alternatively, only one dimesion can be specified, e.g., "xpos" or "ypos".

timestamps

a character string specifying the trajectory dimension containing the timestamps.

prefix

an optional character string that is added as a prefix to the to be created new trajectory dimensions.

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).

verbose

logical indicating whether function should report its progress.

show_progress

Deprecated. Please use verbose instead.

dimension

Deprecated. Please use dimensions instead.

Value

A mousetrap data object (see mt_example) with Euclidian distance, velocity, and acceleration added as additional columns to the trajectory array (called dist, vel, and acc, if no prefix was specified). If the trajectory array was provided directly as data, only the trajectory array will be returned.

Functions

• mt_derivatives: Calculate distance, velocity, and acceleration
• mt_calculate_derivatives: Deprecated

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, distance and velocity is always positive (or 0). If only one dimension is used, increases in x (or y) values result in positive distances and velocity values, decreases in negative distances and velocity values.

See Also

mt_average for averaging trajectories across constant time intervals.

mt_measures for calculating per-trial mouse-tracking measures.

Examples

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

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