table_initializeExisting: Converts an existing table into a known location table

In MazamaScience/MazamaLocationUtils: Manage Spatial Metadata for Known Locations

Converts an existing table into a known location table

Description

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.

Usage

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".

MazamaScience/MazamaLocationUtils documentation built on Jan. 26, 2024, 3:16 p.m.