rearrr (version 0.3.4)

distance: Calculate the distance to an origin

Description

lifecycle::badge("experimental")

Calculates the distance to the specified origin with: $$d(P1, P2) = sqrt( (x2 - x1)^2 + (y2 - y1)^2 + (z2 - z1)^2 + ... )$$

The origin can be supplied as coordinates or as a function that returns coordinates. The latter can be useful when supplying a grouped data.frame and finding the distance to e.g. the centroid of each group.

Usage

distance(
  data,
  cols = NULL,
  origin = NULL,
  origin_fn = NULL,
  distance_col_name = ".distance",
  origin_col_name = ".origin",
  overwrite = FALSE
)

Value

data.frame (tibble) with the additional columns (distances and origin coordinates).

Arguments

data

data.frame or vector.

cols

Names of columns in `data` to measure distance in. Each column is considered a dimension.

origin

Coordinates of the origin to calculate distances to. A scalar to use in all dimensions or a vector with one scalar per dimension.

N.B. Ignored when `origin_fn` is not NULL.

origin_fn

Function for finding the origin coordinates.

Input: Each column will be passed as a vector in the order of `cols`.

Output: A vector with one scalar per dimension.

Can be created with create_origin_fn() if you want to apply the same function to each dimension.

E.g. `create_origin_fn(median)` would find the median of each column.

Built-in functions are centroid(), most_centered(), and midrange()

distance_col_name

Name of new column with the distances.

origin_col_name

Name of new column with the origin coordinates. If NULL, no column is added.

overwrite

Whether to allow overwriting of existing columns. (Logical)

Author

Ludvig Renbo Olsen,

See Also

Other measuring functions: angle(), vector_length()

Other distance functions: closest_to(), dim_values(), expand_distances(), expand_distances_each(), furthest_from(), swirl_2d(), swirl_3d()

Examples

# Attach packages
library(rearrr)
library(dplyr)

# Set seed
set.seed(1)

# Create a data frame
df <- data.frame(
  "x" = runif(20),
  "y" = runif(20),
  "g" = rep(1:4, each = 5)
)

# Calculate distances in the two dimensions (x and y)
# With the origin at x=0.5, y=0.5
distance(
  data = df,
  cols = c("x", "y"),
  origin = c(0.5, 0.5)
)

# Calculate distances to the centroid for each group in 'g'
distance(
  data = dplyr::group_by(df, g),
  cols = c("x", "y"),
  origin_fn = centroid
)