two user-friendly functions ready

DOI-USGS · Aug 26, 2016 · d449ee1 · d449ee1
1 parent cc26e41
commit d449ee1
Show file tree

Hide file tree

Showing 6 changed files with 114 additions and 17 deletions.
diff --git a/NAMESPACE b/NAMESPACE
@@ -14,7 +14,8 @@ export(importWaterML1)
 export(importWaterML2)
 export(pCodeToName)
 export(parameterCdFile)
-export(readNGWMNdata)
+export(readNGWMNlevels)
+export(readNGWMNsites)
 export(readNWISdata)
 export(readNWISdv)
 export(readNWISgwl)

diff --git a/R/importNGWMN_wml2.R b/R/importNGWMN_wml2.R
@@ -19,11 +19,13 @@
 #' @examples
 #' \dontrun{
 #' url <- "http://cida.usgs.gov/ngwmn_cache/sos?request=GetObservation&service=SOS&version=2.0.0
-#' &observedProperty=urn:ogc:def:property:OGC:GroundWaterLevel&responseFormat=text/xml&featureOfInterest=VW_GWDP_GEOSERVER.USGS.403836085374401"
+#' &observedProperty=urn:ogc:def:property:OGC:GroundWaterLevel&responseFormat=text/xml&featureOf
+#' Interest=VW_GWDP_GEOSERVER.USGS.403836085374401"
 #' data <- importNGWMN_wml2(url)
 #' 
 #' url <- "http://cida.usgs.gov/ngwmn_cache/sos?request=GetObservation&service=SOS&version=2.0.0
-#' &observedProperty=urn:ogc:def:property:OGC:GroundWaterLevel&responseFormat=text/xml&featureOfInterest=VW_GWDP_GEOSERVER.USGS.474011117072901"
+#' &observedProperty=urn:ogc:def:property:OGC:GroundWaterLevel&responseFormat=text/xml&featureOf
+#' Interest=VW_GWDP_GEOSERVER.USGS.474011117072901"
 #' data <- importNGWMN_wml2(url)
 #' }
 #' 

diff --git a/R/readNGWMNdata.R b/R/readNGWMNdata.R
@@ -5,12 +5,15 @@
 #' \code{FALSE} since time zone information is not included.  
 #' @param featureID character Vector of feature IDs in the formatted with agency code and site number 
 #' separated by a period, e.g. \code{USGS.404159100494601}.
-#' @param request character Identifies which web service to access.  Only \code{observation} is currently 
+#' @param service character Identifies which web service to access.  Only \code{observation} is currently 
 #' supported, which retrieves all water level for each site.   
+#' @param tz character to set timezone attribute of datetime. Default is an empty quote, which converts the 
+#' datetimes to UTC (properly accounting for daylight savings times based on the data's provided time zone offset).
+#' Possible values to provide are "America/New_York","America/Chicago", "America/Denver","America/Los_Angeles",
+#' "America/Anchorage","America/Honolulu","America/Jamaica","America/Managua","America/Phoenix", and "America/Metlakatla"
 #' @import utils
 #' @importFrom dplyr mutate
 #' @importFrom dplyr bind_rows
-#' @export
 #' 
 #' @examples 
 #' \dontrun{
@@ -28,19 +31,19 @@
 #' 
 #' #site with no data returns empty data frame
 #' noDataSite <- "UTGS.401544112060301"
-#' noDataSite <- readNGWMNdata(featureID = noDataSite, request = "observation")
+#' noDataSite <- readNGWMNdata(featureID = noDataSite, service = "observation")
 #' }
 #' 
 
