feat: added table_getDistanceFromTarget()

MazamaScience · May 6, 2022 · 70b39e8 · 70b39e8
1 parent fc6d2f6
commit 70b39e8
Show file tree

Hide file tree

Showing 65 changed files with 552 additions and 114 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Type: Package
 Package: MazamaLocationUtils
-Version: 0.3.4
+Version: 0.3.6
 Title: Manage Spatial Metadata for Known Locations
 Authors@R: c(
     person("Jonathan", "Callahan", email="[email protected]", role=c("aut","cre")),

diff --git a/NAMESPACE b/NAMESPACE
@@ -23,6 +23,7 @@ export(table_addSingleLocation)
 export(table_filterByDistance)
 export(table_findAdjacentDistances)
 export(table_findAdjacentLocations)
+export(table_getDistanceFromTarget)
 export(table_getLocationID)
 export(table_getNearestDistance)
 export(table_getNearestLocation)

diff --git a/NEWS.md b/NEWS.md
@@ -1,3 +1,13 @@
+# MazamaLocationUtils 0.3.6
+
+* Added `table_getDistanceFromTarget()` and edited the description of other
+distance functions to make clear what each does.
+
+# MazamaLocationUtils 0.3.5
+
+* Removed `validateMazamaSpatialUtils()` test from `table_addCoreMetadata()` as
+this function just adds empty columns and does not need any spatial data.
+
 # MazamaLocationUtils 0.3.4
 
 * Updated `table_addOpenCageInfo()` to handle address components that are

diff --git a/R/table_addCoreMetadata.R b/R/table_addCoreMetadata.R
@@ -54,8 +54,6 @@ table_addCoreMetadata <- function(
   locationTbl = NULL
 ) {
 
-  validateMazamaSpatialUtils()
-
   # ----- Validate parameters --------------------------------------------------
 
   MazamaLocationUtils::validateLocationTbl(locationTbl, locationOnly = TRUE)

diff --git a/R/table_getDistanceFromTarget.R b/R/table_getDistanceFromTarget.R
@@ -0,0 +1,106 @@
+#' @rdname table_getDistanceFromTarget
+#' @export
+#' @importFrom MazamaCoreUtils stopIfNull
+#' @importFrom rlang .data
+#' 
+#' @title Return distances and directions from a target location to known locations
+#' 
+#' @param locationTbl Tibble of known locations.
+#' @param longitude Target longitude in decimal degrees E.
+#' @param latitude Target latitude in decimal degrees N.
+#' @param measure One of "haversine" "vincenty", "geodesic", or "cheap" 
+#' specifying desired method of geodesic distance calculation. 
+#' 
+#' @return Tibble of distances in meters and cardinal directions from a target location.
+#' 
+#' @description Returns a tibble with the same number of rows as \code{locationTbl} 
+#' containing the distance and direction from the target location specified by 
+#' \code{longitude} and \code{latitude} to each known location found in 
+#' \code{locationTbl}. 
+#' 
+#' @note Only a single target location is allowed.
+#' 
+#' @examples
+#' library(MazamaLocationUtils)
+#' 
+#' locationTbl <- get(data("wa_monitors_500"))
+#' 
+#' locationTbl %>%
+#'   table_getDistanceFromTarget(
+#'     longitude = -117.3647, 
+#'     latitude = 47.6725
+#'   ) %>% 
+#'   dplyr::glimpse()
+#' 
+
+
+table_getDistanceFromTarget <- function(
+  locationTbl = NULL,
+  longitude = NULL,
+  latitude = NULL,
+  measure = c("geodesic", "haversine", "vincenty", "cheap")
+) {
+
+  # ----- Validate parameters --------------------------------------------------
+
+  MazamaLocationUtils::validateLocationTbl(locationTbl, locationOnly = TRUE)
+  MazamaLocationUtils::validateLonLat(longitude, latitude)
+  measure <- match.arg(measure)
+
+  if ( length(longitude) > 1 || length(latitude) > 1 ) 
+    stop("Only a single target location is allowed.")
+
+  # ----- Calculate distances --------------------------------------------------
+
+  distanceMatrix <-
+    geodist::geodist(
+      y = cbind(
+        "x" = longitude,
+        "y" = latitude
+      ),
+      x = cbind(
+        "x" = locationTbl$longitude,
+        "y" = locationTbl$latitude
+      ),
+      paired = FALSE,
+      sequential = FALSE,
+      pad = FALSE,
+      measure = measure
+    )
+
+  # NOTE:  distanceMatrix is nrow(locationTbl) X 1
+
+  returnTbl <- 
+    locationTbl %>%
+    dplyr::select(c("locationID")) %>%
+    dplyr::mutate(
+      distanceFromTarget = round(distanceMatrix[,1])
+    )
+
+  # ----- Add direction --------------------------------------------------------
+
+  # https://stackoverflow.com/questions/30794729/find-angle-from-two-points-formula
+
+  x1 <- longitude * pi/180
+  x2 <- locationTbl$longitude * pi/180
+  y1 <- latitude * pi/180
+  y2 <- locationTbl$latitude * pi/180
+
+  angle = atan2(y2 - y1, x2 - x1) * 180/pi
+
+  # NOTE:  Mathematical angle is zero facing East and increases counter-clockwise
+  # NOTE:  Cover everything between -180:180
+
+  returnTbl$directionFromTarget <- 
+    cut(
+      angle,
+      breaks = c(-202.5, -157.5, -112.5, -67.5, -22.5, 22.5, 67.5, 112.5, 157.5, 202.5),
+      labels = c("W", "SW", "S", "SE", "E", "NE", "N", "NW", "W")
+    ) %>%
+    as.character()
+
+  # ----- Return ---------------------------------------------------------------
+
+  return(returnTbl)
+
+}
diff --git a/R/table_getNearestDistance.R b/R/table_getNearestDistance.R
@@ -1,27 +1,45 @@
-
-#' @title Return distances to nearest known locations
-#' @description Returns distances between known locations in \code{locationTbl},
-#' and a vector of target locations specified by \code{longitude} and \code{latitude}.
-#' Only a single distance to the closest known location is returned for each 
-#' incoming target location. If no known location is found within
-#' \code{distanceThreshold} meters for a particular
-#' incoming location, that distance in the vector will be \code{NA}.
+#' @rdname table_getNearestDistance
+#' @export
+#' @importFrom MazamaCoreUtils stopIfNull
+#' @importFrom geodist geodist
+#' @importFrom rlang .data
 #' 
-#' @note The measure \code{"cheap"} may be used to speed things up depending on
-#' the spatial scale being considered. Distances calculated with 
-#' \code{measure = "cheap"} will vary by a few meters compared with those 
-#' calculated using \code{measure = "geodesic"}.
+#' @title Return distances to nearest known locations
 #' 
 #' @param locationTbl Tibble of known locations.
-#' @param longitude Vector of longitudes in decimal degrees E.
-#' @param latitude Vector of latitudes in decimal degrees N.
+#' @param longitude Vector of target longitudes in decimal degrees E.
+#' @param latitude Vector of target latitudes in decimal degrees N.
 #' @param distanceThreshold Distance in meters.
 #' @param measure One of "haversine" "vincenty", "geodesic", or "cheap" 
 #' specifying desired method of geodesic distance calculation. 
 #' 
+#' @description Returns distances between target locations and the closest
+#' location found in \code{locationTbl} (if any). Target locations are specified 
+#' with \code{longitude} and \code{latitude}.
+#' 
+#' For each target location, only a single distance to the closest known location 
+#' is returned. If no known location is found within
+#' \code{distanceThreshold}, the distance associated with that target location
+#' will be \code{NA}. The length and order of resulting distances will match the
+#' order of the incoming target locations.
+#' 
+#' @section Use Case:
+#' You may have a set of locations of interest for which you want to assess whether
+#' any monitoring locations are nearby. In this case, the locations of interest
+#' will provide \code{longitude} and \code{latitude} while \code{locationTbl}
+#' will be the known location table associated with the monitoring locations. 
+#' 
+#' The resulting vector of distances will tell you the distance, for each 
+#' target location, to the nearst monitoring location.
+#' 
+#' @note The measure \code{"cheap"} may be used to speed things up depending on
+#' the spatial scale being considered. Distances calculated with 
+#' \code{measure = "cheap"} will vary by a few meters compared with those 
+#' calculated using \code{measure = "geodesic"}.
+#' 
 #' See \code{geodist::\link[geodist:geodist]{geodist}} for details.
 #' 
-#' @return Vector of distances from known locations.
+#' @return Vector of closest distances between target locations and known locations.
 #' @examples
 #' library(MazamaLocationUtils)
 #' 
@@ -37,11 +55,6 @@
 #' # Expanding the distanceThreshold will find one
 #' table_getNearestDistance(locationTbl, lon, lat, distanceThreshold = 5000)
 #' 
-#' @rdname table_getNearestDistance
-#' @export
-#' @importFrom MazamaCoreUtils stopIfNull
-#' @importFrom geodist geodist
-#' @importFrom rlang .data
 table_getNearestDistance <- function(
   locationTbl = NULL,
   longitude = NULL,
@@ -66,7 +79,7 @@ table_getNearestDistance <- function(
 
   # NOTE:  For the case where the incoming longitude and latitude have many 
   # NOTE:  duplicated locations (a "tidy" dataframe perhaps), we need to speed
-  # NOTE:  things up by only calculating distance for unique locations and then
+  # NOTE:  things up by only calculating distances for unique locations and then
   # NOTE:  merging with all incoming locations.
 
   myTbl <- dplyr::tibble(longitude = longitude, latitude = latitude)

diff --git a/docs/404.html b/docs/404.html
diff --git a/docs/LICENSE-text.html b/docs/LICENSE-text.html
diff --git a/docs/articles/MazamaLocationUtils.html b/docs/articles/MazamaLocationUtils.html
diff --git a/docs/articles/index.html b/docs/articles/index.html
diff --git a/docs/authors.html b/docs/authors.html
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/news/index.html b/docs/news/index.html
diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml
@@ -3,5 +3,5 @@ pkgdown: 1.6.1
 pkgdown_sha: ~
 articles:
   MazamaLocationUtils: MazamaLocationUtils.html
-last_built: 2022-04-04T21:00Z
+last_built: 2022-05-06T18:49Z
 
diff --git a/docs/reference/LocationDataDir.html b/docs/reference/LocationDataDir.html
diff --git a/docs/reference/MazamaLocationUtils.html b/docs/reference/MazamaLocationUtils.html
diff --git a/docs/reference/coreMetadataNames.html b/docs/reference/coreMetadataNames.html
diff --git a/docs/reference/getAPIKey.html b/docs/reference/getAPIKey.html
diff --git a/docs/reference/getLocationDataDir.html b/docs/reference/getLocationDataDir.html
diff --git a/docs/reference/id_monitors_500.html b/docs/reference/id_monitors_500.html