diff --git a/DESCRIPTION b/DESCRIPTION index 96d0452a..e61e5727 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: dataRetrieval Type: Package Title: Retrieval Functions for USGS and EPA Hydrology and Water Quality Data -Version: 2.7.21.9000 +Version: 2.7.22 Authors@R: c( person("Laura", "DeCicco", role = c("aut","cre"), email = "ldecicco@usgs.gov", @@ -29,7 +29,7 @@ Authors@R: c( person("Joeseph", "Zemmels", role="ctb", email = "jzemmels@usgs.gov", comment=c(ORCID = "0009-0008-1463-6313")), - person("Elise", "Hinman", role="ctb", + person("Elise", "Hinman", role="aut", email = "ehinman@usgs.gov", comment=c(ORCID = "0000-0001-5396-1583")), person("Michael", "Mahoney", role="ctb", diff --git a/NEWS b/NEWS index dd228539..3969ef0e 100644 --- a/NEWS +++ b/NEWS @@ -3,8 +3,10 @@ dataRetrieval 2.7.22 * Added read_waterdata_latest_daily to access latest daily USGS water data. * Added read_waterdata_continuous to access continuous USGS water data. * Added state_name and hydrologic_unit_code to read_waterdata_ts_meta -* Removed daily_id from read_waterdata_daily output. Currently it -is not stable over time. +* Removed daily_id from read_waterdata_daily output since it +is not stable over time. Moved other "id" columns to end of returned data frames. +* Changed examples for stateCd, countyCd, and parameterCdFile. Users are +encouraged to migreate to the "read_waterdata_metadata" functions. dataRetrieval 2.7.21 =================== diff --git a/R/AAA.R b/R/AAA.R index 489a3601..aed73232 100644 --- a/R/AAA.R +++ b/R/AAA.R @@ -12,7 +12,8 @@ pkg.env <- new.env() "continuous") collections <- c("parameter-codes", "agency-codes", "altitude-datums", "aquifer-codes", "aquifer-types", "coordinate-accuracy-codes", "coordinate-datum-codes", - "coordinate-method-codes", "medium-codes", + "coordinate-method-codes", "medium-codes", "counties", + "hydrologic-unit-codes", "states", "national-aquifer-codes", "reliability-codes", "site-types", "statistic-codes", "topographic-codes", "time-zone-codes") diff --git a/R/construct_api_requests.R b/R/construct_api_requests.R index cd678de5..72bf80d6 100644 --- a/R/construct_api_requests.R +++ b/R/construct_api_requests.R @@ -109,6 +109,17 @@ construct_api_requests <- function(service, } if(!all(is.na(properties))){ + available_properties <- property_list[[service]] + + if(!all(properties %in% available_properties)){ + # Check again: + schema <- check_OGC_requests(endpoint = service, type = "schema") + properties_fresh <- names(schema$properties) + if(!all(properties %in% properties_fresh)){ + stop("Invalid properties requested.") + } + } + baseURL <- httr2::req_url_query(baseURL, properties = properties, .multi = "comma") @@ -209,67 +220,52 @@ switch_arg_id <- function(ls, id_name, service){ #' Switch properties id #' +#' If a user asks for either "id" or "output_id", it is only included in the +#' properties if that's the only column requested. "id" will always come back, +#' so it is not needed in the properties call. +#' #' @noRd #' @return list #' @examples #' #' properties <- c("id", "state_name", "country_name") #' dataRetrieval:::switch_properties_id(properties, -#' id_name = "monitoring_location_id", -#' service = "monitoring-locations") +#' id = "monitoring_location_id") #' #' properties2 <- c("monitoring_location_id", "state_name", "country_name") #' dataRetrieval:::switch_properties_id(properties2, -#' id_name = "monitoring_location_id", -#' service = "monitoring-locations") +#' id = "monitoring_location_id") #' #' properties3 <- c("monitoring_locations_id", "state_name", "country_name") #' dataRetrieval:::switch_properties_id(properties3, -#' id_name = "monitoring_location_id", -#' service = "monitoring-locations") -switch_properties_id <- function(properties, id_name, service){ - - service_id <- paste0(gsub("-", "_", service), "_id") - - last_letter <- substr(service, nchar(service), nchar(service)) - if(last_letter == "s"){ - service_singluar <- substr(service,1, nchar(service)-1) - service_id_singular <- paste0(gsub("-", "_", service_singluar), "_id") - } else { - service_id_singular <- "" - } - - if(!"id" %in% properties){ - if(service_id %in% properties){ - properties[properties == service_id] <- "id" - - } else if(service_id_singular %in% properties) { - properties[properties == service_id_singular] <- "id" - } else { - properties[properties == id_name] <- "id" - } - } +#' id = "monitoring_location_id") +#' +#' properties4 <- c("monitoring_location_id") +#' dataRetrieval:::switch_properties_id(properties4, +#' id = "monitoring_location_id") +#' +#' properties5 <- c("monitoring_location_id", "geometry") +#' dataRetrieval:::switch_properties_id(properties5, +#' id = "monitoring_location_id") +#' +switch_properties_id <- function(properties, id){ + orig_properties <- properties if(!all(is.na(properties))){ - - schema <- check_OGC_requests(endpoint = service, - type = "schema") - all_properties <- names(schema$properties) - - if(all(all_properties[!all_properties %in% c("id", "geometry")] %in% properties)) { - # Cleans up URL if we're asking for everything - properties <- NA_character_ - } else { - properties <- gsub("-", "_", properties) - properties <- properties[!properties %in% c("id", - "geometry", - paste0(gsub("-", "_", service), "_id"))] + if("id" %in% properties){ + properties <- properties[properties != "id"] + } else if (id %in% properties){ + properties <- properties[properties != id] + } + if("geometry" %in% properties){ + properties <- properties[properties != "geometry"] } - if(!all(is.na(properties))){ - match.arg(properties, choices = all_properties, - several.ok = TRUE) + if(length(properties) == 0){ + # If a user requested only id and/or geometry, properties would now be empty + # geometry is taken care of with skipGeometry + properties <- "id" } } @@ -277,6 +273,41 @@ switch_properties_id <- function(properties, id_name, service){ } +order_results <- function(df){ + + if(all(c("time", "monitoring_location_id") %in% names(df))){ + df <- df[order(df$time, + df$monitoring_location_id), ] + } else if ("time" %in% names(df)) { + df <- df[order(df$time), ] + } + + return(df) +} + +move_id_col <- function(df, output_id){ + # attributes get dropped + req <- attr(df, "request") + queryTime <- attr(df, "queryTime") + + df <- df[, names(df)[names(df)!= output_id]] + if("time_series_id" %in% names(df)){ + df <- df[, c(names(df)[names(df)!= "time_series_id"], + "time_series_id")] + } + + if("field_visit_id" %in% names(df)){ + df <- df[, c(names(df)[names(df)!= "field_visit_id"], + "field_visit_id")] + } + + attr(df, "request") <- req + attr(df, "queryTime") <- queryTime + + return(df) +} + + #' Format the date request #' #' Users will want to give either start/end dates or @@ -617,3 +648,30 @@ get_params <- function(service){ params <- sapply(query_ret$properties, function(x) x[["description"]]) } + + +#' Get property list +#' +#' This function gets a list of available properties, and +#' renames the id column to what is used in dataRetrieval. +#' +#' @param service Character, can be any of the endpoints +#' @param output_id Character, dataRetrieval output name +#' @return list +#' @noRd +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' dataRetrieval:::get_properties_for_docs("monitoring-locations", +#' "monitoring_location_id") +#' +#' } +#' +get_properties_for_docs <- function(service, output_id){ + + schema <- check_OGC_requests(endpoint = service, type = "schema") + properties <- names(schema$properties) + properties[properties == "id"] <- output_id + return(paste(properties, collapse = ", ")) + +} diff --git a/R/dataRetrievals-package.R b/R/dataRetrievals-package.R index cdb8bdf1..c7f431df 100644 --- a/R/dataRetrievals-package.R +++ b/R/dataRetrievals-package.R @@ -58,8 +58,13 @@ token_message) #' #' @docType data #' @export parameterCdFile -#' @examples -#' head(parameterCdFile[, 1:2]) +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' # Please migrate to: +#' parameterCds <- read_waterdata_metadata("parameter-codes") +#' +#' } NULL @@ -113,8 +118,13 @@ NULL #' @docType data #' @export stateCd #' @keywords USGS stateCd -#' @examples -#' head(stateCd) +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' # Please migrate to: +#' stateCd <- read_waterdata_metadata("states") +#' +#' } NULL #' US County Code Lookup Table @@ -136,8 +146,13 @@ NULL #' @docType data #' @export countyCd #' @keywords USGS countyCd -#' @examples -#' head(countyCd) +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' # Please migrate to: +#' countyCd <- read_waterdata_metadata("counties") +#' +#' } NULL # nolint start: commented_code_linter @@ -190,4 +205,21 @@ NULL # # save(countyCd, stateCd, parameterCdFile, pCodeToName, # file = "R/sysdata.rda", compress = "xz") -# nolint end +# +# services <- c("daily", "time-series-metadata", +# "monitoring-locations", "latest-continuous", +# "field-measurements", "latest-daily", +# "continuous") +# +# property_list <- list() +# +# for(i in services){ +# schema <- check_OGC_requests(endpoint = i, type = "schema") +# properties <- names(schema$properties) +# property_list[[i]] <- properties +# } +# rm(schema, i, services, properties) +# save(countyCd, stateCd, parameterCdFile, pCodeToName, property_list, offsetLibrary, +# file = "R/sysdata.rda", compress = "xz") +# +# # nolint end \ No newline at end of file diff --git a/R/readNWISunit.R b/R/readNWISunit.R index cd300d67..387f0898 100644 --- a/R/readNWISunit.R +++ b/R/readNWISunit.R @@ -91,9 +91,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, diff --git a/R/read_waterdata_continuous.R b/R/read_waterdata_continuous.R index 0859c3a1..b43c90fd 100644 --- a/R/read_waterdata_continuous.R +++ b/R/read_waterdata_continuous.R @@ -23,7 +23,8 @@ #' Requesting anything else will most-likely cause a timeout. #' @param properties A vector of requested columns to be returned from the query. #' Available options are: -#' `r schema <- check_OGC_requests(endpoint = "continuous", type = "schema"); paste(names(schema$properties)[!names(schema$properties) %in% c("id", "internal_id")], collapse = ", ")` +#' `r dataRetrieval:::get_properties_for_docs("continuous", "continuous_id")`. +#' The default (`NA`) will return all columns of the data. #' @param limit The optional limit parameter is used to control the subset of the #' selected features that should be returned in each page. The maximum allowable #' limit is 50000. It may be beneficial to set this number lower if your internet @@ -87,27 +88,12 @@ read_waterdata_continuous <- function(monitoring_location_id = NA_character_, service) if(convertType){ - return_list <- order_results(return_list, properties) - return_list <- return_list[, names(return_list)[names(return_list)!= output_id]] - if("time_series_id" %in% names(return_list)){ - return_list <- return_list[, c( names(return_list)[names(return_list)!= "time_series_id"], - "time_series_id")] - } + return_list <- order_results(return_list) + return_list <- move_id_col(return_list, output_id) } return(return_list) } -order_results <- function(return_list, properties){ - - if(all(is.na(properties)) | - all(c("time", "monitoring_location_id") %in% properties)){ - return_list <- return_list[order(return_list$time, - return_list$monitoring_location_id), ] - } else if ("time" %in% properties) { - return_list <- return_list[order(return_list$time), ] - } - - return(return_list) -} + diff --git a/R/read_waterdata_daily.R b/R/read_waterdata_daily.R index 8359e7a9..a3a50213 100644 --- a/R/read_waterdata_daily.R +++ b/R/read_waterdata_daily.R @@ -15,7 +15,8 @@ #' @param qualifier `r get_params("daily")$qualifier` #' @param properties A vector of requested columns to be returned from the query. #' Available options are: -#' `r schema <- check_OGC_requests(endpoint = "daily", type = "schema"); paste(names(schema$properties)[!names(schema$properties) %in% c("id")], collapse = ", ")` +#' `r dataRetrieval:::get_properties_for_docs("daily", "daily_id")`. +#' The default (`NA`) will return all columns of the data. #' @param bbox Only features that have a geometry that intersects the bounding #' box are selected.The bounding box is provided as four or six numbers, depending #' on whether the coordinate reference system includes a vertical axis (height or @@ -93,12 +94,8 @@ read_waterdata_daily <- function(monitoring_location_id = NA_character_, service) if(convertType){ - return_list <- order_results(return_list, properties) - return_list <- return_list[,names(return_list)[names(return_list)!= output_id]] - if("time_series_id" %in% names(return_list)){ - return_list <- return_list[, c( names(return_list)[names(return_list)!= "time_series_id"], - "time_series_id")] - } + return_list <- order_results(return_list) + return_list <- move_id_col(return_list, output_id) } return(return_list) diff --git a/R/read_waterdata_field_measurements.R b/R/read_waterdata_field_measurements.R index 2f56377b..2be9ed0d 100644 --- a/R/read_waterdata_field_measurements.R +++ b/R/read_waterdata_field_measurements.R @@ -18,7 +18,8 @@ #' @param measuring_agency `r get_params("field-measurements")$measuring_agency` #' @param properties A vector of requested columns to be returned from the query. #' Available options are: -#' `r schema <- check_OGC_requests(endpoint = "field-measurements", type = "schema"); paste(names(schema$properties)[!names(schema$properties) %in% c("id")], collapse = ", ")` +#' `r dataRetrieval:::get_properties_for_docs("field-measurements", "field_measurement_id")`. +#' The default (`NA`) will return all columns of the data. #' @param bbox Only features that have a geometry that intersects the bounding #' box are selected.The bounding box is provided as four or six numbers, depending #' on whether the coordinate reference system includes a vertical axis (height or @@ -100,12 +101,8 @@ read_waterdata_field_measurements <- function(monitoring_location_id = NA_charac service) if(convertType){ - return_list <- order_results(return_list, properties) - return_list <- return_list[,names(return_list)[names(return_list)!= output_id]] - if("field_visit_id" %in% names(return_list)){ - return_list <- return_list[, c( names(return_list)[names(return_list)!= "field_visit_id"], - "field_visit_id")] - } + return_list <- order_results(return_list) + return_list <- move_id_col(return_list, output_id) } return(return_list) diff --git a/R/read_waterdata_latest_continuous.R b/R/read_waterdata_latest_continuous.R index 8b95386d..7f72f928 100644 --- a/R/read_waterdata_latest_continuous.R +++ b/R/read_waterdata_latest_continuous.R @@ -17,7 +17,8 @@ #' Requesting anything else will most-likely cause a timeout. #' @param properties A vector of requested columns to be returned from the query. #' Available options are: -#' `r schema <- check_OGC_requests(endpoint = "latest-continuous", type = "schema"); paste(names(schema$properties)[!names(schema$properties) %in% c("id")], collapse = ", ")` +#' `r dataRetrieval:::get_properties_for_docs("latest-continuous", "latest_continuous_id")`. +#' The default (`NA`) will return all columns of the data. #' @param bbox Only features that have a geometry that intersects the bounding #' box are selected.The bounding box is provided as four or six numbers, depending #' on whether the coordinate reference system includes a vertical axis (height or @@ -96,12 +97,8 @@ read_waterdata_latest_continuous <- function(monitoring_location_id = NA_charact service) if(convertType){ - return_list <- order_results(return_list, properties) - return_list <- return_list[, names(return_list)[names(return_list)!= output_id]] - if("time_series_id" %in% names(return_list)){ - return_list <- return_list[, c( names(return_list)[names(return_list)!= "time_series_id"], - "time_series_id")] - } + return_list <- order_results(return_list) + return_list <- move_id_col(return_list, output_id) } return(return_list) diff --git a/R/read_waterdata_latest_daily.R b/R/read_waterdata_latest_daily.R index 5e98cc78..46a21ab0 100644 --- a/R/read_waterdata_latest_daily.R +++ b/R/read_waterdata_latest_daily.R @@ -15,7 +15,8 @@ #' @param qualifier `r get_params("latest-daily")$qualifier` #' @param properties A vector of requested columns to be returned from the query. #' Available options are: -#' `r schema <- check_OGC_requests(endpoint = "latest-daily", type = "schema"); paste(names(schema$properties)[!names(schema$properties) %in% c("id")], collapse = ", ")` +#' `r dataRetrieval:::get_properties_for_docs("latest-daily", "latest_daily_id")`. +#' The default (`NA`) will return all columns of the data. #' @param bbox Only features that have a geometry that intersects the bounding #' box are selected.The bounding box is provided as four or six numbers, depending #' on whether the coordinate reference system includes a vertical axis (height or @@ -87,12 +88,8 @@ read_waterdata_latest_daily <- function(monitoring_location_id = NA_character_, service) if(convertType){ - return_list <- order_results(return_list, properties) - return_list <- return_list[,names(return_list)[names(return_list)!= output_id]] - if("time_series_id" %in% names(return_list)){ - return_list <- return_list[, c( names(return_list)[names(return_list)!= "time_series_id"], - "time_series_id")] - } + return_list <- order_results(return_list) + return_list <- move_id_col(return_list, output_id) } return(return_list) } diff --git a/R/read_waterdata_metadata.R b/R/read_waterdata_metadata.R index 4b617043..54d54d10 100644 --- a/R/read_waterdata_metadata.R +++ b/R/read_waterdata_metadata.R @@ -39,14 +39,8 @@ read_waterdata_metadata <- function(collection, max_results = NA, limit = NA){ - - available <- c("parameter-codes", "agency-codes", "altitude-datums", "aquifer-codes", - "aquifer-types", "coordinate-accuracy-codes", "coordinate-datum-codes", - "coordinate-method-codes", "hydrologic-unit-codes", "medium-codes", - "national-aquifer-codes", "reliability-codes", "site-types", "statistic-codes", - "topographic-codes", "time-zone-codes") - match.arg(collection, available) + match.arg(collection, pkg.env$metadata) output_id <- gsub("-", "_", collection) last_letter <- substr(output_id, diff --git a/R/read_waterdata_monitoring_location.R b/R/read_waterdata_monitoring_location.R index 77d9fb2c..50baa84f 100644 --- a/R/read_waterdata_monitoring_location.R +++ b/R/read_waterdata_monitoring_location.R @@ -45,7 +45,8 @@ #' @param depth_source_code `r get_params("monitoring-locations")$depth_source_code` #' @param properties A vector of requested columns to be returned from the query. #' Available options are: -#' `r schema <- check_OGC_requests(endpoint = "monitoring-locations", type = "schema"); paste(names(schema$properties), collapse = ", ")`. +#' `r dataRetrieval:::get_properties_for_docs("monitoring-locations", "monitoring_location_id")`. +#' The default (`NA`) will return all columns of the data. #' @param bbox Only features that have a geometry that intersects the bounding #' box are selected.The bounding box is provided as four or six numbers, depending #' on whether the coordinate reference system includes a vertical axis (height or diff --git a/R/read_waterdata_parameter_codes.R b/R/read_waterdata_parameter_codes.R index f9f59e18..a04c53ba 100644 --- a/R/read_waterdata_parameter_codes.R +++ b/R/read_waterdata_parameter_codes.R @@ -16,7 +16,8 @@ #' @param epa_equivalence `r get_params("parameter-codes")$epa_equivalence` #' @param properties A vector of requested columns to be returned from the query. #' Available options are: -#' `r schema <- check_OGC_requests(endpoint = "parameter-codes", type = "schema"); paste(names(schema$properties), collapse = ", ")`. +#' `r dataRetrieval:::get_properties_for_docs("parameter-codes", "parameter_code_id")`. +#' The default (`NA`) will return all columns of the data. #' @param limit The optional limit parameter is used to control the subset of the #' selected features that should be returned in each page. The maximum allowable #' limit is 50000. It may be beneficial to set this number lower if your internet diff --git a/R/read_waterdata_ts_meta.R b/R/read_waterdata_ts_meta.R index 7f5be9c8..89442690 100644 --- a/R/read_waterdata_ts_meta.R +++ b/R/read_waterdata_ts_meta.R @@ -22,7 +22,8 @@ #' @param web_description `r get_params("time-series-metadata")$web_description` #' @param properties A vector of requested columns to be returned from the query. #' Available options are: -#' `r schema <- check_OGC_requests(endpoint = "time-series-metadata", type = "schema"); paste(names(schema$properties)[!names(schema$properties) %in% c("id")], collapse = ", ")` +#' `r dataRetrieval:::get_properties_for_docs("time-series-metadata", "time_series_id")`. +#' The default (`NA`) will return all columns of the data. #' @param time_series_id `r get_params("time-series-metadata")$id` #' @param bbox Only features that have a geometry that intersects the bounding #' box are selected.The bounding box is provided as four or six numbers, depending diff --git a/R/sysdata.rda b/R/sysdata.rda index e9befca0..2a50d5aa 100644 Binary files a/R/sysdata.rda and b/R/sysdata.rda differ diff --git a/R/walk_pages.R b/R/walk_pages.R index f5375c41..d7ca6c7a 100644 --- a/R/walk_pages.R +++ b/R/walk_pages.R @@ -98,13 +98,6 @@ rejigger_cols <- function(df, properties, output_id){ if(!"id" %in% properties){ if(output_id %in% properties){ names(df)[(names(df) == "id")] <- output_id - } else { - # just in case users become aware of the singular/plural issue - # where the endpoint name is plural, but input to other endpoints are singular - plural <- gsub("_id", "s_id", output_id) - if(plural %in% properties){ - names(df)[(names(df) == "id")] <- plural - } } } df <- df[, properties] @@ -186,6 +179,11 @@ next_req_url <- function(resp, req) { body <- httr2::resp_body_json(resp) + if(isTRUE(body[["code"]] == "InvalidQuery")){ + message(body[["description"]]) + return(NULL) + } + if(isTRUE(body[["numberReturned"]] == 0)){ return(NULL) } @@ -252,16 +250,13 @@ walk_pages <- function(req, max_results){ if(is.na(max_results)){ resps <- httr2::req_perform_iterative(req, next_req = next_req_url, - max_reqs = Inf) - ###################################### - # So far I haven't tested this because I haven't had - # individual failures + max_reqs = Inf, on_error = "return") failures <- resps |> httr2::resps_failures() |> httr2::resps_requests() if(length(failures) > 0){ - message("There were", length(failures), "failed requests.") + stop(resps[[1]][["message"]]) } return_list <- data.frame() @@ -301,8 +296,7 @@ get_ogc_data <- function(args, properties <- args[["properties"]] args[["properties"]] <- switch_properties_id(properties, - id_name = output_id, - service = service) + id = output_id) convertType <- args[["convertType"]] args[["convertType"]] <- NULL @@ -328,6 +322,7 @@ get_ogc_data <- function(args, attr(return_list, "request") <- req attr(return_list, "queryTime") <- Sys.time() - return(return_list) + return_list } + diff --git a/inst/CITATION b/inst/CITATION index 026d9ef6..a6f2aa60 100644 --- a/inst/CITATION +++ b/inst/CITATION @@ -24,12 +24,11 @@ bibentry(bibtype = "Manual", email = "akrall@usgs.gov", comment=c(ORCID = "0000-0003-2521-5043")), person("Lee", "Stanish", role="ctb", - email = "lstanish@usgs.gov", comment=c(ORCID = "0000-0002-9775-6861")), person("Joeseph", "Zemmels", role="ctb", email = "jzemmels@usgs.gov", comment=c(ORCID = "0009-0008-1463-6313")), - person("Elise", "Hinman", role="ctb", + person("Elise", "Hinman", role="aut", email = "ehinman@usgs.gov", comment=c(ORCID = "0000-0001-5396-1583")), person("Michael", "Mahoney", role="ctb", @@ -39,7 +38,7 @@ bibentry(bibtype = "Manual", title = "dataRetrieval: R packages for discovering and retrieving water data available from U.S. federal hydrologic web services", publisher = "U.S. Geological Survey", address="Reston, VA", - version = "2.7.21", + version = "2.7.22", institution = "U.S. Geological Survey", year = 2025, doi = "10.5066/P9X4L3GE", diff --git a/man/countyCd.Rd b/man/countyCd.Rd index af1ed628..ac2f93ee 100644 --- a/man/countyCd.Rd +++ b/man/countyCd.Rd @@ -21,7 +21,14 @@ Classic lookup table for counties. Has been replaced in functions with \code{check_waterdata_sample_params("counties")}. } \examples{ -head(countyCd) +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +# Please migrate to: +countyCd <- read_waterdata_metadata("counties") + +} +\dontshow{\}) # examplesIf} } \keyword{USGS} \keyword{countyCd} diff --git a/man/parameterCdFile.Rd b/man/parameterCdFile.Rd index 99d82bcc..40c5bc04 100644 --- a/man/parameterCdFile.Rd +++ b/man/parameterCdFile.Rd @@ -21,5 +21,12 @@ parameter_units \tab character \tab Parameter units\cr Complete list of USGS parameter codes as of Oct. 24, 2024. } \examples{ -head(parameterCdFile[, 1:2]) +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +# Please migrate to: +parameterCds <- read_waterdata_metadata("parameter-codes") + +} +\dontshow{\}) # examplesIf} } diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index 489127b2..7dba7ea7 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -28,7 +28,8 @@ read_waterdata_continuous( \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified} +geometry, continuous_id, internal_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint.} diff --git a/man/read_waterdata_daily.Rd b/man/read_waterdata_daily.Rd index a626f248..c4cd3afa 100644 --- a/man/read_waterdata_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -32,7 +32,8 @@ read_waterdata_daily( \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified} +geometry, daily_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint.} diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index c4eaf201..766013cc 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -35,7 +35,8 @@ read_waterdata_field_measurements( \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified} +geometry, field_measurement_id, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified. +The default (\code{NA}) will return all columns of the data.} \item{field_visit_id}{A universally unique identifier (UUID) for the field visit. Multiple measurements may be made during a single field visit.} diff --git a/man/read_waterdata_latest_continuous.Rd b/man/read_waterdata_latest_continuous.Rd index 6317e6f0..9621be68 100644 --- a/man/read_waterdata_latest_continuous.Rd +++ b/man/read_waterdata_latest_continuous.Rd @@ -35,7 +35,8 @@ Requesting anything else will most-likely cause a timeout.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified} +geometry, latest_continuous_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint.} diff --git a/man/read_waterdata_latest_daily.Rd b/man/read_waterdata_latest_daily.Rd index e6f12602..2f55490a 100644 --- a/man/read_waterdata_latest_daily.Rd +++ b/man/read_waterdata_latest_daily.Rd @@ -32,7 +32,8 @@ read_waterdata_latest_daily( \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified} +geometry, latest_daily_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint.} diff --git a/man/read_waterdata_monitoring_location.Rd b/man/read_waterdata_monitoring_location.Rd index b9fba111..e45ad160 100644 --- a/man/read_waterdata_monitoring_location.Rd +++ b/man/read_waterdata_monitoring_location.Rd @@ -135,7 +135,8 @@ read_waterdata_monitoring_location( \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, id, agency_code, agency_name, monitoring_location_number, monitoring_location_name, district_code, country_code, country_name, state_code, state_name, county_code, county_name, minor_civil_division_code, site_type_code, site_type, hydrologic_unit_code, basin_code, altitude, altitude_accuracy, altitude_method_code, altitude_method_name, vertical_datum, vertical_datum_name, horizontal_positional_accuracy_code, horizontal_positional_accuracy, horizontal_position_method_code, horizontal_position_method_name, original_horizontal_datum, original_horizontal_datum_name, drainage_area, contributing_drainage_area, time_zone_abbreviation, uses_daylight_savings, construction_date, aquifer_code, national_aquifer_code, aquifer_type_code, well_constructed_depth, hole_constructed_depth, depth_source_code.} +geometry, monitoring_location_id, agency_code, agency_name, monitoring_location_number, monitoring_location_name, district_code, country_code, country_name, state_code, state_name, county_code, county_name, minor_civil_division_code, site_type_code, site_type, hydrologic_unit_code, basin_code, altitude, altitude_accuracy, altitude_method_code, altitude_method_name, vertical_datum, vertical_datum_name, horizontal_positional_accuracy_code, horizontal_positional_accuracy, horizontal_position_method_code, horizontal_position_method_name, original_horizontal_datum, original_horizontal_datum_name, drainage_area, contributing_drainage_area, time_zone_abbreviation, uses_daylight_savings, construction_date, aquifer_code, national_aquifer_code, aquifer_type_code, well_constructed_depth, hole_constructed_depth, depth_source_code. +The default (\code{NA}) will return all columns of the data.} \item{bbox}{Only features that have a geometry that intersects the bounding box are selected.The bounding box is provided as four or six numbers, depending diff --git a/man/read_waterdata_parameter_codes.Rd b/man/read_waterdata_parameter_codes.Rd index 33970972..7fb569c0 100644 --- a/man/read_waterdata_parameter_codes.Rd +++ b/man/read_waterdata_parameter_codes.Rd @@ -46,7 +46,8 @@ read_waterdata_parameter_codes( \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, id, parameter_name, unit_of_measure, parameter_group_code, parameter_description, medium, statistical_basis, time_basis, weight_basis, particle_size_basis, sample_fraction, temperature_basis, epa_equivalence.} +geometry, parameter_code_id, parameter_name, unit_of_measure, parameter_group_code, parameter_description, medium, statistical_basis, time_basis, weight_basis, particle_size_basis, sample_fraction, temperature_basis, epa_equivalence. +The default (\code{NA}) will return all columns of the data.} \item{limit}{The optional limit parameter is used to control the subset of the selected features that should be returned in each page. The maximum allowable diff --git a/man/read_waterdata_ts_meta.Rd b/man/read_waterdata_ts_meta.Rd index eaad9fd4..9642b537 100644 --- a/man/read_waterdata_ts_meta.Rd +++ b/man/read_waterdata_ts_meta.Rd @@ -40,7 +40,8 @@ read_waterdata_ts_meta( \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, unit_of_measure, parameter_name, parameter_code, statistic_id, hydrologic_unit_code, state_name, last_modified, begin, end, begin_utc, end_utc, computation_period_identifier, computation_identifier, thresholds, sublocation_identifier, primary, monitoring_location_id, web_description, parameter_description, parent_time_series_id} +geometry, time_series_id, unit_of_measure, parameter_name, parameter_code, statistic_id, hydrologic_unit_code, state_name, last_modified, begin, end, begin_utc, end_utc, computation_period_identifier, computation_identifier, thresholds, sublocation_identifier, primary, monitoring_location_id, web_description, parameter_description, parent_time_series_id. +The default (\code{NA}) will return all columns of the data.} \item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://help.waterdata.usgs.gov/code/stat_cd_nm_query?stat_nm_cd=\%25&fmt=html}.} diff --git a/man/stateCd.Rd b/man/stateCd.Rd index b8eaea3d..51f2e3d7 100644 --- a/man/stateCd.Rd +++ b/man/stateCd.Rd @@ -20,7 +20,14 @@ Classic lookup table for states. Has been replaced in functions with \code{check_waterdata_sample_params("states")}. } \examples{ -head(stateCd) +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +# Please migrate to: +stateCd <- read_waterdata_metadata("states") + +} +\dontshow{\}) # examplesIf} } \keyword{USGS} \keyword{stateCd} diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index e515e773..2831d83b 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -527,3 +527,14 @@ test_that("pCode Stuff", { ) }) +context("Smart Errors") +test_that("bad_properties", { + testthat::skip_on_cran() + testthat::skip_on_ci() + + expect_error(read_waterdata_daily(monitoring_location_id = "USGS-02238500", + parameter_code = c("00010"), + time = c("2021-01-01", "2022-01-01"), + properties = c("value", "time", "blah"))) +}) + diff --git a/vignettes/read_waterdata_functions.Rmd b/vignettes/read_waterdata_functions.Rmd index f8feda77..27d7b13d 100644 --- a/vignettes/read_waterdata_functions.Rmd +++ b/vignettes/read_waterdata_functions.Rmd @@ -433,6 +433,15 @@ coordinate_datum_codes <- read_waterdata_metadata("coordinate-datum-codes") coordinate_method_codes <- read_waterdata_metadata("coordinate-method-codes") ``` +### County Identifiers + +`r dataRetrieval:::get_description("counties")` + +```{r} +#| eval: false +counties <- read_waterdata_metadata("counties") +``` + ### Hydrologic Unit Codes `r dataRetrieval:::get_description("hydrologic-unit-codes")` @@ -488,6 +497,25 @@ reliability_codes <- read_waterdata_metadata("reliability-codes") site_types <- read_waterdata_metadata("site-types") ``` +### State Identifiers + +`r dataRetrieval:::get_description("states")` + +```{r} +#| eval: false +states <- read_waterdata_metadata("states") +``` + +### Statistic Codes + +`r dataRetrieval:::get_description("statistic-codes")` + +```{r} +#| eval: false +statistic_codes <- read_waterdata_metadata("statistic-codes") +``` + + ### Topographic Codes `r dataRetrieval:::get_description("topographic-codes")` @@ -497,7 +525,7 @@ site_types <- read_waterdata_metadata("site-types") topographic_codes <- read_waterdata_metadata("topographic-codes") ``` -### Topographic Codes +### Time Zone Codes `r dataRetrieval:::get_description("time-zone-codes")`