nngeo (version 0.2.4)

st_nn: Nearest Neighbor Search for Simple Features

Description

The function returns the indices of layer y which are nearest neighbors of each feature of layer x. The number of nearest neighbors k and the search radius maxdist can be modified. The function has three modes of operation -

• lon-lat points - Calculation using C implementation (see references) of the Vincenty distance, which is identical to geosphere::distVincentyEllipsoid and sf::st_distance

• projected points - Calculation using RANN::nn2, a fast search method based on the ANN C++ library

• lines or polygons, either lon-lat or projected - Calculation based on sf::st_distance

Usage

st_nn(x, y, sparse = TRUE, k = 1, maxdist = Inf,
  returnDist = FALSE, progress = TRUE)

Arguments

x

Object of class sf or sfc

y

Object of class sf or sfc

sparse

logical; should a sparse index list be returned (TRUE) or a dense logical matrix? See below.

k

The maximum number of nearest neighbors to compute. Default is 1, meaning that only a single point (nearest neighbor) is returned

maxdist

Search radius (in meters). Points farther than search radius are not considered. Default is Inf meaning that search is unconstrained

returnDist

logical; whether to return a matrix with the distances between detected neighbors

progress

Display progress bar? (default `TRUE`)

Value

If sparse=FALSE, returned object is a logical matrix with element [i,j] being TRUE when y[j, ] is a neighbor of x[i]; if sparse=TRUE (the default), a sparse list representation of the same matrix is returned, with list element i a numeric vector with the indices j of neighboring features from y for the feature x[i, ], or integer(0) in case there are no neighbors. If returnDists=TRUE the function returns a list, with the first element as specified above, and the second element the matrix of distances (in meters) between each pair of detected neighbors.

References

C code for Vincenty distance by Jan Antala (https://github.com/janantala/GPS-distance/blob/master/c/distance.c)

Examples

# NOT RUN {
data(cities)
data(towns)

cities = st_transform(cities, 32636)
towns = st_transform(towns, 32636)

# Nearest town
st_nn(cities, towns)

# Using 'sfc' objects
st_nn(st_geometry(cities), st_geometry(towns))
st_nn(cities, st_geometry(towns))
st_nn(st_geometry(cities), towns)

# With distances
st_nn(cities, towns, returnDist = TRUE)

# }
# NOT RUN {
# Distance limit
st_nn(cities, towns, maxdist = 7200)
st_nn(cities, towns, k = 3, maxdist = 12000)
st_nn(cities, towns, k = 3, maxdist = 12000, returnDist = TRUE)

# 3 nearest towns
st_nn(cities, towns, k = 3)

# Spatial join
st_join(cities, towns, st_nn, k = 1)
st_join(cities, towns, st_nn, k = 2)
st_join(cities, towns, st_nn, k = 1, maxdist = 7200)
st_join(towns, cities, st_nn, k = 1)

# Polygons to polygons
st_nn(water, water, k = 4)

# Large example
n = 1000
x = data.frame(
  lon = (runif(n) * 2 - 1) * 70,
  lat = (runif(n) * 2 - 1) * 70
)
x = st_as_sf(x, coords = c("lon", "lat"), crs = 4326)
start = Sys.time()
result = st_nn(x, x, k = 3)
end = Sys.time()
end - start

# }