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 absolute velocity, again normalized per time.
mt_derivatives(
data,
use = "trajectories",
save_as = use,
dimensions = c("xpos", "ypos"),
timestamps = "timestamps",
prefix = "",
absolute = FALSE,
return_delta_time = FALSE,
verbose = FALSE
)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).
a character string specifying which trajectory data should be used.
a character string specifying where the resulting trajectory data should be stored.
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 dimension can be specified, e.g.,
"xpos" or "ypos".
a character string specifying the trajectory dimension containing the timestamps.
an optional character string that is added as a prefix to the to be created new trajectory dimensions.
logical indicating if absolute values for distances and
velocities should be reported. Only relevant if a single dimension is
specified in dimensions (see Details).
logical indicating if the timestamp differences should be returned as well (as "delta_time").
logical indicating whether function should report its progress.
A mousetrap data object (see mt_example) with Euclidian
distance, velocity, and acceleration added as additional variables 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.
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 absolute 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.
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, by default (absolute=FALSE), increases in x (or y)
values result in positive distances and velocity values, decreases in
negative distances and velocity values. If absolute=TRUE, absolute
values for distance and velocity are reported.
mt_average for averaging trajectories across constant time intervals.
mt_measures for calculating per-trial mouse-tracking measures.
# Calculate derivatives looking at movement
# across both dimensions
mt_example <- mt_derivatives(mt_example)
# Calculate derivatives only looking at movement along x dimension
# reporting absolute values for distance and velocity
mt_example <- mt_derivatives(mt_example,
dimensions="xpos", absolute=TRUE)