diff --git a/DESCRIPTION b/DESCRIPTION index f9ba7fdf..101d0fc5 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.25 +Version: 2.7.25.9000 Authors@R: c( person("Laura", "DeCicco", role = c("aut","cre"), email = "ldecicco@usgs.gov", diff --git a/NAMESPACE b/NAMESPACE index 5db89fe8..9b96ffa7 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -43,6 +43,12 @@ export(readWQPdata) export(readWQPqw) export(readWQPsummary) export(read_USGS_samples) +export(read_ngwmn) +export(read_ngwmn_lithology) +export(read_ngwmn_providers) +export(read_ngwmn_sites) +export(read_ngwmn_water_level) +export(read_ngwmn_well_construction) export(read_waterdata) export(read_waterdata_channel) export(read_waterdata_combined_meta) diff --git a/NEWS b/NEWS index 6795c745..a4ccbe0c 100644 --- a/NEWS +++ b/NEWS @@ -32,27 +32,27 @@ return full period of record. dataRetrieval 2.7.23 =================== -* Added data.table to Imports + * Added read_waterdata_stats_por and read_waterdata_stats_daterange to access USGS daily data statistics. -* Updated vignettes, examples, and README to reflect new stats functions. -* Added tests for read_waterdata_stats functions +* Added read_waterdata_field_meta, read_waterdata_combine_meta, and read_waterdata_channel +* Added read_ngwmn_water_levels, read_ngwmn_sites, read_ngwmn_providers, read_ngwmn_well_construction, read_ngwmn_lithology +* Removed readNWISgwl, readNWISmeas, and readNGWMN as services have been turned off +* Added data.table to Imports * Updated next_req_url to allow paging through /statistics API output * Added deprecation message to readNWISstat function -* Specify "UTC" attribute for returned time +* Improved time documentation for waterdata functions +* Specify "UTC" attribute for returned time for waterdata functinos * Added options("dataRetrieval.attach_request" = TRUE) as default to attach the request object as an attribute to the returned data frames. Setting options("dataRetrieval.attach_request" = FALSE) will return a data frame without the request attribute -* Improved time documentation * Improved error handling in WQP functions -* Added read_waterdata_field_meta, read_waterdata_combine_meta, -and read_waterdata_channel -* Removed readNWISgwl and readNWISmeas as services have been turned off * Updated CQL2 templates to allow HUC queries specifically to use a wildcard to get multiple inclusive HUCs. * Add deprecation message to readNGWMN functions. read_ngwmn will be coming soon. + dataRetrieval 2.7.22 =================== * Added read_waterdata_latest_daily to access latest daily USGS water data. diff --git a/R/AAA.R b/R/AAA.R index ac8fa366..ad96e464 100644 --- a/R/AAA.R +++ b/R/AAA.R @@ -78,6 +78,7 @@ pkg.env <- new.env() "time_zone_code" ) + num_cols <- c() pkg.env$api_endpoints <- services pkg.env$metadata <- collections } diff --git a/R/construct_api_requests.R b/R/construct_api_requests.R index 9ed7f554..a00d787e 100644 --- a/R/construct_api_requests.R +++ b/R/construct_api_requests.R @@ -43,6 +43,7 @@ construct_api_requests <- function( output_id, ..., bbox = NA, + base = "OGC", convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), chunk_size = getOption("dataRetrieval.site_chunk_size_data"), @@ -92,13 +93,7 @@ construct_api_requests <- function( } single_params <- c( - "datetime", - "last_modified", - "begin", - "end", - "time", - "begin_utc", - "end_utc", + time_periods, "limit", "skipGeometry" ) @@ -159,7 +154,7 @@ construct_api_requests <- function( format_type <- ifelse(isTRUE(no_paging), "csv", "json") - baseURL <- setup_api(service, format = format_type) + baseURL <- setup_api(service, format = format_type, base = base) baseURL <- explode_query(baseURL, POST = FALSE, get_list, multi = "comma") if (all(!is.na(bbox))) { @@ -235,6 +230,7 @@ construct_api_requests <- function( #' Setup the request for the OGC API requests #' #' @noRd +#' @param base Character OGC or NGWMN #' @return httr2 request #' @examplesIf is_dataRetrieval_user() #' @@ -242,9 +238,17 @@ construct_api_requests <- function( #' request <- dataRetrieval:::base_url() #' request #' } -base_url <- function() { - httr2::request("https://api.waterdata.usgs.gov/ogcapi/") |> - httr2::req_url_path_append(getOption("dataRetrieval.api_version")) +base_url <- function(base = "OGC") { + match.arg(base, c("OGC", "NGWMN")) + + if (base == "OGC") { + baseURL <- httr2::request("https://api.waterdata.usgs.gov/ogcapi/") |> + httr2::req_url_path_append(getOption("dataRetrieval.api_version")) + } else { + baseURL <- httr2::request( + "https://api.waterdata.usgs.gov/ngwmn/ogcapi/" + ) + } } #' Setup the request for a particular endpoint collection @@ -257,8 +261,8 @@ base_url <- function() { #' request <- dataRetrieval:::setup_api("daily") #' request #' } -setup_api <- function(service, format = "json") { - baseURL <- base_url() |> +setup_api <- function(service, format = "json", base = "OGC") { + baseURL <- base_url(base) |> httr2::req_url_path_append("collections") |> httr2::req_url_path_append(service, "items") |> basic_request(format = format) diff --git a/R/dataRetrieval-package.R b/R/dataRetrieval-package.R index de5ae89e..0f0d1da4 100644 --- a/R/dataRetrieval-package.R +++ b/R/dataRetrieval-package.R @@ -208,14 +208,15 @@ NULL # "field-measurements", "latest-daily", # "continuous", "field-measurements-metadata", # "combined-metadata", "channel-measurements", "peaks") -# +# # property_list <- list() # for(service in services){ # property_list[[service]] <- dataRetrieval:::get_properties_for_docs(service) # } # # num_cols <- c("value", "contributing_drainage_area", "drainage_area", -# "altitude_accuracy", "well_construction_depth", +# #"altitude_accuracy", +# "well_construction_depth", # "hole_construction_depth", "channel_flow", "channel_width", # "channel_area", "channel_velocity", "channel_location_distance") # diff --git a/R/deal_with_empty.R b/R/deal_with_empty.R index 1170845b..30b05eb0 100644 --- a/R/deal_with_empty.R +++ b/R/deal_with_empty.R @@ -6,6 +6,7 @@ #' as "daily", "monitoring-locations", "time-series-metadata" #' @param skipGeometry A logical for whether to return geometry #' @param convertType A logical for whether to convert value to numeric +#' @param base character, either "OGC" or "NGWMN" depending on data. #' #' @return data.frame #' @noRd @@ -25,18 +26,31 @@ deal_with_empty <- function( service, skipGeometry, convertType, - no_paging = FALSE + no_paging = FALSE, + base = "OGC" ) { if (nrow(return_list) == 0) { if (all(is.na(properties))) { - schema <- check_OGC_requests(endpoint = service, type = "schema") + schema <- check_OGC_requests( + endpoint = service, + type = "schema", + base = base + ) properties <- names(schema$properties) } return_list <- data.frame(matrix(nrow = 0, ncol = length(properties))) return_list <- lapply(return_list, as.character) names(return_list) <- properties - single_params <- c("datetime", "last_modified", "begin", "end", "time") + single_params <- c( + "datetime", + "last_modified", + "begin", + "end", + "time", + "datetime", + "sample_time" + ) for (i in single_params) { if (i %in% names(return_list)) { diff --git a/R/get_ogc_data.R b/R/get_ogc_data.R index 89ebb630..4b01df23 100644 --- a/R/get_ogc_data.R +++ b/R/get_ogc_data.R @@ -6,7 +6,7 @@ #' #' @noRd #' @return data.frame with attributes -get_ogc_data <- function(args, output_id, service) { +get_ogc_data <- function(args, output_id, service, base = "OGC") { chunk_size <- args[["chunk_size"]] args[["..."]] <- NULL @@ -20,7 +20,12 @@ get_ogc_data <- function(args, output_id, service) { rl <- lapply(ml_splits, function(x) { args[["monitoring_location_id"]] <- x - get_ogc_data(args = args, output_id = output_id, service = service) + get_ogc_data( + args = args, + output_id = output_id, + service = service, + base = base + ) }) rl_filtered <- rl[ @@ -35,6 +40,7 @@ get_ogc_data <- function(args, output_id, service) { } else { args[["output_id"]] <- output_id args[["service"]] <- service + args[["base"]] <- base req <- do.call(construct_api_requests, args) @@ -48,13 +54,13 @@ get_ogc_data <- function(args, output_id, service) { return_list <- walk_pages(req) } - return_list <- deal_with_empty( - return_list, - args[["properties"]], - service, - isTRUE(args[["skipGeometry"]]), - args[["convertType"]], - no_paging + return_list <- deal_with_empty(return_list = return_list, + properties = args[["properties"]], + service = service, + skipGeometry = isTRUE(args[["skipGeometry"]]), + convertType = args[["convertType"]], + no_paging = no_paging, + base = base ) return_list <- rejigger_cols(return_list, args[["properties"]], output_id) diff --git a/R/get_ogc_documentation.R b/R/get_ogc_documentation.R index c4474f16..dc29866a 100644 --- a/R/get_ogc_documentation.R +++ b/R/get_ogc_documentation.R @@ -3,6 +3,7 @@ #' This function populates the parameter descriptions. #' #' @param service Character, can be any of the endpoints +#' @param base Character, can be "OGC" or "NGWMN" #' @return list #' @noRd #' @examplesIf is_dataRetrieval_user() @@ -10,10 +11,13 @@ #' \donttest{ #' ml_desc <- dataRetrieval:::get_description("monitoring-locations") #' ml_desc +#' +#' wl_desc <- dataRetrieval:::get_description("waterLevelObs", base = "NGWMN") +#' wl_desc #' } #' -get_description <- function(service) { - query_ret <- get_collection() +get_description <- function(service, base = "OGC") { + query_ret <- get_collection(base) tags <- query_ret[["tags"]] @@ -36,8 +40,8 @@ get_description <- function(service) { #' collection #' } #' -get_collection <- function() { - check_collections <- base_url() |> +get_collection <- function(base = "OGC") { + check_collections <- base_url(base = base) |> httr2::req_url_path_append("openapi") |> httr2::req_url_query(f = "html#/server/getCollections") @@ -55,6 +59,7 @@ get_collection <- function() { #' available, it will also contain a description. #' #' @param service Character, can be any of the USGS Waterdata API endpoints or collections. +#' @param base Either "OGC" for waterdata, or "NGWMN" for National Groundwater Monitoring Network. #' @return list #' @export #' @examplesIf is_dataRetrieval_user() @@ -64,8 +69,8 @@ get_collection <- function() { #' ml$national_aquifer_code #' } #' -get_ogc_params <- function(service) { - check_queryables_req <- base_url() |> +get_ogc_params <- function(service, base = "OGC") { + check_queryables_req <- base_url(base) |> httr2::req_url_path_append("collections") |> httr2::req_url_path_append(service) |> httr2::req_url_path_append("schema") |> @@ -74,7 +79,13 @@ get_ogc_params <- function(service) { query_ret <- httr2::req_perform(check_queryables_req) |> httr2::resp_body_json() - params <- sapply(query_ret$properties, function(x) x[["description"]]) + if (base == "OGC") { + params <- sapply(query_ret$properties, function(x) x[["description"]]) + } else if (base == "NGWMN") { + params <- query_ret$properties + } + + params } @@ -85,6 +96,7 @@ get_ogc_params <- function(service) { #' #' @param service Character, can be any of the endpoints #' @param output_id Character, dataRetrieval output name +#' @param base Character, either "OGC" or "NGWMN" #' @return list #' @noRd #' @examplesIf is_dataRetrieval_user() @@ -93,10 +105,14 @@ get_ogc_params <- function(service) { #' dataRetrieval:::get_properties_for_docs("monitoring-locations", #' "monitoring_location_id") #' +#' dataRetrieval:::get_properties_for_docs("waterLevelObs", +#' base = "NGWMN") +#' #' } #' -get_properties_for_docs <- function(service, output_id = NA) { - schema <- check_OGC_requests(endpoint = service, type = "schema") +get_properties_for_docs <- function(service, output_id = NA, base = "OGC") { + schema <- check_OGC_requests(endpoint = service, type = "schema", base = base) + properties <- names(schema$properties) if (!is.na(output_id)) { properties[properties == "id"] <- output_id @@ -109,6 +125,7 @@ get_properties_for_docs <- function(service, output_id = NA) { #' #' @param endpoint Character, can be any existing collection #' @param type Character, can be "queryables", "schema" +#' @param base Character, can be "OGC" or "NGWMN" #' @export #' @keywords internal #' @return list @@ -124,13 +141,24 @@ get_properties_for_docs <- function(service, output_id = NA) { #' type = "queryables") #' ts_meta_schema <- check_OGC_requests(endpoint = "time-series-metadata", #' type = "schema") +#' +#' ngwml <- check_OGC_requests(endpoint = "waterLevelObs", +#' type = "schema", +#' base = "NGWMN") #' } -check_OGC_requests <- function(endpoint = "daily", type = "queryables") { +check_OGC_requests <- function( + endpoint = "daily", + type = "queryables", + base = "OGC" +) { match.arg(type, c("queryables", "schema")) + match.arg(base, c("OGC", "NGWMN")) - match.arg(endpoint, c(pkg.env$api_endpoints, pkg.env$metadata)) + if (base == "OGC") { + match.arg(endpoint, c(pkg.env$api_endpoints, pkg.env$metadata)) + } - req <- base_url() |> + req <- base_url(base) |> httr2::req_url_path_append("collections") |> httr2::req_url_path_append(endpoint) |> httr2::req_url_path_append(type) |> diff --git a/R/importNGWMN_wml2.R b/R/importNGWMN_wml2.R index f35d4bca..0b2fcec1 100644 --- a/R/importNGWMN_wml2.R +++ b/R/importNGWMN_wml2.R @@ -32,6 +32,13 @@ #' } #' importNGWMN <- function(input, asDateTime = FALSE, tz = "UTC") { + + .Deprecated( + new = "read_ngwmn_water_level", + package = "dataRetrieval", + msg = "Updated NGWMN APIs will use read_ngwmn set of functions." + ) + if (tz != "") { tz <- match.arg(tz, OlsonNames()) } else { diff --git a/R/readNGWMNdata.R b/R/readNGWMNdata.R index 5c01cecd..f9c9a621 100644 --- a/R/readNGWMNdata.R +++ b/R/readNGWMNdata.R @@ -12,37 +12,11 @@ #' "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also `OlsonNames()` #' for more information on time zones. #' @export -#' @examplesIf is_dataRetrieval_user() -#' \donttest{ -#' # one site -#' site <- "USGS.430427089284901" -#' #oneSite <- readNGWMNdata(siteNumbers = site, service = "observation") -#' -#' # multiple sites -#' sites <- c("USGS.272838082142201", "USGS.404159100494601", "USGS.401216080362703") -#' # Very slow: -#' # multiSiteData <- readNGWMNdata(siteNumbers = sites, service = "observation") -#' # attributes(multiSiteData) -#' -#' # non-USGS site -#' # accepts colon or period between agency and ID -#' site <- "MBMG:702934" -#' # data <- readNGWMNdata(siteNumbers = site, service = "featureOfInterest") -#' -#' # bounding box -#' # bboxSites <- readNGWMNdata(service = "featureOfInterest", bbox = c(30, -102, 31, 99)) -#' # retrieve sites. Set asDateTime to false since one site has an invalid date -#' # Very slow: -#' # bboxData <- readNGWMNdata(service = "observation", siteNumbers = bboxSites$site[1:3], -#' # asDateTime = FALSE) -#' } -#' readNGWMNdata <- function(service, ..., asDateTime = TRUE, tz = "UTC") { .Deprecated( - "", - msg = "read_ngwmn_data coming soon. Check back at - https://doi-usgs.github.io/dataRetrieval/articles/Status.html - for more information" + new = "read_ngwmn_water_level", + package = "dataRetrieval", + msg = "Updated NGWMN APIs will use read_ngwmn set of functions." ) dots <- convertLists(...) @@ -64,7 +38,10 @@ readNGWMNdata <- function(service, ..., asDateTime = TRUE, tz = "UTC") { attr_list <- vector("list", length(featureID)) for (idx in seq_along(featureID)) { obsFID <- retrieveObservation( - featureID = featureID[idx], asDateTime, attrs, tz = tz + featureID = featureID[idx], + asDateTime, + attrs, + tz = tz ) attr_list[[idx]] <- saveAttrs(attrs, obsFID) obs_list[[idx]] <- removeAttrs(attrs, obsFID) @@ -120,25 +97,6 @@ readNGWMNdata <- function(service, ..., asDateTime = TRUE, tz = "UTC") { #' "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also `OlsonNames()` #' for more information on time zones. #' @export -#' -#' @examplesIf is_dataRetrieval_user() -#' \donttest{ -#' # one site -#' site <- "USGS.430427089284901" -#' # oneSite <- readNGWMNlevels(siteNumbers = site) -#' -#' # multiple sites -#' sites <- c("USGS:272838082142201", "USGS:404159100494601", "USGS:401216080362703") -#' # multiSiteData <- readNGWMNlevels(sites) -#' -#' # non-USGS site -#' site <- "MBMG.103306" -#' # data <- readNGWMNlevels(siteNumbers = site, asDateTime = FALSE) -#' -#' # site with no data returns empty data frame -#' noDataSite <- "UTGS.401544112060301" -#' # noDataSite <- readNGWMNlevels(siteNumbers = noDataSite) -#' } readNGWMNlevels <- function(siteNumbers, asDateTime = TRUE, tz = "UTC") { data <- readNGWMNdata( siteNumbers = siteNumbers, @@ -162,16 +120,7 @@ readNGWMNlevels <- function(siteNumbers, asDateTime = TRUE, tz = "UTC") { #' description \tab char \tab Site description \cr #' dec_lat_va, dec_lon_va \tab numeric \tab Site latitude and longitude \cr #' } -#' @examplesIf is_dataRetrieval_user() -#' \donttest{ -#' # one site -#' site <- "USGS.430427089284901" -#' #oneSite <- readNGWMNsites(siteNumbers = site) -#' -#' # non-USGS site -#' site <- "MBMG.103306" -#' #siteInfo <- readNGWMNsites(siteNumbers = site) -#' } + readNGWMNsites <- function(siteNumbers) { sites <- readNGWMNdata( siteNumbers = siteNumbers, diff --git a/R/readNWISdata.R b/R/readNWISdata.R index 1e12c1df..b50e03d2 100644 --- a/R/readNWISdata.R +++ b/R/readNWISdata.R @@ -72,81 +72,6 @@ #' #' @seealso [read_waterdata()] #' @export -#' @examplesIf is_dataRetrieval_user() -#' \donttest{ -#' # Examples not run for time considerations -#' -#' instFlow <- readNWISdata( -#' sites = "05114000", service = "iv", -#' parameterCd = "00060", -#' startDate = "2014-05-01T00:00Z", endDate = "2014-05-01T12:00Z" -#' ) -#' -#' instFlowCDT <- readNWISdata( -#' sites = "05114000", service = "iv", -#' parameterCd = "00060", -#' startDate = "2014-05-01T00:00", endDate = "2014-05-01T12:00", -#' tz = "America/Chicago" -#' ) -#' -#' multiSite <- readNWISdata( -#' sites = c("04025500", "040263491"), -#' service = "iv", parameterCd = "00060" -#' ) -#' -#' waterYearStat <- readNWISdata( -#' site = c("01646500"), -#' service = "stat", -#' statReportType = "annual", -#' statYearType = "water", -#' missingData = "on" -#' ) -#' monthlyStat <- readNWISdata( -#' site = c("01646500"), -#' service = "stat", -#' statReportType = "monthly" -#' ) -#' -#' dailyStat <- readNWISdata( -#' site = c("01646500"), -#' service = "stat", -#' statReportType = "daily", -#' statType = c("p25", "p50", "p75", "min", "max"), -#' parameterCd = "00060" -#' ) -#' -#' arg.list <- list( -#' site = "03111548", -#' statReportType = "daily", -#' statType = c("p25", "p50", "p75", "min", "max"), -#' parameterCd = "00060" -#' ) -#' allDailyStats_2 <- readNWISdata(arg.list, service = "stat") -#' -#' -#' site_id <- "01594440" -#' rating_curve <- readNWISdata(service = "rating", site_no = site_id, file_type = "base") -#' all_sites_base <- readNWISdata(service = "rating", file_type = "base") -#' all_sites_core <- readNWISdata(service = "rating", file_type = "corr") -#' all_sites_exsa <- readNWISdata(service = "rating", file_type = "exsa") -#' all_sites_24hrs <- readNWISdata(service = "rating", file_type = "exsa", period = 24) -#' -#' peak_data <- readNWISdata( -#' service = "peak", -#' site_no = c("01594440", "040851325"), -#' range_selection = "data_range" -#' ) -#' -#' peak_data <- readNWISdata( -#' service = "peak", -#' state_cd = "PA" -#' ) -#' -#' peak_data <- readNWISdata( -#' service = "peak", -#' huc2_cd = "20" -#' ) -#' } readNWISdata <- function( ..., asDateTime = TRUE, diff --git a/R/read_ngwmn.R b/R/read_ngwmn.R new file mode 100644 index 00000000..f1b9fca6 --- /dev/null +++ b/R/read_ngwmn.R @@ -0,0 +1,143 @@ +#' Generalized NGWMN API retrieval function +#' +#' Function that allows complex CQL queries on National Groundwater +#' Monitoring Network API. +#' See +#' for more information. +#' +#' @export +#' @param service character, can be any existing collection. Can be: +#' "providers", "constructionObs", "waterLevelObs", "sites", or "lithologyObs". +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$sample_time$description` +#' See also Details below for more information. +#' @param CQL A string in a Common Query Language format. +#' @param monitoring_location_id `r get_ogc_params("waterLevelObs", base = "NGWMN")$monitoring_location_id$description` +#' @param convertType logical, defaults to `TRUE`. If `TRUE`, the function +#' will convert the data to dates and qualifier to string vector. +#' @param \dots Additional arguments to send to the request. +#' @inheritParams check_arguments_non_api +#' +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' cql <- '{ +#' "op": "between", +#' "args": [ +#' { "property": "water_level_above_navd88_ft" }, +#' [ "100.00", "200.00" ] +#' ] +#' }' +#' +#' wl_data <- read_ngwmn(service = "waterLevelObs", +#' monitoring_location_id = c("USGS-272838082142201", +#' "USGS-404159100494601", +#' "USGS-401216080362703"), +#' CQL = cql) +#' +#'cql3 <- '{ +#' "op": "and", +#' "args": [ +#' { +#' "op": "between", +#' "args": [ +#' { "property": "water_level_above_navd88_ft" }, +#' [ "100.00", "200.00" ] +#' ] +#' }, +#' { +#' "op": "in", +#' "args": [ +#' { "property": "monitoring_location_id" }, +#' [ "USGS-272838082142201", "USGS-404159100494601", "USGS-401216080362703" ] +#' ] +#' } +#'] +#'}' +#' +#' +#' wl_data_alt <- read_ngwmn(service = "waterLevelObs", +#' CQL = cql3) +#' +#' } +read_ngwmn <- function( + service, + CQL = NA_character_, + monitoring_location_id = NA_character_, + ..., + convertType = getOption("dataRetrieval.convertType"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) { + match.arg(service, c("providers", "constructionObs", + "waterLevelObs", "sites", + "lithologyObs")) + + args <- list(...) + args[["monitoring_location_id"]] <- monitoring_location_id + + if(service %in% c("lithologyObs", "waterLevelObs", "constructionObs")){ + # Mandatory monitoring_location_ids + if(all(is.na(monitoring_location_id))){ + args[["monitoring_location_id"]] <- "ALL" + } + } else { + if(is.na(monitoring_location_id)){ + args[["monitoring_location_id"]] <- NULL + } + } + + args[["convertType"]] <- convertType + args[["limit"]] <- limit + args[["attach_request"]] <- attach_request + args[["bbox"]] <- NA + args[["no_paging"]] <- FALSE # drops id if TRUE + args[["chunk_size"]] <- NA # Chunking doesn't make sense. + + if (!"properties" %in% names(args)) { + args[["properties"]] <- NA_character_ + } + + args[["output_id"]] <- "id" + args[["base"]] <- "NGWMN" + args[["service"]] <- service + + data_req <- suppressWarnings(do.call(construct_api_requests, args)) + + if(isTRUE(!is.na(CQL) | CQL == "")){ + data_req <- data_req |> + httr2::req_headers(`Content-Type` = "application/query-cql-json") |> + httr2::req_body_raw(CQL) + } + + message("Requesting:\n", data_req$url) + + return_list <- walk_pages(data_req) + + return_list <- deal_with_empty(return_list = return_list, + properties = args[["properties"]], + service = service, + skipGeometry = isTRUE(args[["skipGeometry"]]), + convertType = args[["convertType"]], + no_paging = FALSE, + base = "NGWMN" + ) + + return_list <- rejigger_cols( + return_list, + args[["properties"]], + args[["output_id"]] + ) + + if (convertType) { + return_list <- cleanup_cols(return_list, service) + return_list <- order_results(return_list) + return_list <- move_id_col(return_list, args[["output_id"]]) + } + + if (args[["attach_request"]]) { + attr(return_list, "request") <- data_req + } + attr(return_list, "queryTime") <- Sys.time() + + return(return_list) +} diff --git a/R/read_ngwmn_lithology.R b/R/read_ngwmn_lithology.R new file mode 100644 index 00000000..032352b8 --- /dev/null +++ b/R/read_ngwmn_lithology.R @@ -0,0 +1,58 @@ +#' Get NGWMN Lithology Observations +#' +#' @description `r get_description("lithologyObs", base = "NGWMN")` +#' +#' @export +#' @param monitoring_location_id +#' `r get_ogc_params("lithologyObs", base = "NGWMN")$monitoring_location_id$description` +#' @param monitoring_location_obs_number +#' `r get_ogc_params("lithologyObs", base = "NGWMN")$monitoring_location_obs_number$description` +#' @param properties A vector of requested columns to be returned from the query. +#' Available options are: +#' `r dataRetrieval:::get_properties_for_docs("lithologyObs", base = "NGWMN")`. +#' The default (`NA`) will return all columns of the data. +#' @inheritParams check_arguments_non_api +#' +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' site <- "AKDNR-535134236016630" +#' ngwmn_lith <- read_ngwmn_lithology(monitoring_location_id = site) +#' +#' +#' sites <- c("ISWS-P428197", +#' "AKDNR-535143966816631", +#' "AKDNR-535134236016630") +#' ngwml_lith_sites <- read_ngwmn_lithology(monitoring_location_id = sites) +#' +#' } +read_ngwmn_lithology <- function( + monitoring_location_id = NA_character_, + monitoring_location_obs_number = NA_character_, + properties = NA_character_, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) { + service <- "lithologyObs" + + # Check for mandatory arguments: + if(all(is.na(monitoring_location_id))){ + stop("monitoring_location_id is a mandatory argument.") + } + + rlang::check_dots_empty() + args <- mget(names(formals())) + + return_list <- get_ogc_data( + args = args, + output_id = "id", + service = service, + base = "NGWMN" + ) + + return(return_list) +} diff --git a/R/read_ngwmn_providers.R b/R/read_ngwmn_providers.R new file mode 100644 index 00000000..ae322fdc --- /dev/null +++ b/R/read_ngwmn_providers.R @@ -0,0 +1,55 @@ +#' Get NGWMN Provider Data +#' +#' @description `r get_description("providers", base = "NGWMN")` +#' +#' @export +#' @param state +#' `r get_ogc_params("providers", base = "NGWMN")$state$description` +#' @param agency_code +#' `r get_ogc_params("providers", base = "NGWMN")$agency_code$description` +#' @param organization_type +#' `r get_ogc_params("providers", base = "NGWMN")$organization_type$description` +#' @param properties A vector of requested columns to be returned from the query. +#' Available options are: +#' `r dataRetrieval:::get_properties_for_docs("providers", base = "NGWMN")`. +#' The default (`NA`) will return all columns of the data. +#' @inheritParams check_arguments_non_api +#' +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' +#' ngwmn_providers <- read_ngwmn_providers(state = "WI") +#' +#' ngwml_providers2 <- read_ngwmn_providers(state = c("WI", "CA", "AZ", "MN")) +#' +#' org_type <- read_ngwmn_providers(organization_type = "NWIS", state = c("WI", "MN")) +#' +#' } +read_ngwmn_providers <- function( + state = NA_character_, + agency_code = NA_character_, + organization_type = NA_character_, + properties = NA_character_, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) { + service <- "providers" + rlang::check_dots_empty() + args <- mget(names(formals())) + + return_list <- get_ogc_data( + args = args, + output_id = "id", + service = service, + base = "NGWMN" + ) + + return_list <- sf::st_drop_geometry(return_list) + + return(return_list) +} diff --git a/R/read_ngwmn_sites.R b/R/read_ngwmn_sites.R new file mode 100644 index 00000000..c8eb3857 --- /dev/null +++ b/R/read_ngwmn_sites.R @@ -0,0 +1,131 @@ +#' Get NGWMN Site Data +#' +#' @description `r get_description("sites", base = "NGWMN")` +#' +#' @export +#' @param monitoring_location_id +#' `r get_ogc_params("sites", base = "NGWMN")$monitoring_location_id$description` +#' @param agency_code +#' `r get_ogc_params("sites", base = "NGWMN")$agency_code$description` +#' @param monitoring_location_number +#' `r get_ogc_params("sites", base = "NGWMN")$monitoring_location_number$description` +#' @param altitude +#' `r get_ogc_params("sites", base = "NGWMN")$altitude$description` +#' @param national_aquifer_code +#' `r get_ogc_params("sites", base = "NGWMN")$national_aquifer_code$description` +#' @param national_aquifer_description +#' `r get_ogc_params("sites", base = "NGWMN")$national_aquifer_description$description` +#' @param country_code +#' `r get_ogc_params("sites", base = "NGWMN")$country_code$description` +#' @param country_name +#' `r get_ogc_params("sites", base = "NGWMN")$country_name$description` +#' @param state_name +#' `r get_ogc_params("sites", base = "NGWMN")$state_name$description` +#' @param county_name +#' `r get_ogc_params("sites", base = "NGWMN")$county_name$description` +#' @param aquifer_name +#' `r get_ogc_params("sites", base = "NGWMN")$aquifer_name$description` +#' @param site_type +#' `r get_ogc_params("sites", base = "NGWMN")$site_type$description` +#' @param aquifer_type_code +#' `r get_ogc_params("sites", base = "NGWMN")$aquifer_type_code$description` +#' @param qw_sys_name +#' `r get_ogc_params("sites", base = "NGWMN")$qw_sys_name$description` +#' @param qw_sn_flag +#' `r get_ogc_params("sites", base = "NGWMN")$qw_sn_flag$description` +#' @param qw_baseline_flag +#' `r get_ogc_params("sites", base = "NGWMN")$qw_baseline_flag$description` +#' @param qw_well_chars +#' `r get_ogc_params("sites", base = "NGWMN")$qw_well_chars$description` +#' @param qw_well_type +#' `r get_ogc_params("sites", base = "NGWMN")$qw_well_type$description` +#' @param qw_well_purpose +#' `r get_ogc_params("sites", base = "NGWMN")$qw_well_purpose$description` +#' @param wl_sys_name +#' `r get_ogc_params("sites", base = "NGWMN")$wl_sys_name$description` +#' @param wl_sn_flag +#' `r get_ogc_params("sites", base = "NGWMN")$wl_sn_flag$description` +#' @param wl_baseline_flag +#' `r get_ogc_params("sites", base = "NGWMN")$wl_baseline_flag$description` +#' @param wl_well_chars +#' `r get_ogc_params("sites", base = "NGWMN")$wl_well_chars$description` +#' @param wl_well_type +#' `r get_ogc_params("sites", base = "NGWMN")$wl_well_type$description` +#' @param wl_well_purpose +#' `r get_ogc_params("sites", base = "NGWMN")$wl_well_purpose$description` +#' +#' @param properties A vector of requested columns to be returned from the query. +#' Available options are: +#' `r dataRetrieval:::get_properties_for_docs("sites", base = "NGWMN")`. +#' The default (`NA`) will return all columns of the data. +#' @param skipGeometry This option can be used to skip response geometries for +#' each feature. The returning object will be a data frame with no spatial +#' information. + +#' @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 +#' depth). Coordinates are assumed to be in crs 4326. The expected format is a numeric +#' vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, +#' Southern-most latitude, Eastern-most longitude, Northern-most longitude). +#' +#' @inheritParams check_arguments_non_api +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' +#' ngwmn_sites <- read_ngwmn_sites(state_name = "Minnesota") +#' +#' org_type <- read_ngwmn_sites(agency_code = "MN_DNR", +#' county_name = "Washington County") +#' +#' } +read_ngwmn_sites <- function( + monitoring_location_id = NA_character_, + agency_code = NA_character_, + monitoring_location_number = NA_character_, + altitude = NA_character_, + national_aquifer_code = NA_character_, + national_aquifer_description = NA_character_, + country_code = NA_character_, + country_name = NA_character_, + state_name = NA_character_, + county_name = NA_character_, + aquifer_name = NA_character_, + site_type = NA_character_, + aquifer_type_code = NA_character_, + qw_sys_name = NA_character_, + qw_sn_flag = NA_character_, + qw_baseline_flag = NA_character_, + qw_well_chars = NA_character_, + qw_well_type = NA_character_, + qw_well_purpose = NA_character_, + wl_sys_name = NA_character_, + wl_sn_flag = NA_character_, + wl_baseline_flag = NA_character_, + wl_well_chars = NA_character_, + wl_well_type = NA_character_, + wl_well_purpose = NA_character_, + bbox = NA, + properties = NA_character_, + skipGeometry = FALSE, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) { + service <- "sites" + rlang::check_dots_empty() + args <- mget(names(formals())) + + return_list <- get_ogc_data( + args = args, + output_id = "id", + service = service, + base = "NGWMN" + ) + + return(return_list) +} diff --git a/R/read_ngwmn_water_level.R b/R/read_ngwmn_water_level.R new file mode 100644 index 00000000..307930e9 --- /dev/null +++ b/R/read_ngwmn_water_level.R @@ -0,0 +1,88 @@ +#' Get NGWMN Water Level Data +#' +#' @description `r dataRetrieval:::get_description("waterLevelObs", base = "NGWMN")` +#' +#' @export +#' @param monitoring_location_id +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$monitoring_location_id$description` +#' @param monitoring_location_obs_number +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$monitoring_location_obs_number$description` +#' @param sample_time +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$sample_time$description` +#' See also Details below for more information. +#' +#' @param data_provided_by +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$data_provided_by$description` +#' @param water_depth_below_land_surface_ft +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$water_depth_below_land_surface_ft$description` +#' @param water_level_above_site_datum_ft +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$water_level_above_site_datum_ft$description` +#' @param monitoring_location_vertical_datum +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$monitoring_location_vertical_datum$description` +#' @param water_level_above_navd88_ft +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$water_level_above_navd88_ft$description` +#' +#' @param datetime +#' `r get_ogc_params("waterLevelObs", base = "NGWMN")$sample_time$description` +#' +#' @param properties A vector of requested columns to be returned from the query. +#' Available options are: +#' `r dataRetrieval:::get_properties_for_docs("waterLevelObs", base = "NGWMN")`. +#' The default (`NA`) will return all columns of the data. +#' +#' @inheritParams check_arguments_non_api +#' +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' site <- "USGS-272838082142201" +#' ngwmn_wl <- read_ngwmn_water_level(monitoring_location_id = site) +#' +#' ngwmn_wl_sub <- read_ngwmn_water_level(monitoring_location_id = site, +#' monitoring_location_obs_number = 1:5) +#' +#' ngwml_wl_time2 <- read_ngwmn_water_level(monitoring_location_id = site, +#' datetime = c("2022-01-01", "2024-01-01")) +#' +#' sites <- c("USGS-272838082142201", "USGS-404159100494601", +#' "USGS-401216080362703", "MBMG-702934") +#' ngwml_wl_sites <- read_ngwmn_water_level(monitoring_location_id = sites) +#' +#' } +read_ngwmn_water_level <- function( + monitoring_location_id = NA_character_, + monitoring_location_obs_number = NA_character_, + sample_time = NA_character_, + data_provided_by = NA_character_, + water_depth_below_land_surface_ft = NA_character_, + water_level_above_site_datum_ft = NA_character_, + monitoring_location_vertical_datum = NA_character_, + water_level_above_navd88_ft = NA_character_, + properties = NA_character_, + datetime = NA_character_, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) { + service <- "waterLevelObs" + + # Check for mandatory arguments: + if(all(is.na(monitoring_location_id))){ + stop("monitoring_location_id is a mandatory argument.") + } + + rlang::check_dots_empty() + args <- mget(names(formals())) + + return_list <- get_ogc_data( + args = args, + output_id = "id", + service = service, + base = "NGWMN" + ) + + return(return_list) +} diff --git a/R/read_ngwmn_well_construction.R b/R/read_ngwmn_well_construction.R new file mode 100644 index 00000000..6e11c586 --- /dev/null +++ b/R/read_ngwmn_well_construction.R @@ -0,0 +1,61 @@ +#' Get NGWMN Well Construction Data +#' +#' @description `r get_description("constructionObs", base = "NGWMN")` +#' +#' @export +#' @param monitoring_location_id +#' `r get_ogc_params("constructionObs", base = "NGWMN")$monitoring_location_id$description` +#' @param monitoring_location_obs_number +#' `r get_ogc_params("constructionObs", base = "NGWMN")$monitoring_location_obs_number$description` +#' @param material +#' `r get_ogc_params("constructionObs", base = "NGWMN")$material$description` +#' @param properties A vector of requested columns to be returned from the query. +#' Available options are: +#' `r dataRetrieval:::get_properties_for_docs("constructionObs", base = "NGWMN")`. +#' The default (`NA`) will return all columns of the data. +#' @inheritParams check_arguments_non_api +#' +#' @examplesIf is_dataRetrieval_user() +#' +#' \donttest{ +#' site <- "USGS-272838082142201" +#' ngwmn_well <- read_ngwmn_well_construction(monitoring_location_id = site) +#' +#' ngwmn_well_sub <- read_ngwmn_well_construction(monitoring_location_id = site, +#' monitoring_location_obs_number = 2) +#' +#' sites <- c("USGS-272838082142201", "USGS-404159100494601", +#' "USGS-401216080362703", "MBMG-702934") +#' ngwml_well_sites <- read_ngwmn_well_construction(monitoring_location_id = sites) +#' +#' } +read_ngwmn_well_construction <- function( + monitoring_location_id = NA_character_, + monitoring_location_obs_number = NA_character_, + material = NA_character_, + properties = NA_character_, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) { + service <- "constructionObs" + # Check for mandatory arguments: + if(all(is.na(monitoring_location_id))){ + stop("monitoring_location_id is a mandatory argument.") + } + + rlang::check_dots_empty() + args <- mget(names(formals())) + + return_list <- get_ogc_data( + args = args, + output_id = "id", + service = service, + base = "NGWMN" + ) + + return(return_list) +} diff --git a/R/read_waterdata_daily.R b/R/read_waterdata_daily.R index d13072c8..13922ae1 100644 --- a/R/read_waterdata_daily.R +++ b/R/read_waterdata_daily.R @@ -100,7 +100,7 @@ read_waterdata_daily <- function( rlang::check_dots_empty() args <- mget(names(formals())) - return_list <- get_ogc_data(args, output_id, service) + return_list <- get_ogc_data(args, output_id, service, base = "OGC") return(return_list) } diff --git a/R/read_waterdata_peaks.R b/R/read_waterdata_peaks.R index 216b9130..3fb61447 100644 --- a/R/read_waterdata_peaks.R +++ b/R/read_waterdata_peaks.R @@ -22,6 +22,7 @@ #' @param day `r get_ogc_params("peaks")$day` #' @param time_of_day `r get_ogc_params("peaks")$time_of_day` #' @param peak_since `r get_ogc_params("peaks")$peak_since` +#' @param qualifier `r get_ogc_params("peaks")$qualifier` #' @param properties A vector of requested columns to be returned from the query. #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("peaks", "peak_id")`. @@ -78,6 +79,7 @@ read_waterdata_peaks <- function( day = NA_character_, time_of_day = NA_character_, peak_since = NA_character_, + qualifier = NA_character_, skipGeometry = NA, time = NA_character_, bbox = NA, diff --git a/R/setAccess.R b/R/setAccess.R index f3bdb87c..f0bda683 100644 --- a/R/setAccess.R +++ b/R/setAccess.R @@ -76,6 +76,5 @@ Please contact comptools@usgs.gov for more information." pkg.env$samplesData <- "https://api.waterdata.usgs.gov/samples-data/summary" pkg.env$status <- "https://www.waterqualitydata.us/wqx3/status/" - pkg.env$NGWMN <- "https://cida.usgs.gov/ngwmn_cache/sos" # nolint end } diff --git a/R/sysdata.rda b/R/sysdata.rda index 76776c7d..986927ec 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 4d2a8adf..ab90e9f6 100644 --- a/R/walk_pages.R +++ b/R/walk_pages.R @@ -47,6 +47,10 @@ get_resp_data <- function(resp) { return_df <- coerce_qualifier_cols(return_df, is_sf = TRUE) + if ("altitude_accuracy" %in% names(return_df)) { + return_df$altitude_accuracy <- as.character(return_df$altitude_accuracy) + } + if (!use_sf) { return_df <- sf::st_drop_geometry(return_df) if ("AsGeoJSON(geometry)" %in% names(return_df)) { diff --git a/_pkgdown.yml b/_pkgdown.yml index 6dc8a771..8af889bd 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -119,9 +119,11 @@ reference: - title: National Ground-Water Monitoring Network desc: Functions to retrieve NGWMN data. contents: - - readNGWMNlevels - - readNGWMNsites - - readNGWMNdata + - read_ngwmn_water_levels + - read_ngwmn_sites + - read_ngwmn_providers + - read_ngwmn_well_construction + - read_ngwmn_lithology - title: Network Linked Data Index desc: Functions to interface with the NLDI. contents: diff --git a/man/check_OGC_requests.Rd b/man/check_OGC_requests.Rd index 1d729796..00ad8002 100644 --- a/man/check_OGC_requests.Rd +++ b/man/check_OGC_requests.Rd @@ -4,12 +4,14 @@ \alias{check_OGC_requests} \title{Check OGC requests} \usage{ -check_OGC_requests(endpoint = "daily", type = "queryables") +check_OGC_requests(endpoint = "daily", type = "queryables", base = "OGC") } \arguments{ \item{endpoint}{Character, can be any existing collection} \item{type}{Character, can be "queryables", "schema"} + +\item{base}{Character, can be "OGC" or "NGWMN"} } \value{ list @@ -30,6 +32,10 @@ ts_meta_queryables <- check_OGC_requests(endpoint = "time-series-metadata", type = "queryables") ts_meta_schema <- check_OGC_requests(endpoint = "time-series-metadata", type = "schema") + +ngwml <- check_OGC_requests(endpoint = "waterLevelObs", + type = "schema", + base = "NGWMN") } \dontshow{\}) # examplesIf} } diff --git a/man/construct_api_requests.Rd b/man/construct_api_requests.Rd index cbad0550..98656b98 100644 --- a/man/construct_api_requests.Rd +++ b/man/construct_api_requests.Rd @@ -9,6 +9,7 @@ construct_api_requests( output_id, ..., bbox = NA, + base = "OGC", convertType = getOption("dataRetrieval.convertType"), no_paging = getOption("dataRetrieval.no_paging"), chunk_size = getOption("dataRetrieval.site_chunk_size_data"), diff --git a/man/get_ogc_params.Rd b/man/get_ogc_params.Rd index 9a8ab0d0..d7fe7bdc 100644 --- a/man/get_ogc_params.Rd +++ b/man/get_ogc_params.Rd @@ -4,10 +4,12 @@ \alias{get_ogc_params} \title{Get parameter descriptions} \usage{ -get_ogc_params(service) +get_ogc_params(service, base = "OGC") } \arguments{ \item{service}{Character, can be any of the USGS Waterdata API endpoints or collections.} + +\item{base}{Either "OGC" for waterdata, or "NGWMN" for National Groundwater Monitoring Network.} } \value{ list diff --git a/man/readNGWMNdata.Rd b/man/readNGWMNdata.Rd index c2dd649b..b56d0dbe 100644 --- a/man/readNGWMNdata.Rd +++ b/man/readNGWMNdata.Rd @@ -24,30 +24,3 @@ for more information on time zones.} \description{ Only water level data and site locations and names are currently available through the web service. } -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} -\donttest{ -# one site -site <- "USGS.430427089284901" -#oneSite <- readNGWMNdata(siteNumbers = site, service = "observation") - -# multiple sites -sites <- c("USGS.272838082142201", "USGS.404159100494601", "USGS.401216080362703") -# Very slow: -# multiSiteData <- readNGWMNdata(siteNumbers = sites, service = "observation") -# attributes(multiSiteData) - -# non-USGS site -# accepts colon or period between agency and ID -site <- "MBMG:702934" -# data <- readNGWMNdata(siteNumbers = site, service = "featureOfInterest") - -# bounding box -# bboxSites <- readNGWMNdata(service = "featureOfInterest", bbox = c(30, -102, 31, 99)) -# retrieve sites. Set asDateTime to false since one site has an invalid date -# Very slow: -# bboxData <- readNGWMNdata(service = "observation", siteNumbers = bboxSites$site[1:3], -# asDateTime = FALSE) -} -\dontshow{\}) # examplesIf} -} diff --git a/man/readNGWMNlevels.Rd b/man/readNGWMNlevels.Rd index c53e3787..64637e52 100644 --- a/man/readNGWMNlevels.Rd +++ b/man/readNGWMNlevels.Rd @@ -24,24 +24,3 @@ for more information on time zones.} \description{ Retrieve groundwater levels from the National Ground Water Monitoring Network. } -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} -\donttest{ -# one site -site <- "USGS.430427089284901" -# oneSite <- readNGWMNlevels(siteNumbers = site) - -# multiple sites -sites <- c("USGS:272838082142201", "USGS:404159100494601", "USGS:401216080362703") -# multiSiteData <- readNGWMNlevels(sites) - -# non-USGS site -site <- "MBMG.103306" -# data <- readNGWMNlevels(siteNumbers = site, asDateTime = FALSE) - -# site with no data returns empty data frame -noDataSite <- "UTGS.401544112060301" -# noDataSite <- readNGWMNlevels(siteNumbers = noDataSite) -} -\dontshow{\}) # examplesIf} -} diff --git a/man/readNGWMNsites.Rd b/man/readNGWMNsites.Rd index 0aa0232b..4b5c92be 100644 --- a/man/readNGWMNsites.Rd +++ b/man/readNGWMNsites.Rd @@ -22,16 +22,3 @@ dec_lat_va, dec_lon_va \tab numeric \tab Site latitude and longitude \cr \description{ Retrieve site data from the National Ground Water Monitoring Network. } -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} -\donttest{ -# one site -site <- "USGS.430427089284901" -#oneSite <- readNGWMNsites(siteNumbers = site) - -# non-USGS site -site <- "MBMG.103306" -#siteInfo <- readNGWMNsites(siteNumbers = site) -} -\dontshow{\}) # examplesIf} -} diff --git a/man/readNWISdata.Rd b/man/readNWISdata.Rd index 2e66b64a..8e47c060 100644 --- a/man/readNWISdata.Rd +++ b/man/readNWISdata.Rd @@ -83,84 +83,6 @@ not be expressed in periods of less than a day, or in increments of months M or period returns data for a site generally from now to a time in the past. Note that when period is used all data up to the most recent value are returned. } -\examples{ -\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} -\donttest{ -# Examples not run for time considerations - -instFlow <- readNWISdata( - sites = "05114000", service = "iv", - parameterCd = "00060", - startDate = "2014-05-01T00:00Z", endDate = "2014-05-01T12:00Z" -) - -instFlowCDT <- readNWISdata( - sites = "05114000", service = "iv", - parameterCd = "00060", - startDate = "2014-05-01T00:00", endDate = "2014-05-01T12:00", - tz = "America/Chicago" -) - -multiSite <- readNWISdata( - sites = c("04025500", "040263491"), - service = "iv", parameterCd = "00060" -) - -waterYearStat <- readNWISdata( - site = c("01646500"), - service = "stat", - statReportType = "annual", - statYearType = "water", - missingData = "on" -) -monthlyStat <- readNWISdata( - site = c("01646500"), - service = "stat", - statReportType = "monthly" -) - -dailyStat <- readNWISdata( - site = c("01646500"), - service = "stat", - statReportType = "daily", - statType = c("p25", "p50", "p75", "min", "max"), - parameterCd = "00060" -) - -arg.list <- list( - site = "03111548", - statReportType = "daily", - statType = c("p25", "p50", "p75", "min", "max"), - parameterCd = "00060" -) -allDailyStats_2 <- readNWISdata(arg.list, service = "stat") - - -site_id <- "01594440" -rating_curve <- readNWISdata(service = "rating", site_no = site_id, file_type = "base") -all_sites_base <- readNWISdata(service = "rating", file_type = "base") -all_sites_core <- readNWISdata(service = "rating", file_type = "corr") -all_sites_exsa <- readNWISdata(service = "rating", file_type = "exsa") -all_sites_24hrs <- readNWISdata(service = "rating", file_type = "exsa", period = 24) - -peak_data <- readNWISdata( - service = "peak", - site_no = c("01594440", "040851325"), - range_selection = "data_range" -) - -peak_data <- readNWISdata( - service = "peak", - state_cd = "PA" -) - -peak_data <- readNWISdata( - service = "peak", - huc2_cd = "20" -) -} -\dontshow{\}) # examplesIf} -} \seealso{ \code{\link[=read_waterdata]{read_waterdata()}} } diff --git a/man/read_ngwmn.Rd b/man/read_ngwmn.Rd new file mode 100644 index 00000000..fd529e9d --- /dev/null +++ b/man/read_ngwmn.Rd @@ -0,0 +1,101 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_ngwmn.R +\name{read_ngwmn} +\alias{read_ngwmn} +\title{Generalized NGWMN API retrieval function} +\usage{ +read_ngwmn( + service, + CQL = NA_character_, + monitoring_location_id = NA_character_, + ..., + convertType = getOption("dataRetrieval.convertType"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) +} +\arguments{ +\item{service}{character, can be any existing collection. Can be: +"providers", "constructionObs", "waterLevelObs", "sites", or "lithologyObs". +The date of an observation. Date and time expressions adhere to RFC 3339. Intervals may be bounded or half-bounded (double-dots at start or end). +Examples: +\itemize{ +\item A date-time: "2018-02-12T23:20:50-00:00" +\item A bounded interval:"2018-02-12T00:00:00+05:00/2018-03-18T12:31:12+05:00" +\item Half-bounded intervals: "2018-02-12T00:00:00-05:00/.." or "../2018-03-18T12:31:12-05:00" +} + +Only features that have a \code{sample_time} that intersects the value of datetime are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties. + +See also Details below for more information.} + +\item{CQL}{A string in a Common Query Language format.} + +\item{monitoring_location_id}{This field is required. Combined site identifier of agency code and site number (format of \code{{agency_code}}-\code{{monitoring_location_number}}). A list of values can be passed for this field, seperated by commas.} + +\item{\dots}{Additional arguments to send to the request.} + +\item{convertType}{logical, defaults to \code{TRUE}. If \code{TRUE}, the function +will convert the data to dates and qualifier to string vector.} + +\item{limit}{numeric, 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 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} +} +\description{ +Function that allows complex CQL queries on National Groundwater +Monitoring Network API. +See \url{https://api.waterdata.usgs.gov/docs/ogcapi/complex-queries/} +for more information. +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +cql <- '{ + "op": "between", + "args": [ + { "property": "water_level_above_navd88_ft" }, + [ "100.00", "200.00" ] + ] +}' + +wl_data <- read_ngwmn(service = "waterLevelObs", + monitoring_location_id = c("USGS-272838082142201", + "USGS-404159100494601", + "USGS-401216080362703"), + CQL = cql) + +cql3 <- '{ +"op": "and", +"args": [ + { + "op": "between", + "args": [ + { "property": "water_level_above_navd88_ft" }, + [ "100.00", "200.00" ] + ] + }, + { + "op": "in", + "args": [ + { "property": "monitoring_location_id" }, + [ "USGS-272838082142201", "USGS-404159100494601", "USGS-401216080362703" ] + ] + } +] +}' + + +wl_data_alt <- read_ngwmn(service = "waterLevelObs", + CQL = cql3) + +} +\dontshow{\}) # examplesIf} +} diff --git a/man/read_ngwmn_lithology.Rd b/man/read_ngwmn_lithology.Rd new file mode 100644 index 00000000..b50588ba --- /dev/null +++ b/man/read_ngwmn_lithology.Rd @@ -0,0 +1,77 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_ngwmn_lithology.R +\name{read_ngwmn_lithology} +\alias{read_ngwmn_lithology} +\title{Get NGWMN Lithology Observations} +\usage{ +read_ngwmn_lithology( + monitoring_location_id = NA_character_, + monitoring_location_obs_number = NA_character_, + properties = NA_character_, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) +} +\arguments{ +\item{monitoring_location_id}{This field is required. Combined site identifier of agency code and site number (format of \code{{agency_code}}-\code{{monitoring_location_number}}). A list of values can be passed for this field, seperated by commas.} + +\item{monitoring_location_obs_number}{Number of observation for given site. A list of values can be passed for this field, seperated by commas.} + +\item{properties}{A vector of requested columns to be returned from the query. +Available options are: +agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, lithology_id, lithology_description, lithology_controlled_concept, lithology_depth_from, lithology_depth_to, lithology_depth_to_unit, lithology_depth_from_unit. +The default (\code{NA}) will return all columns of the data.} + +\item{...}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + +\item{convertType}{logical, defaults to TRUE. +If \code{TRUE}, the function will convert the data to dates, any qualifiers to string +vector and reorder the returned data frame.} + +\item{no_paging}{logical, defaults to FALSE. +If \code{TRUE}, the data will +be requested from a native csv format. This can be dangerous because the +data will cut off at 50,000 rows without indication that more data +is available. Use \code{TRUE} with caution.} + +\item{chunk_size}{Number of monitoring_location_ids to chunk requests into. +The default for functions that don't generally return long-term data records +is 250, while +the default for time series functions is +10. +Setting to \code{NA} will eliminate site chunking, giving users full control.} + +\item{limit}{numeric, 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 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} +} +\description{ +Lithology Observations data +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +site <- "AKDNR-535134236016630" +ngwmn_lith <- read_ngwmn_lithology(monitoring_location_id = site) + + +sites <- c("ISWS-P428197", + "AKDNR-535143966816631", + "AKDNR-535134236016630") +ngwml_lith_sites <- read_ngwmn_lithology(monitoring_location_id = sites) + +} +\dontshow{\}) # examplesIf} +} diff --git a/man/read_ngwmn_providers.Rd b/man/read_ngwmn_providers.Rd new file mode 100644 index 00000000..82bd71d7 --- /dev/null +++ b/man/read_ngwmn_providers.Rd @@ -0,0 +1,78 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_ngwmn_providers.R +\name{read_ngwmn_providers} +\alias{read_ngwmn_providers} +\title{Get NGWMN Provider Data} +\usage{ +read_ngwmn_providers( + state = NA_character_, + agency_code = NA_character_, + organization_type = NA_character_, + properties = NA_character_, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) +} +\arguments{ +\item{state}{State code for provider. A list of values can be passed for this field, seperated by commas.} + +\item{agency_code}{Code for the name of the agency or organization that owns the site and/or contributed it to the network. A list of values can be passed for this field, seperated by commas.} + +\item{organization_type}{Type of organization of data provider.} + +\item{properties}{A vector of requested columns to be returned from the query. +Available options are: +agency_name, agency_code, organization_type, state, link. +The default (\code{NA}) will return all columns of the data.} + +\item{...}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + +\item{convertType}{logical, defaults to TRUE. +If \code{TRUE}, the function will convert the data to dates, any qualifiers to string +vector and reorder the returned data frame.} + +\item{no_paging}{logical, defaults to FALSE. +If \code{TRUE}, the data will +be requested from a native csv format. This can be dangerous because the +data will cut off at 50,000 rows without indication that more data +is available. Use \code{TRUE} with caution.} + +\item{chunk_size}{Number of monitoring_location_ids to chunk requests into. +The default for functions that don't generally return long-term data records +is 250, while +the default for time series functions is +10. +Setting to \code{NA} will eliminate site chunking, giving users full control.} + +\item{limit}{numeric, 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 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} +} +\description{ +NGWMN contributing providers +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ + +ngwmn_providers <- read_ngwmn_providers(state = "WI") + +ngwml_providers2 <- read_ngwmn_providers(state = c("WI", "CA", "AZ", "MN")) + +org_type <- read_ngwmn_providers(organization_type = "NWIS", state = c("WI", "MN")) + +} +\dontshow{\}) # examplesIf} +} diff --git a/man/read_ngwmn_sites.Rd b/man/read_ngwmn_sites.Rd new file mode 100644 index 00000000..f291585e --- /dev/null +++ b/man/read_ngwmn_sites.Rd @@ -0,0 +1,156 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_ngwmn_sites.R +\name{read_ngwmn_sites} +\alias{read_ngwmn_sites} +\title{Get NGWMN Site Data} +\usage{ +read_ngwmn_sites( + monitoring_location_id = NA_character_, + agency_code = NA_character_, + monitoring_location_number = NA_character_, + altitude = NA_character_, + national_aquifer_code = NA_character_, + national_aquifer_description = NA_character_, + country_code = NA_character_, + country_name = NA_character_, + state_name = NA_character_, + county_name = NA_character_, + aquifer_name = NA_character_, + site_type = NA_character_, + aquifer_type_code = NA_character_, + qw_sys_name = NA_character_, + qw_sn_flag = NA_character_, + qw_baseline_flag = NA_character_, + qw_well_chars = NA_character_, + qw_well_type = NA_character_, + qw_well_purpose = NA_character_, + wl_sys_name = NA_character_, + wl_sn_flag = NA_character_, + wl_baseline_flag = NA_character_, + wl_well_chars = NA_character_, + wl_well_type = NA_character_, + wl_well_purpose = NA_character_, + bbox = NA, + properties = NA_character_, + skipGeometry = FALSE, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) +} +\arguments{ +\item{monitoring_location_id}{Site identifier, combination of agency code and site number (format \code{agency_code}- \code{monitoring_location_number}). A list of values can be passed for this field, seperated by commas.} + +\item{agency_code}{Code for the name of the agency or organization that owns the site and/or contributed it to the network. A list of values can be passed for this field, seperated by commas.} + +\item{monitoring_location_number}{Local, unique well or spring identification number or code. A list of values can be passed for this field, seperated by commas.} + +\item{altitude}{Elevation of the land surface at the site.} + +\item{national_aquifer_code}{Code for U.S. Pricinpal Aquifer, lookup \href{https://www.usgs.gov/mission-areas/water-resources/science/national-aquifer-code-reference-list}{here}. A list of values can be passed for this field, seperated by commas.} + +\item{national_aquifer_description}{Name for U.S. Principal Aquifer, lookup \href{https://www.usgs.gov/mission-areas/water-resources/science/national-aquifer-code-reference-list}{here}. A list of values can be passed for this field, seperated by commas.} + +\item{country_code}{Abbreviation of country of site location. A list of values can be passed for this field, seperated by commas.} + +\item{country_name}{Name of country of site location.} + +\item{state_name}{Name of state of site location. A list of values can be passed for this field, seperated by commas.} + +\item{county_name}{Name of county of site location. A list of values can be passed for this field, seperated by commas.} + +\item{aquifer_name}{Name of local aquifer of site. A list of values can be passed for this field, seperated by commas.} + +\item{site_type}{Type of groundwater site (Spring or Well).} + +\item{aquifer_type_code}{Characteristic of the type of aquifer that the well is completed in (Confined or Unconfined). For NGWMN, shallow semi-confined wells can be considered unconfined if they respond to climatic fluctuations in a relatively short period of time.} + +\item{qw_sys_name}{The system from which water quality data from the well or spring is served to the portal. A list of values can be passed for this field, seperated by commas.} + +\item{qw_sn_flag}{Flag for whether the well or spring is part of the NGWMN water-quality network.} + +\item{qw_baseline_flag}{Flag for whether the well or spring has completed its 5-year baseline period, classifies it as being in one of the three QW subnetworks.} + +\item{qw_well_chars}{The characteristics of the aquifer the well represents. There are 3 options: 'Background', 'Suspected / Anticipated Changes', 'Known Changes'. The field is NULL if the site is still in the baseline period.} + +\item{qw_well_type}{Description of the assigned QW monitoring category for the well or spring.} + +\item{qw_well_purpose}{Description of the prupose of conducting QW monitoring of the well or spring.} + +\item{wl_sys_name}{The system from which water level data from the well or spring is served to the portal. A list of values can be passed for this field, seperated by commas.} + +\item{wl_sn_flag}{Flag for whether the well or spring is part of the NGWMN water-level network.} + +\item{wl_baseline_flag}{Flag for whether the well or spring has completed its 5-year baseline period, classifies it as being in one of the three WL subnetworks.} + +\item{wl_well_chars}{The characteristics of the aquifer the well represents. There are 3 options: 'Background', 'Suspected / Anticipated Changes', 'Known Changes'. The field is NULL if the site is still in the baseline period.} + +\item{wl_well_type}{Description of the assigned WL monitoring category for the well or spring} + +\item{wl_well_purpose}{Description of the purpose of conducting WL monitoring of the well or spring.} + +\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 +on whether the coordinate reference system includes a vertical axis (height or +depth). Coordinates are assumed to be in crs 4326. The expected format is a numeric +vector structured: c(xmin,ymin,xmax,ymax). Another way to think of it is c(Western-most longitude, +Southern-most latitude, Eastern-most longitude, Northern-most longitude).} + +\item{properties}{A vector of requested columns to be returned from the query. +Available options are: +geometry, monitoring_location_id, agency_code, agency_name, monitoring_location_number, monitoring_location_name, longitude, original_horizontal_datum, horizontal_position_accuracy_code, altitude, vertical_datum, altitude_method_name, altitude_accuracy, well_constructed_depth, well_depth_units, national_aquifer_code, national_aquifer_description, country_code, country_name, state_name, county_name, aquifer_name, site_type, aquifer_type_code, qw_sys_name, qw_sn_flag, qw_baseline_flag, qw_well_chars, qw_well_type, qw_well_purpose, qw_well_purpose_notes, wl_sys_name, wl_sn_flag, wl_baseline_flag, wl_well_chars, wl_well_type, wl_well_purpose, wl_well_purpose_notes, link. +The default (\code{NA}) will return all columns of the data.} + +\item{skipGeometry}{This option can be used to skip response geometries for +each feature. The returning object will be a data frame with no spatial +information.} + +\item{...}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + +\item{convertType}{logical, defaults to TRUE. +If \code{TRUE}, the function will convert the data to dates, any qualifiers to string +vector and reorder the returned data frame.} + +\item{no_paging}{logical, defaults to FALSE. +If \code{TRUE}, the data will +be requested from a native csv format. This can be dangerous because the +data will cut off at 50,000 rows without indication that more data +is available. Use \code{TRUE} with caution.} + +\item{chunk_size}{Number of monitoring_location_ids to chunk requests into. +The default for functions that don't generally return long-term data records +is 250, while +the default for time series functions is +10. +Setting to \code{NA} will eliminate site chunking, giving users full control.} + +\item{limit}{numeric, 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 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} +} +\description{ +Site data (from Monitoring Location Registry), including the name, identifier, agency, features, and location of the site +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ + +ngwmn_sites <- read_ngwmn_sites(state_name = "Minnesota") + +org_type <- read_ngwmn_sites(agency_code = "MN_DNR", + county_name = "Washington County") + +} +\dontshow{\}) # examplesIf} +} diff --git a/man/read_ngwmn_water_level.Rd b/man/read_ngwmn_water_level.Rd new file mode 100644 index 00000000..949c0751 --- /dev/null +++ b/man/read_ngwmn_water_level.Rd @@ -0,0 +1,120 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_ngwmn_water_level.R +\name{read_ngwmn_water_level} +\alias{read_ngwmn_water_level} +\title{Get NGWMN Water Level Data} +\usage{ +read_ngwmn_water_level( + monitoring_location_id = NA_character_, + monitoring_location_obs_number = NA_character_, + sample_time = NA_character_, + data_provided_by = NA_character_, + water_depth_below_land_surface_ft = NA_character_, + water_level_above_site_datum_ft = NA_character_, + monitoring_location_vertical_datum = NA_character_, + water_level_above_navd88_ft = NA_character_, + properties = NA_character_, + datetime = NA_character_, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) +} +\arguments{ +\item{monitoring_location_id}{This field is required. Combined site identifier of agency code and site number (format of \code{{agency_code}}-\code{{monitoring_location_number}}). A list of values can be passed for this field, seperated by commas.} + +\item{monitoring_location_obs_number}{Number of observation for given site. A list of values can be passed for this field, seperated by commas.} + +\item{sample_time}{The date of an observation. Date and time expressions adhere to RFC 3339. Intervals may be bounded or half-bounded (double-dots at start or end). +Examples: +\itemize{ +\item A date-time: "2018-02-12T23:20:50-00:00" +\item A bounded interval:"2018-02-12T00:00:00+05:00/2018-03-18T12:31:12+05:00" +\item Half-bounded intervals: "2018-02-12T00:00:00-05:00/.." or "../2018-03-18T12:31:12-05:00" +} + +Only features that have a \code{sample_time} that intersects the value of datetime are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties. + +See also Details below for more information.} + +\item{data_provided_by}{Code for the agency or organization that provides, collects, owns, and/or manages the water level measurement record.} + +\item{water_depth_below_land_surface_ft}{Calculated depth to water in feet.} + +\item{water_level_above_site_datum_ft}{Water-level value represented as depth to site datum in feet.} + +\item{monitoring_location_vertical_datum}{Code indicating the vertical datum.} + +\item{water_level_above_navd88_ft}{Mediated water-level value represented as depth to water relative to the NAVD88 datum.} + +\item{properties}{A vector of requested columns to be returned from the query. +Available options are: +agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, sample_time, orig_unit, orig_value, accuracy_unit, accuracy_value, obs_datum_cd, obs_comment, obs_method, data_provided_by, water_depth_below_land_surface_ft, water_level_above_site_datum_ft, monitoring_location_vertical_datum, water_level_above_navd88_ft. +The default (\code{NA}) will return all columns of the data.} + +\item{datetime}{The date of an observation. Date and time expressions adhere to RFC 3339. Intervals may be bounded or half-bounded (double-dots at start or end). +Examples: +\itemize{ +\item A date-time: "2018-02-12T23:20:50-00:00" +\item A bounded interval:"2018-02-12T00:00:00+05:00/2018-03-18T12:31:12+05:00" +\item Half-bounded intervals: "2018-02-12T00:00:00-05:00/.." or "../2018-03-18T12:31:12-05:00" +} + +Only features that have a \code{sample_time} that intersects the value of datetime are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties.} + +\item{...}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + +\item{convertType}{logical, defaults to TRUE. +If \code{TRUE}, the function will convert the data to dates, any qualifiers to string +vector and reorder the returned data frame.} + +\item{no_paging}{logical, defaults to FALSE. +If \code{TRUE}, the data will +be requested from a native csv format. This can be dangerous because the +data will cut off at 50,000 rows without indication that more data +is available. Use \code{TRUE} with caution.} + +\item{chunk_size}{Number of monitoring_location_ids to chunk requests into. +The default for functions that don't generally return long-term data records +is 250, while +the default for time series functions is +10. +Setting to \code{NA} will eliminate site chunking, giving users full control.} + +\item{limit}{numeric, 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 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} +} +\description{ +Water Level Observations data +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +site <- "USGS-272838082142201" +ngwmn_wl <- read_ngwmn_water_level(monitoring_location_id = site) + +ngwmn_wl_sub <- read_ngwmn_water_level(monitoring_location_id = site, + monitoring_location_obs_number = 1:5) + +ngwml_wl_time2 <- read_ngwmn_water_level(monitoring_location_id = site, + datetime = c("2022-01-01", "2024-01-01")) + +sites <- c("USGS-272838082142201", "USGS-404159100494601", + "USGS-401216080362703", "MBMG-702934") +ngwml_wl_sites <- read_ngwmn_water_level(monitoring_location_id = sites) + +} +\dontshow{\}) # examplesIf} +} diff --git a/man/read_ngwmn_well_construction.Rd b/man/read_ngwmn_well_construction.Rd new file mode 100644 index 00000000..352e166e --- /dev/null +++ b/man/read_ngwmn_well_construction.Rd @@ -0,0 +1,81 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/read_ngwmn_well_construction.R +\name{read_ngwmn_well_construction} +\alias{read_ngwmn_well_construction} +\title{Get NGWMN Well Construction Data} +\usage{ +read_ngwmn_well_construction( + monitoring_location_id = NA_character_, + monitoring_location_obs_number = NA_character_, + material = NA_character_, + properties = NA_character_, + ..., + convertType = getOption("dataRetrieval.convertType"), + no_paging = getOption("dataRetrieval.no_paging"), + chunk_size = getOption("dataRetrieval.site_chunk_size_data"), + limit = getOption("dataRetrieval.limit"), + attach_request = getOption("dataRetrieval.attach_request") +) +} +\arguments{ +\item{monitoring_location_id}{This field is required. Combined site identifier of agency code and site number (format of \code{{agency_code}}-\code{{monitoring_location_number}}). A list of values can be passed for this field, seperated by commas.} + +\item{monitoring_location_obs_number}{Number of observation for given site. A list of values can be passed for this field, seperated by commas.} + +\item{material}{Screen type or material.} + +\item{properties}{A vector of requested columns to be returned from the query. +Available options are: +agency_code, monitoring_location_number, monitoring_location_id, monitoring_location_obs_number, type, depth_from, depth_to, depth_from_unit, depth_to_unit, material, diameter, diameter_unit, hole_size, hole_size_unit. +The default (\code{NA}) will return all columns of the data.} + +\item{...}{Not used. Included to help differentiate official Water Data API arguments +from more seldom used, optional dataRetrieval-specific arguments.} + +\item{convertType}{logical, defaults to TRUE. +If \code{TRUE}, the function will convert the data to dates, any qualifiers to string +vector and reorder the returned data frame.} + +\item{no_paging}{logical, defaults to FALSE. +If \code{TRUE}, the data will +be requested from a native csv format. This can be dangerous because the +data will cut off at 50,000 rows without indication that more data +is available. Use \code{TRUE} with caution.} + +\item{chunk_size}{Number of monitoring_location_ids to chunk requests into. +The default for functions that don't generally return long-term data records +is 250, while +the default for time series functions is +10. +Setting to \code{NA} will eliminate site chunking, giving users full control.} + +\item{limit}{numeric, 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 50,000. It may be beneficial to set this number lower if your internet +connection is spotty. The default (\code{NA}) will set the limit to the maximum +allowable limit for the service.} + +\item{attach_request}{logical, defaults to TRUE. +If set to \code{TRUE}, the full request sent to the Water Data API is attached +as an attribute to the data set.} +} +\description{ +Well Construction Observations data +} +\examples{ +\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf} + +\donttest{ +site <- "USGS-272838082142201" +ngwmn_well <- read_ngwmn_well_construction(monitoring_location_id = site) + +ngwmn_well_sub <- read_ngwmn_well_construction(monitoring_location_id = site, + monitoring_location_obs_number = 2) + +sites <- c("USGS-272838082142201", "USGS-404159100494601", + "USGS-401216080362703", "MBMG-702934") +ngwml_well_sites <- read_ngwmn_well_construction(monitoring_location_id = sites) + +} +\dontshow{\}) # examplesIf} +} diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index b35db866..e722a5ed 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -34,7 +34,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, continuous_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +geometry, 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 ef3d7eed..9c0efdd0 100644 --- a/man/read_waterdata_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -41,7 +41,7 @@ Multiple statistic_ids can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, daily_id, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +geometry, 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 b9543526..95271b34 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -45,7 +45,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, field_measurement_id, field_measurements_series_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, control_condition, measurement_rated. +geometry, field_measurements_series_id, reading_type, 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, control_condition, measurement_rated, year, month, day, time_of_day. 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_peaks.Rd b/man/read_waterdata_peaks.Rd index 79e98b2c..830040ab 100644 --- a/man/read_waterdata_peaks.Rd +++ b/man/read_waterdata_peaks.Rd @@ -18,6 +18,7 @@ read_waterdata_peaks( day = NA_character_, time_of_day = NA_character_, peak_since = NA_character_, + qualifier = NA_character_, skipGeometry = NA, time = NA_character_, bbox = NA, @@ -41,7 +42,7 @@ Multiple parameter_codes can be requested as a character vector.} \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, peak_id, unit_of_measure, value, last_modified, time, water_year, year, month, day, time_of_day, peak_since. +geometry, time_series_id, monitoring_location_id, parameter_code, peak_id, unit_of_measure, value, last_modified, time, water_year, year, month, day, time_of_day, peak_since, qualifier. 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.} @@ -76,6 +77,8 @@ See also Details below for more information.} \item{peak_since}{If not null, this record represents the peak value for the parameter code since the year contained in "peak_since".} +\item{qualifier}{This field indicates any qualifiers associated with an observation, for instance if a sensor may have been impacted by ice or if values were estimated.} + \item{skipGeometry}{This parameter can be used to skip response geometries for each feature. The returning object will be a data frame with no spatial information. The default \code{NA} will not specify the argument in the request.} diff --git a/tests/testthat/test_ngwmn.R b/tests/testthat/test_ngwmn.R new file mode 100644 index 00000000..1c625685 --- /dev/null +++ b/tests/testthat/test_ngwmn.R @@ -0,0 +1,76 @@ +context("NGWMN functions") + +test_that("NGWMN retrievals working", { + testthat::skip_on_cran() + testthat::skip_on_ci() + + cql <- '{ + "op": "between", + "args": [ + { "property": "water_level_above_navd88_ft" }, + [ "100.00", "200.00" ] + ] +}' + + wl_data <- read_ngwmn(service = "waterLevelObs", + monitoring_location_id = c("USGS-272838082142201", + "USGS-404159100494601", + "USGS-401216080362703"), + CQL = cql) + + # no CQL should work too: + wl_data_full <- read_ngwmn(service = "waterLevelObs", + monitoring_location_id = c("USGS-272838082142201", + "USGS-404159100494601", + "USGS-401216080362703")) + + cql3 <- '{ + "op": "and", + "args": [ + { + "op": "between", + "args": [ + { "property": "water_level_above_navd88_ft" }, + [ "100.00", "200.00" ] + ] + }, + { + "op": "in", + "args": [ + { "property": "monitoring_location_id" }, + [ "USGS-272838082142201", "USGS-404159100494601", "USGS-401216080362703" ] + ] + } + ] + }' + + + wl_data_alt <- read_ngwmn(service = "waterLevelObs", + CQL = cql3) + + expect_equal(nrow(wl_data_alt), nrow(wl_data)) + expect_gt(nrow(wl_data_full), nrow(wl_data)) + + sites <- c("ISWS-P428197", + "AKDNR-535143966816631", + "AKDNR-535134236016630") + ngwml_lith_sites <- read_ngwmn_lithology(monitoring_location_id = sites) + expect_all_true(c("ISWS", "AKDNR") %in% unique(ngwml_lith_sites$agency_code)) + + org_type <- read_ngwmn_sites(agency_code = "MN_DNR", + county_name = "Washington County") + expect_true("MN_DNR" == unique(org_type$agency_code)) + + site <- "USGS-272838082142201" + + ngwml_wl_time2 <- read_ngwmn_water_level(monitoring_location_id = site, + datetime = c("2022-01-01", "2024-01-01")) + expect_true(min(as.Date(ngwml_wl_time2$sample_time)) >= as.Date("2022-01-01")) + expect_true(max(as.Date(ngwml_wl_time2$sample_time)) <= as.Date("2024-01-01")) + + sites <- c("USGS-272838082142201", "USGS-404159100494601", + "USGS-401216080362703", "MBMG-702934") + ngwml_well_sites <- read_ngwmn_well_construction(monitoring_location_id = sites) + + expect_all_true(unique(ngwml_well_sites$monitoring_location_id) %in% sites) +}) diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index 393c13b4..2d05e114 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -169,13 +169,12 @@ test_that("peak, rating curves, surface-water measurements", { expect_equal(unique(gwl_1$monitoring_location_id), siteID) # No data: - stations <- "06011000" - expect_message(readNWISpeak( - stations, - startDate = "2024-08-01", - endDate = "2024-08-31", - convertType = FALSE - )) + + no_data <- read_waterdata_peaks( + monitoring_location_id = "USGS-06011000", + time = c("2024-08-01", "2024-08-31") + ) + expect_equal(nrow(no_data), 0) }) test_that("read_waterdata_daily", { diff --git a/vignettes/tutorial.Rmd b/vignettes/tutorial.Rmd index e97fa1cf..3f4900cb 100644 --- a/vignettes/tutorial.Rmd +++ b/vignettes/tutorial.Rmd @@ -441,9 +441,11 @@ There are two services that also have functions in `dataRetrieval`, the National Similar to WQP, the NGWMN brings groundwater data from multiple sources into a single location. There are currently a few `dataRetrieval` functions included: -* `readNGWMNsites()` -* `readNGWMNlevels()` -* `readNGWMNdata()`. +* `read_ngwmn_sites` +* `read_ngwmn_water_levels` +* `read_ngwmn_providers` +* `read_ngwmn_well_construction` +* `read_ngwmn_lithology` ## Network Linked Data Index (NLDI)