-readNGWMNdata <- function(featureID, request = "observation", asDateTime = TRUE){
+readNGWMNdata <- function(featureID, service = "observation", asDateTime = TRUE, tz = ""){
   message("          ********************************************************
           DISCLAIMER: NGWMN retrieval functions are still in flux, 
               and no future behavior or output is guaranteed
           *********************************************************")
-  match.arg(request, c("observation", "featureOfInterest"))
+  match.arg(service, c("observation", "featureOfInterest"))
 
 
-  if(request == "observation"){
+  if(service == "observation"){
     allObs <- NULL
     allAttrs <- NULL
     allSites <- NULL
@@ -64,11 +67,91 @@ readNGWMNdata <- function(featureID, request = "observation", asDateTime = TRUE)
       attr(allObs, "siteInfo") <- allSites
       returnData <- allObs
     }
-  } #TODO: add direct feature of interest request
+  }else if(service == "featureOfInterest"){
+    allSites <- NULL
+    for(f in featureID){
+      siteFID <- retrieveFeatureOfInterest(f, asDateTime)
+      if(is.null(allSites)){
+        allSites <- siteFID
+        }else{
+        allSites <- bind_rows(allSites, siteFID)
+      }
+    }
+    returnData <- allSites
+  }else{
+    stop("unrecognized service request")
+  }
 
   return(returnData)
 }
 
+#' Retrieve groundwater levels from the National Ground Water Monitoring Network \url{http://cida.usgs.gov/ngwmn/}.
+#'
+#' @param featureID character Vector of feature IDs in the formatted with agency code and site number 
+#' separated by a period, e.g. \code{USGS.404159100494601}.
+#' 
+#' @export
+#' 
+#' @examples 
+#' \dontrun{
+#' #one site
+#' site <- "USGS.430427089284901"
+#' oneSite <- readNGWMNlevels(featureID = site)
+#' 
+#' #multiple sites
+#' sites <- c("USGS.272838082142201","USGS.404159100494601", "USGS.401216080362703")
+#' multiSiteData <- readNGWMNlevels(sites)
+#' 
+#' #non-USGS site
+#' site <- "MBMG.892195"
+#' data <- readNGWMNlevels(featureID = site)
+#' 
+#' #site with no data returns empty data frame
+#' noDataSite <- "UTGS.401544112060301"
+#' noDataSite <- readNGWMNlevels(featureID = noDataSite)
+#' }
+
+readNGWMNlevels <- function(featureID){
+  data <- readNGWMNdata(featureID, service = "observation")
+  return(data)
+}
+
+#' Retrieve site data from the National Ground Water Monitoring Network \url{http://cida.usgs.gov/ngwmn/}.
+#'
+#' @param featureID character Vector of feature IDs in the formatted with agency code and site number 
+#' separated by a period, e.g. \code{USGS.404159100494601}.
+#' 
+#' @export
+#' @return A data frame the following columns: 
+#' #' \tabular{lll}{
+#' Name \tab Type \tab Description \cr
+#' site \tab char \tab Site FID \cr
+#' description \tab char \tab Site description \cr
+#' dec_lat_va, dec_lon_va \tab numeric \tab Site latitude and longitude \cr
+#' }
+#' @examples 
+#' \dontrun{
+#' #one site
+#' site <- "USGS.430427089284901"
+#' oneSite <- readNGWMNsites(featureID = site)
+#' 
+#' #multiple sites
+#' sites <- c("USGS.272838082142201","USGS.404159100494601", "USGS.401216080362703")
+#' multiSiteInfo <- readNGWMNsites(sites)
+#' 
+#' #non-USGS site
+#' site <- "MBMG.892195"
+#' siteInfo <- readNGWMNsites(featureID = site)
+#' 
+#' }
+
+readNGWMNsites <- function(featureID){
+  sites <- readNGWMNdata(featureID, service = "featureOfInterest")
+  return(sites)
+}
+
+
+
 retrieveObservation <- function(featureID, asDateTime, attrs){
   #will need to contruct this more piece by piece if other versions, properties are added
   baseURL <- "http://cida.usgs.gov/ngwmn_cache/sos?request=GetObservation&service=SOS&version=2.0.0&observedProperty=urn:ogc:def:property:OGC:GroundWaterLevel&responseFormat=text/xml&featureOfInterest=VW_GWDP_GEOSERVER."

diff --git a/man/importNGWMN_wml2.Rd b/man/importNGWMN_wml2.Rd
diff --git a/man/readNGWMNdata.Rd b/man/readNGWMNdata.Rd
diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R
@@ -218,14 +218,17 @@ test_that("state county tests",{
 
 test_that("NGWMN functions working", {
   noDataSite <- "UTGS.401544112060301"
-  noDataSite <- readNGWMNdata(featureID = noDataSite, request = "observation")
+  noDataSite <- readNGWMNlevels(featureID = noDataSite)
   expect_true(is.data.frame(noDataSite))
 
   #one site
   site <- "USGS.430427089284901"
-  oneSite <- readNGWMNdata(featureID = site)
+  oneSite <- readNGWMNlevels(featureID = site)
+  siteInfo <- readNGWMNsites(site)
   expect_true(is.numeric(oneSite$value))
   expect_true(is.character(oneSite$site))
+  expect_true(is.data.frame(siteInfo))
+  expect_true(nrow(siteInfo) > 0)
   expect_true(nrow(oneSite) > 0)