mousetrap (version 3.2.3)

mt_angles: 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
)

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.

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.

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 NAs in the angle values should be replaced using the next existing angle value (see Details). Defaults to FALSE.

unit

character specifying the unit for the angles. Default is "radian", alternative is "degree".

verbose

logical indicating whether function should report its progress.

Author

Dirk U. Wulff

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.

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)