Extra query params

.github/workflows/pkgdown.yaml

@@ -74,7 +74,8 @@ jobs:
       - name: Build site
         run: |
           pkgdown::build_site(override = list(destination = "public")) |
-          file.copy(from = "./public/articles/logo.png",to = "./public/reference/logo.png")
+          file.copy(from = "./public/articles/logo.png",to = "./public/reference/logo.png") |
+          file.copy(from = "./public/articles/logo.png", to = "./public/news/logo.png")
         shell: Rscript {0}
       - name: Set up Quarto
         uses: quarto-dev/quarto-actions/setup@v2

.gitlab-ci.yml

@@ -141,7 +141,8 @@ pages:
     - |
       Rscript -e '
         pkgdown::build_site(override = list(destination = "public"))
-        file.copy(from = "./public/articles/logo.png", to = "./public/reference/logo.png")'
+        file.copy(from = "./public/articles/logo.png", to = "./public/reference/logo.png")
+        file.copy(from = "./public/articles/logo.png", to = "./public/news/logo.png")'
     - quarto render
   artifacts:
     paths:

NAMESPACE

@@ -23,6 +23,7 @@ export(importWQP)
 export(importWaterML1)
 export(importWaterML2)
 export(is_dataRetrieval_user)
+export(make_monitoring_location_arguments)
 export(pCodeToName)
 export(parameterCdFile)
 export(parse_WQP)

NEWS → NEWS.md

@@ -2,8 +2,12 @@ dataRetrieval 2.7.26
 ===================
 * Added suite of read_ngwmn to access new National Groundwater Monitoring
 Network API.
-* Added read_waterdata_use to access USGS's National Water Availability
-Assessment Data Companion API service.
+* Added read_wateruse to access USGS's National Water Availability Assessment Data Companion API service.
+* Created make_monitoring_location_arguments to help users understand 
+what new optional arguments are available in many of the read_waterdata functions.
+* Added ability to use `...` in the Water Data functions for: daily, latest-continuous, field-measurements, latest-daily, latest-field-measurements, continuous, and peaks. The "..." argument can now accept any parameter that is output from the make_monitoring_location_arguments function.
+* Added "q" argument to read_waterdata_monitoring_location. Full-text search across the most relevant text fields for this collection (e.g. site name, identifier, number, state, county, and site type).
+* Added "skipGeometry" argument to read_waterdata_continuous. Previously geometry wasn't included with continuous data, but now is supported.
 
 dataRetrieval 2.7.25
 ===================

R/get_ogc_data.R

@@ -54,13 +54,14 @@ get_ogc_data <- function(args, output_id, service, base = "OGC") {
       return_list <- walk_pages(req)
     }
 
