Wraps a vector of angles to a standard interval using modulo arithmetic.
By default that is the signed range (-pi, pi], which the suite uses for
every direction; see the section below.
Usage
wrap_angle(x, modulo = c("pi", "2pi", "asis"))The range of a direction
Directions throughout the animovement suite are signed, in (-pi, pi]
((-180, 180] in degrees). It is the range atan2() returns, so per-row
directions such as a course or a heading come out in it already, and the
circular summaries circ_mean() and circ_median() return it too, so a
summary can be compared with the values it summarises. 0 points along
x, and the sign says which side of x a direction lies on: positive
toward y, negative away from it. Which way that turns on screen is the
frame's angle direction, get_angle_direction().
The range does not change what a direction means: -pi / 2 and
3 * pi / 2 are the same direction, and every circ_*() function treats
them alike. To report directions in [0, 2*pi) instead, wrap at the end
with wrap_angle(x, "2pi"). Differences (circ_difference()) are signed
in (-pi, pi] as well, while unwrapped and cumulative angles
(unwrap_angle()) are not confined to any range. The
orientation article
covers the convention alongside the frame's axis directions.
See also
Other angle utilities:
angle_to_rad(),
deg_to_rad(),
rad_to_deg(),
unwrap_angle()
Examples
angles <- c(-pi, 0, pi, 3 * pi / 2, 2 * pi, 3 * pi)
# The signed range, which directions use throughout the suite
wrap_angle(angles)
#> [1] 3.141593 0.000000 3.141593 -1.570796 0.000000 3.141593
# The same angles on [0, 2*pi)
wrap_angle(angles, "2pi")
#> [1] 3.141593 0.000000 3.141593 4.712389 0.000000 3.141593
# "asis" is a no-op, useful when the range is chosen by a caller
wrap_angle(angles, "asis")
#> [1] -3.141593 0.000000 3.141593 4.712389 6.283185 9.424778