createLocationID: Create one or more unique locationIDs

In MazamaCoreUtils: Utility Functions for Production R Code

Create one or more unique locationIDs

Description

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.

Usage

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.

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.

Value

Vector of character locationIDs.

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)
createLocationID(longitude, latitude, invalidID = "bad")
createLocationID(longitude, latitude, algorithm = "digest")

MazamaCoreUtils documentation built on Nov. 14, 2023, 1:09 a.m.