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", prefix = "", 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). 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.

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 can be used.

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

show_progress

logical indicating whether function should report on its progress.

Value

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

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.

Examples

Run this code

# 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")