diff --git a/.Rbuildignore b/.Rbuildignore index 8c7cdb4f..a4686bfb 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -90,7 +90,7 @@ vignettes/Status.Rmd vignettes/long_to_wide.Rmd vignettes/join_by_closest.Rmd vignettes/wqx3_development_plan.Rmd -vignettes/read_USGS_functions.Rmd +vignettes/read_waterdata_functions.Rmd vignettes/dataretrieval_discrete_changes_images/* ^ci$ ^public$ diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml index b6aa1e55..15254f9b 100644 --- a/.github/workflows/R-CMD-check.yaml +++ b/.github/workflows/R-CMD-check.yaml @@ -24,6 +24,7 @@ jobs: env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + API_USGS_PAT: ${{ secrets.API_USGS_PAT }} R_KEEP_PKG_SOURCE: yes CUSTOM_DR_UA: 'GitHub_CI' diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 7c20a4cb..ac3360ad 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -28,6 +28,7 @@ jobs: group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + API_USGS_PAT: ${{ secrets.API_USGS_PAT }} CUSTOM_DR_UA: 'GitHub_CI' steps: - uses: actions/checkout@581d62f320f2a4043a1ea6ac77290c60d27485cc diff --git a/.github/workflows/test-coverage.yaml b/.github/workflows/test-coverage.yaml index ce05609b..98e4b9e6 100644 --- a/.github/workflows/test-coverage.yaml +++ b/.github/workflows/test-coverage.yaml @@ -14,6 +14,7 @@ jobs: env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + API_USGS_PAT: ${{ secrets.API_USGS_PAT }} R_KEEP_PKG_SOURCE: yes CUSTOM_DR_UA: 'GitHub_CI' diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 76402775..fc5dec06 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -31,6 +31,7 @@ variables: NOT_CRAN: "true" PAGES_OUTDIR: "$CI_PROJECT_DIR/public" CUSTOM_DR_UA: "GitLab_CI" + API_USGS_PAT: "${API_USGS_PAT}" build-image: stage: build diff --git a/NAMESPACE b/NAMESPACE index 73f14c7c..c396b414 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -4,12 +4,12 @@ export(addWaterYear) export(calcWaterYear) export(checkWQPdates) export(check_OGC_requests) -export(check_USGS_sample_params) +export(check_waterdata_sample_params) export(constructNWISURL) export(constructUseURL) export(constructWQPURL) -export(construct_USGS_sample_request) export(construct_api_requests) +export(construct_waterdata_sample_request) export(countyCd) export(countyCdLookup) export(create_NWIS_bib) @@ -44,16 +44,18 @@ export(readNWISuv) export(readWQPdata) export(readWQPqw) export(readWQPsummary) -export(read_USGS_daily) -export(read_USGS_data) -export(read_USGS_monitoring_location) export(read_USGS_samples) -export(read_USGS_ts_meta) +export(read_waterdata) +export(read_waterdata_daily) +export(read_waterdata_monitoring_location) +export(read_waterdata_samples) +export(read_waterdata_ts_meta) export(renameNWISColumns) export(setAccess) export(stateCd) export(stateCdLookup) export(summarize_USGS_samples) +export(summarize_waterdata_samples) export(whatNWISdata) export(whatNWISsites) export(whatWQPdata) diff --git a/NEWS b/NEWS index c8981de2..2e656a3a 100644 --- a/NEWS +++ b/NEWS @@ -1,8 +1,11 @@ dataRetrieval 2.7.19 =================== -* Added read_USGS_daily, read_USGS_monitoring_location, read_USGS_ts_meta to access +* Added read_waterdata_daily, read_waterdata_monitoring_location, read_waterdata_ts_meta to access new USGS web services. * Added whisker and sf as dependencies. +* Renamed read_USGS_samples to read_waterdata_samples. +* Renamed summarize_USGS_samples to summarize_waterdata_samples. +* Added warning to setAccess for non-public endpoints. dataRetrieval 2.7.18 =================== diff --git a/R/dataRetrievals-package.R b/R/dataRetrievals-package.R index b92eda0e..cd205de7 100644 --- a/R/dataRetrievals-package.R +++ b/R/dataRetrievals-package.R @@ -96,7 +96,7 @@ NULL #' US State Code Lookup Table #' #' Classic lookup table for states. Has been replaced in functions with -#' `check_USGS_sample_params("states")`. +#' `check_waterdata_sample_params("states")`. #' #' @name stateCd #' @return stateCd data frame. @@ -118,7 +118,7 @@ NULL #' US County Code Lookup Table #' #' Classic lookup table for counties. Has been replaced in functions with -#' `check_USGS_sample_params("counties")`. +#' `check_USGS_waterdata_params("counties")`. #' #' @name countyCd #' @return countyCd data frame. diff --git a/R/readNWISdata.R b/R/readNWISdata.R index 8179fcde..d0c47fc4 100644 --- a/R/readNWISdata.R +++ b/R/readNWISdata.R @@ -71,7 +71,7 @@ #' queryTime \tab POSIXct \tab The time the data was returned \cr #' } #' -#' @seealso [read_USGS_data()] +#' @seealso [read_waterdata()] #' @export #' @examplesIf is_dataRetrieval_user() #' \donttest{ @@ -189,14 +189,14 @@ for more information. https://cran.r-project.org/web/packages/dataRetrieval/vignettes/qwdata_changes.html" ) } else if (service == "dv"){ - .Deprecated(new = "read_USGS_daily", + .Deprecated(new = "read_waterdata_daily", package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_USGS_daily.") + msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_daily.") } else if (service == "site"){ - .Deprecated(new = "read_USGS_monitoring_location", + .Deprecated(new = "read_waterdata_monitoring_location", package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_USGS_monitoring_location") + msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_monitoring_location") } else { message(new_nwis_message()) } @@ -288,7 +288,7 @@ stateCdLookup <- function(input, outputType <- match.arg(outputType, c("postal", "fullName", "id", "fips")) - states <- check_USGS_sample_params("states") + states <- check_waterdata_sample_params("states") country <- match.arg(country, choices = unique(states$countryCode), several.ok = FALSE) states <- states[states$countryCode == country,] @@ -360,7 +360,7 @@ countyCdLookup <- function(state, county, outputType = "fips") { stop("Only one state allowed in countyCdLookup.") } - counties <- check_USGS_sample_params("counties") + counties <- check_waterdata_sample_params("counties") # first turn state into stateCd postal name state_postal <- stateCdLookup(state, diff --git a/R/readNWISdv.R b/R/readNWISdv.R index acd70335..c67a773c 100644 --- a/R/readNWISdv.R +++ b/R/readNWISdv.R @@ -49,12 +49,12 @@ #' queryTime \tab POSIXct \tab The time the data was returned \cr #' } #' -#' @seealso [read_USGS_daily()] +#' @seealso [read_waterdata_daily()] #' @export #' @keywords data import USGS web service #' @examples #' -#' # see ?read_USGS_daily +#' # see ?read_waterdata_daily #' #' #site_id <- "04085427" #' #startDate <- "2012-01-01" @@ -69,9 +69,9 @@ readNWISdv <- function(siteNumbers, endDate = "", statCd = "00003") { - .Deprecated(new = "read_USGS_daily", + .Deprecated(new = "read_waterdata_daily", package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_USGS_daily.") + msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_daily.") url <- constructNWISURL( siteNumbers = siteNumbers, diff --git a/R/readNWISsite.R b/R/readNWISsite.R index 722b512f..4ab14e63 100644 --- a/R/readNWISsite.R +++ b/R/readNWISsite.R @@ -59,17 +59,17 @@ #' comment \tab character \tab Header comments from the RDB file \cr #' } #' @export -#' @seealso [read_USGS_monitoring_location()] +#' @seealso [read_waterdata_monitoring_location()] #' @examples #' -#' # see ?read_USGS_monitoring_location +#' # see ?read_waterdata_monitoring_location #' # siteINFOMulti <- readNWISsite(c("05114000", "09423350")) #' readNWISsite <- function(siteNumbers) { - .Deprecated(new = "read_USGS_monitoring_location", + .Deprecated(new = "read_waterdata_monitoring_location", package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_USGS_monitoring_location") + msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_monitoring_location") baseURL <- httr2::request(pkg.env[["site"]]) diff --git a/R/read_USGS_data.R b/R/read_waterdata.R similarity index 92% rename from R/read_USGS_data.R rename to R/read_waterdata.R index e8f52c49..b19e9a7a 100644 --- a/R/read_USGS_data.R +++ b/R/read_waterdata.R @@ -1,4 +1,4 @@ -#' Generalized USGS data retrieval function +#' Generalized USGS Water Data API retrieval function #' #' Function that allows complex CQL queries. #' See @@ -34,17 +34,15 @@ #' ] #' }' #' -#' dv_data <- read_USGS_data(service = "daily", +#' dv_data <- read_waterdata(service = "daily", #' CQL = cql, #' time = c("2023-01-01", "2024-01-01")) #' #' } -read_USGS_data <- function(service, +read_waterdata <- function(service, CQL, ..., convertType = TRUE){ - - message("Function in development, use at your own risk.") query_req <- get_collection() diff --git a/R/read_USGS_daily.R b/R/read_waterdata_daily.R similarity index 91% rename from R/read_USGS_daily.R rename to R/read_waterdata_daily.R index 87947a84..2ac5f01c 100644 --- a/R/read_USGS_daily.R +++ b/R/read_waterdata_daily.R @@ -40,33 +40,33 @@ #' \donttest{ #' site <- "USGS-02238500" #' pcode <- "00060" -#' dv_data_sf <- read_USGS_daily(monitoring_location_id = site, +#' dv_data_sf <- read_waterdata_daily(monitoring_location_id = site, #' parameter_code = "00060", #' time = c("2021-01-01", "2022-01-01")) #' -#' dv_data_trim <- read_USGS_daily(monitoring_location_id = site, +#' dv_data_trim <- read_waterdata_daily(monitoring_location_id = site, #' parameter_code = "00060", #' properties = c("monitoring_location_id", #' "value", #' "time"), #' time = c("2021-01-01", "2022-01-01")) #' -#' dv_data <- read_USGS_daily(monitoring_location_id = site, +#' dv_data <- read_waterdata_daily(monitoring_location_id = site, #' parameter_code = "00060", #' skipGeometry = TRUE) #' -#' dv_data_period <- read_USGS_daily(monitoring_location_id = site, +#' dv_data_period <- read_waterdata_daily(monitoring_location_id = site, #' parameter_code = "00060", #' time = "P7D") #' -#' multi_site <- read_USGS_daily(monitoring_location_id = c("USGS-01491000", +#' multi_site <- read_waterdata_daily(monitoring_location_id = c("USGS-01491000", #' "USGS-01645000"), #' parameter_code = c("00060", "00010"), #' limit = 500, #' time = c("2023-01-01", "2024-01-01")) #' #' } -read_USGS_daily <- function(monitoring_location_id = NA_character_, +read_waterdata_daily <- function(monitoring_location_id = NA_character_, parameter_code = NA_character_, statistic_id = NA_character_, properties = NA_character_, @@ -84,8 +84,6 @@ read_USGS_daily <- function(monitoring_location_id = NA_character_, max_results = NA, convertType = TRUE){ - message("Function in development, use at your own risk.") - service <- "daily" output_id <- "daily_id" diff --git a/R/read_USGS_monitoring_location.R b/R/read_waterdata_monitoring_location.R similarity index 93% rename from R/read_USGS_monitoring_location.R rename to R/read_waterdata_monitoring_location.R index cb0dba35..9489a1bb 100644 --- a/R/read_USGS_monitoring_location.R +++ b/R/read_waterdata_monitoring_location.R @@ -66,30 +66,30 @@ #' #' \donttest{ #' site <- "USGS-02238500" -#' site_info <- read_USGS_monitoring_location(monitoring_location_id = site) +#' site_info <- read_waterdata_monitoring_location(monitoring_location_id = site) #' -#' site_slim <- read_USGS_monitoring_location(monitoring_location_id = site, +#' site_slim <- read_waterdata_monitoring_location(monitoring_location_id = site, #' properties = c("monitoring_location_id", #' "state_name", #' "country_name")) #' -#' site_slim_no_sf_slim <- read_USGS_monitoring_location(monitoring_location_id = site, +#' site_slim_no_sf_slim <- read_waterdata_monitoring_location(monitoring_location_id = site, #' properties = c("monitoring_location_id", #' "state_name", #' "country_name"), #' skipGeometry = TRUE) #' -#' site_info_no_sf <- read_USGS_monitoring_location(monitoring_location_id = site, +#' site_info_no_sf <- read_waterdata_monitoring_location(monitoring_location_id = site, #' skipGeometry = TRUE) #' #' bbox_vals = c(-94.00, 35.0, -93.5, 35.5) -#' multi_site <- read_USGS_monitoring_location(bbox = bbox_vals) -#' multi_site_n_100 <- read_USGS_monitoring_location(bbox = bbox_vals, +#' multi_site <- read_waterdata_monitoring_location(bbox = bbox_vals) +#' multi_site_n_100 <- read_waterdata_monitoring_location(bbox = bbox_vals, #' max_results = 100) -#' multi_site_limit_100 <- read_USGS_monitoring_location(bbox = bbox_vals, +#' multi_site_limit_100 <- read_waterdata_monitoring_location(bbox = bbox_vals, #' limit = 100) #' } -read_USGS_monitoring_location <- function(monitoring_location_id = NA_character_, +read_waterdata_monitoring_location <- function(monitoring_location_id = NA_character_, agency_code = NA_character_, agency_name = NA_character_, monitoring_location_number = NA_character_, @@ -134,9 +134,7 @@ read_USGS_monitoring_location <- function(monitoring_location_id = NA_character_ limit = NA, max_results = NA, skipGeometry = NA){ - - message("Function in development, use at your own risk.") - + service <- "monitoring-locations" output_id <- "monitoring_location_id" diff --git a/R/read_USGS_samples.R b/R/read_waterdata_samples.R similarity index 79% rename from R/read_USGS_samples.R rename to R/read_waterdata_samples.R index 032955b0..d41f0448 100644 --- a/R/read_USGS_samples.R +++ b/R/read_waterdata_samples.R @@ -14,9 +14,9 @@ #' numbers without an agency prefix are assumed to have the prefix USGS. #' @param activityMediaName Sample media refers to the environmental medium that #' was sampled or analyzed. See available options by running -#' `check_USGS_sample_params("samplemedia")$activityMedia`. +#' `check_waterdata_sample_params("samplemedia")$activityMedia`. #' @param siteTypeCode Site type code query parameter. See available -#' options by running `check_USGS_sample_params("sitetype")$typeCode`. +#' options by running `check_waterdata_sample_params("sitetype")$typeCode`. #' @param boundingBox North and South are latitude values; East and West are longitude values. #' A vector of 4 (west, south, east, north) is expected. #' An example would be: c(-92.8, 44.2, -88.9, 46.0). @@ -35,7 +35,7 @@ #' records that match the date. #' @param characteristicGroup Characteristic group is a broad category describing the sample. #' See available options by running -#' `check_USGS_sample_params("characteristicgroup")$characteristicGroup`. +#' `check_waterdata_sample_params("characteristicgroup")$characteristicGroup`. #' @param characteristicUserSupplied Observed property is the USGS term for the #' constituent sampled and the property name gives a detailed description of what #' was sampled. Observed property is mapped to characteristicUserSupplied and replaces @@ -45,21 +45,21 @@ #' . #' @param characteristic Characteristic is a specific category describing the sample. #' See available options by running -#' `check_USGS_sample_params("characteristics")$characteristicName`. +#' `check_waterdata_sample_params("characteristics")$characteristicName`. #' @param stateFips State query parameter. To get a list of available state fips, -#' run `check_USGS_sample_params("states")`. The "fips" can be created using the function +#' run `check_waterdata_sample_params("states")`. The "fips" can be created using the function #' `stateCdLookup` - for example: `stateCdLookup("WI", "fips")`. #' FIPs codes for states take the format: #' CountryAbbrev:StateNumber, like US:55 for Wisconsin. #' @param countyFips County query parameter. To get a list of available counties, -#' run `check_USGS_sample_params("counties")`. The "Fips" can be created using the function +#' run `check_waterdata_sample_params("counties")`. The "Fips" can be created using the function #' `countyCdLookup` - for example: `countyCdLookup("WI", "Dane", "fips")` #' for Dane County, WI. #' FIPs codes for counties take the format: #' CountryAbbrev:StateNumber:CountyNumber, like US:55:025 for Dane County, WI. #' @param countryFips Country query parameter. Do not set redundant parameters. #' If another query parameter contains the country information, leave this parameter -#' set to the default NA. See available options by running `check_USGS_sample_params("countries")`, +#' set to the default NA. See available options by running `check_waterdata_sample_params("countries")`, #' where the "id" field contains the value to use in the countryFips input. #' @param projectIdentifier Project identifier query parameter. This information #' would be needed from prior project information. @@ -68,7 +68,7 @@ #' @param siteTypeName Site type name query parameter. See available #' options by running `check_param("sitetype")$typeName`. #' @param usgsPCode USGS parameter code. See available options by running -#' `check_USGS_sample_params("characteristics")$parameterCode`. +#' `check_waterdata_sample_params("characteristics")$parameterCode`. #' @param pointLocationLatitude Latitude for a point/radius query (decimal degrees). Must be used #' with pointLocationLongitude and pointLocationWithinMiles. #' @param pointLocationLongitude Longitude for a point/radius query (decimal degrees). Must be used @@ -91,13 +91,13 @@ #' @examplesIf is_dataRetrieval_user() #' #' \donttest{ -#' req <- construct_USGS_sample_request( +#' req <- construct_waterdata_sample_request( #' monitoringLocationIdentifier = "USGS-04074950", #' characteristicUserSupplied = "pH, water, unfiltered, field") #' rawData <- importWQP(req) #' #' } -construct_USGS_sample_request <- function(monitoringLocationIdentifier = NA, +construct_waterdata_sample_request <- function(monitoringLocationIdentifier = NA, siteTypeCode = NA, boundingBox = NA, hydrologicUnit = NA, @@ -176,36 +176,36 @@ construct_USGS_sample_request <- function(monitoringLocationIdentifier = NA, if(all(!is.na(siteTypeCode))){ siteTypeCode <- match.arg(siteTypeCode, - check_USGS_sample_params("sitetype")$typeCode, + check_waterdata_sample_params("sitetype")$typeCode, several.ok = TRUE) } if(all(!is.na(activityMediaName))){ activityMediaName <- match.arg(activityMediaName, - check_USGS_sample_params("samplemedia")$activityMedia, + check_waterdata_sample_params("samplemedia")$activityMedia, several.ok = TRUE) } if(all(!is.na(characteristicGroup))){ characteristicGroup <- match.arg(characteristicGroup, - check_USGS_sample_params("characteristicgroup")$characteristicGroup, + check_waterdata_sample_params("characteristicgroup")$characteristicGroup, several.ok = TRUE) } if(all(!is.na(countryFips))){ countryFips <- match.arg(countryFips, - check_USGS_sample_params("countries")$countryCode, + check_waterdata_sample_params("countries")$countryCode, several.ok = TRUE) } if(all(!is.na(siteTypeName))){ siteTypeName <- match.arg(siteTypeName, - check_USGS_sample_params("sitetype")$typeLongName, + check_waterdata_sample_params("sitetype")$typeLongName, several.ok = TRUE) } if(all(!is.na(stateFips))){ - states <- check_USGS_sample_params("states") + states <- check_waterdata_sample_params("states") state_codes <- paste(states$countryCode, states$fipsCode, sep = ":") stateFips <- match.arg(stateFips, state_codes, @@ -213,10 +213,10 @@ construct_USGS_sample_request <- function(monitoringLocationIdentifier = NA, } if(all(!is.na(countyFips))){ - states <- check_USGS_sample_params("states") + states <- check_waterdata_sample_params("states") state_codes <- paste(states$countryCode, states$fipsCode, sep = ":") - counties <- check_USGS_sample_params("counties") + counties <- check_waterdata_sample_params("counties") state_cd <- stats::setNames(states$fipsCode, states$stateAbbrev) county_codes <- paste(counties$countryCode, @@ -329,19 +329,19 @@ explode_query <- function(baseURL, POST = FALSE, x){ #' @examplesIf is_dataRetrieval_user() #' #' \donttest{ -#' groups <- check_USGS_sample_params("characteristicgroup") -#' states <- check_USGS_sample_params("states") -#' countries <- check_USGS_sample_params("countries") -#' counties <- check_USGS_sample_params("counties") -#' sitetypes <- check_USGS_sample_params("sitetype") -#' samplemedia <- check_USGS_sample_params("samplemedia") -#' characteristics <- check_USGS_sample_params("characteristics", +#' groups <- check_waterdata_sample_params("characteristicgroup") +#' states <- check_waterdata_sample_params("states") +#' countries <- check_waterdata_sample_params("countries") +#' counties <- check_waterdata_sample_params("counties") +#' sitetypes <- check_waterdata_sample_params("sitetype") +#' samplemedia <- check_waterdata_sample_params("samplemedia") +#' characteristics <- check_waterdata_sample_params("characteristics", #' group = "Biological") -#' observedProperties <- check_USGS_sample_params("observedproperty", +#' observedProperties <- check_waterdata_sample_params("observedproperty", #' text = "phosphorus") #' #' } -check_USGS_sample_params <- function(service = "characteristicgroup", +check_waterdata_sample_params <- function(service = "characteristicgroup", ...){ service_options <- c("characteristicgroup", "states", "counties", @@ -365,9 +365,7 @@ check_USGS_sample_params <- function(service = "characteristicgroup", check_group_req <- httr2::req_url_query(check_group_req, !!!params) } - - message("GET: ", check_group_req$url) - + check_group <- httr2::req_perform(check_group_req) |> httr2::resp_body_string() |> jsonlite::fromJSON() @@ -381,35 +379,35 @@ check_USGS_sample_params <- function(service = "characteristicgroup", #' This function creates the call and gets the data for discrete water quality samples data #' service described at . #' -#' @inheritParams construct_USGS_sample_request +#' @inheritParams construct_waterdata_sample_request #' @param tz character to set timezone attribute of datetime. Default is UTC #' (properly accounting for daylight savings times based on the data's provided tz_cd column). #' Possible values include "America/New_York","America/Chicago", "America/Denver","America/Los_Angeles", #' "America/Anchorage","America/Honolulu","America/Jamaica","America/Managua", #' "America/Phoenix", and "America/Metlakatla" #' @export -#' +#' @rdname read_waterdata_samples #' @examplesIf is_dataRetrieval_user() #' #' \donttest{ -#' ph_data <- read_USGS_samples( +#' ph_data <- read_waterdata_samples( #' monitoringLocationIdentifier = "USGS-04074950", #' characteristicUserSupplied = "pH, water, unfiltered, field", #' activityStartDateUpper = "2000-01-01", #' dataProfile = "narrow") #' #' nameToUse <- "pH" -#' pHData <- read_USGS_samples(monitoringLocationIdentifier = "USGS-04024315", +#' pHData <- read_waterdata_samples(monitoringLocationIdentifier = "USGS-04024315", #' characteristic = nameToUse) #' ncol(pHData) #' attr(pHData, "url") #' attr(pHData, "queryTime") #' -#' summary_data <- read_USGS_samples(monitoringLocationIdentifier = "USGS-04024315", +#' summary_data <- read_waterdata_samples(monitoringLocationIdentifier = "USGS-04024315", #' dataType = "projects") #' #' } -read_USGS_samples <- function(monitoringLocationIdentifier = NA, +read_waterdata_samples <- function(monitoringLocationIdentifier = NA, siteTypeCode = NA, boundingBox = NA, hydrologicUnit = NA, @@ -433,7 +431,7 @@ read_USGS_samples <- function(monitoringLocationIdentifier = NA, dataProfile = NA, tz = "UTC"){ - request_url <- construct_USGS_sample_request(monitoringLocationIdentifier = monitoringLocationIdentifier, + request_url <- construct_waterdata_sample_request(monitoringLocationIdentifier = monitoringLocationIdentifier, siteTypeCode = siteTypeCode, boundingBox = boundingBox, hydrologicUnit = hydrologicUnit, @@ -474,18 +472,17 @@ read_USGS_samples <- function(monitoringLocationIdentifier = NA, #' numbers without an agency prefix are assumed to have the prefix USGS. #' @export #' @return data frame with summary of data available based on the monitoringLocationIdentifier -#' +#' @rdname summarize_waterdata_samples #' @examplesIf is_dataRetrieval_user() #' #' \donttest{ #' monitoringLocationIdentifier <- "USGS-04074950" #' -#' what_data <- summarize_USGS_samples(monitoringLocationIdentifier) +#' what_data <- summarize_waterdata_samples(monitoringLocationIdentifier) #' #' } -summarize_USGS_samples <- function(monitoringLocationIdentifier){ - message("Function in development, use at your own risk.") - +summarize_waterdata_samples <- function(monitoringLocationIdentifier){ + if(length(monitoringLocationIdentifier) > 1){ stop("Summary service only available for one site at a time.") } @@ -507,4 +504,74 @@ summarize_USGS_samples <- function(monitoringLocationIdentifier){ attr(df, "queryTime") <- Sys.time() return(df) -} \ No newline at end of file +} + + +#' @rdname read_waterdata_samples +#' @export +read_USGS_samples <- function(monitoringLocationIdentifier = NA, + siteTypeCode = NA, + boundingBox = NA, + hydrologicUnit = NA, + activityMediaName = NA, + characteristicGroup = NA, + characteristic = NA, + characteristicUserSupplied = NA, + activityStartDateLower = NA, + activityStartDateUpper = NA, + countryFips = NA, + stateFips = NA, + countyFips = NA, + projectIdentifier = NA, + recordIdentifierUserSupplied = NA, + siteTypeName = NA, + usgsPCode = NA, + pointLocationLatitude = NA, + pointLocationLongitude = NA, + pointLocationWithinMiles = NA, + dataType = "results", + dataProfile = NA, + tz = "UTC"){ + + .Deprecated(new = "read_waterdata_samples", + package = "dataRetrieval", + msg = "Function has been renamed. Please begin to migrate to read_waterdata_samples") + + + read_waterdata_samples(monitoringLocationIdentifier = monitoringLocationIdentifier, + siteTypeCode = siteTypeCode, + boundingBox = boundingBox, + hydrologicUnit = hydrologicUnit, + activityMediaName = activityMediaName, + characteristicGroup = characteristicGroup, + characteristic = characteristic, + characteristicUserSupplied = characteristicUserSupplied, + activityStartDateLower = activityStartDateLower, + activityStartDateUpper = activityStartDateUpper, + countryFips = countryFips, + stateFips = stateFips, + countyFips = countyFips, + projectIdentifier = projectIdentifier, + recordIdentifierUserSupplied = recordIdentifierUserSupplied, + siteTypeName = siteTypeName, + usgsPCode = usgsPCode, + pointLocationLatitude = pointLocationLatitude, + pointLocationLongitude = pointLocationLongitude, + pointLocationWithinMiles = pointLocationWithinMiles, + dataType = dataType, + dataProfile = dataProfile, + tz = tz) +} + + +#' @rdname summarize_waterdata_samples +#' @export +summarize_USGS_samples <- function(monitoringLocationIdentifier){ + + .Deprecated(new = "summarize_waterdata_samples", + package = "dataRetrieval", + msg = "Function has been renamed. Please begin to migrate to summarize_waterdata_samples") + + summarize_waterdata_samples(monitoringLocationIdentifier) +} + diff --git a/R/read_USGS_ts_meta.R b/R/read_waterdata_ts_meta.R similarity index 95% rename from R/read_USGS_ts_meta.R rename to R/read_waterdata_ts_meta.R index e2f7efd2..1dc701f7 100644 --- a/R/read_USGS_ts_meta.R +++ b/R/read_waterdata_ts_meta.R @@ -43,9 +43,9 @@ #' #' \donttest{ #' site <- "USGS-02238500" -#' meta_1 <- read_USGS_ts_meta(monitoring_location_id = site) +#' meta_1 <- read_waterdata_ts_meta(monitoring_location_id = site) #' -#' meta_multi <- read_USGS_ts_meta(monitoring_location_id = c("USGS-01491000", +#' meta_multi <- read_waterdata_ts_meta(monitoring_location_id = c("USGS-01491000", #' "USGS-01645000"), #' parameter_code = c("00060", "00010"), #' properties = c("monitoring_location_id", @@ -55,7 +55,7 @@ #' "time_series_id"), #' skipGeometry = TRUE) #' } -read_USGS_ts_meta <- function(monitoring_location_id = NA_character_, +read_waterdata_ts_meta <- function(monitoring_location_id = NA_character_, parameter_code = NA_character_, parameter_name = NA_character_, properties = NA_character_, @@ -76,9 +76,7 @@ read_USGS_ts_meta <- function(monitoring_location_id = NA_character_, max_results = NA, bbox = NA, convertType = FALSE){ - - message("Function in development, use at your own risk.") - + service = "time-series-metadata" output_id <- "time_series_id" diff --git a/R/setAccess.R b/R/setAccess.R index 643ac7ed..ac33a195 100644 --- a/R/setAccess.R +++ b/R/setAccess.R @@ -27,12 +27,18 @@ setAccess <- function(access = "public") { if (access == "internal") { pkg.env$access <- "3" message("setting access to internal") + warning("Internal access is slated for decommision. +Please contact comptools@usgs.gov for more information.") } else if (access == "cooperator") { pkg.env$access <- "1" message("setting access to cooperator") + warning("Cooperator access is slated for decommision. +Please contact comptools@usgs.gov for more information.") } else if (access == "USGS") { pkg.env$access <- "2" message("setting access to all USGS Water Science Centers") + warning("Water Science Center access is slated for decommision. +Please contact comptools@usgs.gov for more information.") } else { pkg.env$access <- NULL message("setting access to public") diff --git a/R/whatNWISdata.R b/R/whatNWISdata.R index 13e29f76..dfdf1a23 100644 --- a/R/whatNWISdata.R +++ b/R/whatNWISdata.R @@ -63,10 +63,10 @@ #' queryTime \tab POSIXct \tab The time the data was returned \cr #' } #' @export -#' @seealso [read_USGS_ts_meta()] +#' @seealso [read_waterdata_ts_meta()] #' @examples #' -#' # see ?read_USGS_ts_meta +#' # see ?read_waterdata_ts_meta #' #' #site1 <- whatWQPsamples(siteid = "USGS-01594440") #' @@ -83,9 +83,9 @@ whatNWISdata <- function(..., convertType = TRUE) { prewarned <- FALSE - .Deprecated(new = "read_USGS_ts_meta", + .Deprecated(new = "read_waterdata_ts_meta", package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_USGS_ts_meta") + msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_ts_meta") if ("service" %in% names(matchReturn)) { service <- matchReturn$service diff --git a/R/whatNWISsites.R b/R/whatNWISsites.R index cb15ce73..8ece54c8 100644 --- a/R/whatNWISsites.R +++ b/R/whatNWISsites.R @@ -26,19 +26,19 @@ #' queryTime \tab POSIXct \tab The time the data was returned \cr #' } #' @export -#' @seealso [read_USGS_monitoring_location()] +#' @seealso [read_waterdata_monitoring_location()] #' #' @examples #' -#' # see ?read_USGS_monitoring_location +#' # see ?read_waterdata_monitoring_location #' #siteListPhos <- whatNWISsites(stateCd = "OH", parameterCd = "00665") #' #oneSite <- whatNWISsites(sites = "05114000") #' whatNWISsites <- function(...) { - .Deprecated(new = "read_USGS_monitoring_location", + .Deprecated(new = "read_waterdata_monitoring_location", package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_USGS_monitoring_location") + msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_monitoring_location") matchReturn <- convertLists(...) diff --git a/README.Rmd b/README.Rmd index ae80bcc8..af74e5a4 100644 --- a/README.Rmd +++ b/README.Rmd @@ -39,15 +39,15 @@ If you have additional questions about these changes, email CompTools@usgs.gov. 1. Get instantaneous USGS data (for example, discharge sensor data). Start here: `?readNWISuv` -2. Get daily USGS data (for example, mean daily discharge). Start here: `?read_USGS_daily` +2. Get daily USGS data (for example, mean daily discharge). Start here: `?read_waterdata_daily` 3. Get USGS groundwater data. Start here: `?readNWISgwl` 4. Get discrete water quality data from a cooperative service that integrates publicly available water-quality data from the USGS, EPA, and over 400 state, federal, tribal, and local agencies. Start here: `?readWQPdata` -5. Get USGS discrete water quality data. Start here: `?read_USGS_samples` +5. Get USGS discrete water quality data. Start here: `?read_waterdata_samples` -6. Get metadata about USGS time series data, including instantaneous and daily data. Start here: `?read_USGS_ts_meta` +6. Get metadata about USGS time series data, including instantaneous and daily data. Start here: `?read_waterdata_ts_meta` 7. Find Hydro Network-Linked Data Index (NLDI) data. Start here: `?findNLDI` @@ -88,7 +88,7 @@ You can use `usethis::edit_r_environ()` to edit find and open your .Renviron fil ### Style -New functions will use a "snake case", such as "read_USGS_samples". Older functions use camel case, such as "readNWISdv". The difference is the underscore between words. This should be a handy way to tell the difference between newer modern data access, and the older traditional functions. +New functions will use a "snake case", such as "read_waterdata_samples". Older functions use camel case, such as "readNWISdv". The difference is the underscore between words. This should be a handy way to tell the difference between newer modern data access, and the older traditional functions. ### Structure @@ -96,7 +96,7 @@ Historically, we allowed users to customize their queries via the `...` argument ### Dependencies -As we develop functions for the modern USGS web services, we'll continue to explore updating package dependencies. +As we develop functions for the modern USGS Water Data APIs, we'll continue to explore updating package dependencies. ### Developmental workflow diff --git a/README.md b/README.md index a9a35dda..5125410f 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ If you have additional questions about these changes, email Start here: `?readNWISuv` 2. Get daily USGS data (for example, mean daily discharge). Start here: - `?read_USGS_daily` + `?read_waterdata_daily` 3. Get USGS groundwater data. Start here: `?readNWISgwl` @@ -41,10 +41,10 @@ If you have additional questions about these changes, email `?readWQPdata` 5. Get USGS discrete water quality data. Start here: - `?read_USGS_samples` + `?read_waterdata_samples` 6. Get metadata about USGS time series data, including instantaneous - and daily data. Start here: `?read_USGS_ts_meta` + and daily data. Start here: `?read_waterdata_ts_meta` 7. Find Hydro Network-Linked Data Index (NLDI) data. Start here: `?findNLDI` @@ -94,7 +94,7 @@ recognized. ### Style -New functions will use a “snake case”, such as “read_USGS_samples”. +New functions will use a “snake case”, such as “read_waterdata_samples”. Older functions use camel case, such as “readNWISdv”. The difference is the underscore between words. This should be a handy way to tell the difference between newer modern data access, and the older traditional @@ -116,8 +116,8 @@ able to build up argument lists to pass into the function. ### Dependencies -As we develop functions for the modern USGS web services, we’ll continue -to explore updating package dependencies. +As we develop functions for the modern USGS Water Data APIs, we’ll +continue to explore updating package dependencies. ### Developmental workflow @@ -157,17 +157,17 @@ citation(package = "dataRetrieval") #> #> De Cicco, L.A., Hirsch, R.M., Lorenz, D., Watkins, W.D., Johnson, M., #> 2025, dataRetrieval: R packages for discovering and retrieving water -#> data available from Federal hydrologic web services, v.2.7.18, +#> data available from Federal hydrologic web services, v.2.7.19, #> doi:10.5066/P9X4L3GE #> #> A BibTeX entry for LaTeX users is #> #> @Manual{, -#> author = {Laura DeCicco and Robert Hirsch and David Lorenz and Jordan Read and Jordan Walker and Lindsay Platt and David Watkins and David Blodgett and Mike Johnson and Aliesha Krall and Lee Stanish}, +#> author = {Laura DeCicco and Robert Hirsch and David Lorenz and Jordan Read and Jordan Walker and Lindsay Platt and David Watkins and David Blodgett and Mike Johnson and Aliesha Krall and Lee Stanish and Joeseph Zemmels and Elise Hinman and Michael Mahoney}, #> title = {dataRetrieval: R packages for discovering and retrieving water data available from U.S. federal hydrologic web services}, #> publisher = {U.S. Geological Survey}, #> address = {Reston, VA}, -#> version = {2.7.18}, +#> version = {2.7.19}, #> institution = {U.S. Geological Survey}, #> year = {2025}, #> doi = {10.5066/P9X4L3GE}, @@ -193,14 +193,14 @@ NWIScitation #> U.S. Geological Survey (2025). _National Water Information System data #> available on the World Wide Web (USGS Water Data for the Nation)_. #> doi:10.5066/F7P55KJN , Accessed Jun -#> 04, 2025, +#> 13, 2025, #> . print(NWIScitation, style = "Bibtex") #> @Manual{, #> title = {National Water Information System data available on the World Wide Web (USGS Water Data for the Nation)}, #> author = {{U.S. Geological Survey}}, #> doi = {10.5066/F7P55KJN}, -#> note = {Accessed Jun 04, 2025}, +#> note = {Accessed Jun 13, 2025}, #> year = {2025}, #> url = {https://waterservices.usgs.gov/nwis/dv/?site=09010500&format=waterml%2C1.1&ParameterCd=00060&StatCd=00003&startDT=1851-01-01}, #> } @@ -224,14 +224,14 @@ WQPcitation <- create_WQP_bib(SC) WQPcitation #> National Water Quality Monitoring Council (2025). _Water Quality #> Portal_. doi:10.5066/P9QRKUVJ , -#> Accessed Jun 04, 2025, +#> Accessed Jun 13, 2025, #> . print(WQPcitation, style = "Bibtex") #> @Manual{, #> title = {Water Quality Portal}, #> author = {{National Water Quality Monitoring Council}}, #> doi = {10.5066/P9QRKUVJ}, -#> note = {Accessed Jun 04, 2025}, +#> note = {Accessed Jun 13, 2025}, #> year = {2025}, #> url = {https://www.waterqualitydata.us/data/Result/search?siteid=USGS-05288705&count=no&pCode=00300&mimeType=csv}, #> } diff --git a/_pkgdown.yml b/_pkgdown.yml index 102b4999..20530cc1 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -40,8 +40,8 @@ navbar: menu: - text: Tutorial href: articles/tutorial.html - - text: New USGS Functions - href: articles/read_USGS_functions.html + - text: USGS Water Data APIs + href: articles/read_waterdata_functions.html - text: Background href: articles/dataRetrieval.html - text: Pivot Data @@ -67,16 +67,15 @@ reference: - title: USGS new data services desc: Functions to retrieve USGS data from new services. contents: - - read_USGS_samples - - read_USGS_daily - - read_USGS_ts_meta - - read_USGS_data - - read_USGS_monitoring_location - - read_USGS_data - - summarize_USGS_samples - - check_USGS_sample_params + - read_waterdata_samples + - read_waterdata_daily + - read_waterdata_ts_meta + - read_waterdata_monitoring_location + - read_waterdata + - summarize_waterdata_samples + - check_waterdata_sample_params - title: National Water Information System (NWIS) - desc: Functions to retrieve (USGS) NWIS data. These will be slowly phased out and replaced with the read_USGS family of functions. + desc: Functions to retrieve (USGS) NWIS data. These will be slowly phased out and replaced with the read_waterdata family of functions. contents: - readNWISdv - readNWISuv diff --git a/man/check_USGS_sample_params.Rd b/man/check_waterdata_sample_params.Rd similarity index 55% rename from man/check_USGS_sample_params.Rd rename to man/check_waterdata_sample_params.Rd index eb387605..d8b4a9eb 100644 --- a/man/check_USGS_sample_params.Rd +++ b/man/check_waterdata_sample_params.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/read_USGS_samples.R -\name{check_USGS_sample_params} -\alias{check_USGS_sample_params} +% Please edit documentation in R/read_waterdata_samples.R +\name{check_waterdata_sample_params} +\alias{check_waterdata_sample_params} \title{Check values from codeservice} \usage{ -check_USGS_sample_params(service = "characteristicgroup", ...) +check_waterdata_sample_params(service = "characteristicgroup", ...) } \arguments{ \item{service}{Options are: "characteristicgroup", "states", "counties", @@ -24,15 +24,15 @@ Call a service to check on values from: \dontshow{if (is_dataRetrieval_user()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} \donttest{ -groups <- check_USGS_sample_params("characteristicgroup") -states <- check_USGS_sample_params("states") -countries <- check_USGS_sample_params("countries") -counties <- check_USGS_sample_params("counties") -sitetypes <- check_USGS_sample_params("sitetype") -samplemedia <- check_USGS_sample_params("samplemedia") -characteristics <- check_USGS_sample_params("characteristics", +groups <- check_waterdata_sample_params("characteristicgroup") +states <- check_waterdata_sample_params("states") +countries <- check_waterdata_sample_params("countries") +counties <- check_waterdata_sample_params("counties") +sitetypes <- check_waterdata_sample_params("sitetype") +samplemedia <- check_waterdata_sample_params("samplemedia") +characteristics <- check_waterdata_sample_params("characteristics", group = "Biological") -observedProperties <- check_USGS_sample_params("observedproperty", +observedProperties <- check_waterdata_sample_params("observedproperty", text = "phosphorus") } diff --git a/man/construct_USGS_sample_request.Rd b/man/construct_waterdata_sample_request.Rd similarity index 88% rename from man/construct_USGS_sample_request.Rd rename to man/construct_waterdata_sample_request.Rd index d3b89415..6835e7f2 100644 --- a/man/construct_USGS_sample_request.Rd +++ b/man/construct_waterdata_sample_request.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/read_USGS_samples.R -\name{construct_USGS_sample_request} -\alias{construct_USGS_sample_request} +% Please edit documentation in R/read_waterdata_samples.R +\name{construct_waterdata_sample_request} +\alias{construct_waterdata_sample_request} \title{Construct request for USGS Samples Data} \usage{ -construct_USGS_sample_request( +construct_waterdata_sample_request( monitoringLocationIdentifier = NA, siteTypeCode = NA, boundingBox = NA, @@ -36,7 +36,7 @@ for example: AZ014-320821110580701, CAX01-15304600, USGS-040851385. Location numbers without an agency prefix are assumed to have the prefix USGS.} \item{siteTypeCode}{Site type code query parameter. See available -options by running \code{check_USGS_sample_params("sitetype")$typeCode}.} +options by running \code{check_waterdata_sample_params("sitetype")$typeCode}.} \item{boundingBox}{North and South are latitude values; East and West are longitude values. A vector of 4 (west, south, east, north) is expected. @@ -51,11 +51,11 @@ was sampled or analyzed.} \item{characteristicGroup}{Characteristic group is a broad category describing the sample. See available options by running -\code{check_USGS_sample_params("characteristicgroup")$characteristicGroup}.} +\code{check_waterdata_sample_params("characteristicgroup")$characteristicGroup}.} \item{characteristic}{Characteristic is a specific category describing the sample. See available options by running -\code{check_USGS_sample_params("characteristics")$characteristicName}.} +\code{check_waterdata_sample_params("characteristics")$characteristicName}.} \item{characteristicUserSupplied}{Observed property is the USGS term for the constituent sampled and the property name gives a detailed description of what @@ -77,17 +77,17 @@ records that match the date.} \item{countryFips}{Country query parameter. Do not set redundant parameters. If another query parameter contains the country information, leave this parameter -set to the default NA. See available options by running \code{check_USGS_sample_params("countries")}, +set to the default NA. See available options by running \code{check_waterdata_sample_params("countries")}, where the "id" field contains the value to use in the countryFips input.} \item{stateFips}{State query parameter. To get a list of available state fips, -run \code{check_USGS_sample_params("states")}. The "fips" can be created using the function +run \code{check_waterdata_sample_params("states")}. The "fips" can be created using the function \code{stateCdLookup} - for example: \code{stateCdLookup("WI", "fips")}. FIPs codes for states take the format: CountryAbbrev:StateNumber, like US:55 for Wisconsin.} \item{countyFips}{County query parameter. To get a list of available counties, -run \code{check_USGS_sample_params("counties")}. The "Fips" can be created using the function +run \code{check_waterdata_sample_params("counties")}. The "Fips" can be created using the function \code{countyCdLookup} - for example: \code{countyCdLookup("WI", "Dane", "fips")} for Dane County, WI. FIPs codes for counties take the format: @@ -103,7 +103,7 @@ information would be needed from the data supplier.} options by running \code{check_param("sitetype")$typeName}.} \item{usgsPCode}{USGS parameter code. See available options by running -\code{check_USGS_sample_params("characteristics")$parameterCode}.} +\code{check_waterdata_sample_params("characteristics")$parameterCode}.} \item{pointLocationLatitude}{Latitude for a point/radius query (decimal degrees). Must be used with pointLocationLongitude and pointLocationWithinMiles.} @@ -142,7 +142,7 @@ See also: \url{https://api.waterdata.usgs.gov/samples-data/docs}. \dontshow{if (is_dataRetrieval_user()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} \donttest{ -req <- construct_USGS_sample_request( +req <- construct_waterdata_sample_request( monitoringLocationIdentifier = "USGS-04074950", characteristicUserSupplied = "pH, water, unfiltered, field") rawData <- importWQP(req) diff --git a/man/countyCd.Rd b/man/countyCd.Rd index 9fd7e511..5fcac308 100644 --- a/man/countyCd.Rd +++ b/man/countyCd.Rd @@ -18,7 +18,7 @@ COUNTY_ID \tab character \tab County id \cr } \description{ Classic lookup table for counties. Has been replaced in functions with -\code{check_USGS_sample_params("counties")}. +\code{check_USGS_waterdata_params("counties")}. } \examples{ head(countyCd) diff --git a/man/readNWISdata.Rd b/man/readNWISdata.Rd index 6d7d90db..1201b6ac 100644 --- a/man/readNWISdata.Rd +++ b/man/readNWISdata.Rd @@ -179,5 +179,5 @@ peak_data <- readNWISdata( \dontshow{\}) # examplesIf} } \seealso{ -\code{\link[=read_USGS_data]{read_USGS_data()}} +\code{\link[=read_waterdata]{read_waterdata()}} } diff --git a/man/readNWISdv.Rd b/man/readNWISdv.Rd index 83d36b8b..bd131c90 100644 --- a/man/readNWISdv.Rd +++ b/man/readNWISdv.Rd @@ -72,7 +72,7 @@ More information on the web service can be found here: } \examples{ -# see ?read_USGS_daily +# see ?read_waterdata_daily #site_id <- "04085427" #startDate <- "2012-01-01" @@ -83,7 +83,7 @@ More information on the web service can be found here: } \seealso{ -\code{\link[=read_USGS_daily]{read_USGS_daily()}} +\code{\link[=read_waterdata_daily]{read_waterdata_daily()}} } \keyword{USGS} \keyword{data} diff --git a/man/readNWISpCode.Rd b/man/readNWISpCode.Rd index 8b5887cb..ebeef88b 100644 --- a/man/readNWISpCode.Rd +++ b/man/readNWISpCode.Rd @@ -7,9 +7,9 @@ readNWISpCode(parameterCd) } \arguments{ -\item{parameterCd}{character of USGS parameter codes (or multiple parameter codes). These are 5 digit number codes, -more information can be found here: \url{https://help.waterdata.usgs.gov/}. To get a -complete list of all current parameter codes in the USGS, use "all" as the input.} +\item{parameterCd}{character of USGS parameter codes (or multiple parameter codes). +These are 5 digit number codes. To get a complete list of all current parameter +codes in the USGS, use "all" as the input.} } \value{ parameterData data frame with the following information: diff --git a/man/readNWISsite.Rd b/man/readNWISsite.Rd index f38434cf..4447faab 100644 --- a/man/readNWISsite.Rd +++ b/man/readNWISsite.Rd @@ -70,12 +70,12 @@ Imports data from USGS site file site. This function gets data from here: \url{h } \examples{ -# see ?read_USGS_monitoring_location +# see ?read_waterdata_monitoring_location # siteINFOMulti <- readNWISsite(c("05114000", "09423350")) } \seealso{ -\code{\link[=read_USGS_monitoring_location]{read_USGS_monitoring_location()}} +\code{\link[=read_waterdata_monitoring_location]{read_waterdata_monitoring_location()}} } \keyword{USGS} \keyword{data} diff --git a/man/read_USGS_data.Rd b/man/read_waterdata.Rd similarity index 82% rename from man/read_USGS_data.Rd rename to man/read_waterdata.Rd index 85406a3e..544cf63f 100644 --- a/man/read_USGS_data.Rd +++ b/man/read_waterdata.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/read_USGS_data.R -\name{read_USGS_data} -\alias{read_USGS_data} -\title{Generalized USGS data retrieval function} +% Please edit documentation in R/read_waterdata.R +\name{read_waterdata} +\alias{read_waterdata} +\title{Generalized USGS Water Data API retrieval function} \usage{ -read_USGS_data(service, CQL, ..., convertType = TRUE) +read_waterdata(service, CQL, ..., convertType = TRUE) } \arguments{ \item{service}{character, can be any existing collection such @@ -46,7 +46,7 @@ cql <- '{ ] }' -dv_data <- read_USGS_data(service = "daily", +dv_data <- read_waterdata(service = "daily", CQL = cql, time = c("2023-01-01", "2024-01-01")) diff --git a/man/read_USGS_daily.Rd b/man/read_waterdata_daily.Rd similarity index 94% rename from man/read_USGS_daily.Rd rename to man/read_waterdata_daily.Rd index aa7a7f10..5a29c4ed 100644 --- a/man/read_USGS_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/read_USGS_daily.R -\name{read_USGS_daily} -\alias{read_USGS_daily} +% Please edit documentation in R/read_waterdata_daily.R +\name{read_waterdata_daily} +\alias{read_waterdata_daily} \title{Get USGS Daily Data} \usage{ -read_USGS_daily( +read_waterdata_daily( monitoring_location_id = NA_character_, parameter_code = NA_character_, statistic_id = NA_character_, @@ -102,26 +102,26 @@ Description Daily data provide one data value to represent water conditions for \donttest{ site <- "USGS-02238500" pcode <- "00060" -dv_data_sf <- read_USGS_daily(monitoring_location_id = site, +dv_data_sf <- read_waterdata_daily(monitoring_location_id = site, parameter_code = "00060", time = c("2021-01-01", "2022-01-01")) -dv_data_trim <- read_USGS_daily(monitoring_location_id = site, +dv_data_trim <- read_waterdata_daily(monitoring_location_id = site, parameter_code = "00060", properties = c("monitoring_location_id", "value", "time"), time = c("2021-01-01", "2022-01-01")) -dv_data <- read_USGS_daily(monitoring_location_id = site, +dv_data <- read_waterdata_daily(monitoring_location_id = site, parameter_code = "00060", skipGeometry = TRUE) -dv_data_period <- read_USGS_daily(monitoring_location_id = site, +dv_data_period <- read_waterdata_daily(monitoring_location_id = site, parameter_code = "00060", time = "P7D") -multi_site <- read_USGS_daily(monitoring_location_id = c("USGS-01491000", +multi_site <- read_waterdata_daily(monitoring_location_id = c("USGS-01491000", "USGS-01645000"), parameter_code = c("00060", "00010"), limit = 500, diff --git a/man/read_USGS_monitoring_location.Rd b/man/read_waterdata_monitoring_location.Rd similarity index 95% rename from man/read_USGS_monitoring_location.Rd rename to man/read_waterdata_monitoring_location.Rd index 58d3fa69..40cd6e0b 100644 --- a/man/read_USGS_monitoring_location.Rd +++ b/man/read_waterdata_monitoring_location.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/read_USGS_monitoring_location.R -\name{read_USGS_monitoring_location} -\alias{read_USGS_monitoring_location} +% Please edit documentation in R/read_waterdata_monitoring_location.R +\name{read_waterdata_monitoring_location} +\alias{read_waterdata_monitoring_location} \title{Get USGS Site Data} \usage{ -read_USGS_monitoring_location( +read_waterdata_monitoring_location( monitoring_location_id = NA_character_, agency_code = NA_character_, agency_name = NA_character_, @@ -165,27 +165,27 @@ Description Location information is basic information about the monitoring locat \donttest{ site <- "USGS-02238500" -site_info <- read_USGS_monitoring_location(monitoring_location_id = site) +site_info <- read_waterdata_monitoring_location(monitoring_location_id = site) -site_slim <- read_USGS_monitoring_location(monitoring_location_id = site, +site_slim <- read_waterdata_monitoring_location(monitoring_location_id = site, properties = c("monitoring_location_id", "state_name", "country_name")) -site_slim_no_sf_slim <- read_USGS_monitoring_location(monitoring_location_id = site, +site_slim_no_sf_slim <- read_waterdata_monitoring_location(monitoring_location_id = site, properties = c("monitoring_location_id", "state_name", "country_name"), skipGeometry = TRUE) -site_info_no_sf <- read_USGS_monitoring_location(monitoring_location_id = site, +site_info_no_sf <- read_waterdata_monitoring_location(monitoring_location_id = site, skipGeometry = TRUE) bbox_vals = c(-94.00, 35.0, -93.5, 35.5) -multi_site <- read_USGS_monitoring_location(bbox = bbox_vals) -multi_site_n_100 <- read_USGS_monitoring_location(bbox = bbox_vals, +multi_site <- read_waterdata_monitoring_location(bbox = bbox_vals) +multi_site_n_100 <- read_waterdata_monitoring_location(bbox = bbox_vals, max_results = 100) -multi_site_limit_100 <- read_USGS_monitoring_location(bbox = bbox_vals, +multi_site_limit_100 <- read_waterdata_monitoring_location(bbox = bbox_vals, limit = 100) } \dontshow{\}) # examplesIf} diff --git a/man/read_USGS_samples.Rd b/man/read_waterdata_samples.Rd similarity index 81% rename from man/read_USGS_samples.Rd rename to man/read_waterdata_samples.Rd index 0af207d2..6eb9081f 100644 --- a/man/read_USGS_samples.Rd +++ b/man/read_waterdata_samples.Rd @@ -1,9 +1,36 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/read_USGS_samples.R -\name{read_USGS_samples} +% Please edit documentation in R/read_waterdata_samples.R +\name{read_waterdata_samples} +\alias{read_waterdata_samples} \alias{read_USGS_samples} \title{USGS Samples Data} \usage{ +read_waterdata_samples( + monitoringLocationIdentifier = NA, + siteTypeCode = NA, + boundingBox = NA, + hydrologicUnit = NA, + activityMediaName = NA, + characteristicGroup = NA, + characteristic = NA, + characteristicUserSupplied = NA, + activityStartDateLower = NA, + activityStartDateUpper = NA, + countryFips = NA, + stateFips = NA, + countyFips = NA, + projectIdentifier = NA, + recordIdentifierUserSupplied = NA, + siteTypeName = NA, + usgsPCode = NA, + pointLocationLatitude = NA, + pointLocationLongitude = NA, + pointLocationWithinMiles = NA, + dataType = "results", + dataProfile = NA, + tz = "UTC" +) + read_USGS_samples( monitoringLocationIdentifier = NA, siteTypeCode = NA, @@ -37,7 +64,7 @@ for example: AZ014-320821110580701, CAX01-15304600, USGS-040851385. Location numbers without an agency prefix are assumed to have the prefix USGS.} \item{siteTypeCode}{Site type code query parameter. See available -options by running \code{check_USGS_sample_params("sitetype")$typeCode}.} +options by running \code{check_waterdata_sample_params("sitetype")$typeCode}.} \item{boundingBox}{North and South are latitude values; East and West are longitude values. A vector of 4 (west, south, east, north) is expected. @@ -52,11 +79,11 @@ was sampled or analyzed.} \item{characteristicGroup}{Characteristic group is a broad category describing the sample. See available options by running -\code{check_USGS_sample_params("characteristicgroup")$characteristicGroup}.} +\code{check_waterdata_sample_params("characteristicgroup")$characteristicGroup}.} \item{characteristic}{Characteristic is a specific category describing the sample. See available options by running -\code{check_USGS_sample_params("characteristics")$characteristicName}.} +\code{check_waterdata_sample_params("characteristics")$characteristicName}.} \item{characteristicUserSupplied}{Observed property is the USGS term for the constituent sampled and the property name gives a detailed description of what @@ -78,17 +105,17 @@ records that match the date.} \item{countryFips}{Country query parameter. Do not set redundant parameters. If another query parameter contains the country information, leave this parameter -set to the default NA. See available options by running \code{check_USGS_sample_params("countries")}, +set to the default NA. See available options by running \code{check_waterdata_sample_params("countries")}, where the "id" field contains the value to use in the countryFips input.} \item{stateFips}{State query parameter. To get a list of available state fips, -run \code{check_USGS_sample_params("states")}. The "fips" can be created using the function +run \code{check_waterdata_sample_params("states")}. The "fips" can be created using the function \code{stateCdLookup} - for example: \code{stateCdLookup("WI", "fips")}. FIPs codes for states take the format: CountryAbbrev:StateNumber, like US:55 for Wisconsin.} \item{countyFips}{County query parameter. To get a list of available counties, -run \code{check_USGS_sample_params("counties")}. The "Fips" can be created using the function +run \code{check_waterdata_sample_params("counties")}. The "Fips" can be created using the function \code{countyCdLookup} - for example: \code{countyCdLookup("WI", "Dane", "fips")} for Dane County, WI. FIPs codes for counties take the format: @@ -104,7 +131,7 @@ information would be needed from the data supplier.} options by running \code{check_param("sitetype")$typeName}.} \item{usgsPCode}{USGS parameter code. See available options by running -\code{check_USGS_sample_params("characteristics")$parameterCode}.} +\code{check_waterdata_sample_params("characteristics")$parameterCode}.} \item{pointLocationLatitude}{Latitude for a point/radius query (decimal degrees). Must be used with pointLocationLongitude and pointLocationWithinMiles.} @@ -140,20 +167,20 @@ service described at \url{https://waterdata.usgs.gov/download-samples/}. \dontshow{if (is_dataRetrieval_user()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} \donttest{ -ph_data <- read_USGS_samples( +ph_data <- read_waterdata_samples( monitoringLocationIdentifier = "USGS-04074950", characteristicUserSupplied = "pH, water, unfiltered, field", activityStartDateUpper = "2000-01-01", dataProfile = "narrow") nameToUse <- "pH" -pHData <- read_USGS_samples(monitoringLocationIdentifier = "USGS-04024315", +pHData <- read_waterdata_samples(monitoringLocationIdentifier = "USGS-04024315", characteristic = nameToUse) ncol(pHData) attr(pHData, "url") attr(pHData, "queryTime") -summary_data <- read_USGS_samples(monitoringLocationIdentifier = "USGS-04024315", +summary_data <- read_waterdata_samples(monitoringLocationIdentifier = "USGS-04024315", dataType = "projects") } diff --git a/man/read_USGS_ts_meta.Rd b/man/read_waterdata_ts_meta.Rd similarity index 96% rename from man/read_USGS_ts_meta.Rd rename to man/read_waterdata_ts_meta.Rd index 9a4e7387..4847f0a4 100644 --- a/man/read_USGS_ts_meta.Rd +++ b/man/read_waterdata_ts_meta.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/read_USGS_ts_meta.R -\name{read_USGS_ts_meta} -\alias{read_USGS_ts_meta} +% Please edit documentation in R/read_waterdata_ts_meta.R +\name{read_waterdata_ts_meta} +\alias{read_waterdata_ts_meta} \title{Get USGS Time Series Metadata} \usage{ -read_USGS_ts_meta( +read_waterdata_ts_meta( monitoring_location_id = NA_character_, parameter_code = NA_character_, parameter_name = NA_character_, @@ -104,9 +104,9 @@ Description Daily data and continuous measurements are grouped into time series, \donttest{ site <- "USGS-02238500" -meta_1 <- read_USGS_ts_meta(monitoring_location_id = site) +meta_1 <- read_waterdata_ts_meta(monitoring_location_id = site) -meta_multi <- read_USGS_ts_meta(monitoring_location_id = c("USGS-01491000", +meta_multi <- read_waterdata_ts_meta(monitoring_location_id = c("USGS-01491000", "USGS-01645000"), parameter_code = c("00060", "00010"), properties = c("monitoring_location_id", diff --git a/man/stateCd.Rd b/man/stateCd.Rd index 0e595174..b8eaea3d 100644 --- a/man/stateCd.Rd +++ b/man/stateCd.Rd @@ -17,7 +17,7 @@ STATENS \tab character \tab Geographic Names Information System Identifier (GNI } \description{ Classic lookup table for states. Has been replaced in functions with -\code{check_USGS_sample_params("states")}. +\code{check_waterdata_sample_params("states")}. } \examples{ head(stateCd) diff --git a/man/summarize_USGS_samples.Rd b/man/summarize_waterdata_samples.Rd similarity index 80% rename from man/summarize_USGS_samples.Rd rename to man/summarize_waterdata_samples.Rd index 92a0023d..c7c8972b 100644 --- a/man/summarize_USGS_samples.Rd +++ b/man/summarize_waterdata_samples.Rd @@ -1,9 +1,12 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/read_USGS_samples.R -\name{summarize_USGS_samples} +% Please edit documentation in R/read_waterdata_samples.R +\name{summarize_waterdata_samples} +\alias{summarize_waterdata_samples} \alias{summarize_USGS_samples} \title{USGS Samples Summary Data} \usage{ +summarize_waterdata_samples(monitoringLocationIdentifier) + summarize_USGS_samples(monitoringLocationIdentifier) } \arguments{ @@ -25,7 +28,7 @@ service described at \url{https://api.waterdata.usgs.gov/samples-data/docs}. \donttest{ monitoringLocationIdentifier <- "USGS-04074950" -what_data <- summarize_USGS_samples(monitoringLocationIdentifier) +what_data <- summarize_waterdata_samples(monitoringLocationIdentifier) } \dontshow{\}) # examplesIf} diff --git a/man/whatNWISdata.Rd b/man/whatNWISdata.Rd index a27c1a35..fcc94de5 100644 --- a/man/whatNWISdata.Rd +++ b/man/whatNWISdata.Rd @@ -74,7 +74,7 @@ of sites that have useful data. } \examples{ -# see ?read_USGS_ts_meta +# see ?read_waterdata_ts_meta #site1 <- whatWQPsamples(siteid = "USGS-01594440") @@ -88,7 +88,7 @@ of sites that have useful data. } \seealso{ -\code{\link[=read_USGS_ts_meta]{read_USGS_ts_meta()}} +\code{\link[=read_waterdata_ts_meta]{read_waterdata_ts_meta()}} } \keyword{USGS} \keyword{data} diff --git a/man/whatNWISsites.Rd b/man/whatNWISsites.Rd index 3f580bac..b4310020 100644 --- a/man/whatNWISsites.Rd +++ b/man/whatNWISsites.Rd @@ -37,11 +37,11 @@ Mapper format is used } \examples{ -# see ?read_USGS_monitoring_location +# see ?read_waterdata_monitoring_location #siteListPhos <- whatNWISsites(stateCd = "OH", parameterCd = "00665") #oneSite <- whatNWISsites(sites = "05114000") } \seealso{ -\code{\link[=read_USGS_monitoring_location]{read_USGS_monitoring_location()}} +\code{\link[=read_waterdata_monitoring_location]{read_waterdata_monitoring_location()}} } diff --git a/tests/testthat/tests_general.R b/tests/testthat/tests_general.R index 4cd73e48..97469582 100644 --- a/tests/testthat/tests_general.R +++ b/tests/testthat/tests_general.R @@ -23,7 +23,7 @@ test_that("General USGS retrievals working", { ] }' - dv_data <- read_USGS_data(service = "daily", + dv_data <- read_waterdata(service = "daily", CQL = cql, time = c("2023-01-01", "2024-01-01")) expect_equal(as.Date(c("2023-01-01", "2024-01-01")), @@ -52,7 +52,7 @@ test_that("General USGS retrievals working", { ] }' - notActiveUSGS <- read_USGS_data(CQL = cql_not_active, + notActiveUSGS <- read_waterdata(CQL = cql_not_active, service = "daily", time = c("2014-01-01", "2014-01-07")) expect_true(nrow(notActiveUSGS) == 0) @@ -97,14 +97,14 @@ test_that("General NWIS retrievals working", { expect_error(readNWISdata(), "No arguments supplied") expect_error(readNWISdata(siteNumber = NA), "NA's are not allowed in query") - bBox_inventory <- read_USGS_ts_meta(bbox = c(-83, 38, -82.5, 38.5), + bBox_inventory <- read_waterdata_ts_meta(bbox = c(-83, 38, -82.5, 38.5), parameter_code = "00010") expect_true(length(unique(bBox_inventory$monitoring_location_id)) > 1) - siteInfo <- read_USGS_monitoring_location(state_name = "Wisconsin") + siteInfo <- read_waterdata_monitoring_location(state_name = "Wisconsin") - timeseriesInfo <- read_USGS_ts_meta(bbox = sf::st_bbox(siteInfo), + timeseriesInfo <- read_waterdata_ts_meta(bbox = sf::st_bbox(siteInfo), parameter_code = "00010", computation_period_identifier = "Points" ) @@ -174,18 +174,18 @@ test_that("General NWIS retrievals working", { time = c("2014-05-01", endDate = "2014-05-01") ) - daily_USGS <- do.call(read_USGS_daily, args2) + daily_USGS <- do.call(read_waterdata_daily, args2) expect_lt(nrow(daily_USGS), nrow(instData)) - ohio <- read_USGS_monitoring_location(state_name = "Ohio", + ohio <- read_waterdata_monitoring_location(state_name = "Ohio", site_type_code = "ST") bbox <- sf::st_bbox(ohio) - what_sites <- read_USGS_ts_meta(parameter_code = "00665", + what_sites <- read_waterdata_ts_meta(parameter_code = "00665", bbox = bbox) expect_true(all(c("monitoring_location_id", "begin", "end", "parameter_name") %in% names(what_sites))) - huc <- read_USGS_monitoring_location(hydrologic_unit_code = "02080202") + huc <- read_waterdata_monitoring_location(hydrologic_unit_code = "02080202") expect_true(nrow(huc) > 0) # Test counties: @@ -194,11 +194,11 @@ test_that("General NWIS retrievals working", { county = "Stafford", outputType = "id") state_code_va <- stateCdLookup(input = "Virginia", outputType = "id") - stafford <- read_USGS_monitoring_location(county_code = county_code_stafford, + stafford <- read_waterdata_monitoring_location(county_code = county_code_stafford, state_code = state_code_va) stafford_bbox <- sf::st_bbox(stafford) - dailyStaffordVA <- read_USGS_daily( + dailyStaffordVA <- read_waterdata_daily( bbox = stafford_bbox, parameter_code = "00060", time = c("2015-01-01", "2015-01-30") @@ -206,7 +206,7 @@ test_that("General NWIS retrievals working", { expect_gt(nrow(dailyStaffordVA), 1) # America Samoa? - AS <- read_USGS_monitoring_location(state_name = "American Samoa") + AS <- read_waterdata_monitoring_location(state_name = "American Samoa") expect_gt(nrow(AS), 0) site_id <- "01594440" @@ -239,9 +239,9 @@ test_that("General NWIS retrievals working", { ))) multi_hucs <- c("07130007", "07130011") - multi_huc_sites <- read_USGS_monitoring_location(hydrologic_unit_code = multi_hucs) + multi_huc_sites <- read_waterdata_monitoring_location(hydrologic_unit_code = multi_hucs) - multi_huc <- read_USGS_daily(bbox = sf::st_bbox(multi_huc_sites), + multi_huc <- read_waterdata_daily(bbox = sf::st_bbox(multi_huc_sites), parameter_code = "63680", statistic_id = "00003", time = c("2015-06-18", "2015-06-18") @@ -261,18 +261,18 @@ test_that("General NWIS retrievals working", { expect_lt(nrow(peak_data), 100000) }) -test_that("read_USGS_ts_meta", { +test_that("read_waterdata_ts_meta", { # no service specified: - availableData <- read_USGS_ts_meta(monitoring_location_id = "USGS-05114000") + availableData <- read_waterdata_ts_meta(monitoring_location_id = "USGS-05114000") expect_equal(ncol(availableData), 17) - uvData <- read_USGS_ts_meta(monitoring_location_id = "USGS-05114000", + uvData <- read_waterdata_ts_meta(monitoring_location_id = "USGS-05114000", computation_period_identifier = c("Points")) expect_equal(unique(uvData$computation_period_identifier), "Points") # multiple services - uvDataMulti <- read_USGS_ts_meta(monitoring_location_id = c("USGS-05114000", + uvDataMulti <- read_waterdata_ts_meta(monitoring_location_id = c("USGS-05114000", "USGS-09423350"), computation_period_identifier = c("Daily", "Points")) @@ -281,8 +281,8 @@ test_that("read_USGS_ts_meta", { "Points"))) # state codes: - wi_sites <- read_USGS_monitoring_location(state_name = "Wisconsin") - flow_and_temp <- read_USGS_ts_meta(bbox = sf::st_bbox(wi_sites), + wi_sites <- read_waterdata_monitoring_location(state_name = "Wisconsin") + flow_and_temp <- read_waterdata_ts_meta(bbox = sf::st_bbox(wi_sites), parameter_code = c("00060", "00010"), statistic_id = "00003", computation_period_identifier = c("Daily", @@ -426,16 +426,16 @@ test_that("whatWQPdata working", { expect_is(lakeSites$activityCount, "numeric") }) -context("read_USGS_ts_meta") -test_that("read_USGS_ts_meta working", { +context("read_waterdata_ts_meta") +test_that("read_waterdata_ts_meta working", { testthat::skip_on_cran() - siteListOhio <- read_USGS_monitoring_location(state_name = "Ohio") - siteListPhos <- read_USGS_ts_meta(bbox = sf::st_bbox(siteListOhio), + siteListOhio <- read_waterdata_monitoring_location(state_name = "Ohio") + siteListPhos <- read_waterdata_ts_meta(bbox = sf::st_bbox(siteListOhio), parameter_code = "00665") expect_true(nrow(siteListPhos) > 0) expect_is(siteListPhos$begin, "POSIXct") - bboxSites <- read_USGS_ts_meta(bbox = c(-92.5, 45.4, -87, 47), + bboxSites <- read_waterdata_ts_meta(bbox = c(-92.5, 45.4, -87, 47), parameter_code = "00060") expect_true(nrow(bboxSites) > 0) diff --git a/tests/testthat/tests_samples.R b/tests/testthat/tests_samples.R index 2c87d4ef..da145998 100644 --- a/tests/testthat/tests_samples.R +++ b/tests/testthat/tests_samples.R @@ -4,17 +4,17 @@ context("General functions") test_that("General samples-data retrievals work using WQP tests", { testthat::skip_on_cran() nameToUse <- "pH" - pHData <- read_USGS_samples(monitoringLocationIdentifier = "USGS-04024315", + pHData <- read_waterdata_samples(monitoringLocationIdentifier = "USGS-04024315", characteristic = nameToUse) expect_is(pHData$Activity_StartDateTime, "POSIXct") # testing lists: startDate <- as.Date("2022-01-01") - secchi_ops <- check_USGS_sample_params("observedproperty", + secchi_ops <- check_waterdata_sample_params("observedproperty", text = "secchi") state_fips <- paste0("US:", stateCdLookup("WI", "id")) - lakeData <- read_USGS_samples(activityStartDateLower = startDate, + lakeData <- read_waterdata_samples(activityStartDateLower = startDate, activityStartDateUpper = "2024-01-01", stateFips = "US:55", characteristicUserSupplied = secchi_ops$observedProperty, @@ -22,20 +22,20 @@ test_that("General samples-data retrievals work using WQP tests", { expect_true(nrow(lakeData) > 0) - lakeSites <- read_USGS_samples(monitoringLocationIdentifier = unique(lakeData$Location_Identifier), + lakeSites <- read_waterdata_samples(monitoringLocationIdentifier = unique(lakeData$Location_Identifier), dataType = "locations", dataProfile = "site") expect_type(lakeSites, "list") - rawPcode <- read_USGS_samples(monitoringLocationIdentifier = "USGS-01594440", + rawPcode <- read_waterdata_samples(monitoringLocationIdentifier = "USGS-01594440", usgsPCode = "01075") expect_true(all(c("url", "queryTime", "headerInfo") %in% names(attributes(rawPcode)))) - pHData <- read_USGS_samples(monitoringLocationIdentifier = "USGS-04024315", + pHData <- read_waterdata_samples(monitoringLocationIdentifier = "USGS-04024315", characteristic = "pH", dataProfile = "narrow") @@ -50,7 +50,7 @@ context("samples-data samples") test_that("samples-data activities working", { testthat::skip_on_cran() - activityInfo <- read_USGS_samples(monitoringLocationIdentifier = "USGS-01594440", + activityInfo <- read_waterdata_samples(monitoringLocationIdentifier = "USGS-01594440", dataType = "activities") expect_true(nrow(activityInfo) > 0) }) @@ -60,17 +60,17 @@ test_that("samples-data project working", { testthat::skip_on_cran() type <- "Stream" - projectInfo <- read_USGS_samples(countyFips = countyCdLookup("WI", "Dane"), + projectInfo <- read_waterdata_samples(countyFips = countyCdLookup("WI", "Dane"), siteTypeName = type, dataType = "projects") expect_true(ncol(projectInfo) >= 0) }) -context("summary_USGS_samples") -test_that("summary_USGS_samples working", { +context("summary_waterdata_samples") +test_that("summary_waterdata_samples working", { testthat::skip_on_cran() - site1 <- summarize_USGS_samples(monitoringLocationIdentifier = "USGS-01594440") + site1 <- summarize_waterdata_samples(monitoringLocationIdentifier = "USGS-01594440") expect_is(site1, "data.frame") }) @@ -79,13 +79,13 @@ test_that("profiles", { testthat::skip_on_cran() # Data profiles: "Organization Data" - org_data <- read_USGS_samples( + org_data <- read_waterdata_samples( countyFips = countyCdLookup("WI", "Dane"), dataType = "organizations" ) # Data profiles: "Site Data Only" - site_data <- read_USGS_samples( + site_data <- read_waterdata_samples( countyFips = countyCdLookup("WI", "Dane"), dataType = "locations" ) @@ -93,7 +93,7 @@ test_that("profiles", { expect_true(all(c("ProviderName", "Location_Identifier") %in% names(site_data))) # Data profiles: "Project Data" - project_data <- read_USGS_samples( + project_data <- read_waterdata_samples( countyFips = countyCdLookup("WI", "Dane"), dataType = "projects" ) @@ -104,7 +104,7 @@ test_that("profiles", { ) %in% names(project_data))) # Data profiles: "Project Monitoring Location Weighting Data" - proj_mlwd <- read_USGS_samples( + proj_mlwd <- read_waterdata_samples( countyFips = countyCdLookup("WI", "Dane"), dataType = "projects", dataProfile = "projectmonitoringlocationweight" @@ -116,7 +116,7 @@ test_that("profiles", { ) %in% names(proj_mlwd))) # Data profiles: "Sample Results (biological metadata)" - samp_bio <- read_USGS_samples( + samp_bio <- read_waterdata_samples( monitoringLocationIdentifier = "USGS-04024315", dataProfile = "basicbio", dataType = "results" @@ -128,7 +128,7 @@ test_that("profiles", { ) %in% names(samp_bio))) # Data profiles: "Sample Results (narrow)" - samp_narrow <- read_USGS_samples( + samp_narrow <- read_waterdata_samples( monitoringLocationIdentifier = "USGS-04024315", dataProfile = "narrow", dataType = "results" @@ -140,7 +140,7 @@ test_that("profiles", { ) %in% names(samp_narrow))) # Data profiles: "Sampling Activity" - samp_activity <- read_USGS_samples( + samp_activity <- read_waterdata_samples( monitoringLocationIdentifier = "USGS-04024315", dataProfile = "sampact", # Sampling Activities dataType = "activities" @@ -152,7 +152,7 @@ test_that("profiles", { ) %in% names(samp_activity))) # Data profile: "Result Detection Quantitation Limit Data" - dl_data <- read_USGS_samples( + dl_data <- read_waterdata_samples( monitoringLocationIdentifier = "USGS-04024315", dataType = "results", dataProfile = "resultdetectionquantitationlimit" diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index ed36dce7..ba58c224 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -83,11 +83,11 @@ test_that("peak, rating curves, surface-water measurements", { data <- readNWISmeas(siteNumbers) expect_is(data$agency_cd, "character") - siteINFO_USGS <- read_USGS_monitoring_location(monitoring_location_id = "USGS-05114000") + siteINFO_USGS <- read_waterdata_monitoring_location(monitoring_location_id = "USGS-05114000") expect_is(siteINFO_USGS$agency_code, "character") expect_equal(siteINFO_USGS$monitoring_location_id, "USGS-05114000") - siteINFOMulti_USGS <- read_USGS_monitoring_location(monitoring_location_id = c("USGS-05114000", + siteINFOMulti_USGS <- read_waterdata_monitoring_location(monitoring_location_id = c("USGS-05114000", "USGS-09423350")) expect_true(nrow(siteINFOMulti_USGS) == 2) @@ -95,9 +95,9 @@ test_that("peak, rating curves, surface-water measurements", { expect_is(Meas07227500.ex$measurement_dt, "Date") expect_is(Meas07227500.ex$measurement_dateTime, "POSIXct") - expect_equal(nrow(read_USGS_ts_meta(monitoring_location_id = "USGS-10312000", + expect_equal(nrow(read_waterdata_ts_meta(monitoring_location_id = "USGS-10312000", parameter_code = "50286")), 0) - expect_equal(ncol(read_USGS_ts_meta(monitoring_location_id = "USGS-10312000", + expect_equal(ncol(read_waterdata_ts_meta(monitoring_location_id = "USGS-10312000", parameter_code = "50286", properties = c("geometry", "id", "unit_of_measure", @@ -118,7 +118,7 @@ test_that("peak, rating curves, surface-water measurements", { convertType = FALSE)) }) -test_that("read_USGS_daily", { +test_that("read_waterdata_daily", { testthat::skip_on_cran() siteNumber <- "USGS-04085427" @@ -126,30 +126,30 @@ test_that("read_USGS_daily", { endDate <- "2012-06-30" pCode <- "00060" - raw_USGS_daily <- read_USGS_daily(monitoring_location_id = siteNumber, + raw_waterdata_daily <- read_waterdata_daily(monitoring_location_id = siteNumber, parameter_code = pCode, time = c(startDate, endDate)) - expect_is(raw_USGS_daily$time, "Date") + expect_is(raw_waterdata_daily$time, "Date") - raw_USGS_TempMeanMax <- read_USGS_daily(monitoring_location_id = siteNumber, + raw_waterdata_TempMeanMax <- read_waterdata_daily(monitoring_location_id = siteNumber, parameter_code = c("00010", "00060"), time = c(startDate, endDate), statistic_id = c("00001", "00003")) - expect_true(length(unique(raw_USGS_TempMeanMax$parameter_code)) == 2) - expect_true(length(unique(raw_USGS_TempMeanMax$statistic_id)) == 2) - expect_true(length(unique(raw_USGS_TempMeanMax$monitoring_location_id)) == 1) + expect_true(length(unique(raw_waterdata_TempMeanMax$parameter_code)) == 2) + expect_true(length(unique(raw_waterdata_TempMeanMax$statistic_id)) == 2) + expect_true(length(unique(raw_waterdata_TempMeanMax$monitoring_location_id)) == 1) - raw_USGS_MultiSites <- read_USGS_daily(monitoring_location_id = c("USGS-01491000", "USGS-01645000"), + raw_waterdata_MultiSites <- read_waterdata_daily(monitoring_location_id = c("USGS-01491000", "USGS-01645000"), parameter_code = c("00010", "00060"), time = c(startDate, endDate), statistic_id = c("00001", "00003")) - expect_true(length(unique(raw_USGS_MultiSites$monitoring_location_id)) == 2) + expect_true(length(unique(raw_waterdata_MultiSites$monitoring_location_id)) == 2) site <- "05212700" - notActiveUSGS <- read_USGS_daily(monitoring_location_id = paste0("USGS-", site), + notActiveUSGS <- read_waterdata_daily(monitoring_location_id = paste0("USGS-", site), parameter_code = "00060", time = c("2014-01-01", "2014-01-07")) expect_true(nrow(notActiveUSGS) == 0) diff --git a/vignettes/Status.Rmd b/vignettes/Status.Rmd index f18b27bc..a258c888 100644 --- a/vignettes/Status.Rmd +++ b/vignettes/Status.Rmd @@ -25,12 +25,12 @@ Please contact the Computational Tools team at CompTools@usgs.gov with questions
What is an application programming interface (API)? - When you run a `dataRetrieval` function like `read_USGS_samples()` or `readNWISdv()`, you are actually generating a URL that contains within it specifications of the dataset in which you are interested (e.g. which monitoring locations, characteristics, pcodes, start and end dates, etc.). The format of that URL is special: it is parsed by a USGS-specific API web service, which translates the request into a database call. It then packages the response object from the database (with the data) into a format that can be sent to and then unpacked by the user. `dataRetrieval` takes a lot of the guesswork out of this process by generating the URL, sending it to the API, and wrangling the response object into a tabular dataset. + When you run a `dataRetrieval` function like `read_waterdata_samples()` or `readNWISdv()`, you are actually generating a URL that contains within it specifications of the dataset in which you are interested (e.g. which monitoring locations, characteristics, pcodes, start and end dates, etc.). The format of that URL is special: it is parsed by a USGS-specific API web service, which translates the request into a database call. It then packages the response object from the database (with the data) into a format that can be sent to and then unpacked by the user. `dataRetrieval` takes a lot of the guesswork out of this process by generating the URL, sending it to the API, and wrangling the response object into a tabular dataset.

The USGS is in the process of creating new, [publicly available APIs](https://api.waterdata.usgs.gov/) (a.k.a. "web services") to replace the existing [WaterServices](https://waterservices.usgs.gov/). `dataRetrieval` relies upon these web services to provide monitoring location information and water quantity/quality datasets. As new web services come online, `dataRetrieval` will be furnished with new functions to accommodate these changes. -The table below shows the **existing** NWIS functions and, if applicable, their slated replacements. Note that several functions do not have direct replacements because the new services to support them do not yet exist. We will update this table as new services and functions come online. Also note that some new functions may only be available on the "develop" branch of `dataRetrieval` (`remotes::install_github("DOI-USGS/dataRetrieval", ref = "develop")`). More information on each function's specifications (complete with examples) are available in the [Introduction to New USGS Services vignette](add link here), the [package index](https://doi-usgs.github.io/dataRetrieval/reference/index.html) and/or function documentation (e.g. `?read_USGS_daily`). +The table below shows the **existing** NWIS functions and, if applicable, their slated replacements. Note that several functions do not have direct replacements because the new services to support them do not yet exist. We will update this table as new services and functions come online. Also note that some new functions may only be available on the "develop" branch of `dataRetrieval` (`remotes::install_github("DOI-USGS/dataRetrieval", ref = "develop")`). More information on each function's specifications (complete with examples) are available in the [Introduction to New USGS Services vignette](add link here), the [package index](https://doi-usgs.github.io/dataRetrieval/reference/index.html) and/or function documentation (e.g. `?read_waterdata_daily`). ```{r echo=FALSE} df <- data.frame( @@ -52,11 +52,11 @@ df <- data.frame( "readNWISpCode" ), New = c( - "read_USGS_samples", - "read_USGS_daily", - "read_USGS_monitoring_location", - "read_USGS_ts_meta", - "read_USGS_data", + "read_waterdata_samples", + "read_waterdata_daily", + "read_waterdata_monitoring_location", + "read_waterdata_ts_meta", + "read_waterdata", rep("", 10) ), "Available on (branch)" = c("main (CRAN)", "develop", "develop", "develop", "develop", rep("", 10)) @@ -88,9 +88,9 @@ What does this mean for water quality data users of `dataRetrieval`? Check out t ## Samples Data -There's a new set of functions that access the USGS "samples-data" services! If you are **only** interested in USGS discrete water quality data, you can use the `read_USGS_samples` function. +There's a new set of functions that access the USGS "samples-data" services! If you are **only** interested in USGS discrete water quality data, you can use the `read_waterdata_samples` function. -Read more about it in the vignette, [Introducing read_USGS_samples](https://doi-usgs.github.io/dataRetrieval/articles/samples_data.html). +Read more about it in the vignette, [Introducing read_waterdata_samples](https://doi-usgs.github.io/dataRetrieval/articles/samples_data.html). ## WQP diff --git a/vignettes/long_to_wide.Rmd b/vignettes/long_to_wide.Rmd index c1b3404c..d3ecceb9 100644 --- a/vignettes/long_to_wide.Rmd +++ b/vignettes/long_to_wide.Rmd @@ -68,7 +68,7 @@ sites <- c("USGS-04027000", "USGS-04063700") characteristic_names <- c("Phosphorus as phosphorus, water, filtered", "Orthophosphate as phosphorus, water, filtered" ) -nutrient_data <- read_USGS_samples(monitoringLocationIdentifier = sites, +nutrient_data <- read_waterdata_samples(monitoringLocationIdentifier = sites, characteristicUserSupplied = characteristic_names, dataProfile = "basicphyschem") diff --git a/vignettes/read_USGS_functions.Rmd b/vignettes/read_waterdata_functions.Rmd similarity index 84% rename from vignettes/read_USGS_functions.Rmd rename to vignettes/read_waterdata_functions.Rmd index d1eb03bc..3713f452 100644 --- a/vignettes/read_USGS_functions.Rmd +++ b/vignettes/read_waterdata_functions.Rmd @@ -1,5 +1,5 @@ --- -title: "Introduction to New USGS Services" +title: "Introduction to New USGS Water Data APIs" editor_options: chunk_output_type: console output: @@ -31,13 +31,13 @@ knitr::opts_chunk$set( ) ``` -As we bid adieu to the NWIS web services, we welcome a host of new web service offering: the [USGS Water Data OGC APIs](https://api.waterdata.usgs.gov/ogcapi/v0/). This is a modern access point for USGS water data. The USGS will be modernizing [**all** of the NWIS web services](https://waterdata.usgs.gov/blog/api-whats-new-wdfn-apis/) in the near future. For each of these updates, `dataRetrieval` will create a new function to access the new services and deprecate functions for accessing the legacy services. +As we bid adieu to the NWIS web services, we welcome a host of new web service offering: the [USGS Water Data APIs](https://api.waterdata.usgs.gov/ogcapi/v0/). This is a modern access point for USGS water data. The USGS will be modernizing [all of the NWIS web services](https://waterdata.usgs.gov/blog/api-whats-new-wdfn-apis/) in the near future. For each of these updates, `dataRetrieval` will create a new function to access the new services and deprecate functions for accessing the legacy services. -This document will introduce each new function (note as time goes on, we'll update this document to include additional functions). Note the timeline for the NWIS servers being shut down is currently very uncertain. We'd recommend incorporating these new functions as soon as possible to avoid future headaches. +This document will introduce each new function (note as time goes on, we'll update this document to include additional functions). The timeline for the NWIS servers being shut down is currently very uncertain. We'd recommend incorporating these new functions as soon as possible to avoid future headaches. # New Features -Each new "API endpoint" will deliver a new type of USGS data. Currently the available endpoints are "monitoring-locations", "time-series-metadata", and "daily". All of these endpoints offer some new features that the legacy services did not have: +Each new "API endpoint" will deliver a new type of USGS water data. Currently the available endpoints are "monitoring-locations", "time-series-metadata", and "daily". All of these endpoints offer some new features that the legacy services did not have: ## Flexible Queries @@ -68,7 +68,7 @@ You can use `usethis::edit_r_environ()` to edit find and open your .Renviron fil ## Contextual Query Language Support -Supports [Contextual Query Language](https://www.loc.gov/standards/sru/cql/) (CQL2) syntax for flexible queries. We'll show how to use the `read_USGS_data` function to make specific CQL2 queries. +Supports [Contextual Query Language](https://www.loc.gov/standards/sru/cql/) (CQL2) syntax for flexible queries. We'll show how to use the `read_waterdata` function to make specific CQL2 queries. ## Simple Features @@ -87,7 +87,7 @@ There are at least 2 ways to deal with this. One is to manually split the data r Example: ```{r} -ohio <- read_USGS_monitoring_location(state_name = "Ohio", +ohio <- read_waterdata_monitoring_location(state_name = "Ohio", site_type_code = "ST") ``` @@ -95,7 +95,7 @@ ohio <- read_USGS_monitoring_location(state_name = "Ohio", There are `r nrow(ohio)` rows returned that are stream sites in Ohio. If we tried to ask for all the discharge data over the last 7 days from that list of sites: ``` -ohio_discharge <- read_USGS_daily(monitoring_location_id = ohio$monitoring_location_id, +ohio_discharge <- read_waterdata_daily(monitoring_location_id = ohio$monitoring_location_id, parameter_code = "00060", time = "P7D") Error in `req_perform()`: @@ -106,7 +106,7 @@ Error in `req_perform()`: We could use the fact that the `ohio` data frame contains geospatial information, create a bounding box, and ask for that data like this: ```{r} -ohio_discharge <- read_USGS_daily(bbox = sf::st_bbox(ohio), +ohio_discharge <- read_waterdata_daily(bbox = sf::st_bbox(ohio), parameter_code = "00060", time = "P7D") @@ -123,7 +123,7 @@ site_list <- split(big_vector_of_sites, ceiling(seq_along(big_vector_of_sites)/2 data_returned <- data.frame() for(sites in site_list){ - df_sites <- read_USGS_daily(monitoring_location_id = sites, + df_sites <- read_waterdata_daily(monitoring_location_id = sites, parameter_code = "00060", time = "P7D") if(nrow(df_sites) == 0){ @@ -155,9 +155,9 @@ Each API endpoint natively returns a column named "id". The results of the "id" Therefore, `dataRetrieval` functions will rename the "id" column to whatever it is referred to in other functions. Here are the id translations: ```{r echo=FALSE} -df <- dplyr::tibble(Function = c("read_USGS_monitoring_location", - "read_USGS_ts_meta", - "read_USGS_daily"), +df <- dplyr::tibble(Function = c("read_waterdata_monitoring_location", + "read_waterdata_ts_meta", + "read_waterdata_daily"), "ID returned" = c("monitoring_location_id", "time_series_id", "daily_id")) @@ -170,12 +170,12 @@ If a user would prefer the columns to come back as "id", they can specify that u ```{r} site <- "USGS-02238500" -site_1 <- read_USGS_monitoring_location(monitoring_location_id = site, +site_1 <- read_waterdata_monitoring_location(monitoring_location_id = site, properties = c("monitoring_location_id", "state_name", "country_name")) names(site_1) -site_2 <- read_USGS_monitoring_location(monitoring_location_id = site, +site_2 <- read_waterdata_monitoring_location(monitoring_location_id = site, properties = c("id", "state_name", "country_name")) @@ -190,7 +190,7 @@ As new API endpoints come online, this section will be updated with any `dataRet ## Monitoring Location -The `read_USGS_monitoring_location` function replaces the `readNWISsite` function. +The `read_waterdata_monitoring_location` function replaces the `readNWISsite` function. `r dataRetrieval:::get_description("monitoring-locations")` @@ -199,7 +199,7 @@ To access these services on a web browser, go to ## Time Series Metadata -The `read_USGS_ts_meta` function replaces the `whatNWISdata` function. +The `read_waterdata_ts_meta` function replaces the `whatNWISdata` function. `r dataRetrieval:::get_description("time-series-metadata")` @@ -262,7 +262,7 @@ To access these services on a web browser, go to . @@ -340,7 +340,7 @@ cql <- '{ ] }' -sites_mn_wi <- read_USGS_data(service = "monitoring-locations", +sites_mn_wi <- read_waterdata(service = "monitoring-locations", CQL = cql) ``` @@ -368,7 +368,7 @@ leaflet(data = sites_mn_wi |> ## Discrete Samples -Discrete USGS water quality can be accessed via the `read_USGS_samples` function. While this is a new, modern USGS endpoint, it is not served in the same infrastructure as the rest of these new advertised functions. See [Samples Data](articles/samples_data.html)) for information on accessing USGS discrete water quality data. +Discrete USGS water quality can be accessed via the `read_waterdata_samples` function. While this is a new, modern USGS endpoint, it is not served in the same infrastructure as the rest of these new advertised functions. See [Samples Data](articles/samples_data.html)) for information on accessing USGS discrete water quality data. # Notes on dataRetrieval development @@ -376,7 +376,7 @@ Discrete USGS water quality can be accessed via the `read_USGS_samples` function ### Style -New functions will use a "snake case", such as `read_USGS_samples`. Older functions use camel case, such as `readNWISdv`. The difference is the underscore between words. This should be a handy way to tell the difference between newer modern data access, and the older traditional functions. +New functions will use a "snake case", such as `read_waterdata_samples`. Older functions use camel case, such as `readNWISdv`. The difference is the underscore between words. This should be a handy way to tell the difference between newer modern data access, and the older traditional functions. ### Structure diff --git a/vignettes/samples_data.Rmd b/vignettes/samples_data.Rmd index 32d9043b..8895130d 100644 --- a/vignettes/samples_data.Rmd +++ b/vignettes/samples_data.Rmd @@ -1,5 +1,5 @@ --- -title: "Introducing read_USGS_samples" +title: "Introducing read_waterdata_samples" author: Laura A. DeCicco editor_options: chunk_output_type: console @@ -8,7 +8,7 @@ output: toc: true number_sections: true vignette: > - %\VignetteIndexEntry{Introducing read_USGS_samples} + %\VignetteIndexEntry{Introducing read_waterdata_samples} \usepackage[utf8]{inputenc} %\VignetteEngine{knitr::rmarkdown} --- @@ -91,7 +91,7 @@ This is a modern access point for USGS discrete water quality data. The USGS is ### Style -New functions will use a "snake case", such as "read_USGS_samples". Older functions use camel case, such as "readNWISdv". The difference is the underscore between words. This should be a handy way to tell the difference between newer modern data access, and the older traditional functions. +New functions will use a "snake case", such as "read_waterdata_samples". Older functions use camel case, such as "readNWISdv". The difference is the underscore between words. This should be a handy way to tell the difference between newer modern data access, and the older traditional functions. ### Structure @@ -112,13 +112,13 @@ And here is a link to the web service documentation: ## Retrieving data from a known site -Let's say we have a USGS site. We can check the data available at that site using `summarize_USGS_samples` like this: +Let's say we have a USGS site. We can check the data available at that site using `summarize_waterdata_samples` like this: ```{r} library(dataRetrieval) site <- "USGS-04183500" -data_at_site <- summarize_USGS_samples(monitoringLocationIdentifier = site) +data_at_site <- summarize_waterdata_samples(monitoringLocationIdentifier = site) ``` @@ -137,11 +137,11 @@ DT::datatable(formatted_data_at_site, rownames = FALSE) We see there's `r data_at_site$resultCount[data_at_site$characteristicUserSupplied == "Phosphorus as phosphorus, water, unfiltered"]` filtered phosphorus values available. Note that if we ask for a simple characteristic = "Phosphorus", we'd get back both filtered and unfiltered, which might not be appropriate to mix together in an analysis. "characteristicUserSupplied" allows us to query by a very specific set of data. It is similar to a long-form USGS parameter code. -To get that data, use the `read_USGS_samples` function: +To get that data, use the `read_waterdata_samples` function: ```{r} user_char <- "Phosphorus as phosphorus, water, unfiltered" -phos_data <- read_USGS_samples(monitoringLocationIdentifier = site, +phos_data <- read_waterdata_samples(monitoringLocationIdentifier = site, characteristicUserSupplied = user_char) ``` @@ -150,7 +150,7 @@ Inspecting phos_data, there are `r ncol(phos_data)` columns (!). That is because Instead of using the "Full physical chemical" profile, we could ask for the "Narrow" profile, which contains fewer columns: ```{r} -phos_narrow <- read_USGS_samples(monitoringLocationIdentifier = site, +phos_narrow <- read_waterdata_samples(monitoringLocationIdentifier = site, characteristicUserSupplied = user_char, dataProfile = "narrow") ``` @@ -206,7 +206,7 @@ North and south are latitude values; east and west are longitude values. A vecto bbox <- c(-90.8, 44.2, -89.9, 45.0) user_char <- "Phosphorus as phosphorus, water, unfiltered" -bbox_sites <- read_USGS_samples(boundingBox = bbox, +bbox_sites <- read_waterdata_samples(boundingBox = bbox, characteristicUserSupplied = user_char, dataType = "locations", dataProfile = "site") @@ -224,7 +224,7 @@ Hydrologic Unit Codes (HUCs) identify physical areas within the US that drain to ```{r} -huc_sites <- read_USGS_samples(hydrologicUnit = "070700", +huc_sites <- read_waterdata_samples(hydrologicUnit = "070700", characteristicUserSupplied = user_char, dataType = "locations", dataProfile = "site") @@ -242,7 +242,7 @@ map_it(huc_sites) Location latitude (pointLocationLatitude) and longitude (pointLocationLongitude), and the radius (pointLocationWithinMiles) are required for this geographic filter: ```{r} -point_sites <- read_USGS_samples(pointLocationLatitude = 43.074680, +point_sites <- read_waterdata_samples(pointLocationLatitude = 43.074680, pointLocationLongitude = -89.428054, pointLocationWithinMiles = 20, characteristicUserSupplied = user_char, @@ -259,13 +259,13 @@ map_it(point_sites) ### countyFips County query parameter. To get a list of available counties, -run `check_USGS_sample_params("counties")`. The "Fips" values can be created using the function `countyCdLookup`. +run `check_waterdata_sample_params("counties")`. The "Fips" values can be created using the function `countyCdLookup`. ```{r} dane_county <- countyCdLookup("WI", "Dane", outputType = "fips") -county_sites <- read_USGS_samples(countyFips = dane_county, +county_sites <- read_waterdata_samples(countyFips = dane_county, characteristicUserSupplied = user_char, dataType = "locations", dataProfile = "site") @@ -280,13 +280,13 @@ map_it(county_sites) ### stateFips State query parameter. To get a list of available state fips values, -run `check_USGS_sample_params("states")`. The "fips" values can be created using the function +run `check_waterdata_sample_params("states")`. The "fips" values can be created using the function `stateCdLookup`. ```{r} state_fip <- stateCdLookup("WI", outputType = "fips") -state_sites <- read_USGS_samples(stateFips = state_fip, +state_sites <- read_waterdata_samples(stateFips = state_fip, characteristicUserSupplied = user_char, dataType = "locations", dataProfile = "site") @@ -307,7 +307,7 @@ Additional parameters can be included to limit the results coming back from a re Site type code query parameter. ```{r} -site_type_info <- check_USGS_sample_params("sitetype") +site_type_info <- check_waterdata_sample_params("sitetype") site_type_info$typeCode ``` @@ -324,7 +324,7 @@ site_type_info$typeLongName Sample media refers to the environmental medium that was sampled or analyzed. ```{r} -media_info <- check_USGS_sample_params("samplemedia") +media_info <- check_waterdata_sample_params("samplemedia") media_info$activityMedia ``` @@ -333,34 +333,34 @@ media_info$activityMedia Characteristic group is a broad category describing the sample measurement. The options for this parameter generally follow the values described in the Water Quality Portal [User Guide](https://www.waterqualitydata.us/portal_userguide), but not always. ```{r} -group_info <- check_USGS_sample_params("characteristicgroup") +group_info <- check_waterdata_sample_params("characteristicgroup") group_info$characteristicGroup ``` ### characteristic -Characteristic is a specific category describing the sample. See `check_USGS_sample_params("characteristics")` for a full list, below is a small sample: +Characteristic is a specific category describing the sample. See `check_waterdata_sample_params("characteristics")` for a full list, below is a small sample: ```{r} -characteristic_info <- check_USGS_sample_params("characteristics") +characteristic_info <- check_waterdata_sample_params("characteristics") head(unique(characteristic_info$characteristicName)) ``` ### characteristicUserSupplied -Observed property is the USGS term for the constituent sampled and the property name gives a detailed description of what was sampled. Observed Property is mapped to characteristicUserSupplied, and replaces the parameter name and pcode USGS previously used to describe discrete sample data. See `check_USGS_sample_params("observedproperty")` for a full list, below is a small sample: +Observed property is the USGS term for the constituent sampled and the property name gives a detailed description of what was sampled. Observed Property is mapped to characteristicUserSupplied, and replaces the parameter name and pcode USGS previously used to describe discrete sample data. See `check_waterdata_sample_params("observedproperty")` for a full list, below is a small sample: ```{r} -char_us <- check_USGS_sample_params("observedproperty") +char_us <- check_waterdata_sample_params("observedproperty") head(char_us$observedProperty) ``` ### usgsPCode -USGS parameter code. See `check_USGS_sample_params("characteristics")` for a full list, below is a small sample: +USGS parameter code. See `check_waterdata_sample_params("characteristics")` for a full list, below is a small sample: ```{r} -characteristic_info <- check_USGS_sample_params("characteristics") +characteristic_info <- check_waterdata_sample_params("characteristics") head(unique(characteristic_info$parameterCode)) ``` @@ -379,7 +379,7 @@ Specify one or both of these fields to filter on the activity start date. The se For instance, let's grab Wisconsin sites that measured phosphorus in October or November of 2024: ```{r} -state_sites_recent <- read_USGS_samples(stateFips = state_fip, +state_sites_recent <- read_waterdata_samples(stateFips = state_fip, characteristicUserSupplied = user_char, dataType = "locations", activityStartDateLower = "2024-10-01", @@ -401,7 +401,7 @@ The above examples showed how to find sites within a geographic filter. We can u ```{r} dane_county <- countyCdLookup("WI", "Dane") -county_lake_sites <- read_USGS_samples(countyFips = dane_county, +county_lake_sites <- read_waterdata_samples(countyFips = dane_county, characteristicUserSupplied = user_char, siteTypeName = "Lake, Reservoir, Impoundment", dataType = "locations", @@ -409,13 +409,13 @@ county_lake_sites <- read_USGS_samples(countyFips = dane_county, ``` -There are only `r nrow(county_lake_sites)` lake sites measuring phosphorus in Dane County, WI. We can get a summary of the data at each site using the `summarize_USGS_samples` function. This function only accepts 1 site at a time: +There are only `r nrow(county_lake_sites)` lake sites measuring phosphorus in Dane County, WI. We can get a summary of the data at each site using the `summarize_waterdata_samples` function. This function only accepts 1 site at a time: ```{r message=FALSE} all_data <- data.frame() for(i in county_lake_sites$Location_Identifier){ - avail_i <- summarize_USGS_samples(monitoringLocationIdentifier = i) + avail_i <- summarize_waterdata_samples(monitoringLocationIdentifier = i) all_data <- avail_i |> filter(characteristicUserSupplied == user_char) |> bind_rows(all_data) diff --git a/vignettes/tutorial.Rmd b/vignettes/tutorial.Rmd index dbe1faae..68e2605f 100644 --- a/vignettes/tutorial.Rmd +++ b/vignettes/tutorial.Rmd @@ -49,7 +49,7 @@ vignette("dataRetrieval", package = "dataRetrieval") Additionally, each function has a help file. These can be accessed by typing a question mark, followed by the function name in the R console: ```{r echo=TRUE, eval=FALSE} -?read_USGS_daily +?read_waterdata_daily ``` Each function's help file has working examples to demonstrate the usage. The examples may have comments "## Not run". These examples CAN be run, they just are not run by the CRAN maintainers due to the external service calls. @@ -95,14 +95,14 @@ There are many types of data served from NWIS. To understand how the services ar * * USGS functions will slowly replace NWIS functions - * `read_USGS_samples` has replaced `readNWISqw` - * `read_USGS_daily` can replace `readNWISdv` - * `read_USGS_monitoring_location` can replace `readNWISsite` - * `read_USGS_ts_meta` can replace `whatNWISdata` + * `read_waterdata_samples` has replaced `readNWISqw` + * `read_waterdata_daily` can replace `readNWISdv` + * `read_waterdata_monitoring_location` can replace `readNWISsite` + * `read_waterdata_ts_meta` can replace `whatNWISdata` * Discrete water quality data: * WQP functions should be used when accessing non-USGS discrete water quality data - * `read_USGS_samples` should be used for USGS data + * `read_waterdata_samples` should be used for USGS data # NWIS Data: Current NWIS offerings @@ -110,16 +110,16 @@ There are many types of data served from NWIS. To understand how the services ar | data_type_cd |Function| Data description | Replacement Function | |--------|:-------|------:|-------:| |uv|[readNWISuv](https://doi-usgs.github.io/dataRetrieval/reference/readNWISuv.html)|Continuous data| None yet | -|dv|[readNWISdv](https://doi-usgs.github.io/dataRetrieval/reference/readNWISdv.html)|Daily aggregated | [read_USGS_daily](https://doi-usgs.github.io/dataRetrieval/reference/read_USGS_daily.html) | +|dv|[readNWISdv](https://doi-usgs.github.io/dataRetrieval/reference/readNWISdv.html)|Daily aggregated | [read_waterdata_daily](https://doi-usgs.github.io/dataRetrieval/reference/read_waterdata_daily.html) | |gwlevels|[readNWISgwl](https://doi-usgs.github.io/dataRetrieval/reference/readNWISgwl.html)|Groundwater levels | None yet | -|site|[readNWISsite](https://doi-usgs.github.io/dataRetrieval/reference/readNWISsite.html)|Site metadata| [read_USGS_monitoring_location](https://doi-usgs.github.io/dataRetrieval/reference/read_USGS_monitoring_location.html) | +|site|[readNWISsite](https://doi-usgs.github.io/dataRetrieval/reference/readNWISsite.html)|Site metadata| [read_waterdata_monitoring_location](https://doi-usgs.github.io/dataRetrieval/reference/read_waterdata_monitoring_location.html) | |pcode|[readNWISpCode](https://doi-usgs.github.io/dataRetrieval/reference/readNWISpCode.html)|Parameter code metadata | None yet | |stat|[readNWISstat](https://doi-usgs.github.io/dataRetrieval/reference/readNWISstat.html)| Site statistics | None yet | |rating|[readNWISrating](https://doi-usgs.github.io/dataRetrieval/reference/readNWISrating.html)| Rating curves| None yet | |peak|[readNWISpeak](https://doi-usgs.github.io/dataRetrieval/reference/readNWISpeak.html)|Peak flow| None yet | |use|[readNWISuse](https://doi-usgs.github.io/dataRetrieval/reference/readNWISuse.html)|Water Use| None yet | |meas|[readNWISmeas](https://doi-usgs.github.io/dataRetrieval/reference/readNWISmeas.html)|Discrete surface water| None yet | -| | [readNWISdata](https://doi-usgs.github.io/dataRetrieval/reference/readNWISdata.html) | General data import for NWIS| [read_USGS_data](https://doi-usgs.github.io/dataRetrieval/reference/read_USGS_data.html) | +| | [readNWISdata](https://doi-usgs.github.io/dataRetrieval/reference/readNWISdata.html) | General data import for NWIS| [read_waterdata](https://doi-usgs.github.io/dataRetrieval/reference/read_waterdata.html) | ## USGS Basic Retrievals @@ -201,7 +201,7 @@ pCode <- "00060" start.date <- "2023-10-01" end.date <- "2024-09-30" -pheasant <- read_USGS_daily(monitoring_location_id = siteNo, +pheasant <- read_waterdata_daily(monitoring_location_id = siteNo, parameter_code = pCode, time = c(start.date, end.date)) ``` @@ -224,12 +224,12 @@ ts <- ggplot( ts ``` -Then we can use the `readNWISpCode` and `read_USGS_monitoring_location` functions to create better labels: +Then we can use the `readNWISpCode` and `read_waterdata_monitoring_location` functions to create better labels: ```{r echo=TRUE, eval=TRUE, fig.height=3.5} parameterInfo <- readNWISpCode(pCode) -siteInfo <- read_USGS_monitoring_location(siteNo) +siteInfo <- read_waterdata_monitoring_location(siteNo) ts <- ts + xlab("") + @@ -250,7 +250,7 @@ First verify that the data you think is available is actually associated with th library(dplyr) site <- "USGS-05407000" -ts_data_available <- read_USGS_ts_meta(monitoring_location_id = site) +ts_data_available <- read_waterdata_ts_meta(monitoring_location_id = site) data_available <- ts_data_available |> @@ -272,13 +272,13 @@ datatable(data_available, ``` -The time series that have "Instantaneous" in the computation_identifier column will be available in the instantaneous data service (currently `readNWISuv`), and the rest of the data will be available in the daily service (`read_USGS_daily`). +The time series that have "Instantaneous" in the computation_identifier column will be available in the instantaneous data service (currently `readNWISuv`), and the rest of the data will be available in the daily service (`read_waterdata_daily`). ```{r eval=FALSE, echo=TRUE} dv_pcodes <- data_available$parameter_code[data_available$computation_identifier != "Instantaneous"] stat_cds <- data_available$statistic_id[data_available$computation_identifier != "Instantaneous"] -dv_data <- read_USGS_daily(monitoring_location_id = site, +dv_data <- read_waterdata_daily(monitoring_location_id = site, parameter_code = unique(dv_pcodes), statistic_id = unique(stat_cds)) @@ -291,10 +291,10 @@ peak_data <- readNWISpeak(gsub("USGS-", "", site)) ``` -For discrete water quality data, use the `summarize_USGS_samples` function: +For discrete water quality data, use the `summarize_waterdata_samples` function: ```{r echo=TRUE} -discrete_data_available_all <- summarize_USGS_samples(site) +discrete_data_available_all <- summarize_waterdata_samples(site) discrete_data_available <- discrete_data_available_all |> select(parameter_name = characteristicUserSupplied, @@ -313,10 +313,10 @@ datatable(discrete_data_available, ``` -The discrete water quality data can be accessed with the `read_USGS_samples` function: +The discrete water quality data can be accessed with the `read_waterdata_samples` function: ```{r eval=FALSE, echo=TRUE} -samples_data <- read_USGS_samples(monitoringLocationIdentifier = site, +samples_data <- read_waterdata_samples(monitoringLocationIdentifier = site, dataProfile = "basicphyschem") ``` @@ -362,8 +362,8 @@ This is all great when you know your site numbers. What do you do when you don't There are 2 `dataRetrieval` functions that help with USGS data discovery: -* `read_USGS_monitoring_location` finds sites within a specified filter -* `read_USGS_ts_meta` summarizes the time series meta data +* `read_waterdata_monitoring_location` finds sites within a specified filter +* `read_waterdata_ts_meta` summarizes the time series meta data And 2 functions that help with discover in WQP: @@ -377,8 +377,8 @@ Here are a few examples: ```{r eval=FALSE} # Daily temperature in Ohio -ohio_sites <- read_USGS_monitoring_location(state_name = "Ohio") -ohio_ts_meta <- read_USGS_ts_meta(bbox = sf::st_bbox(ohio_sites), +ohio_sites <- read_waterdata_monitoring_location(state_name = "Ohio") +ohio_ts_meta <- read_waterdata_ts_meta(bbox = sf::st_bbox(ohio_sites), parameter_code = "00010") # Real-time discharge at a site