Merge pull request #848 from ldecicco-USGS/develop

Add flexibility to read_waterdata_metadata

Author: ldecicco-USGS

NAMESPACE

@@ -17,6 +17,7 @@ export(create_WQP_bib)
 export(findNLDI)
 export(getWebServiceData)
 export(get_nldi_sources)
+export(get_ogc_params)
 export(importNGWMN)
 export(importRDB1)
 export(importWQP)

NEWS

@@ -11,7 +11,9 @@ encouraged to migrate to the "read_waterdata_metadata" functions.
 recommended because it will silently cut off data after 50,000 rows.
 * Removed max_results argument. Was confusing and redundant with the combination
 of no_paging and limit.
+* Increase the flexibility of read_waterdata_metadata to match other OGC functions.
 * NLDI to use agency code prefixes and should no longer be stripping the "USGS-" off the site ides.
+* Add deprecate message to readNWISuse function as data services have been retired.
 
 dataRetrieval 2.7.21
 ===================

R/AAA.R

@@ -16,6 +16,12 @@ pkg.env <- new.env()
                    "hydrologic-unit-codes", "states",
                    "national-aquifer-codes", "reliability-codes", "site-types", "statistic-codes",
                    "topographic-codes", "time-zone-codes")
+  names(collections) <- c("parameter_code", "agency_code", "altitude_datum", "aquifer_code",
+                          "aquifer_type", "coordinate_accuracy_code", "coordinate_datum_code",
+                          "coordinate_method_code", "medium_code", "county",
+                          "hydrologic_unit_code", "state",
+                          "national_aquifer_code", "reliability_code", "site_types", "statistic_code",
+                          "topographic_code", "time_zone_code")
 
   pkg.env$api_endpoints <- services
   pkg.env$metadata <- collections

R/construct_api_requests.R

@@ -53,7 +53,7 @@ construct_api_requests <- function(service,
                     "computation_period_identifier",
                     "computation_identifier")
 
