geodist {geodist}

geodist.

Description

Dependency-free, ultra fast calculation of geodesic distances. Includes the reference nanometre-accuracy geodesic distances of Karney (2013) doi:10.1007/s00190-012-0578-z, as used by the 'sf' package, as well as Haversine and Vincenty distances. Default distance measure is the "Mapbox cheap ruler" which is generally more accurate than Haversine or Vincenty for distances out to a few hundred kilometres, and is considerably faster. The main function accepts one or two inputs in almost any generic rectangular form, and returns either matrices of pairwise distances, or vectors of sequential distances.

Convert one or two rectangular objects containing lon-lat coordinates into vector or matrix of geodesic distances in metres.

Usage

geodist(
  x,
  y,
  paired = FALSE,
  sequential = FALSE,
  pad = FALSE,
  measure = "cheap",
  quiet = FALSE
)

Arguments

x

Rectangular object (matrix, data.frame, tibble, whatever) containing longitude and latitude coordinates.

y

Optional second object which, if passed, results in distances calculated between each object in x and each in y.

paired

If TRUE, calculate paired distances between each entry in x and y, returning a single vector.

sequential

If TRUE, calculate (vector of) distances sequentially along x (when no y is passed), otherwise calculate matrix of pairwise distances between all points.

pad

If sequential = TRUE values are padded with initial NA to return n values for input with n rows, otherwise return n - 1 values.

measure

One of "haversine" "vincenty", "geodesic", or "cheap" specifying desired method of geodesic distance calculation; see Notes.

quiet

If FALSE, check whether max of calculated distances is greater than accuracy threshold and warn.

Value

If only x passed and sequential = FALSE, a square symmetric matrix containing distances between all items in x; If only x passed and sequential = TRUE, a vector of sequential distances between rows of x; otherwise if y is passed, a matrix of nrow(x) rows and nrow(y) columns. All return values are distances in metres.

Note

measure = "cheap" denotes the mapbox cheap ruler https://github.com/mapbox/cheap-ruler-cpp; measure = "geodesic" denotes the very accurate geodesic methods given in Karney (2013) "Algorithms for geodesics" J Geod 87:43-55, and as provided by the 'st_dist()' function from the sf package.

Author(s)

Maintainer: Mark Padgham [e-mail]

Authors:

• Michael D. Sumner

Other contributors:

• Charles F.F Karney (Original author of included code for geodesic distances) [copyright holder]

See Also

Useful links:

• https://github.com/hypertidy/geodist

• https://hypertidy.github.io/geodist/

• Report bugs at https://github.com/hypertidy/geodist/issues

Examples

n <- 50
# Default "cheap" distance measure is only accurate for short distances:
x <- cbind (runif (n, -0.1, 0.1), runif (n, -0.1, 0.1))
y <- cbind (runif (2 * n, -0.1, 0.1), runif (2 * n, -0.1, 0.1))
colnames (x) <- colnames (y) <- c ("x", "y")
d0 <- geodist (x) # A 50-by-50 matrix
d1 <- geodist (x, y) # A 50-by-100 matrix
d2 <- geodist (x, sequential = TRUE) # Vector of length 49
d2 <- geodist (x, sequential = TRUE, pad = TRUE) # Vector of length 50
d0_2 <- geodist (x, measure = "geodesic") # nanometre-accurate version of d0

# Input data can also be 'data.frame' objects:
xy <- data.frame (x = runif (n, -0.1, 0.1), y = runif (n, -0.1, 0.1))
d <- geodist (xy)