-    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 <- 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)
@@ -217,46 +218,19 @@ switch_properties_id <- function(properties, id) {
 #' the default for time series functions is
 #' `r getOption("dataRetrieval.site_chunk_size_data")`.
 #' Setting to `NA` will eliminate site chunking, giving users full control.
-#' @param \dots Not used. Included to help differentiate official Water Data API arguments
-#' from more seldom used, optional dataRetrieval-specific arguments.
 #' @keywords internal
 check_arguments_non_api <- function(
   convertType,
   no_paging,
   limit,
   attach_request,
-  chunk_size,
-  ...
+  chunk_size
 ) {
-  if (!is.null(convertType)) {
-    if (!is.na(convertType) & !is.logical(convertType)) {
-      stop("convertType should be a logical TRUE/FALSE")
-    }
-  }
-
-  if (!is.null(no_paging)) {
-    if (!is.na(no_paging) & !is.logical(no_paging)) {
-      stop("no_paging should be a logical TRUE/FALSE")
-    }
-  }
-
-  if (!is.null(attach_request)) {
-    if (!is.na(attach_request) & !is.logical(attach_request)) {
-      stop("attach_request should be a logical TRUE/FALSE")
-    }
-  }
-
-  if (!is.null(limit)) {
-    if (!is.na(limit) & !is.numeric(limit)) {
-      stop("limit should be an integer")
-    }
-  }
-
-  if (!is.null(chunk_size)) {
-    if (!is.na(chunk_size) & !is.numeric(chunk_size)) {
-      stop("chunk_size should be an integer")
-    }
-  }
+  check_logical(convertType, "convertType")
+  check_logical(no_paging, "no_paging")
+  check_logical(attach_request, "attach_request")
+  check_integer(limit, "limit")
+  check_integer(chunk_size, "chunk_size")
 }
 
 #' Check other arguments
@@ -276,11 +250,7 @@ check_arguments_non_api <- function(
 #'
 #' @keywords internal
 check_arguments_api <- function(bbox, skipGeometry) {
-  if (!is.null(skipGeometry)) {
-    if (!is.na(skipGeometry) & !is.logical(skipGeometry)) {
-      stop("skipGeometry should be a logical TRUE/FALSE")
-    }
-  }
+  check_logical(skipGeometry, "skipGeometry")
 
   if (!is.null(bbox)) {
     if (!all(is.na(bbox))) {

R/make_monitoring_location_arguments.R

@@ -0,0 +1,204 @@
+#' Get Monitoring Location Arguments
+#'
+#' Many read_waterdata functions have a long list of arguments that can be used
+#' to find sites that have data. Users can use this function to create a list
+#' of possible arguments that can be used as input to the `monitoring_location_arguments`
+#' argument (found in many of the read_waterdata functions). This function
+#' also is used to check that user supplied available parameters to their queries
+#' when using the `monitoring_location_arguments` argument.
+#'
+#' @param service Endpoint to check arguments against. Possible values are
+#' "daily", "latest-continuous", "field-measurements", "latest-daily",
+#' "latest-field-measurements", "continuous", "peaks".
+#' @param agency_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$agency_code$description`
+#' @param agency_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$agency_name$description`
+#' @param monitoring_location_number `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$monitoring_location_number$description`
+#' @param monitoring_location_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$monitoring_location_name$description`
+#' @param district_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$district_code$description`
+#' @param country_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$country_code$description`
+#' @param country_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$country_name$description`
+#' @param state_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$state_code$description`
+#' @param state_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$state_name$description`
+#' @param county_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$county_code$description`
+#' @param county_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$county_name$description`
+#' @param minor_civil_division_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$minor_civil_division_code$description`
+#' @param site_type_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$site_type_code$description`
+#' @param site_type `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$site_type$description`
+#' @param hydrologic_unit_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$hydrologic_unit_code$description`
+#' @param basin_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$basin_code$description`
+#' @param altitude `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$altitude$description`
+#' @param altitude_accuracy `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$altitude_accuracy$description`
+#' @param altitude_method_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$altitude_method_code$description`
+#' @param altitude_method_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$altitude_method_name$description`
+#' @param vertical_datum `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$vertical_datum$description`
+#' @param vertical_datum_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$vertical_datum_name$description`
+#' @param horizontal_positional_accuracy_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$horizontal_positional_accuracy_code$description`
+#' @param horizontal_positional_accuracy `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$agency_code$description`
+#' @param horizontal_position_method_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$horizontal_position_method_code$description`
+#' @param horizontal_position_method_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$horizontal_position_method_name$description`
+#' @param original_horizontal_datum `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$original_horizontal_datum$description`
+#' @param original_horizontal_datum_name `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$original_horizontal_datum_name$description`
+#' @param drainage_area `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$drainage_area$description`
+#' @param contributing_drainage_area `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$contributing_drainage_area$description`
+#' @param time_zone_abbreviation `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$time_zone_abbreviation$description`
+#' @param uses_daylight_savings `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$agency_code$description`
+#' @param construction_date `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$construction_date$description`
+#' @param aquifer_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$aquifer_code$description`
+#' @param national_aquifer_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$national_aquifer_code$description`
+#' @param aquifer_type_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$agency_code$description`
+#' @param well_constructed_depth `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$well_constructed_depth$description`
+#' @param hole_constructed_depth `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$hole_constructed_depth$description`
+#' @param depth_source_code `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$depth_source_code$description`
+#' @param data_gap_interval `r check_OGC_requests(endpoint = "daily", type = "queryables")$properties$data_gap_interval$description`
+#' @param \dots Not used. Used to make sure the user isn't passing in arguments that aren't available.
+#' @param check_arguments Logical. Used to decide if the arguments passed in are available or not. The
+#' default is `FALSE`. Using `TRUE` will make two calls to the API, so if you are concerned
+#' with minimizing API calls, keep this value as `FALSE`. If you are concerned with
+#' making sure your calls are accepted by the service, set to `TRUE`.
+#' @export
+#' @examples
+#'
+#' make_monitoring_location_arguments(service = "daily", agency_name = "USGS")
+#' make_monitoring_location_arguments(service = "field-measurements",
+#'                                    state_name = c("Ohio", "Wisconsin"))
+make_monitoring_location_arguments <- function(
+  service = "daily",
+  agency_code = NA_character_,
+  agency_name = NA_character_,
+  monitoring_location_number = NA_character_,
+  monitoring_location_name = NA_character_,
+  district_code = NA_character_,
+  country_code = NA_character_,
+  country_name = NA_character_,
+  state_code = NA_character_,
+  state_name = NA_character_,
+  county_code = NA_character_,
+  county_name = NA_character_,
+  minor_civil_division_code = NA_character_,
+  site_type_code = NA_character_,
+  site_type = NA_character_,
+  hydrologic_unit_code = NA_character_,
+  basin_code = NA_character_,
+  altitude = NA_character_,
+  altitude_accuracy = NA_character_,
+  altitude_method_code = NA_character_,
+  altitude_method_name = NA_character_,
+  vertical_datum = NA_character_,
+  vertical_datum_name = NA_character_,
+  horizontal_positional_accuracy_code = NA_character_,
+  horizontal_positional_accuracy = NA_character_,
+  horizontal_position_method_code = NA_character_,
+  horizontal_position_method_name = NA_character_,
+  original_horizontal_datum = NA_character_,
+  original_horizontal_datum_name = NA_character_,
+  drainage_area = NA_character_,
+  contributing_drainage_area = NA_character_,
+  time_zone_abbreviation = NA_character_,
+  uses_daylight_savings = NA_character_,
+  construction_date = NA_character_,
+  aquifer_code = NA_character_,
+  national_aquifer_code = NA_character_,
+  aquifer_type_code = NA_character_,
+  well_constructed_depth = NA_character_,
+  hole_constructed_depth = NA_character_,
+  depth_source_code = NA_character_,
+  data_gap_interval = NA_character_,
+  ...,
+  check_arguments = FALSE
+) {
+  # Make sure no one passes in an argument that's not suppose to be there
+  rlang::check_dots_empty()
+  service_with_extra_queries <- c(
+    "daily",
+    "latest-continuous",
+    "field-measurements",
+    "latest-daily",
+    "latest-field-measurements",
+    "continuous",
+    "peaks"
+  )
+  match.arg(service, choices = service_with_extra_queries, several.ok = FALSE)
+
+  args <- mget(names(formals()))
+  args[["..."]] <- NULL
+  args[["service"]] <- NULL
+  args[["check_arguments"]] <- NULL
+
+  n_args <- names(args)
+
+  lapply(n_args, function(x) {
+    check_character(args[[x]], x)
+  })
+
+  if (check_arguments) {
+    # think about if we want this as an option
+    # don't want to waste a lot of hits to the API if people are
+    # running into their token limits
+    properties <- dataRetrieval::get_ogc_params(service)
+    queryables <- check_OGC_requests(endpoint = service, type = "queryables")
+    non_returned <- queryables$properties[
+      !names(queryables$properties) %in% names(properties)
+    ]
+
+    args_not_available <- args[!names(args) %in% names(non_returned)]
+    if (length(args_not_available) > 0) {
+      message(
+        "The ",
+        service,
+        " service doesn't accept: ",
+        paste0(names(args_not_available), collapse = ", "),
+        "."
+      )
+      message("Those arguments will be ignored.")
+    }
+
+    args <- args[names(args) %in% names(non_returned)]
+  }
+
+  return(args)
+}
+
+cleanup_arguments <- function(args, monitoring_location_arguments, service) {
+  query_args <- do.call(
+    make_monitoring_location_arguments,
+    c(monitoring_location_arguments, service = service)
+  )
+
+  args[["monitoring_location_arguments"]] <- NULL
+  args[["..."]] <- NULL
+  args <- c(args, query_args)
+
+  return(args)
+}
+
+check_character <- function(x, name) {
+  if (!is.null(x)) {
+    if (all(!is.na(x) & !is.character(x))) {
+      stop(paste(name, "should be a character"))
+    }
+  }
+}
+
+check_numeric <- function(x, name) {
+  if (!is.null(x)) {
+    if (all(!is.na(x) & !is.numeric(x))) {
+      stop(paste(name, "should be a numeric"))
+    }
+  }
+}
+
+check_integer <- function(x, name) {
+  if (!is.null(x)) {
+    if (all(!is.na(x) & !is.numeric(x))) {
+      stop(paste(name, "should be a integer"))
+    }
+  }
+}
+
+check_logical <- function(x, name) {
+  if (!is.null(x)) {
+    if (all(!is.na(x) & !is.logical(x))) {
+      stop(paste(name, "should be a logical (TRUE/FALSE)"))
+    }
+  }
+}

R/read_ngwmn_lithology.R

@@ -11,6 +11,8 @@
 #' Available options are:
 #' `r dataRetrieval:::get_properties_for_docs("lithologyObs", base = "NGWMN")`.
 #' The default (`NA`) will return all columns of the data.
+#' @param \dots Not used. Included to help differentiate official NGWMN API arguments
+#' from more seldom used, optional dataRetrieval-specific arguments.
 #' @inheritParams check_arguments_non_api
 #'
 #' @examplesIf is_dataRetrieval_user()
@@ -38,12 +40,12 @@ read_ngwmn_lithology <- function(
   attach_request = getOption("dataRetrieval.attach_request")
 ) {
   service <- "lithologyObs"
-  
+
   # Check for mandatory arguments:
-  if(all(is.na(monitoring_location_id))){
+  if (all(is.na(monitoring_location_id))) {
     stop("monitoring_location_id is a mandatory argument.")
   }
-  
+
   rlang::check_dots_empty()
   args <- mget(names(formals()))
 

R/read_ngwmn_providers.R

@@ -13,6 +13,8 @@
 #' Available options are:
 #' `r dataRetrieval:::get_properties_for_docs("providers", base = "NGWMN")`.
 #' The default (`NA`) will return all columns of the data.
+#' @param \dots Not used. Included to help differentiate official NGWMN API arguments
+#' from more seldom used, optional dataRetrieval-specific arguments.
 #' @inheritParams check_arguments_non_api
 #'
 #' @examplesIf is_dataRetrieval_user()

R/read_ngwmn_sites.R

@@ -68,7 +68,8 @@
 #' 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).
-#'
+#' @param \dots Not used. Included to help differentiate official NGWMN API arguments
+#' from more seldom used, optional dataRetrieval-specific arguments.
 #' @inheritParams check_arguments_non_api
 #' @examplesIf is_dataRetrieval_user()
 #'