-  if(service %in% c("monitoring-locations", #"parameter-codes", 
+  if(service %in% c("monitoring-locations", "parameter-codes", 
                     "time-series-metadata")){
     comma_params <- c(comma_params, "id")
   }

R/get_ogc_documentation.R

@@ -52,21 +52,22 @@ get_collection <- function(){
   return(query_ret)
 }
 
-#' Create parameter descriptions dynamically
+#' Get parameter descriptions
 #' 
-#' This function populates the parameter descriptions.
+#' This function returns a list of properties available from an endpoint. When 
+#' available, it will also contain a description.
 #' 
-#' @param service Character, can be any of the endpoints
+#' @param service Character, can be any of the USGS Waterdata API endpoints or collections.
 #' @return list
-#' @noRd
+#' @export
 #' @examplesIf is_dataRetrieval_user()
 #' 
 #' \donttest{
-#' ml <- dataRetrieval:::get_params("monitoring-locations")
+#' ml <- dataRetrieval::get_ogc_params("monitoring-locations")
 #' ml$national_aquifer_code
 #' }
 #' 
-get_params <- function(service){
+get_ogc_params <- function(service){
 
   check_queryables_req <- base_url() |> 
     httr2::req_url_path_append("collections") |> 

R/readNWISpCode.R

@@ -1,7 +1,6 @@
 #' USGS Parameter Data Retrieval
 #'
 #' Imports data from NWIS about measured parameter based on user-supplied parameter code or codes.
-#' This function gets the data from here: <https://nwis.waterdata.usgs.gov/nwis/pmcodes>
 #'
 #' @param parameterCd character of USGS parameter codes (or multiple parameter codes).
 #' These are 5 digit number codes. To get a complete list of all current parameter

R/readNWISunit.R

@@ -1,29 +1,23 @@
 #' Instantaneous value data retrieval from USGS (NWIS)
 #'
-#' Imports data from NWIS web service. This function gets the data from here:
-#' <https://waterservices.usgs.gov/docs/instantaneous-values/instantaneous-values-details/>
-#' Inputs to this function are just USGS site ids, USGS parameter codes,
+#' Imports data from NWIS web service. 
+#' Inputs to this function are USGS site ids, USGS parameter codes,
 #' and start and end date. For a more complex query, use [readNWISdata()],
 #' including an arguement service="uv".
 #' Not all parameter codes are available for all data.
 #' Use the function [whatNWISdata()] to discover what data
 #' is available for a USGS site. The column data_type_cd with the values "uv"
 #' returned from [whatNWISdata()]) are available from this service.
 #' 
-#' More information on the web service can be found here:
-#' <https://waterservices.usgs.gov/test-tools>, choosing the
-#' "Instantaneous Value Service".
 #'
 #' @param siteNumbers character USGS site number (or multiple sites).  This is usually an 8 digit number
 #' @param parameterCd character USGS parameter code.  This is usually an 5 digit number.
 #' @param startDate character starting date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
 #' retrieval for the earliest possible record. Simple date arguments are specified in local time.
-#' See more information here: <https://waterservices.usgs.gov/docs/instantaneous-values/>.
 #' @param endDate character ending date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
 #' retrieval for the latest possible record. Simple date arguments are specified in local time.
-#' See more information here: <https://waterservices.usgs.gov/docs/instantaneous-values/>.
 #' @param tz character to set timezone attribute of dateTime. Default is "UTC", and converts the
-#' date times to UTC, properly accounting for daylight savings times based on the data's provided tz_cd column.
+#' date times to UTC, properly accounting for daylight savings times based on the data provided tz_cd column.
 #' Possible values to provide are "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles",
 #' "America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu",
 #' "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also  `OlsonNames()`
@@ -91,9 +85,9 @@ readNWISuv <- function(siteNumbers, parameterCd, startDate = "", endDate = "", t
     service <- "iv_recent"
   }
 
-  # .Deprecated(new = "read_waterdata_continuous",
-  #             package = "dataRetrieval", 
-  #             msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_continuous.")
+  .Deprecated(new = "read_waterdata_continuous",
+              package = "dataRetrieval",
+              msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_continuous.")
 
 
   url <- constructNWISURL(siteNumbers,
@@ -111,8 +105,8 @@ readNWISuv <- function(siteNumbers, parameterCd, startDate = "", endDate = "", t
 
 #' Peak flow data from USGS (NWIS)
 #'
-#' Reads peak flow from NWISweb. Data is retrieved from
-#' <https://waterdata.usgs.gov/nwis>.
+#' Reads peak flow from NWISweb. 
+#' 
 #' In some cases, the specific date of the peak data is not know. This function
 #' will default to
 #' converting complete dates to a "Date" object, and converting incomplete dates to
@@ -233,7 +227,6 @@ readNWISpeak <- function(siteNumbers,
 #' Rating table for an active USGS streamgage retrieval
 #'
 #' Reads current rating table for an active USGS streamgage from NWISweb.
-#' Data is retrieved from <https://waterdata.usgs.gov/nwis>.
 #'
 #' @param siteNumber character USGS site number.  This is usually an 8 digit number
 #' @param type character can be "base", "corr", or "exsa"
@@ -304,8 +297,7 @@ readNWISrating <- function(siteNumber, type = "base", convertType = TRUE) {
 
 #' Surface-water measurement data retrieval from USGS (NWIS)
 #'
-#' Reads surface-water measurement data from NWISweb. Data is retrieved from <https://waterdata.usgs.gov/nwis>.
-#' See <https://waterdata.usgs.gov/usa/nwis/sw> for details about surface water.
+#' Reads surface-water measurement data from NWISweb. 
 #'
 #' @param siteNumbers character USGS site number (or multiple sites).  This is usually an 8 digit number
 #' @param startDate character starting date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
@@ -334,9 +326,6 @@ readNWISrating <- function(siteNumber, type = "base", convertType = TRUE) {
 #' tz_cd \tab character \tab The time zone code for the measurement_dt column \cr
 #' }
 #'
-#' See <https://waterdata.usgs.gov/usa/nwis/sw> for details about surface water, and
-#' <https://waterdata.usgs.gov/nwis/help?output_formats_help>
-#' for help on the columns and codes.
 #'
 #' There are also several useful attributes attached to the data frame:
 #' \tabular{lll}{
@@ -438,8 +427,7 @@ readNWISmeas <- function(siteNumbers,
 
 #' Groundwater level measurements retrieval from USGS (NWIS)
 #'
-#' Imports groundwater level data from NWIS web service. This function gets the data from here:
-#' <https://waterservices.usgs.gov/docs/groundwater-levels/groundwater-levels-details/>
+#' Imports groundwater level data from NWIS web service. 
 #' Inputs to this function are just USGS site ids, USGS parameter codes,
 #' and start and end date. For a more complex query, use [readNWISdata()],
 #' including an argument service="gwlevels".
@@ -448,16 +436,7 @@ readNWISmeas <- function(siteNumbers,
 #' is available for a USGS site. The column data_type_cd with the values "gw"
 #' returned from [whatNWISdata()]) are available from this service.
 #' 
-#' More information on the web service can be found here:
-#' <https://waterservices.usgs.gov/test-tools>, choosing the
-#' "Groundwater Levels Value Service".
-#' 
 #' 
-#' Mixed date/times come back from the service
-#' depending on the year that the data was collected. See <https://waterdata.usgs.gov/usa/nwis/gw>
-#' for details about groundwater. By default the returned dates are converted to date objects, unless convertType
-#' is specified as FALSE. Sites with non-standard date formats (i.e. lacking a day) can be affected (see examples).
-#' See <https://waterservices.usgs.gov/docs/groundwater-levels/> for more information.
 #'
 #' @param siteNumbers character USGS site number (or multiple sites).  This is usually an 8 digit number
 #' @param startDate character starting date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
@@ -569,7 +548,6 @@ readNWISgwl <- function(siteNumbers,
 #' Site statistics retrieval from USGS (NWIS)
 #'
 #' Retrieves site statistics from the USGS Statistics Web Service beta.
-#' See <https://waterservices.usgs.gov/docs/statistics/> for more information.
 #'
 #' @param siteNumbers character USGS site number (or multiple sites).  This is usually an 8 digit number.
 #' @param parameterCd character USGS parameter code.  This is usually a 5 digit number.
@@ -593,9 +571,7 @@ readNWISgwl <- function(siteNumbers,
 #' for water years. Monthly and yearly
 #' provide statistics for each month and year within the range indivually.
 #' @param statType character type(s) of statistics to output for daily values.
-#' Default is mean, which is the only
-#' option for monthly and yearly report types. See the statistics service documentation
-#' at <https://waterservices.usgs.gov/docs/statistics/> for a full list of codes.
+#' Default is mean, which is the only option for monthly and yearly report types.
 #' @return A data frame with the following columns:
 #' \tabular{lll}{
 #' Name \tab Type \tab Description \cr
@@ -679,9 +655,7 @@ readNWISstat <- function(siteNumbers, parameterCd, startDate = "", endDate = "",
 
 #' Water use data retrieval from USGS (NWIS)
 #'
-#' Retrieves water use data from USGS Water Use Data for the Nation.  See
-#' <https://waterdata.usgs.gov/nwis/wu> for
-#' more information.  All available use categories for the supplied arguments are retrieved.
+#' Retrieves water use data from USGS Water Use Data for the Nation.
 #'
 #' @param stateCd could be character (full name, abbreviation, id), or numeric (id).
 #' Only one is accepted per query.
@@ -711,81 +685,17 @@ readNWISstat <- function(siteNumbers, parameterCd, startDate = "", endDate = "",
 #' County and state fields will be included as appropriate.
 #'
 #' @export
-#' @examplesIf is_dataRetrieval_user()
-#' \donttest{
-#' # All data for a county
-#' allegheny <- readNWISuse(stateCd = "Pennsylvania", countyCd = "Allegheny")
-#'
-#' # Data for an entire state for certain years
-#' ohio <- readNWISuse(years = c(2000, 2005, 2010), stateCd = "OH", countyCd = NULL)
-#'
-#' # Data for an entire state, county by county
-#' pr <- readNWISuse(years = c(2000, 2005, 2010), stateCd = "PR", countyCd = "ALL")
-#'
-#' # All national-scale data, transforming data frame to named columns from named rows
-#' national <- readNWISuse(stateCd = NULL, countyCd = NULL, transform = TRUE)
-#'
-#' # Washington, DC data
-#' dc <- readNWISuse(stateCd = "DC", countyCd = NULL)
-#'
-#' # data for multiple counties, with different input formatting
-#' paData <- readNWISuse(stateCd = "42", countyCd = c("Allegheny County", "BUTLER", 1, "031"))
-#'
-#' # retrieving two specific categories for an entire state
-#' ks <- readNWISuse(stateCd = "KS", countyCd = NULL, categories = c("IT", "LI"))
-#' }
 readNWISuse <- function(stateCd,
                         countyCd,
                         years = "ALL",
                         categories = "ALL",
                         convertType = TRUE,
                         transform = FALSE) {
-  message(new_nwis_message())
-  countyID <- NULL
-  countyCd <- countyCd[countyCd != ""]
-
-  if (exists("countyCd") && !is.null(countyCd)) {
-    if (!any(toupper(countyCd) == "ALL")) {
-      for (c in countyCd) {
-        code <- countyCdLookup(state = stateCd, county = c, outputType = "id")
-        countyID <- c(countyID, code)
-      }
-    } else {
-      countyID <- toupper(countyID)
-    }
-  }
-
-  years <- .capitalALL(years)
-  categories <- .capitalALL(categories)
-
-  url <- constructUseURL(
-    years = years,
-    stateCd = stateCd,
-    countyCd = countyID,
-    categories = categories
-  )
-  returned_data <- importRDB1(
-    obs_url = url,
-    convertType = convertType
-  )
+  .Deprecated(new = "read_waterdata_use_data in development",
+              package = "dataRetrieval", 
+              msg = "NWIS servers for water use have been decommission. New functions are being developed.")
+  return(NULL)
 
-  # for total country data arriving in named rows
-  if (transform) {
-    cmmnt <- comment(returned_data)
-    returned_data <- t(returned_data)
-    colnames(returned_data) <- returned_data[1, ]
-    returned_data <- as.data.frame(returned_data[-1, ], stringsAsFactors = FALSE)
-    returned_data <- cbind(
-      Year = as.integer(substr(rownames(returned_data), 2, 5)),
-      returned_data
-    )
-    rownames(returned_data) <- NULL
-    comment(returned_data) <- cmmnt
-    if (!all(is.null(stateCd)) && all(nchar(stateCd) != 0)) {
-      warning("transform = TRUE is only intended for national data")
-    }
-  }
-  return(returned_data)
 }
 
 .capitalALL <- function(input) {

R/read_waterdata_continuous.R

@@ -11,22 +11,22 @@
 #' Geometry output is not supported in the continuous data API endpoint.
 #' 
 #' @export
-#' @param monitoring_location_id `r get_params("continuous")$monitoring_location_id`
+#' @param monitoring_location_id `r get_ogc_params("continuous")$monitoring_location_id`
 #' Multiple monitoring_location_ids can be requested as a character vector.
-#' @param parameter_code `r get_params("continuous")$parameter_code`
+#' @param parameter_code `r get_ogc_params("continuous")$parameter_code`
 #' Multiple parameter_codes can be requested as a character vector.
-#' @param time `r get_params("continuous")$time`. 
+#' @param time `r get_ogc_params("continuous")$time`. 
 #' You can also use a vector of length 2: the first value being the starting date,
 #' the second value being the ending date. NA's within the vector indicate a
 #' half-bound date. For example, c("2024-01-01", NA) will return all data starting
 #' at 2024-01-01.
-#' @param value `r get_params("continuous")$value`
-#' @param unit_of_measure `r get_params("continuous")$unit_of_measure`
-#' @param approval_status `r get_params("continuous")$approval_status`
-#' @param last_modified `r get_params("continuous")$last_modified`
-#' @param time_series_id `r get_params("continuous")$time_series_id`
+#' @param value `r get_ogc_params("continuous")$value`
+#' @param unit_of_measure `r get_ogc_params("continuous")$unit_of_measure`
+#' @param approval_status `r get_ogc_params("continuous")$approval_status`
+#' @param last_modified `r get_ogc_params("continuous")$last_modified`
+#' @param time_series_id `r get_ogc_params("continuous")$time_series_id`
 #' Multiple time_series_ids can be requested as a character vector.
-#' @param qualifier `r get_params("continuous")$qualifier`
+#' @param qualifier `r get_ogc_params("continuous")$qualifier`
 #' @param properties A vector of requested columns to be returned from the query.
 #' Available options are: 
 #' `r dataRetrieval:::get_properties_for_docs("continuous", "continuous_id")`.

R/read_waterdata_daily.R

@@ -3,24 +3,24 @@
 #' @description `r get_description("daily")`
 #' 
 #' @export
-#' @param monitoring_location_id `r get_params("daily")$monitoring_location_id`
+#' @param monitoring_location_id `r get_ogc_params("daily")$monitoring_location_id`
 #' Multiple monitoring_location_ids can be requested as a character vector.
-#' @param parameter_code `r get_params("daily")$parameter_code`
+#' @param parameter_code `r get_ogc_params("daily")$parameter_code`
 #' Multiple parameter_codes can be requested as a character vector.
-#' @param statistic_id `r get_params("daily")$statistic_id`
+#' @param statistic_id `r get_ogc_params("daily")$statistic_id`
 #' Multiple statistic_ids can be requested as a character vector.
-#' @param time `r get_params("daily")$time`
+#' @param time `r get_ogc_params("daily")$time`
 #' You can also use a vector of length 2: the first value being the starting date,
 #' the second value being the ending date. NA's within the vector indicate a
 #' half-bound date. For example, c("2024-01-01", NA) will return all data starting
 #' at 2024-01-01.
-#' @param value `r get_params("daily")$value`
-#' @param unit_of_measure `r get_params("daily")$unit_of_measure`
-#' @param approval_status `r get_params("daily")$approval_status`
-#' @param last_modified `r get_params("daily")$last_modified`
-#' @param time_series_id `r get_params("daily")$time_series_id`
+#' @param value `r get_ogc_params("daily")$value`
+#' @param unit_of_measure `r get_ogc_params("daily")$unit_of_measure`
+#' @param approval_status `r get_ogc_params("daily")$approval_status`
+#' @param last_modified `r get_ogc_params("daily")$last_modified`
+#' @param time_series_id `r get_ogc_params("daily")$time_series_id`
 #' Multiple time_series_ids can be requested as a character vector.
-#' @param qualifier `r get_params("daily")$qualifier`
+#' @param qualifier `r get_ogc_params("daily")$qualifier`
 #' @param properties A vector of requested columns to be returned from the query.
 #' Available options are: 
 #' `r dataRetrieval:::get_properties_for_docs("daily", "daily_id")`.