Package 'anispace'

Calculate angular difference

Description

Computes the shortest signed angular distance (in radians) from from_angle to to_angle.

Usage

calculate_angular_difference(from_angle, to_angle)

Arguments

from_angle	Numeric. Starting angle (radians).
to_angle	Numeric. Target angle (radians).

Value

Numeric scalar – the angular difference wrapped to [-π, π].

---

Cartesian azimuth (φ) from coordinates

Description

Returns the planar angle measured from the positive x‑axis toward the positive y‑axis. By default the result is mapped to [0, 2π); setting centered = TRUE leaves the native atan2 range [-π, π].

Usage

cartesian_to_phi(x, y, centered = FALSE)

Arguments

x	numeric vector of x‑coordinates
y	numeric vector of y‑coordinates
centered	logical; if TRUE keep the [-π, π] range, otherwise map to [0, 2π\)

Value

numeric vector of azimuth angles (φ) in radians

---

Cartesian radius (ρ) from coordinates

Description

Computes the Euclidean distance from the origin to a point in either 2‑D (z omitted) or 3‑D space.

Usage

cartesian_to_rho(x, y, z = NULL)

Arguments

x	numeric vector of x‑coordinates
y	numeric vector of y‑coordinates
z	optional numeric vector of z‑coordinates; if NULL a 2‑D radius is returned

Value

numeric vector of radii (ρ)

---

Polar angle (θ) from Cartesian coordinates

Description

Calculates the inclination angle measured from the positive z‑axis (the “polar” angle) for each point.

Usage

cartesian_to_theta(x, y, z)

Arguments

x	numeric vector of x‑coordinates
y	numeric vector of y‑coordinates
z	numeric vector of z‑coordinates

Value

numeric vector of polar angles (θ) in radians

---

Difference of angular values

Description

Computes lagged differences between successive angles (in radians) and converts each raw subtraction into the shortest signed angular distance using calculate_angular_difference(). The output mimics base::diff(), returning NAs for the first lag positions so it works nicely inside dplyr::mutate().

Usage

diff_angle(x, lag = 1L)

Arguments

x	Numeric vector of angles (radians).
lag	Positive integer indicating the lag (default = 1L). Must be an integer ≥ 1.

Value

Numeric vector of the same length as x. The first lag entries are NA; subsequent entries contain the angular differences.

Examples

# Simple example
angles <- c(0, pi/2, pi, 3*pi/2)
diff_angle(angles)

# Using a lag of 2
diff_angle(angles, lag = 2L)

---

Map from polar to Cartesian coordinates

Description

Map from polar to Cartesian coordinates

Usage

map_to_cartesian(data)

Arguments

data	an aniframe with polar coordinates

Value

an aniframe with Cartesian coordinates

---

Map from Cartesian to cylindrical coordinates

Description

Map from Cartesian to cylindrical coordinates

Usage

map_to_cylindrical(data)

Arguments

data	movement data frame with Cartesian coordinates

Value

movement data frame with cylindrical coordinates

---

Map from Cartesian to polar coordinates

Description

Map from Cartesian to polar coordinates

Usage

map_to_polar(data)

Arguments

data	movement data frame with Cartesian coordinates

Value

movement data frame with polar coordinates

---

Map from Cartesian to spherical coordinates

Description

Map from Cartesian to spherical coordinates

Usage

map_to_spherical(data)

Arguments

data	A data frame/tibble containing columns x, y, z

Value

Same data frame with columns rho, theta, phi

---

Convert polar radius to Cartesian x‑coordinate

Description

Convert polar radius to Cartesian x‑coordinate

Usage

polar_to_x(rho, phi)

Arguments

rho	numeric vector of radial distances
phi	numeric vector of azimuth angles (radians)

Value

numeric vector of x‑coordinates

---

Convert polar radius to Cartesian y‑coordinate

Description

Convert polar radius to Cartesian y‑coordinate

Usage

polar_to_y(rho, phi)

Arguments

rho	numeric vector of radial distances
phi	numeric vector of azimuth angles (radians)

Value

numeric vector of y‑coordinates

---

Rotate coordinates in Cartesian space (2D or 3D)

Description

Automatically detects whether data are 2D or 3D and applies the corresponding rotation method.

Usage

rotate_coords(data, alignment_points, align_perpendicular = FALSE)

Arguments

