Converts an existing table into a known location table

Source: R/table_initializeExisting.R

An existing table may have much of the data that is needed for a known location table. This function accepts an incoming table and searches for required columns:

  • locationID

  • locationName

  • longitude

  • latitude

  • elevation

  • countryCode

  • stateCode

  • countyName

  • timezone

  • houseNumber

  • street

  • city

  • postalCode

The longitude and latitude columns are required but all others are optional.

If any of these optional columns are found, they will be used and the often slow and sometimes slightly inaccurate steps to generate that information will be skipped for locations that have non-missing data. Any additional columns of information that are not part of the required core metadata will be retained.

This method skips the assignment of columns like elevation and all address related fields that require web service requests.

Compared to initializing a brand new table and populating it one record at a time, this is a much faster way of creating a known location table from a pre-existing table of metadata.

table_initializeExisting(
  locationTbl = NULL,
  stateDataset = "NaturalEarthAdm1",
  countryCodes = NULL,
  distanceThreshold = NULL,
  measure = c("geodesic", "haversine", "vincenty", "cheap"),
  precision = 10,
  verbose = TRUE
)

Arguments

locationTbl

Tibble of known locations. This input tibble need not be a standardized "known location" table with all required columns. Missing columns will be added.

stateDataset

Name of spatial dataset to use for determining state codes, Default: 'NaturalEarthAdm1'

countryCodes

Vector of country codes used to optimize spatial searching. (See ?MazamaSpatialUtils::getStateCode())

distanceThreshold

Distance in meters.

measure

One of "haversine" "vincenty", "geodesic", or "cheap" specifying desired method of geodesic distance calculation. See ?geodist::geodist.

precision

precision argument passed on to location_createID.

verbose

Logical controlling the generation of progress messages.

Value

Known location tibble with the specified metadata columns. Any locations whose circles (as defined by distanceThreshold) overlap will generate warning messages.

It is incumbent upon the user to address overlapping locations by one of:

  1. reduce the distanceThreshold until no overlaps occur

  2. assign one of the overlapping locations to the other location

Note

The measure "cheap" may be used to speed things up depending on the spatial scale being considered. Distances calculated with measure = "cheap" will vary by a few meters compared with those calculated using measure = "geodesic".