knitr::opts_chunk$set(fig.width = 7, fig.height = 5)
This package is intended for use in data management activities associated with fixed locations in space. The motivating fields include air and water quality monitoring where fixed sensors report at regular time intervals.
When working with environmental monitoring time series, one of the first things
you have to do is create unique identifiers for each individual time series. In
an ideal world, each environmental time series would have both a
locationID
and a deviceID
that uniquely identify the specific instrument
making measurements and the physical location where measurements are made. A
unique timeseriesID
could
be produced as locationID_deviceID
. Metadata associated with each
timeseriesID
would contain basic information needed for downstream analysis
including at least:
timeseriesID, locationID, deviceID, longitude, latitude, ...
deviceID
.locationID
.longitude, latitude
.data
table with
timeseriesID
column names.Unfortunately, we are rarely supplied with a truly unique and truly spatial
locationID
. Instead we often use deviceID
or an associated non-spatial
identifier as a stand-in for locationID
.
Complications we have seen include:
locationID
.locationID
.A solution to all these problems is possible if we store spatial metadata in
simple tables in a standard directory. These tables will be referred to as
collections. Location lookups can be performed with
geodesic distance calculations where a longitude-latitude pair is assigned to a pre-existing
known location if it is within distanceThreshold
meters of that location.
These lookups will be extremely fast.
If no previously known location is found, the relatively slow (seconds) creation of a new known location metadata record can be performed and then added to the growing collection.
For collections of stationary environmental monitors that only number in the
thousands, this entire collection can be stored as either a
.rda
or .csv
file and will be under a megabyte in size making it fast to
load. This small size also makes it possible to store multiple known locations
files, each created with different locations and different distance thresholds
to address the needs of different scientific studies.
The package comes with some example known locations tables.
Lets take some metadata we have for air quality monitors in Washington state and create a known locations table for them.
wa <- get(data("wa_airfire_meta", package = "MazamaLocationUtils")) names(wa)
library(MazamaLocationUtils) wa_monitors_500 <- get(data("wa_monitors_500", package = "MazamaLocationUtils"))
We can create a known locations table for them with a minimum 500 meter separation between distinct locations:
library(MazamaLocationUtils) # Initialize with standard directories mazama_initialize() setLocationDataDir("./data") wa_monitors_500 <- table_initialize() %>% table_addLocation(wa$longitude, wa$latitude, distanceThreshold = 500)
Right now, our known locations table contains only automatically generated spatial metadata:
dplyr::glimpse(wa_monitors_500)
Perhaps we would like to import some of the original metadata into our new table. This is a very common use case where non-spatial metadata like site name or agency responsible for a monitor can be added.
Just to make it interesting, let's assume that our known locations table is already large and we are only providing additional metadata for a subset of the records.
# Use a subset of the wa metadata wa_indices <- seq(5,65,5) wa_sub <- wa[wa_indices,] # Use a generic name for the location table locationTbl <- wa_monitors_500 # Find the location IDs associated with our subset locationID <- table_getLocationID( locationTbl, longitude = wa_sub$longitude, latitude = wa_sub$latitude, distanceThreshold = 500 ) # Now add the "siteName" column for our subset of locations locationData <- wa_sub$siteName locationTbl <- table_updateColumn( locationTbl, columnName = "siteName", locationID = locationID, locationData = locationData ) # Lets see how we did locationTbl_indices <- table_getRecordIndex(locationTbl, locationID) locationTbl[locationTbl_indices, c("city", "siteName")]
Very nice. We have added siteName
to our known locations table for a more
detailed description of each monitors' location.
The whole point of a known locations table is to speed up access to spatial and other metadata. Here's how we can use it with a set of longitudes and latitudes that are not currently in our table.
# Create new locations near our known locations lons <- jitter(wa_sub$longitude) lats <- jitter(wa_sub$latitude) # Any known locations within 50 meters? table_getNearestLocation( wa_monitors_500, longitude = lons, latitude = lats, distanceThreshold = 50 ) %>% dplyr::pull(city) # Any known locations within 500 meters table_getNearestLocation( wa_monitors_500, longitude = lons, latitude = lats, distanceThreshold = 500 ) %>% dplyr::pull(city) # How about 5000 meters? table_getNearestLocation( wa_monitors_500, longitude = lons, latitude = lats, distanceThreshold = 5000 ) %>% dplyr::pull(city)
Before using MazamaLocationUtils you must first install MazamaSpatialUtils and then install core spatial data with:
library(MazamaSpatialUtils) setSpatialDataDir("~/Data/Spatial") installSpatialData("EEZCountries") installSpatialData("OSMTimezones") installSpatialData("NaturalEarthAdm1") installSpatialData("USCensusCounties") Once the required datasets have been installed, the easiest way to set things up each session is with: ```r library(MazamaLocationUtils) mazama_initialize() setLocationDataDir("~/Data/KnownLocations")
mazama_initialize()
assumes spatial data are installed in the standard
location and is just a wrapper for:
MazamaSpatialUtils::setSpatialDataDir("~/Data/Spatial") MazamaSpatialUtils::loadSpatialData("EEZCountries.rda") MazamaSpatialUtils::loadSpatialData("OSMTimezones.rda") MazamaSpatialUtils::loadSpatialData("NaturalEarthAdm1.rda") MazamaSpatialUtils::loadSpatialData("USCensusCounties.rda")
Every time you table_save()
your location table, a backup will be created
so you can experiment without losing your work. File sizes are pretty tiny
so you don't have to worry about filling up your disk.
Best wishes for well organized spatial metadata!
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.