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

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_distance()' function from the sf package.

Author(s)

Maintainer: Mark Padgham mark.padgham@email.com

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)

geodist_benchmark

Description

Benchmark errors for different geodist measures

Usage

geodist_benchmark(lat = 0, d = 1, n = 100L)

Arguments

Value

A 'data.frame' with three columns respectively comparing the accuracy of the [Haversine, Vincenty, cheap] metrics against geodesic measures in both absolute and relative terms (as two rows of the table).

Examples

geodist_benchmark (0.0, 1.0, 100L)

Minimal pairwise distances between two input matrices

Description

Convert two rectangular objects containing lon-lat coordinates into an index vector of the elements in the second matrix corresponding to the minimal distance to each element of the first matrix.

Usage

geodist_min(x, y, measure = "cheap", quiet = FALSE)

Arguments

Value

A integer index vector indexing elements of 'y' corresponding to minimal distances to each element of 'x'. The length of this vector is equal to the number of rows in 'x'.

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_distance()' function from the sf package.

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")
index <- geodist_min (x, y, measure = "Haversine")
# 'index' is a vector of 50 values indexing elements of `y` corresponding to
# minimal distances to each element of `x`. It is exactly the same as the
# value returned by these lines:
d0 <- geodist (x, y, measure = "Haversine")
index0 <- apply (d0, 1, which.min)
identical (index, index0)

geodist_vec

Description

An alternative interface to the main geodist function that directly accepts inputs as individual vectors of coordinates, rather than the matrix or 'data.frame' inputs of the main function. This interface is provided for cases where computational efficiency is important, and will generally provide faster results than the main function.

Usage

geodist_vec(
  x1,
  y1,
  x2,
  y2,
  paired = FALSE,
  sequential = FALSE,
  pad = FALSE,
  measure = "cheap",
  quiet = FALSE
)

Arguments

Value

If only (x1, y1) are passed and sequential = FALSE, a square symmetric matrix containing distances between all items in (x1, y1); If only (x1, y1) are passed and sequential = TRUE, a vector of sequential distances between matching elements of (x1, y1); otherwise if (x2, y2) are passed, a matrix of lenght(x1) == length(y1) rows and length(x2) == length(y2) columns.

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_distance()' function from the sf package.

Examples

n <- 50
# Default "cheap" distance measure is only accurate for short distances:
x1 <- -1 + 2 * runif (n, -0.1, 0.1)
y1 <- -1 + 2 * runif (n, -0.1, 0.1)
d0 <- geodist_vec (x1, y1) # A 50-by-50 matrix
d2 <- geodist_vec (x1, y1, sequential = TRUE) # Vector of length 49
d2 <- geodist_vec (x1, y1, sequential = TRUE, pad = TRUE) # length 50
x2 <- -10 + 20 * runif (2 * n, -0.1, 0.1)
y2 <- -10 + 20 * runif (2 * n, -0.1, 0.1)
d1 <- geodist_vec (x1, y1, x2, y2) # A 50-by-100 matrix

georange

Description

Calculate range of distances (min-max) between all points in one or two rectangular objects containing lon-lat coordinates.

Usage

georange(x, y, sequential = FALSE, measure = "cheap")

Arguments

Value

A named vector of two numeric values: minimum and maximum, giving the respective 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_distance()' function from the sf package.

Examples

n <- 50
x <- cbind (-10 + 20 * runif (n), -10 + 20 * runif (n))
y <- cbind (-10 + 20 * runif (2 * n), -10 + 20 * runif (2 * n))
colnames (x) <- colnames (y) <- c ("x", "y")
# All of the following returns vector of two values: minimum and maximum:
d0 <- georange (x)
d1 <- georange (x, y)
d2 <- georange (x, sequential = TRUE)
d0_2 <- georange (x, measure = "geodesic") # nanometre-accurate version of d0