Create one or more unique locationIDs

A locationID is created for each incoming longitude and latitude. Each locationID is unique to within a certain spatial scale. With algorithm = "geohash", the precision argument determines the size of a geohash grid cell. At the equator, the following grid cell sizes apply for different precision levels:

precision   (maximum grid cell X axis, in m)
        5   ± 2400
        6   ± 610
        7   ± 76
        8   ± 19
        9   ± 2.4
       10   ± 0.6

Invalid locations will be assigned a locationID specified by the user with the invalidID argument, typically NA.

createLocationID(
  longitude = NULL,
  latitude = NULL,
  algorithm = c("geohash", "digest"),
  precision = 10,
  invalidID = as.character(NA)
)

Arguments

longitude

Vector of longitudes in decimal degrees E.

latitude

Vector of latitudes in decimal degrees N.

algorithm

Algorithm to use -- either "geohash" or "digest".

precision

precision argument used when encoding with "geohash".

invalidID

Identifier to use for invalid locations. This can be a character string or NA.

Value

Vector of character locationIDs.

Details

When the "geohash" algorithm is specified, the following code is used to generate each locationID:

  locationID <-
    geohashTools::gh_encode(latitude, longitude, precision)

When the "digest" algorithm is specified, the following code is used:

# Retain accuracy up to ~.1m
locationString <- paste0(
  sprintf("%.7f", longitude),
  "_",
  sprintf("%.7f", latitude)
)
# Avoid collisions until billions of records
locationID <- digest::digest(locationString, algo = "xxhash64")

See the references for details on either algorithm.

Note

The "geohash" algorithm is preferred but the "digest" algorithm is retained because several existing databases use the "digest" algorithm as a unique identifier.

References

https://en.wikipedia.org/wiki/Decimal_degrees

https://www.johndcook.com/blog/2017/01/10/probability-of-secure-hash-collisions/

https://michaelchirico.github.io/geohashTools/index.html

Examples

library(MazamaCoreUtils)

longitude <- c(-122.5, 0, NA, -122.5, -122.5)
latitude <- c( 47.5, 0, 47.5, NA, 47.5)

createLocationID(longitude, latitude)
#> [1] "c22yhrn5x1" NA           NA           NA           "c22yhrn5x1"
createLocationID(longitude, latitude, precision = 7)
#> [1] "c22yhrn" NA        NA        NA        "c22yhrn"
createLocationID(longitude, latitude, invalidID = "bad")
#> [1] "c22yhrn5x1" "bad"        "bad"        "bad"        "c22yhrn5x1"
createLocationID(longitude, latitude, algorithm = "digest")
#> [1] "00cf3f93141268b9" NA                 NA                 NA                
#> [5] "00cf3f93141268b9"