data	movement data frame with columns: time, individual, keypoint, x, y, z (optional)
alignment_points	character vector of length 2 specifying the keypoints used for alignment
align_perpendicular	logical; if TRUE, alignment_points are rotated to be perpendicular to the 0-degree axis (y-axis). If FALSE (default), they are aligned with the x-axis.

Value

movement data frame with rotated coordinates

---

Convert cylindrical radius and polar angle to Cartesian z‑coordinate

Description

Handles regular points as well as the two pole regions (θ≈0 and θ≈π). Non‑finite inputs remain NA.

Usage

spherical_to_z(rho, theta)

Arguments

rho	Numeric vector – cylindrical radius (√(x² + y²)).
theta	Numeric vector – polar angle measured from the +z axis (radians).

Value

Numeric vector of z‑coordinates (same length as input)

---

Transform coordinates to egocentric reference frame

Description

Transforms Cartesian coordinates into an egocentric reference frame through a two-step process: translation followed by rotation. First translates all coordinates relative to a reference keypoint, then rotates the coordinate system based on specified alignment points.

Usage

transform_to_egocentric(
  data,
  to_keypoint,
  alignment_points,
  align_perpendicular = FALSE
)

Arguments

data	movement data frame with columns: time, individual, keypoint, x, y
to_keypoint	character; keypoint to use as the new origin
alignment_points	character vector of length 2 specifying the keypoint names to use for alignment
align_perpendicular	logical; if TRUE, alignment_points will be rotated to be perpendicular to the 0-degree axis. If FALSE (default), alignment_points will be rotated to align with the 0-degree axis

Details

This function combines translation and rotation to create an egocentric reference frame. It:

1. Translates all coordinates relative to the specified keypoint (to_keypoint)

2. Rotates the coordinate system based on the alignment points

The translation makes the reference keypoint the new origin (0,0), while the rotation standardizes the orientation. This is particularly useful for:

• Creating egocentric reference frames

• Standardizing pose data across frames or individuals

• Analyzing relative motion patterns

Value

movement data frame in egocentric reference frame

Examples

## Not run: 
# Transform coordinates to make nose the origin and align body axis
transformed_data <- transform_to_egocentric(
  data,
  to_keypoint = "nose",
  alignment_points = c("nose", "tail"),
  align_perpendicular = FALSE
)

# Transform to make nose origin and ears perpendicular to forward axis
transformed_data <- transform_to_egocentric(
  data,
  to_keypoint = "nose",
  alignment_points = c("ear_left", "ear_right"),
  align_perpendicular = TRUE
)

## End(Not run)

---

Translate coordinates (Cartesian)

Description

Translates coordinates in Cartesian space. Takes either a single point (to_x and to_y), a vector with the same length as the time dimension or a keypoint (to_keypoint), which can be used to transform the data into an egocentric reference frame.

Usage

translate_coords(data, to_x = 0, to_y = 0, to_z = NULL, to_keypoint = NULL)

Arguments

data	movement data frame with columns: time, individual, keypoint, x, y
to_x	x coordinates; either a single value or a time-length vector
to_y	y coordinates; either a single value or a time-length vector
to_z	z coordinates (only if 3D); either a single value or a time-length vector
to_keypoint	all other coordinates becomes relative to this keypoint

Value

movement data frame with translated coordinates

---

Remove constrain for angles to keep within [0, 2π)

Description

Unwraps any numeric vector from the interval [0, 2π).

Usage

unwrap_angle(x)

Arguments

x	Numeric vector of angles (radians).

Value

Numeric vector of the same length.

---

Constrain angles to a standard range

Description

Wraps any numeric vector of angles (in radians) to a standard interval using modulo arithmetic.

Usage

wrap_angle(x, modulo = c("2pi", "pi", "asis"))

Arguments

x	Numeric vector of angles (radians).
modulo	Character string specifying the target range: "2pi" Wrap to [0, 2π) (default) "pi" Wrap to (-π, π] "asis" No wrapping, return unchanged

Value

Numeric vector of the same length as x, with angles wrapped to the specified range.

Examples

angles <- c(-pi, 0, pi, 2 * pi, 3 * pi)

# Wrap to [0, 2π)
wrap_angle(angles, "2pi")

# Wrap to (-π, π]
wrap_angle(angles, "pi")

# No wrapping
wrap_angle(angles, "asis")

---