mt_angles {mousetrap} | R Documentation |
Calculate movement angles.
Description
Calculate point-based and vertical-based angles for the points in the movement trajectory. Point-based angles are the angle defined by three subsequent points on the trajectory. Vertical-based angles are the angles between two subsequent points and the vertical axis.
Usage
mt_angles(
data,
use = "trajectories",
dimensions = c("xpos", "ypos"),
save_as = use,
na_replace = FALSE,
unit = "radian",
verbose = FALSE
)
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 |
a character string specifying which trajectory data should be used. |
dimensions |
a character string specifying which trajectory variables should be used. Must be of length 2. |
save_as |
a character string specifying where the resulting trajectory data should be stored. |
na_replace |
logical specifying whether |
unit |
character specifying the unit for the angles. Default is "radian", alternative is "degree". |
verbose |
logical indicating whether function should report its progress. |
Details
By default, angles are reported in radians, the alternative is degrees. For
the first point in a trajectory, the angle values are always not defined
(NA
).
For vertical-based angles (angle_v
), positive values indicate a
movement to the left of the vertical, negative values to the right of the
vertical. If there was no movement across two consecutive points,
angle_v
is not defined and, by default, NA
is returned. If
na_replace
is TRUE
, the next existing angle value is reported
instead.
For point-based angles (angle_p
), angles indicate changes of movement
within three consecutive time steps. The reported angle is always the smaller
one. A value of pi (= 3.14...) (for radians) or 180 (for degrees) indicates a
constant movement direction, a value of 0 (both for radians and degrees) a
complete reversal. If there was no movement across two consecutive points,
angle_p
is not defined and, by default, NA
is returned. If
na_replace
is TRUE
, the next existing angle value is reported
instead. angle_p
is also not defined for the last point of the
trajectory.
Value
A mousetrap data object (see mt_example) with point-based and
vertical-based angles added as additional variables to the trajectory array
(called angle_p
and angle_v
). If a trajectory array was
provided directly as data
, only the trajectory array will be
returned.
Author(s)
Dirk U. Wulff
Examples
# Calculate movement angles
mt_example <- mt_angles(mt_example)
# Calculate movement angles (in degree)
# and replace NAs with next existing value
mt_example <- mt_angles(mt_example,
unit="degree", na_replace=TRUE)