From 92e97d11f90e667875c4ecc9530b0df3ba734f50 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 6 Oct 2026 13:11:12 -0500 Subject: [PATCH 01/16] Error out with NWIS functions --- DESCRIPTION | 2 +- NAMESPACE | 1 - NEWS.md | 4 + R/constructNWISURL.R | 8 +- R/readNWISdv.R | 65 ++-- R/readNWISpCode.R | 186 ++++++------ R/readNWISsite.R | 64 ++-- R/readNWISunit.R | 372 ++++++++++++----------- R/whatNWISdata.R | 201 ++++++------ R/whatNWISsites.R | 169 +++++----- README.Rmd | 15 +- README.md | 33 +- _pkgdown.yml | 11 +- inst/CITATION | 6 +- man/get_monitoring_location_arguments.Rd | 32 +- man/readNWISdv.Rd | 25 +- man/readNWISpCode.Rd | 7 +- man/readNWISpeak.Rd | 8 +- man/readNWISrating.Rd | 12 +- man/readNWISsite.Rd | 7 +- man/readNWISstat.Rd | 8 +- man/readNWISuse.Rd | 53 ---- man/readNWISuv.Rd | 14 +- man/whatNWISdata.Rd | 24 +- man/whatNWISsites.Rd | 7 +- tests/testthat/tests_general.R | 15 - 26 files changed, 680 insertions(+), 669 deletions(-) delete mode 100644 man/readNWISuse.Rd diff --git a/DESCRIPTION b/DESCRIPTION index db12e4545..2ee3f4a03 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: dataRetrieval Type: Package Title: Retrieval Functions for USGS and EPA Hydrology and Water Quality Data -Version: 2.7.26 +Version: 2.7.27 Authors@R: c( person("Laura", "DeCicco", role = c("aut","cre"), email = "ldecicco@usgs.gov", diff --git a/NAMESPACE b/NAMESPACE index c68d3c966..3eabecbe3 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -35,7 +35,6 @@ export(readNWISpeak) export(readNWISrating) export(readNWISsite) export(readNWISstat) -export(readNWISuse) export(readNWISuv) export(readWQPdata) export(readWQPqw) diff --git a/NEWS.md b/NEWS.md index d7a4a6e17..064b941ee 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,7 @@ +dataRetrieval 2.7.27 +=================== +* All NWIS functions will now error out by default. NWIS servers will be taken offline February 22nd, 2027. Use override_error = TRUE to temporarily override this error. + dataRetrieval 2.7.26 =================== * Switching to v1 of the Water Data APIs. diff --git a/R/constructNWISURL.R b/R/constructNWISURL.R index fd06ed227..5fc372844 100644 --- a/R/constructNWISURL.R +++ b/R/constructNWISURL.R @@ -146,12 +146,6 @@ constructNWISURL <- function( }, stat = { # for statistics service - - message( - "Please be aware the NWIS data service feeding this function is in BETA.\n - Data formatting could be changed at any time, and is not guaranteed" - ) - # make sure only statTypes allowed for the statReportType are being requested if ( !grepl("(?i)daily", statReportType) && @@ -327,7 +321,7 @@ constructWQPURL <- function( pCodeLogic <- TRUE - POST = nchar(paste0(siteNumbers, collapse = "")) > 2048 + POST <- nchar(paste0(siteNumbers, collapse = "")) > 2048 if (!allPCode) { multiplePcodes <- length(parameterCd) > 1 diff --git a/R/readNWISdv.R b/R/readNWISdv.R index 069c0dccb..614a9792c 100644 --- a/R/readNWISdv.R +++ b/R/readNWISdv.R @@ -24,6 +24,10 @@ #' @param endDate character ending date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates #' retrieval for the latest possible record. Date arguments are always specified in local time. #' @param statCd character USGS statistic code. This is usually 5 digits. Daily mean (00003) is the default. +#' @param override_error Logical parameter that allows users to run this +#' function during the final stages of NWIS decommission. NWIS servers will be taken +#' offline February 22nd, 2027. Setting this parameter to `TRUE` should only +#' be used as a tool to convert readNWIS to read_waterdata functions. #' @return A data frame with the following columns: #' \tabular{lll}{ #' Name \tab Type \tab Description \cr @@ -51,48 +55,43 @@ #' #' @seealso [read_waterdata_daily()] #' @export -#' @keywords data import USGS web service -#' @examples -#' -#' # see ?read_waterdata_daily -#' -#' #site_id <- "04085427" -#' #startDate <- "2012-01-01" -#' #endDate <- "2012-06-30" -#' #pCode <- "00060" -#' # -#' #rawDailyQ <- readNWISdv(site_id, pCode, startDate, endDate) -#' readNWISdv <- function( siteNumbers, parameterCd, startDate = "", endDate = "", - statCd = "00003" + statCd = "00003", + override_error = FALSE ) { - .Deprecated( - new = "read_waterdata_daily", - package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_daily." - ) + if (override_error) { + warning( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISdv to read_waterdata_daily." + ) - url <- constructNWISURL( - siteNumbers = siteNumbers, - parameterCd = parameterCd, - startDate = startDate, - endDate = endDate, - service = "dv", - statCd = statCd - ) + url <- constructNWISURL( + siteNumbers = siteNumbers, + parameterCd = parameterCd, + startDate = startDate, + endDate = endDate, + service = "dv", + statCd = statCd + ) - data <- importWaterML1(url, asDateTime = FALSE) + data <- importWaterML1(url, asDateTime = FALSE) - if (nrow(data) > 0) { - data$dateTime <- as.Date(data$dateTime) - data$tz_cd <- NULL + if (nrow(data) > 0) { + data$dateTime <- as.Date(data$dateTime) + data$tz_cd <- NULL - names(data)[names(data) == "dateTime"] <- "Date" - } + names(data)[names(data) == "dateTime"] <- "Date" + } - return(data) + return(data) + } else { + stop( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISdv to read_waterdata_daily. +Use override_error = TRUE to temporarily override this error. For more information: +https://doi-usgs.github.io/dataRetrieval/articles/read_waterdata_functions.html" + ) + } } diff --git a/R/readNWISpCode.R b/R/readNWISpCode.R index c39bc2606..5b3d77528 100644 --- a/R/readNWISpCode.R +++ b/R/readNWISpCode.R @@ -5,6 +5,10 @@ #' @param parameterCd character of USGS parameter codes (or multiple parameter codes). #' These are 5 digit number codes. To get a complete list of all current parameter #' codes in the USGS, use "all" as the input. +#' @param override_error Logical parameter that allows users to run this +#' function during the final stages of NWIS decommission. NWIS servers will be taken +#' offline February 22nd, 2027. Setting this parameter to `TRUE` should only +#' be used as a tool to convert readNWIS to read_waterdata functions. #' @keywords data import USGS web service #' @return parameterData data frame with the following information: #' \tabular{lll}{ @@ -19,104 +23,112 @@ #' #' @export #' @seealso [importRDB1()] -readNWISpCode <- function(parameterCd) { - .Deprecated( - new = "read_waterdata_parameter_codes", - package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_parameter_codes" - ) - - parameterCd.orig <- parameterCd - parameterCd <- parameterCd[!is.na(parameterCd)] - baseURL <- httr2::request(pkg.env[["pCode"]]) - fullURL <- httr2::req_url_query(baseURL, fmt = "rdb", group_cd = "%") - - if (any(parameterCd == "all")) { - temp_df <- importRDB1(fullURL, asDateTime = FALSE) - parameterData <- data.frame( - parameter_cd = temp_df$parm_cd, - parameter_group_nm = temp_df$group, - parameter_nm = temp_df$parm_nm, - casrn = temp_df$CASRN, - srsname = temp_df$SRSName, - parameter_units = temp_df$parm_unit, - stringsAsFactors = FALSE +readNWISpCode <- function(parameterCd, override_error = FALSE) { + if (override_error) { + warning( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISpCode to read_waterdata_parameter_codes." ) - attr(parameterData, "url") <- fullURL$url - } else { - parameterData <- parameterCdFile[ - parameterCdFile$parameter_cd %in% parameterCd, - ] - if (nrow(parameterData) != length(parameterCd)) { - parameterCd_lookup <- parameterCd[ - !parameterCd %in% unique(parameterData$parameter_cd) + parameterCd.orig <- parameterCd + parameterCd <- parameterCd[!is.na(parameterCd)] + baseURL <- httr2::request(pkg.env[["pCode"]]) + fullURL <- httr2::req_url_query(baseURL, fmt = "rdb", group_cd = "%") + + if (any(parameterCd == "all")) { + temp_df <- importRDB1(fullURL, asDateTime = FALSE) + parameterData <- data.frame( + parameter_cd = temp_df$parm_cd, + parameter_group_nm = temp_df$group, + parameter_nm = temp_df$parm_nm, + casrn = temp_df$CASRN, + srsname = temp_df$SRSName, + parameter_units = temp_df$parm_unit, + stringsAsFactors = FALSE + ) + attr(parameterData, "url") <- fullURL$url + } else { + parameterData <- parameterCdFile[ + parameterCdFile$parameter_cd %in% parameterCd, ] - if (length(parameterCd_lookup) == 1) { - baseURL <- httr2::request(pkg.env[["pCodeSingle"]]) - baseURL <- httr2::req_url_query(baseURL, fmt = "rdb") - baseURL <- httr2::req_url_query( - baseURL, - parm_nm_cd = parameterCd_lookup - ) + if (nrow(parameterData) != length(parameterCd)) { + parameterCd_lookup <- parameterCd[ + !parameterCd %in% unique(parameterData$parameter_cd) + ] - temp_df <- importRDB1(baseURL, asDateTime = FALSE) + if (length(parameterCd_lookup) == 1) { + baseURL <- httr2::request(pkg.env[["pCodeSingle"]]) + baseURL <- httr2::req_url_query(baseURL, fmt = "rdb") + baseURL <- httr2::req_url_query( + baseURL, + parm_nm_cd = parameterCd_lookup + ) - temp_df <- data.frame( - parameter_cd = temp_df$parameter_cd, - parameter_group_nm = temp_df$group, - parameter_nm = temp_df$parm_nm, - casrn = temp_df$CASRN, - srsname = temp_df$SRSName, - parameter_units = temp_df$parm_unit, - stringsAsFactors = FALSE - ) + temp_df <- importRDB1(baseURL, asDateTime = FALSE) - if (nrow(temp_df) > 0) { - parameterData <- rbind(parameterData, temp_df) - } + temp_df <- data.frame( + parameter_cd = temp_df$parameter_cd, + parameter_group_nm = temp_df$group, + parameter_nm = temp_df$parm_nm, + casrn = temp_df$CASRN, + srsname = temp_df$SRSName, + parameter_units = temp_df$parm_unit, + stringsAsFactors = FALSE + ) - attr(parameterData, "url") <- baseURL$url - } else { - temp_df <- importRDB1(fullURL, asDateTime = FALSE) - trim_df <- data.frame( - parameter_cd = temp_df$parm_cd, - parameter_group_nm = temp_df$group, - parameter_nm = temp_df$parm_nm, - casrn = temp_df$CASRN, - srsname = temp_df$SRSName, - parameter_units = temp_df$parm_unit, - stringsAsFactors = FALSE - ) - parameterData <- trim_df[trim_df$parameter_cd %in% parameterCd, ] - attr(parameterData, "url") <- fullURL$url - } + if (nrow(temp_df) > 0) { + parameterData <- rbind(parameterData, temp_df) + } - if (nrow(parameterData) != length(parameterCd)) { - badPcode <- parameterCd[!(parameterCd %in% parameterData$parameter_cd)] - warning( - "The following pCodes seem mistyped, and no information was returned: ", - paste(badPcode, collapse = ", ") - ) + attr(parameterData, "url") <- baseURL$url + } else { + temp_df <- importRDB1(fullURL, asDateTime = FALSE) + trim_df <- data.frame( + parameter_cd = temp_df$parm_cd, + parameter_group_nm = temp_df$group, + parameter_nm = temp_df$parm_nm, + casrn = temp_df$CASRN, + srsname = temp_df$SRSName, + parameter_units = temp_df$parm_unit, + stringsAsFactors = FALSE + ) + parameterData <- trim_df[trim_df$parameter_cd %in% parameterCd, ] + attr(parameterData, "url") <- fullURL$url + } + + if (nrow(parameterData) != length(parameterCd)) { + badPcode <- parameterCd[ + !(parameterCd %in% parameterData$parameter_cd) + ] + warning( + "The following pCodes seem mistyped, and no information was returned: ", + paste(badPcode, collapse = ", ") + ) + } } } - } - if (nrow(parameterData) != sum(is.na(parameterCd.orig))) { - na.params <- data.frame(matrix( - ncol = ncol(parameterData), - nrow = sum(is.na(parameterCd.orig)) - )) - names(na.params) <- names(parameterData) - parameterData <- rbind(parameterData, na.params) - } - # order by parameterCd.orig - if (!isTRUE(parameterCd.orig == "all")) { - parameterData <- parameterData[ - match(parameterCd.orig, parameterData$parameter_cd), - ] - parameterData$parameter_cd <- parameterCd.orig + if (nrow(parameterData) != sum(is.na(parameterCd.orig))) { + na.params <- data.frame(matrix( + ncol = ncol(parameterData), + nrow = sum(is.na(parameterCd.orig)) + )) + names(na.params) <- names(parameterData) + parameterData <- rbind(parameterData, na.params) + } + # order by parameterCd.orig + if (!isTRUE(parameterCd.orig == "all")) { + parameterData <- parameterData[ + match(parameterCd.orig, parameterData$parameter_cd), + ] + parameterData$parameter_cd <- parameterCd.orig + } + return(parameterData) + } else { + stop( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISpCode to read_waterdata_parameter_codes. +Use override_error = TRUE to temporarily override this error. For more information: +https://doi-usgs.github.io/dataRetrieval/articles/read_waterdata_functions.html" + ) } - return(parameterData) } diff --git a/R/readNWISsite.R b/R/readNWISsite.R index 5f1b48f3a..b31f57e47 100644 --- a/R/readNWISsite.R +++ b/R/readNWISsite.R @@ -3,6 +3,10 @@ #' Imports data from USGS site file site. This function gets data from here: #' #' @param siteNumbers character USGS site number (or multiple sites). This is usually an 8 digit number +#' @param override_error Logical parameter that allows users to run this +#' function during the final stages of NWIS decommission. NWIS servers will be taken +#' offline February 22nd, 2027. Setting this parameter to `TRUE` should only +#' be used as a tool to convert readNWIS to read_waterdata functions. #' @keywords data import USGS web service #' @return A data frame with at least the following columns: #' \tabular{lll}{ @@ -65,37 +69,43 @@ #' # see ?read_waterdata_monitoring_location #' # siteINFOMulti <- readNWISsite(c("05114000", "09423350")) #' -readNWISsite <- function(siteNumbers) { - .Deprecated( - new = "read_waterdata_monitoring_location", - package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_monitoring_location" - ) +readNWISsite <- function(siteNumbers, override_error = FALSE) { + if (override_error) { + warning( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISsite to read_waterdata_monitoring_location" + ) - baseURL <- httr2::request(pkg.env[["site"]]) - urlSitefile <- httr2::req_url_query( - baseURL, - siteOutput = "Expanded", - format = "rdb" - ) + baseURL <- httr2::request(pkg.env[["site"]]) + urlSitefile <- httr2::req_url_query( + baseURL, + siteOutput = "Expanded", + format = "rdb" + ) - POST <- nchar(paste0(siteNumbers, collapse = "")) > 2048 + POST <- nchar(paste0(siteNumbers, collapse = "")) > 2048 - urlSitefile <- get_or_post( - urlSitefile, - POST = POST, - site = siteNumbers, - .multi = "comma" - ) + urlSitefile <- get_or_post( + urlSitefile, + POST = POST, + site = siteNumbers, + .multi = "comma" + ) - data <- importRDB1(urlSitefile, asDateTime = FALSE) - # readr needs multiple lines to convert to anything but characters: - data[grep("_va", names(data))][data[grep("_va", names(data))] == "."] <- NA + data <- importRDB1(urlSitefile, asDateTime = FALSE) + # readr needs multiple lines to convert to anything but characters: + data[grep("_va", names(data))][data[grep("_va", names(data))] == "."] <- NA - data[, grep("_va", names(data))] <- sapply( - data[, grep("_va", names(data))], - as.numeric - ) + data[, grep("_va", names(data))] <- sapply( + data[, grep("_va", names(data))], + as.numeric + ) - return(data) + return(data) + } else { + stop( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISsite to read_waterdata_monitoring_location +Use override_error = TRUE to temporarily override this error. For more information: +https://doi-usgs.github.io/dataRetrieval/articles/read_waterdata_functions.html" + ) + } } diff --git a/R/readNWISunit.R b/R/readNWISunit.R index 515054de8..908003e95 100644 --- a/R/readNWISunit.R +++ b/R/readNWISunit.R @@ -22,6 +22,10 @@ #' "America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", #' "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also `OlsonNames()` #' for more information on time zones. +#' @param override_error Logical parameter that allows users to run this +#' function during the final stages of NWIS decommission. NWIS servers will be taken +#' offline February 22nd, 2027. Setting this parameter to `TRUE` should only +#' be used as a tool to convert readNWIS to read_waterdata functions. #' @keywords data import USGS web service #' @return A data frame with the following columns: #' \tabular{lll}{ @@ -68,34 +72,41 @@ readNWISuv <- function( parameterCd, startDate = "", endDate = "", - tz = "UTC" + tz = "UTC", + override_error = FALSE ) { - if ( - as.character(startDate) == "" || (as.Date(startDate) <= Sys.Date() - 120) - ) { - service <- "iv" - } else { - service <- "iv_recent" - } + if (override_error) { + warning( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISuv to read_waterdata_continuous." + ) - .Deprecated( - new = "read_waterdata_continuous", - package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_continuous." - ) + if ( + as.character(startDate) == "" || (as.Date(startDate) <= Sys.Date() - 120) + ) { + service <- "iv" + } else { + service <- "iv_recent" + } - url <- constructNWISURL( - siteNumbers, - parameterCd, - startDate, - endDate, - service, - format = "xml" - ) + url <- constructNWISURL( + siteNumbers, + parameterCd, + startDate, + endDate, + service, + format = "xml" + ) - data <- importWaterML1(url, asDateTime = TRUE, tz = tz) + data <- importWaterML1(url, asDateTime = TRUE, tz = tz) - return(data) + return(data) + } else { + stop( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISuv to read_waterdata_continuous. +Use override_error = TRUE to temporarily override this error. For more information: +https://doi-usgs.github.io/dataRetrieval/articles/read_waterdata_functions.html" + ) + } } #' Peak flow data from USGS (NWIS) @@ -123,6 +134,10 @@ readNWISuv <- function( #' @param convertType logical, defaults to `TRUE`. If `TRUE`, the function #' will convert the data to dates, datetimes, #' numerics based on a standard algorithm. If false, everything is returned as a character +#' @param override_error Logical parameter that allows users to run this +#' function during the final stages of NWIS decommission. NWIS servers will be taken +#' offline February 22nd, 2027. Setting this parameter to `TRUE` should only +#' be used as a tool to convert readNWIS to read_waterdata functions. #' @return A data frame with the following columns: #' \tabular{lll}{ #' Name \tab Type \tab Description \cr @@ -168,63 +183,73 @@ readNWISpeak <- function( startDate = "", endDate = "", asDateTime = TRUE, - convertType = TRUE + convertType = TRUE, + override_error = FALSE ) { - .Deprecated( - new = "read_waterdata_peaks", - package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_peaks." - ) - # Doesn't seem to be a peak xml service - url <- constructNWISURL( - siteNumbers = siteNumbers, - parameterCd = NA, - startDate = startDate, - endDate = endDate, - service = "peak" - ) + if (override_error) { + warning( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISpeak to read_waterdata_peaks." + ) + # Doesn't seem to be a peak xml service + url <- constructNWISURL( + siteNumbers = siteNumbers, + parameterCd = NA, + startDate = startDate, + endDate = endDate, + service = "peak" + ) - data <- importRDB1(url, asDateTime = asDateTime, convertType = convertType) + data <- importRDB1(url, asDateTime = asDateTime, convertType = convertType) - if (nrow(data) > 0) { - if (asDateTime && convertType) { - if ("peak_dt" %in% names(data)) { - if ( - any(nchar(as.character(data$peak_dt)) <= 7, na.rm = TRUE) || - any(grepl("[0-9]*-[0-9]*-00", data$peak_dt), na.rm = TRUE) - ) { - stop( - "Not all dates could be converted to Date object. Use convertType=FALSE to retrieve the raw text" - ) - } else { - data$peak_dt <- as.Date(data$peak_dt, format = "%Y-%m-%d") + if (nrow(data) > 0) { + if (asDateTime && convertType) { + if ("peak_dt" %in% names(data)) { + if ( + any(nchar(as.character(data$peak_dt)) <= 7, na.rm = TRUE) || + any(grepl("[0-9]*-[0-9]*-00", data$peak_dt), na.rm = TRUE) + ) { + stop( + "Not all dates could be converted to Date object. Use convertType=FALSE to retrieve the raw text" + ) + } else { + data$peak_dt <- as.Date(data$peak_dt, format = "%Y-%m-%d") + } + if (anyNA(data$peak_dt)) { + message( + "Some dates could not be converted to a valid date, and were returned as NA" + ) + } } - if (anyNA(data$peak_dt)) { - message( - "Some dates could not be converted to a valid date, and were returned as NA" - ) + + if ("ag_dt" %in% names(data)) { + data$ag_dt <- as.Date(data$ag_dt, format = "%Y-%m-%d") } } - if ("ag_dt" %in% names(data)) { - data$ag_dt <- as.Date(data$ag_dt, format = "%Y-%m-%d") - } + siteInfo <- suppressWarnings(readNWISsite( + siteNumbers, + override_error = TRUE + )) + siteInfo <- merge( + x = unique(data[, c("agency_cd", "site_no")]), + y = siteInfo, + by = c("agency_cd", "site_no"), + all.x = TRUE + ) + + attr(data, "siteInfo") <- siteInfo + attr(data, "variableInfo") <- NULL + attr(data, "statisticInfo") <- NULL } - siteInfo <- suppressWarnings(readNWISsite(siteNumbers)) - siteInfo <- merge( - x = unique(data[, c("agency_cd", "site_no")]), - y = siteInfo, - by = c("agency_cd", "site_no"), - all.x = TRUE + return(data) + } else { + stop( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISdv to read_waterdata_peaks. +Use override_error = TRUE to temporarily override this error. For more information: +https://doi-usgs.github.io/dataRetrieval/articles/read_waterdata_functions.html" ) - - attr(data, "siteInfo") <- siteInfo - attr(data, "variableInfo") <- NULL - attr(data, "statisticInfo") <- NULL } - - return(data) } #' Rating table for an active USGS streamgage retrieval @@ -236,6 +261,10 @@ readNWISpeak <- function( #' @param convertType logical, defaults to `TRUE`. If `TRUE`, the function #' will convert the data to dates, datetimes, #' numerics based on a standard algorithm. If false, everything is returned as a character +#' @param override_error Logical parameter that allows users to run this +#' function during the final stages of NWIS decommission. NWIS servers will be taken +#' offline February 22nd, 2027. Setting this parameter to `TRUE` should only +#' be used as a tool to convert readNWIS to read_waterdata functions. #' @return A data frame. If `type` is "base, " then the columns are #' INDEP, typically the gage height, in feet; DEP, typically the streamflow, #' in cubic feet per second; and STOR, where "*" indicates that the pair are @@ -267,38 +296,52 @@ readNWISpeak <- function( #' #data <- readNWISrating(site_id, "base") #' #attr(data, "RATING") #' } -readNWISrating <- function(siteNumber, type = "base", convertType = TRUE) { - .Deprecated( - new = "read_waterdata_ratings", - package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_ratings." - ) - - # No rating xml service - url <- constructNWISURL(siteNumber, service = "rating", ratingType = type) +readNWISrating <- function( + siteNumber, + type = "base", + convertType = TRUE, + override_error = FALSE +) { + if (override_error) { + warning( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISrating to read_waterdata_ratings." + ) - data <- importRDB1(url, asDateTime = FALSE, convertType = convertType) + # No rating xml service + url <- constructNWISURL(siteNumber, service = "rating", ratingType = type) - if ("current_rating_nu" %in% names(data)) { - data$current_rating_nu <- gsub(" ", "", data$current_rating_nu) - } + data <- importRDB1(url, asDateTime = FALSE, convertType = convertType) - if (nrow(data) > 0) { - if (type == "base") { - Rat <- grep("//RATING ", comment(data), value = TRUE, fixed = TRUE) - Rat <- sub("# //RATING ", "", Rat) - Rat <- scan(text = Rat, sep = " ", what = "") - attr(data, "RATING") <- Rat + if ("current_rating_nu" %in% names(data)) { + data$current_rating_nu <- gsub(" ", "", data$current_rating_nu) } - siteInfo <- suppressWarnings(readNWISsite(siteNumbers = siteNumber)) + if (nrow(data) > 0) { + if (type == "base") { + Rat <- grep("//RATING ", comment(data), value = TRUE, fixed = TRUE) + Rat <- sub("# //RATING ", "", Rat) + Rat <- scan(text = Rat, sep = " ", what = "") + attr(data, "RATING") <- Rat + } - attr(data, "siteInfo") <- siteInfo - attr(data, "variableInfo") <- NULL - attr(data, "statisticInfo") <- NULL - } + siteInfo <- suppressWarnings(readNWISsite( + siteNumbers = siteNumber, + override_error = TRUE + )) - return(data) + attr(data, "siteInfo") <- siteInfo + attr(data, "variableInfo") <- NULL + attr(data, "statisticInfo") <- NULL + } + + return(data) + } else { + stop( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISrating to read_waterdata_ratings. +Use override_error = TRUE to temporarily override this error. For more information: +https://doi-usgs.github.io/dataRetrieval/articles/read_waterdata_functions.html" + ) + } } @@ -329,6 +372,10 @@ readNWISrating <- function(siteNumber, type = "base", convertType = TRUE) { #' provide statistics for each month and year within the range indivually. #' @param statType character type(s) of statistics to output for daily values. #' Default is mean, which is the only option for monthly and yearly report types. +#' @param override_error Logical parameter that allows users to run this +#' function during the final stages of NWIS decommission. NWIS servers will be taken +#' offline February 22nd, 2027. Setting this parameter to `TRUE` should only +#' be used as a tool to convert readNWIS to read_waterdata functions. #' @return A data frame with the following columns: #' \tabular{lll}{ #' Name \tab Type \tab Description \cr @@ -372,99 +419,60 @@ readNWISstat <- function( endDate = "", convertType = TRUE, statReportType = "daily", - statType = "mean" + statType = "mean", + override_error = FALSE ) { - .Deprecated( - new = "read_waterdata_stats_por", - package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to either read_waterdata_stats_por or read_waterdata_stats_daterange." - ) - - message(new_nwis_message()) - # check for NAs in site numbers - if (any(is.na(siteNumbers))) { - siteNumbers <- siteNumbers[!is.na(siteNumbers)] - if (length(siteNumbers) == 0) { - stop("siteNumbers was all NAs") + if (override_error) { + warning( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISstat to read_waterdata_stats_por" + ) + # check for NAs in site numbers + if (any(is.na(siteNumbers))) { + siteNumbers <- siteNumbers[!is.na(siteNumbers)] + if (length(siteNumbers) == 0) { + stop("siteNumbers was all NAs") + } + warning("NAs were passed in siteNumbers; they were ignored") } - warning("NAs were passed in siteNumbers; they were ignored") - } - url <- constructNWISURL( - siteNumbers = siteNumbers, - parameterCd = parameterCd, - startDate = startDate, - endDate = endDate, - service = "stat", - format = "rdb", - statType = statType, - statReportType = statReportType - ) - - data <- importRDB1( - obs_url = url, - asDateTime = TRUE, - convertType = convertType - ) - - siteInfo <- suppressWarnings(readNWISsite(siteNumbers)) + url <- constructNWISURL( + siteNumbers = siteNumbers, + parameterCd = parameterCd, + startDate = startDate, + endDate = endDate, + service = "stat", + format = "rdb", + statType = statType, + statReportType = statReportType + ) - if (nrow(data) > 0) { - siteInfo <- merge( - x = unique(data[, c("agency_cd", "site_no")]), - y = siteInfo, - by = c("agency_cd", "site_no"), - all.x = TRUE + data <- importRDB1( + obs_url = url, + asDateTime = TRUE, + convertType = convertType ) - } - attr(data, "siteInfo") <- siteInfo + siteInfo <- suppressWarnings(readNWISsite( + siteNumbers, + override_error = TRUE + )) - return(data) -} + if (nrow(data) > 0) { + siteInfo <- merge( + x = unique(data[, c("agency_cd", "site_no")]), + y = siteInfo, + by = c("agency_cd", "site_no"), + all.x = TRUE + ) + } -#' Water use data retrieval from USGS (NWIS) -#' -#' Retrieves water use data from USGS Water Use Data for the Nation. -#' -#' @param stateCd could be character (full name, abbreviation, id), or numeric (id). -#' Only one is accepted per query. -#' @param countyCd could be character (name, with or without "County", or "ALL"), -#' numeric (id), or `NULL`, which will -#' return state or national data depending on the stateCd argument. "ALL" may -#' also be supplied, which will return data -#' for every county in a state. Can be a vector of counties in the same state. -#' @param years integer Years for data retrieval. Must be years ending in 0 or 5. -#' Default is all available years. -#' @param categories character categories of water use. Defaults to "ALL". -#' Specific categories must be supplied as two- -#' letter abbreviations as seen in the URL when using the NWIS water use web interface. Note that -#' there are different codes for national and state level data. -#' @param convertType logical defaults to `TRUE`. If `TRUE`, the function -#' will convert the data to -#' numerics based on a standard algorithm. Years, months, and days (if appliccable) are -#' also returned as numerics -#' in separate columns. If convertType is false, everything is returned as a character. -#' @param transform logical only intended for use with national data. Defaults to -#' `FALSE`, with data being returned as -#' presented by the web service. If `TRUE`, data will be transformed and -#' returned with column names, which will reformat -#' national data to be similar to state data. -#' @return A data frame with at least the year of record, and all available -#' statistics for the given geographic parameters. -#' County and state fields will be included as appropriate. -#' -#' @export -readNWISuse <- function( - stateCd, - countyCd, - years = "ALL", - categories = "ALL", - convertType = TRUE, - transform = FALSE -) { - .Deprecated( - package = "dataRetrieval", - msg = "NWIS servers for water use have been decommissioned. New functions are being developed." - ) - return(NULL) + attr(data, "siteInfo") <- siteInfo + + return(data) + } else { + stop( + "NWIS servers will be taken offline February 22nd, 2027. Update readNWISstat to read_waterdata_stats_por +Use override_error = TRUE to temporarily override this error. For more information: +https://doi-usgs.github.io/dataRetrieval/articles/read_waterdata_functions.html" + ) + } } diff --git a/R/whatNWISdata.R b/R/whatNWISdata.R index a1731b345..4c1fba08f 100644 --- a/R/whatNWISdata.R +++ b/R/whatNWISdata.R @@ -9,6 +9,10 @@ #' @param convertType logical, defaults to `TRUE`. If `TRUE`, the function will #' convert the data to dates, datetimes, #' numerics based on a standard algorithm. If false, everything is returned as a character +#' @param override_error Logical parameter that allows users to run this +#' function during the final stages of NWIS decommission. NWIS servers will be taken +#' offline February 22nd, 2027. Setting this parameter to `TRUE` should only +#' be used as a tool to convert readNWIS to read_waterdata functions. #' @keywords data import USGS web service #' #' @details This function requires users to create their own arguments @@ -63,129 +67,106 @@ #' queryTime \tab POSIXct \tab The time the data was returned \cr #' } #' @export -#' @seealso [read_waterdata_ts_meta()] -#' @examples -#' -#' # see ?read_waterdata_ts_meta -#' -#' #site1 <- whatWQPsamples(siteid = "USGS-01594440") -#' -#' #type <- "Stream" -#' -#' #sites <- whatWQPsamples(countycode = "US:55:025", siteType = type) -#' -#' #lakeSites_samples <- whatWQPsamples(siteType = "Lake, Reservoir, Impoundment", -#' # countycode = "US:55:025") -#' -#' -whatNWISdata <- function(..., convertType = TRUE) { - matchReturn <- convertLists(...) - - prewarned <- FALSE - - .Deprecated( - new = "read_waterdata_ts_meta", - package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_ts_meta" - ) - - if ("service" %in% names(matchReturn)) { - service <- matchReturn$service - - if (any(service %in% c("qw", "qwdata"))) { - .Deprecated( - old = "whatNWISdata", - package = "dataRetrieval", - new = "whatWQPdata", - msg = nwis_message() - ) - prewarned <- TRUE - } - } else { - service <- "all" - } +#' @seealso [read_waterdata_combined_meta()] +whatNWISdata <- function(..., convertType = TRUE, override_error = FALSE) { + if (override_error) { + warning( + "NWIS servers will be taken offline February 22nd, 2027. Update whatNWISdata to read_waterdata_combined_meta" + ) - if (any(service == "site")) { - service <- "all" - } else if (any(service == "iv")) { - service[service == "iv"] <- "uv" - } else if (any(service == "peak")) { - service[service == "peak"] <- "pk" - } + matchReturn <- convertLists(...) - if ("statCd" %in% names(matchReturn)) { - statCd <- matchReturn$statCd - matchReturn <- matchReturn[names(matchReturn) != "statCd"] - } else { - statCd <- "all" - } + prewarned <- FALSE - if ("parameterCd" %in% names(matchReturn)) { - parameterCd <- matchReturn$parameterCd - matchReturn[["parameterCd"]] <- NULL - } else { - parameterCd <- "all" - } + if ("service" %in% names(matchReturn)) { + service <- matchReturn$service + } else { + service <- "all" + } - if ( - "startDate" %in% names(matchReturn) && !"endDate" %in% names(matchReturn) - ) { - matchReturn[["endDate"]] <- matchReturn[["startDate"]] - } + if (any(service == "site")) { + service <- "all" + } else if (any(service == "iv")) { + service[service == "iv"] <- "uv" + } else if (any(service == "peak")) { + service[service == "peak"] <- "pk" + } - matchReturn$service <- "site" + if ("statCd" %in% names(matchReturn)) { + statCd <- matchReturn$statCd + matchReturn <- matchReturn[names(matchReturn) != "statCd"] + } else { + statCd <- "all" + } - valuesList <- readNWISdots(matchReturn) + if ("parameterCd" %in% names(matchReturn)) { + parameterCd <- matchReturn$parameterCd + matchReturn[["parameterCd"]] <- NULL + } else { + parameterCd <- "all" + } - values <- valuesList[["values"]] - values <- values[names(values) != "format"] + if ( + "startDate" %in% names(matchReturn) && !"endDate" %in% names(matchReturn) + ) { + matchReturn[["endDate"]] <- matchReturn[["startDate"]] + } - POST <- nchar(paste0(unlist(values), collapse = "")) > 2048 + matchReturn$service <- "site" - urlSitefile <- httr2::request(pkg.env[["site"]]) - urlSitefile <- get_or_post( - urlSitefile, - POST = POST, - seriesCatalogOutput = "true" - ) - urlSitefile <- get_or_post( - urlSitefile, - POST = POST, - !!!values, - .multi = "comma" - ) + valuesList <- readNWISdots(matchReturn) - SiteFile <- importRDB1( - urlSitefile, - asDateTime = FALSE, - convertType = convertType - ) + values <- valuesList[["values"]] + values <- values[names(values) != "format"] - if (!("all" %in% service)) { - SiteFile <- SiteFile[SiteFile$data_type_cd %in% service, ] - } - if (!("all" %in% statCd)) { - SiteFile <- SiteFile[SiteFile$stat_cd %in% c(statCd, NA), ] - } - if (!("all" %in% parameterCd)) { - SiteFile <- SiteFile[SiteFile$parm_cd %in% parameterCd, ] - } + POST <- nchar(paste0(unlist(values), collapse = "")) > 2048 - if (nrow(SiteFile) > 0 && convertType) { - SiteFile$begin_date <- as.Date(suppressWarnings(lubridate::parse_date_time( - SiteFile$begin_date, - c("Ymd", "mdY", "Y!") - ))) - SiteFile$end_date <- as.Date(suppressWarnings(lubridate::parse_date_time( - SiteFile$end_date, - c("Ymd", "mdY", "Y!") - ))) - } + urlSitefile <- httr2::request(pkg.env[["site"]]) + urlSitefile <- get_or_post( + urlSitefile, + POST = POST, + seriesCatalogOutput = "true" + ) + urlSitefile <- get_or_post( + urlSitefile, + POST = POST, + !!!values, + .multi = "comma" + ) + + SiteFile <- importRDB1( + urlSitefile, + asDateTime = FALSE, + convertType = convertType + ) + + if (!("all" %in% service)) { + SiteFile <- SiteFile[SiteFile$data_type_cd %in% service, ] + } + if (!("all" %in% statCd)) { + SiteFile <- SiteFile[SiteFile$stat_cd %in% c(statCd, NA), ] + } + if (!("all" %in% parameterCd)) { + SiteFile <- SiteFile[SiteFile$parm_cd %in% parameterCd, ] + } - if (any(SiteFile$data_type_cd == "qw")) { - if (!prewarned) { - message(nwis_message()) + if (nrow(SiteFile) > 0 && convertType) { + SiteFile$begin_date <- as.Date(suppressWarnings(lubridate::parse_date_time( + SiteFile$begin_date, + c("Ymd", "mdY", "Y!") + ))) + SiteFile$end_date <- as.Date(suppressWarnings(lubridate::parse_date_time( + SiteFile$end_date, + c("Ymd", "mdY", "Y!") + ))) } + + return(SiteFile) + } else { + stop( + "NWIS servers will be taken offline February 22nd, 2027. Update whatNWISdata to read_waterdata_combined_meta +Use override_error = TRUE to temporarily override this error. For more information: +https://doi-usgs.github.io/dataRetrieval/articles/read_waterdata_functions.html" + ) } - return(SiteFile) } diff --git a/R/whatNWISsites.R b/R/whatNWISsites.R index 937b2d3ef..96dc295a0 100644 --- a/R/whatNWISsites.R +++ b/R/whatNWISsites.R @@ -6,7 +6,10 @@ #' #' @param \dots see #' for a complete list of options. A list (or lists) can also be supplied. -#' +#' @param override_error Logical parameter that allows users to run this +#' function during the final stages of NWIS decommission. NWIS servers will be taken +#' offline February 22nd, 2027. Setting this parameter to `TRUE` should only +#' be used as a tool to convert readNWIS to read_waterdata functions. #' @return A data frame with at least the following columns: #' \tabular{lll}{ #' Name \tab Type \tab Description \cr @@ -34,101 +37,107 @@ #' #siteListPhos <- whatNWISsites(stateCd = "OH", parameterCd = "00665") #' #oneSite <- whatNWISsites(sites = "05114000") #' -whatNWISsites <- function(...) { - .Deprecated( - new = "read_waterdata_monitoring_location", - package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_monitoring_location" - ) - - matchReturn <- convertLists(...) - if ("service" %in% names(matchReturn)) { - service <- matchReturn$service - matchReturn$service <- NULL - } else { - service <- NULL - } +whatNWISsites <- function(..., override_error = FALSE) { + if (override_error) { + warning( + "NWIS servers will be taken offline February 22nd, 2027. Update whatNWISsites to read_waterdata_monitoring_location" + ) - valuesList <- readNWISdots(matchReturn) + matchReturn <- convertLists(...) + if ("service" %in% names(matchReturn)) { + service <- matchReturn$service + matchReturn$service <- NULL + } else { + service <- NULL + } - values <- valuesList[["values"]] - values <- values[names(values) != "format"] + valuesList <- readNWISdots(matchReturn) - ################# - # temporary gwlevels fixes - values <- values[ - !names(values) %in% - c( - "date_format", - "TZoutput", - "rdb_inventory_output", - "list_of_search_criteria" - ) - ] + values <- valuesList[["values"]] + values <- values[names(values) != "format"] - names(values)[names(values) == "state_cd"] <- "stateCd" - ################## + ################# + # temporary gwlevels fixes + values <- values[ + !names(values) %in% + c( + "date_format", + "TZoutput", + "rdb_inventory_output", + "list_of_search_criteria" + ) + ] - if (!is.null(service)) { - service[service == "peak"] <- "pk" - service[service == "uv"] <- "id" + names(values)[names(values) == "state_cd"] <- "stateCd" + ################## - values[["hasDataTypeCd"]] <- service - } + if (!is.null(service)) { + service[service == "peak"] <- "pk" + service[service == "uv"] <- "id" - POST <- nchar(paste0(unlist(values), collapse = "")) > 2048 + values[["hasDataTypeCd"]] <- service + } - urlCall <- httr2::request(pkg.env[["site"]]) + POST <- nchar(paste0(unlist(values), collapse = "")) > 2048 - urlCall <- get_or_post(urlCall, POST = POST, !!!values, .multi = "comma") + urlCall <- httr2::request(pkg.env[["site"]]) - urlCall <- get_or_post(urlCall, POST = POST, format = "mapper") + urlCall <- get_or_post(urlCall, POST = POST, !!!values, .multi = "comma") - rawData <- getWebServiceData(urlCall) - if (is.null(rawData)) { - return(invisible(NULL)) - } - doc <- xml2::xml_root(rawData) - siteCategories <- xml2::xml_children(doc) - retVal <- NULL - for (sc in siteCategories) { - sites <- xml2::xml_children(sc) - site_no <- xml2::xml_attr(sites, "sno") - station_nm <- xml2::xml_attr(sites, "sna") - site_tp_cd <- xml2::xml_attr(sites, "cat") - dec_lat_va <- as.numeric(xml2::xml_attr(sites, "lat")) - dec_long_va <- as.numeric(xml2::xml_attr(sites, "lng")) - agency_cd <- xml2::xml_attr(sites, "agc") - - colocated <- isTRUE(xml2::xml_name(sc) == "colocated_sites") - - df <- data.frame( - agency_cd, - site_no, - station_nm, - site_tp_cd, - dec_lat_va, - dec_long_va, - colocated, - stringsAsFactors = FALSE - ) + urlCall <- get_or_post(urlCall, POST = POST, format = "mapper") - if (is.null(retVal)) { - retVal <- df - } else { - retVal <- r_bind_dr(retVal, df) + rawData <- getWebServiceData(urlCall) + if (is.null(rawData)) { + return(invisible(NULL)) } - } + doc <- xml2::xml_root(rawData) + siteCategories <- xml2::xml_children(doc) + retVal <- NULL + for (sc in siteCategories) { + sites <- xml2::xml_children(sc) + site_no <- xml2::xml_attr(sites, "sno") + station_nm <- xml2::xml_attr(sites, "sna") + site_tp_cd <- xml2::xml_attr(sites, "cat") + dec_lat_va <- as.numeric(xml2::xml_attr(sites, "lat")) + dec_long_va <- as.numeric(xml2::xml_attr(sites, "lng")) + agency_cd <- xml2::xml_attr(sites, "agc") + + colocated <- isTRUE(xml2::xml_name(sc) == "colocated_sites") + + df <- data.frame( + agency_cd, + site_no, + station_nm, + site_tp_cd, + dec_lat_va, + dec_long_va, + colocated, + stringsAsFactors = FALSE + ) - retVal <- retVal[!duplicated(retVal), ] + if (is.null(retVal)) { + retVal <- df + } else { + retVal <- r_bind_dr(retVal, df) + } + } - attr(retVal, "url") <- urlCall$url + retVal <- retVal[!duplicated(retVal), ] - timenow <- Sys.time() + attr(retVal, "url") <- urlCall$url - attr(retVal, "queryTime") <- timenow - # Backwards compatible, might remove later: - retVal$queryTime <- timenow + timenow <- Sys.time() - return(retVal) + attr(retVal, "queryTime") <- timenow + # Backwards compatible, might remove later: + retVal$queryTime <- timenow + + return(retVal) + } else { + stop( + "NWIS servers will be taken offline February 22nd, 2027. Update whatNWISsites to read_waterdata_monitoring_location. +Use override_error = TRUE to temporarily override this error. For more information: +https://doi-usgs.github.io/dataRetrieval/articles/read_waterdata_functions.html" + ) + } } diff --git a/README.Rmd b/README.Rmd index 747fdd573..07331a043 100644 --- a/README.Rmd +++ b/README.Rmd @@ -31,7 +31,20 @@ The `dataRetrieval` package was created to simplify the process of loading hydro # Introduction -:warning: NWIS web services (readNWIS functions) will be replaced over time by USGS Water Data APIs (read_waterdata_). Read more about it here: +:warning: ALL NWIS web services (readNWIS functions) will be retired Feb. 22, 2027. Replace all readNWIS functions with read_waterdata functions as soon as possible. + +WaterServices (web services behind the "readNWIS" functions) will be taken offline February 22nd, 2027. Ahead of that date, we'll be intentionally adding "waits" into requests to the legacy APIs, and will have two intentional outages on January 27th and February 16th. + +The full decommissioning schedule for WaterServices can be found here: +[Intentional degradations to WaterServices ahead of final decommissioning](https://waterdata.usgs.gov/blog/wdfn-waterservices-degradation/) + +Intentional degradations to WaterServices ahead of final decommissioning + +Users will need to migrate to services hosted at [USGS Water Data APIs](https://api.waterdata.usgs.gov/) before this date. Note that any users who may be accessing this data from internal-only URLs, or directly from the legacy servers, will also be impacted; we will be removing the underpinning databases and decommissioning hardware. + +In order to alert automated users of WaterServices, we will intentionally slow down requests and perform two scheduled outages before permanently decommissioning the services in February 2027. + +Read more about the new Water Data dataRetrieval functions here: :warning: USGS discrete water-quality data availability and format are changing. To view the status of changes in data availability and code functionality, visit: diff --git a/README.md b/README.md index 63c6ff255..5d5ac86d4 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,32 @@ Environmental Protection Agency (EPA), U.S. Department of Agriculture # Introduction -:warning: NWIS web services (readNWIS functions) will be replaced over -time by USGS Water Data APIs (read_waterdata\_). Read more about it -here: +:warning: ALL NWIS web services (readNWIS functions) will be retired +Feb. 22, 2027. Replace all readNWIS functions with read_waterdata +functions as soon as possible. + +WaterServices (web services behind the “readNWIS” functions) will be +taken offline February 22nd, 2027. Ahead of that date, we’ll be +intentionally adding “waits” into requests to the legacy APIs, and will +have two intentional outages on January 27th and February 16th. + +The full decommissioning schedule for WaterServices can be found here: +[Intentional degradations to WaterServices ahead of final +decommissioning](https://waterdata.usgs.gov/blog/wdfn-waterservices-degradation/) + +Intentional degradations to WaterServices ahead of final decommissioning + +Users will need to migrate to services hosted at [USGS Water Data +APIs](https://api.waterdata.usgs.gov/) before this date. Note that any +users who may be accessing this data from internal-only URLs, or +directly from the legacy servers, will also be impacted; we will be +removing the underpinning databases and decommissioning hardware. + +In order to alert automated users of WaterServices, we will +intentionally slow down requests and perform two scheduled outages +before permanently decommissioning the services in February 2027. + +Read more about the new Water Data dataRetrieval functions here: :warning: USGS discrete water-quality data availability and format are @@ -209,14 +232,14 @@ WQPcitation <- create_WQP_bib(SC) WQPcitation #> National Water Quality Monitoring Council (2026). _Water Quality #> Portal_. doi:10.5066/P9QRKUVJ . -#> Accessed Oct 01, 2026, +#> Accessed Oct 06, 2026, #> . print(WQPcitation, style = "Bibtex") #> @Manual{, #> title = {Water Quality Portal}, #> author = {{National Water Quality Monitoring Council}}, #> doi = {10.5066/P9QRKUVJ}, -#> note = {Accessed Oct 01, 2026}, +#> note = {Accessed Oct 06, 2026}, #> year = {2026}, #> 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 d40aaa82a..1a58b4ca1 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -96,8 +96,8 @@ reference: - summarize_waterdata_samples - check_waterdata_sample_params - get_monitoring_location_arguments - - title: National Water Information System (NWIS) - desc: Functions to retrieve (USGS) NWIS data. These will be slowly phased out and replaced with the read_waterdata family of functions. + - title: RETIRED FUNCTIONS - Discontinue Using! + desc: USGS WaterServices will be taken offline February 22nd, 2027. These functions will be removed after that date: contents: - readNWISdv - readNWISuv @@ -106,10 +106,12 @@ reference: - readNWISpCode - readNWISrating - readNWISpeak - - readNWISuse - readNWISdata - whatNWISsites - whatNWISdata + - create_NWIS_bib + - constructNWISURL + - renameNWISColumns - title: Water Quality Portal (WQP) desc: Functions to retrieve WQP data. contents: @@ -145,11 +147,9 @@ reference: - importWQP - title: Helper functions contents: - - create_NWIS_bib - create_WQP_bib - calcWaterYear - addWaterYear - - renameNWISColumns - setAccess - countyCdLookup - stateCdLookup @@ -163,7 +163,6 @@ reference: - title: Web query utilities desc: Functions to create web queries contents: - - constructNWISURL - constructWQPURL - getQuerySummary - getWebServiceData diff --git a/inst/CITATION b/inst/CITATION index 4348352ee..b331b039c 100644 --- a/inst/CITATION +++ b/inst/CITATION @@ -34,12 +34,12 @@ bibentry(bibtype = "Manual", email = "mjmahoney@usgs.gov", comment=c(ORCID = "0000-0003-2402-304X")) ), - title = "dataRetrieval: R packages for discovering and retrieving water data available from U.S. federal hydrologic web services", + title = "dataRetrieval: R packages for discovering and retrieving water data available from Federal hydrologic web services", publisher = "U.S. Geological Survey", address="Reston, VA", - version = "2.7.26", + version = "2.7.27", institution = "U.S. Geological Survey", year = 2026, doi = "10.5066/P9X4L3GE", - textVersion = "De Cicco, L.A., Hirsch, R.M., Lorenz, D., Watkins, W.D., Johnson, M., Blodgett, D.L., Hinman, E.D., Zemmels, J., 2026, dataRetrieval: R packages for discovering and retrieving water data available from Federal hydrologic web services, v.2.7.26, doi:10.5066/P9X4L3GE" + textVersion = "De Cicco, L.A., Hirsch, R.M., Lorenz, D., Watkins, W.D., Johnson, M., Blodgett, D.L., Hinman, E.D., Zemmels, J., 2026, dataRetrieval: R packages for discovering and retrieving water data available from Federal hydrologic web services, v.2.7.27, doi:10.5066/P9X4L3GE" ) diff --git a/man/get_monitoring_location_arguments.Rd b/man/get_monitoring_location_arguments.Rd index 57a146af7..cca635018 100644 --- a/man/get_monitoring_location_arguments.Rd +++ b/man/get_monitoring_location_arguments.Rd @@ -55,7 +55,7 @@ get_monitoring_location_arguments( "daily", "latest-continuous", "field-measurements", "latest-daily", "latest-field-measurements", "continuous", "peaks".} -\item{agency_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items}.} +\item{agency_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/agency-codes/items}.} \item{agency_name}{The name of the agency that is reporting the data.} @@ -73,15 +73,15 @@ get_monitoring_location_arguments( \item{state_name}{The name of the state or state equivalent in which the monitoring location is located.} -\item{county_code}{The code for the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items}.} +\item{county_code}{The code for the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/counties/items}.} -\item{county_name}{The name of the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. [A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items}.} +\item{county_name}{The name of the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. [A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/counties/items}.} \item{minor_civil_division_code}{Codes for primary governmental or administrative divisions of the county or county equivalent in which the monitoring location is located.} -\item{site_type_code}{A code describing the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items}.} +\item{site_type_code}{A code describing the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/site-types/items}.} -\item{site_type}{A description of the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items}.} +\item{site_type}{A description of the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/site-types/items}.} \item{hydrologic_unit_code}{The hydrologic unit code (HUC) for the monitoring location. Supports prefix matching — querying with a shorter HUC (e.g. "04") matches all locations within that hydrologic region.} @@ -95,21 +95,21 @@ get_monitoring_location_arguments( \item{altitude_method_name}{The name of the method used to measure altitude.} -\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items}.} +\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/altitude-datums/items}.} -\item{vertical_datum_name}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items}.} +\item{vertical_datum_name}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/altitude-datums/items}.} -\item{horizontal_positional_accuracy_code}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items}.} +\item{horizontal_positional_accuracy_code}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-accuracy-codes/items}.} -\item{horizontal_positional_accuracy}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items}.} +\item{horizontal_positional_accuracy}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/agency-codes/items}.} -\item{horizontal_position_method_code}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items}.} +\item{horizontal_position_method_code}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-method-codes/items}.} -\item{horizontal_position_method_name}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items}.} +\item{horizontal_position_method_name}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-method-codes/items}.} -\item{original_horizontal_datum}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items}.} +\item{original_horizontal_datum}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-datum-codes/items}.} -\item{original_horizontal_datum_name}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items}.} +\item{original_horizontal_datum_name}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-datum-codes/items}.} \item{drainage_area}{The area enclosed by a topographic divide from which direct surface runoff from precipitation normally drains by gravity into the stream above that point.} @@ -117,15 +117,15 @@ get_monitoring_location_arguments( \item{time_zone_abbreviation}{A short code describing the time zone used by a monitoring location.} -\item{uses_daylight_savings}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items}.} +\item{uses_daylight_savings}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/agency-codes/items}.} \item{construction_date}{Date the well was completed.} \item{aquifer_code}{Local aquifers in the USGS water resources data base are identified by a geohydrologic unit code (a three-digit number related to the age of the formation, followed by a 4 or 5 character abbreviation for the geologic unit or aquifer name).} -\item{national_aquifer_code}{National aquifers are the principal aquifers or aquifer systems in the United States, defined as regionally extensive aquifers or aquifer systems that have the potential to be used as a source of potable water. Not all groundwater monitoring locations can be associated with a National Aquifer. Such monitoring locations will not be retrieved using this search criteria. A list of National aquifer codes and names is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/national-aquifer-codes/items}.} +\item{national_aquifer_code}{National aquifers are the principal aquifers or aquifer systems in the United States, defined as regionally extensive aquifers or aquifer systems that have the potential to be used as a source of potable water. Not all groundwater monitoring locations can be associated with a National Aquifer. Such monitoring locations will not be retrieved using this search criteria. A list of National aquifer codes and names is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/national-aquifer-codes/items}.} -\item{aquifer_type_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items}.} +\item{aquifer_type_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/agency-codes/items}.} \item{well_constructed_depth}{The depth of the finished well, in feet below land surface datum. Note: Not all groundwater monitoring locations have information on Well Depth. Such monitoring locations will not be retrieved using this search criteria.} diff --git a/man/readNWISdv.Rd b/man/readNWISdv.Rd index bd131c909..1c0e49112 100644 --- a/man/readNWISdv.Rd +++ b/man/readNWISdv.Rd @@ -9,7 +9,8 @@ readNWISdv( parameterCd, startDate = "", endDate = "", - statCd = "00003" + statCd = "00003", + override_error = FALSE ) } \arguments{ @@ -26,6 +27,11 @@ retrieval for the earliest possible record. Date arguments are always specified retrieval for the latest possible record. Date arguments are always specified in local time.} \item{statCd}{character USGS statistic code. This is usually 5 digits. Daily mean (00003) is the default.} + +\item{override_error}{Logical parameter that allows users to run this +function during the final stages of NWIS decommission. NWIS servers will be taken +offline February 22nd, 2027. Setting this parameter to \code{TRUE} should only +be used as a tool to convert readNWIS to read_waterdata functions.} } \value{ A data frame with the following columns: @@ -69,24 +75,7 @@ returned from \code{\link[=whatNWISdata]{whatNWISdata()}}) are available from th More information on the web service can be found here: \url{https://waterservices.usgs.gov/test-tools}, choosing the "Daily Value Service". -} -\examples{ - -# see ?read_waterdata_daily - -#site_id <- "04085427" -#startDate <- "2012-01-01" -#endDate <- "2012-06-30" -#pCode <- "00060" -# -#rawDailyQ <- readNWISdv(site_id, pCode, startDate, endDate) - } \seealso{ \code{\link[=read_waterdata_daily]{read_waterdata_daily()}} } -\keyword{USGS} -\keyword{data} -\keyword{import} -\keyword{service} -\keyword{web} diff --git a/man/readNWISpCode.Rd b/man/readNWISpCode.Rd index 604d27cfb..010894784 100644 --- a/man/readNWISpCode.Rd +++ b/man/readNWISpCode.Rd @@ -4,12 +4,17 @@ \alias{readNWISpCode} \title{USGS Parameter Data Retrieval} \usage{ -readNWISpCode(parameterCd) +readNWISpCode(parameterCd, override_error = FALSE) } \arguments{ \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.} + +\item{override_error}{Logical parameter that allows users to run this +function during the final stages of NWIS decommission. NWIS servers will be taken +offline February 22nd, 2027. Setting this parameter to \code{TRUE} should only +be used as a tool to convert readNWIS to read_waterdata functions.} } \value{ parameterData data frame with the following information: diff --git a/man/readNWISpeak.Rd b/man/readNWISpeak.Rd index c07c8a96a..85e5c92de 100644 --- a/man/readNWISpeak.Rd +++ b/man/readNWISpeak.Rd @@ -9,7 +9,8 @@ readNWISpeak( startDate = "", endDate = "", asDateTime = TRUE, - convertType = TRUE + convertType = TRUE, + override_error = FALSE ) } \arguments{ @@ -31,6 +32,11 @@ columns are removed, but no dates are converted.} \item{convertType}{logical, defaults to \code{TRUE}. If \code{TRUE}, the function will convert the data to dates, datetimes, numerics based on a standard algorithm. If false, everything is returned as a character} + +\item{override_error}{Logical parameter that allows users to run this +function during the final stages of NWIS decommission. NWIS servers will be taken +offline February 22nd, 2027. Setting this parameter to \code{TRUE} should only +be used as a tool to convert readNWIS to read_waterdata functions.} } \value{ A data frame with the following columns: diff --git a/man/readNWISrating.Rd b/man/readNWISrating.Rd index cf520780a..eac6352c8 100644 --- a/man/readNWISrating.Rd +++ b/man/readNWISrating.Rd @@ -4,7 +4,12 @@ \alias{readNWISrating} \title{Rating table for an active USGS streamgage retrieval} \usage{ -readNWISrating(siteNumber, type = "base", convertType = TRUE) +readNWISrating( + siteNumber, + type = "base", + convertType = TRUE, + override_error = FALSE +) } \arguments{ \item{siteNumber}{character USGS site number. This is usually an 8 digit number} @@ -14,6 +19,11 @@ readNWISrating(siteNumber, type = "base", convertType = TRUE) \item{convertType}{logical, defaults to \code{TRUE}. If \code{TRUE}, the function will convert the data to dates, datetimes, numerics based on a standard algorithm. If false, everything is returned as a character} + +\item{override_error}{Logical parameter that allows users to run this +function during the final stages of NWIS decommission. NWIS servers will be taken +offline February 22nd, 2027. Setting this parameter to \code{TRUE} should only +be used as a tool to convert readNWIS to read_waterdata functions.} } \value{ A data frame. If \code{type} is "base, " then the columns are diff --git a/man/readNWISsite.Rd b/man/readNWISsite.Rd index 4447faab1..ed3cc84be 100644 --- a/man/readNWISsite.Rd +++ b/man/readNWISsite.Rd @@ -4,10 +4,15 @@ \alias{readNWISsite} \title{USGS Site File Data Retrieval} \usage{ -readNWISsite(siteNumbers) +readNWISsite(siteNumbers, override_error = FALSE) } \arguments{ \item{siteNumbers}{character USGS site number (or multiple sites). This is usually an 8 digit number} + +\item{override_error}{Logical parameter that allows users to run this +function during the final stages of NWIS decommission. NWIS servers will be taken +offline February 22nd, 2027. Setting this parameter to \code{TRUE} should only +be used as a tool to convert readNWIS to read_waterdata functions.} } \value{ A data frame with at least the following columns: diff --git a/man/readNWISstat.Rd b/man/readNWISstat.Rd index ab394f0a0..eea30c657 100644 --- a/man/readNWISstat.Rd +++ b/man/readNWISstat.Rd @@ -11,7 +11,8 @@ readNWISstat( endDate = "", convertType = TRUE, statReportType = "daily", - statType = "mean" + statType = "mean", + override_error = FALSE ) } \arguments{ @@ -44,6 +45,11 @@ provide statistics for each month and year within the range indivually.} \item{statType}{character type(s) of statistics to output for daily values. Default is mean, which is the only option for monthly and yearly report types.} + +\item{override_error}{Logical parameter that allows users to run this +function during the final stages of NWIS decommission. NWIS servers will be taken +offline February 22nd, 2027. Setting this parameter to \code{TRUE} should only +be used as a tool to convert readNWIS to read_waterdata functions.} } \value{ A data frame with the following columns: diff --git a/man/readNWISuse.Rd b/man/readNWISuse.Rd deleted file mode 100644 index 5072d3977..000000000 --- a/man/readNWISuse.Rd +++ /dev/null @@ -1,53 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/readNWISunit.R -\name{readNWISuse} -\alias{readNWISuse} -\title{Water use data retrieval from USGS (NWIS)} -\usage{ -readNWISuse( - stateCd, - countyCd, - years = "ALL", - categories = "ALL", - convertType = TRUE, - transform = FALSE -) -} -\arguments{ -\item{stateCd}{could be character (full name, abbreviation, id), or numeric (id). -Only one is accepted per query.} - -\item{countyCd}{could be character (name, with or without "County", or "ALL"), -numeric (id), or \code{NULL}, which will -return state or national data depending on the stateCd argument. "ALL" may -also be supplied, which will return data -for every county in a state. Can be a vector of counties in the same state.} - -\item{years}{integer Years for data retrieval. Must be years ending in 0 or 5. -Default is all available years.} - -\item{categories}{character categories of water use. Defaults to "ALL". -Specific categories must be supplied as two- -letter abbreviations as seen in the URL when using the NWIS water use web interface. Note that -there are different codes for national and state level data.} - -\item{convertType}{logical defaults to \code{TRUE}. If \code{TRUE}, the function -will convert the data to -numerics based on a standard algorithm. Years, months, and days (if appliccable) are -also returned as numerics -in separate columns. If convertType is false, everything is returned as a character.} - -\item{transform}{logical only intended for use with national data. Defaults to -\code{FALSE}, with data being returned as -presented by the web service. If \code{TRUE}, data will be transformed and -returned with column names, which will reformat -national data to be similar to state data.} -} -\value{ -A data frame with at least the year of record, and all available -statistics for the given geographic parameters. -County and state fields will be included as appropriate. -} -\description{ -Retrieves water use data from USGS Water Use Data for the Nation. -} diff --git a/man/readNWISuv.Rd b/man/readNWISuv.Rd index 2878063f3..976b785ab 100644 --- a/man/readNWISuv.Rd +++ b/man/readNWISuv.Rd @@ -4,7 +4,14 @@ \alias{readNWISuv} \title{Instantaneous value data retrieval from USGS (NWIS)} \usage{ -readNWISuv(siteNumbers, parameterCd, startDate = "", endDate = "", tz = "UTC") +readNWISuv( + siteNumbers, + parameterCd, + startDate = "", + endDate = "", + tz = "UTC", + override_error = FALSE +) } \arguments{ \item{siteNumbers}{character USGS site number (or multiple sites). This is usually an 8 digit number} @@ -23,6 +30,11 @@ Possible values to provide are "America/New_York", "America/Chicago", "America/D "America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also \code{OlsonNames()} for more information on time zones.} + +\item{override_error}{Logical parameter that allows users to run this +function during the final stages of NWIS decommission. NWIS servers will be taken +offline February 22nd, 2027. Setting this parameter to \code{TRUE} should only +be used as a tool to convert readNWIS to read_waterdata functions.} } \value{ A data frame with the following columns: diff --git a/man/whatNWISdata.Rd b/man/whatNWISdata.Rd index fcc94de58..43f01be13 100644 --- a/man/whatNWISdata.Rd +++ b/man/whatNWISdata.Rd @@ -4,7 +4,7 @@ \alias{whatNWISdata} \title{USGS data availability} \usage{ -whatNWISdata(..., convertType = TRUE) +whatNWISdata(..., convertType = TRUE, override_error = FALSE) } \arguments{ \item{\dots}{see \url{https://waterservices.usgs.gov/docs/site-service/} @@ -13,6 +13,11 @@ for a complete list of options. A list of arguments can also be supplied.} \item{convertType}{logical, defaults to \code{TRUE}. If \code{TRUE}, the function will convert the data to dates, datetimes, numerics based on a standard algorithm. If false, everything is returned as a character} + +\item{override_error}{Logical parameter that allows users to run this +function during the final stages of NWIS decommission. NWIS servers will be taken +offline February 22nd, 2027. Setting this parameter to \code{TRUE} should only +be used as a tool to convert readNWIS to read_waterdata functions.} } \value{ A data frame with the following columns: @@ -71,24 +76,9 @@ flexibility to the possible queries. If the "service" argument is included, the results will be filtered to the proper data_type_cd. This is a great function to use before a large data set, by filtering down the number of sites that have useful data. -} -\examples{ - -# see ?read_waterdata_ts_meta - -#site1 <- whatWQPsamples(siteid = "USGS-01594440") - -#type <- "Stream" - -#sites <- whatWQPsamples(countycode = "US:55:025", siteType = type) - -#lakeSites_samples <- whatWQPsamples(siteType = "Lake, Reservoir, Impoundment", -# countycode = "US:55:025") - - } \seealso{ -\code{\link[=read_waterdata_ts_meta]{read_waterdata_ts_meta()}} +\code{\link[=read_waterdata_combined_meta]{read_waterdata_combined_meta()}} } \keyword{USGS} \keyword{data} diff --git a/man/whatNWISsites.Rd b/man/whatNWISsites.Rd index b4310020f..6a972b9d5 100644 --- a/man/whatNWISsites.Rd +++ b/man/whatNWISsites.Rd @@ -4,11 +4,16 @@ \alias{whatNWISsites} \title{Site Data Import from NWIS} \usage{ -whatNWISsites(...) +whatNWISsites(..., override_error = FALSE) } \arguments{ \item{\dots}{see \url{https://waterservices.usgs.gov/docs/site-service/} for a complete list of options. A list (or lists) can also be supplied.} + +\item{override_error}{Logical parameter that allows users to run this +function during the final stages of NWIS decommission. NWIS servers will be taken +offline February 22nd, 2027. Setting this parameter to \code{TRUE} should only +be used as a tool to convert readNWIS to read_waterdata functions.} } \value{ A data frame with at least the following columns: diff --git a/tests/testthat/tests_general.R b/tests/testthat/tests_general.R index f1ca15ae3..4dbdea899 100644 --- a/tests/testthat/tests_general.R +++ b/tests/testthat/tests_general.R @@ -76,9 +76,6 @@ test_that("General NWIS retrievals working", { expect_is(multiSite$time, "POSIXct") - expect_error(readNWISdata(), "No arguments supplied") - expect_error(readNWISdata(siteNumber = NA), "NA's are not allowed in query") - bBox_inventory <- read_waterdata_ts_meta( bbox = c(-83, 38, -82.5, 38.5), parameter_code = "00010" @@ -182,18 +179,6 @@ test_that("General NWIS retrievals working", { time = c("2015-06-18", "2015-06-18") ) expect_equal(4, length(unique(multi_huc$monitoring_location_id))) - - peak_data <- readNWISdata( - service = "peak", - state_cd = "PA" - ) - expect_lt(nrow(peak_data), 100000) - - peak_data <- readNWISdata( - service = "peak", - huc2_cd = "20" - ) - expect_lt(nrow(peak_data), 100000) }) test_that("read_waterdata_ts_meta", { From 3bce094339b85564b29fe1b17b2b6ee30a57fcd0 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 6 Oct 2026 13:12:10 -0500 Subject: [PATCH 02/16] v1 link updates --- man/read_waterdata_field_measurements.Rd | 6 ++-- man/read_waterdata_field_meta.Rd | 4 +-- man/read_waterdata_latest_continuous.Rd | 2 +- man/read_waterdata_latest_daily.Rd | 4 +-- ...ead_waterdata_latest_field_measurements.Rd | 4 +-- man/read_waterdata_monitoring_location.Rd | 28 +++++++++---------- man/read_waterdata_peaks.Rd | 2 +- man/read_waterdata_ts_meta.Rd | 6 ++-- 8 files changed, 28 insertions(+), 28 deletions(-) diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index 707d73b24..786fa7faa 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -37,7 +37,7 @@ read_waterdata_field_measurements( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} @@ -45,7 +45,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, field_measurements_series_id, reading_type, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified, control_condition, measurement_rated, year, month, day, time_of_day. +geometry, field_measurements_series_id, reading_type, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified, control_condition, measurement_rated, year, month, day, time_of_day, sublocation_identifier. The default (\code{NA}) will return all columns of the data.} \item{field_visit_id}{A universally unique identifier (UUID) for the field visit. Multiple measurements may be made during a single field visit.} @@ -80,7 +80,7 @@ See also Details below for more information.} \item{observing_procedure}{Water measurement or water-quality observing procedure descriptions.} -\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items}.} +\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/altitude-datums/items}.} \item{measuring_agency}{The agency performing the measurement.} diff --git a/man/read_waterdata_field_meta.Rd b/man/read_waterdata_field_meta.Rd index 9047ae656..161ef6ee4 100644 --- a/man/read_waterdata_field_meta.Rd +++ b/man/read_waterdata_field_meta.Rd @@ -28,7 +28,7 @@ read_waterdata_field_meta( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} @@ -83,7 +83,7 @@ See also Details below for more information.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, field_measurement_id, reading_type, monitoring_location_id, parameter_code, parameter_name, parameter_description, begin, end, last_modified. +geometry, field_measurement_id, reading_type, monitoring_location_id, parameter_code, parameter_name, parameter_description, begin, end, last_modified, sublocation_identifier. The default (\code{NA}) will return all columns of the data.} \item{skipGeometry}{This parameter can be used to skip response geometries for diff --git a/man/read_waterdata_latest_continuous.Rd b/man/read_waterdata_latest_continuous.Rd index 8921a917a..4851048d5 100644 --- a/man/read_waterdata_latest_continuous.Rd +++ b/man/read_waterdata_latest_continuous.Rd @@ -30,7 +30,7 @@ read_waterdata_latest_continuous( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} diff --git a/man/read_waterdata_latest_daily.Rd b/man/read_waterdata_latest_daily.Rd index 2ac341a0a..82dcfae11 100644 --- a/man/read_waterdata_latest_daily.Rd +++ b/man/read_waterdata_latest_daily.Rd @@ -31,11 +31,11 @@ read_waterdata_latest_daily( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} -\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/statistic-codes/items}. +\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/statistic-codes/items}. Multiple statistic_ids can be requested as a character vector.} diff --git a/man/read_waterdata_latest_field_measurements.Rd b/man/read_waterdata_latest_field_measurements.Rd index 1c541ad5e..cae620e6e 100644 --- a/man/read_waterdata_latest_field_measurements.Rd +++ b/man/read_waterdata_latest_field_measurements.Rd @@ -31,7 +31,7 @@ read_waterdata_latest_field_measurements( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} @@ -39,7 +39,7 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, field_measurements_series_id, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified, control_condition, measurement_rated, year, month, day, time_of_day. +geometry, field_measurements_series_id, field_visit_id, parameter_code, monitoring_location_id, observing_procedure_code, observing_procedure, value, unit_of_measure, time, qualifier, vertical_datum, approval_status, measuring_agency, last_modified, control_condition, measurement_rated, year, month, day, time_of_day, sublocation_identifier. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{Multiple time_series_ids can be requested as a character vector.} diff --git a/man/read_waterdata_monitoring_location.Rd b/man/read_waterdata_monitoring_location.Rd index 573cbaf1b..de18a8e00 100644 --- a/man/read_waterdata_monitoring_location.Rd +++ b/man/read_waterdata_monitoring_location.Rd @@ -65,7 +65,7 @@ read_waterdata_monitoring_location( Multiple monitoring_location_ids can be requested as a character vector.} -\item{agency_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items}.} +\item{agency_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/agency-codes/items}.} \item{agency_name}{The name of the agency that is reporting the data.} @@ -83,15 +83,15 @@ Multiple monitoring_location_ids can be requested as a character vector.} \item{state_name}{The name of the state or state equivalent in which the monitoring location is located.} -\item{county_code}{The code for the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items}.} +\item{county_code}{The code for the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/counties/items}.} -\item{county_name}{The name of the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. [A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items}.} +\item{county_name}{The name of the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. [A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/counties/items}.} \item{minor_civil_division_code}{Codes for primary governmental or administrative divisions of the county or county equivalent in which the monitoring location is located.} -\item{site_type_code}{A code describing the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items}.} +\item{site_type_code}{A code describing the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/site-types/items}.} -\item{site_type}{A description of the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items}.} +\item{site_type}{A description of the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/site-types/items}.} \item{hydrologic_unit_code}{The hydrologic unit code (HUC) for the monitoring location. Supports prefix matching — querying with a shorter HUC (e.g. "04") matches all locations within that hydrologic region.} @@ -105,21 +105,21 @@ Multiple monitoring_location_ids can be requested as a character vector.} \item{altitude_method_name}{The name of the method used to measure altitude.} -\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items}.} +\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/altitude-datums/items}.} -\item{vertical_datum_name}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items}.} +\item{vertical_datum_name}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/altitude-datums/items}.} -\item{horizontal_positional_accuracy_code}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items}.} +\item{horizontal_positional_accuracy_code}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-accuracy-codes/items}.} -\item{horizontal_positional_accuracy}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items}.} +\item{horizontal_positional_accuracy}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-accuracy-codes/items}.} -\item{horizontal_position_method_code}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items}.} +\item{horizontal_position_method_code}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-method-codes/items}.} -\item{horizontal_position_method_name}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items}.} +\item{horizontal_position_method_name}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-method-codes/items}.} -\item{original_horizontal_datum}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items}.} +\item{original_horizontal_datum}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-datum-codes/items}.} -\item{original_horizontal_datum_name}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items}.} +\item{original_horizontal_datum_name}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-datum-codes/items}.} \item{drainage_area}{The area enclosed by a topographic divide from which direct surface runoff from precipitation normally drains by gravity into the stream above that point.} @@ -133,7 +133,7 @@ Multiple monitoring_location_ids can be requested as a character vector.} \item{aquifer_code}{Local aquifers in the USGS water resources data base are identified by a geohydrologic unit code (a three-digit number related to the age of the formation, followed by a 4 or 5 character abbreviation for the geologic unit or aquifer name).} -\item{national_aquifer_code}{National aquifers are the principal aquifers or aquifer systems in the United States, defined as regionally extensive aquifers or aquifer systems that have the potential to be used as a source of potable water. Not all groundwater monitoring locations can be associated with a National Aquifer. Such monitoring locations will not be retrieved using this search criteria. A list of National aquifer codes and names is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/national-aquifer-codes/items}.} +\item{national_aquifer_code}{National aquifers are the principal aquifers or aquifer systems in the United States, defined as regionally extensive aquifers or aquifer systems that have the potential to be used as a source of potable water. Not all groundwater monitoring locations can be associated with a National Aquifer. Such monitoring locations will not be retrieved using this search criteria. A list of National aquifer codes and names is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/national-aquifer-codes/items}.} \item{aquifer_type_code}{Describes the confinement status of an aquifer at the monitoring location. A confined aquifer is an aquifer below the land surface that is saturated with water. A water table--or unconfined--aquifer is an aquifer whose upper water surface (water table) is at atmospheric pressure, and thus is able to rise and fall.} diff --git a/man/read_waterdata_peaks.Rd b/man/read_waterdata_peaks.Rd index 42b25d0e7..607c7cc66 100644 --- a/man/read_waterdata_peaks.Rd +++ b/man/read_waterdata_peaks.Rd @@ -36,7 +36,7 @@ read_waterdata_peaks( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} diff --git a/man/read_waterdata_ts_meta.Rd b/man/read_waterdata_ts_meta.Rd index 95300a17b..3cb7a81bd 100644 --- a/man/read_waterdata_ts_meta.Rd +++ b/man/read_waterdata_ts_meta.Rd @@ -41,7 +41,7 @@ read_waterdata_ts_meta( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} @@ -49,10 +49,10 @@ Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, time_series_id, unit_of_measure, parameter_name, parameter_code, statistic_id, last_modified, begin, end, computation_period_identifier, computation_identifier, thresholds, sublocation_identifier, primary, monitoring_location_id, web_description, parameter_description, parent_time_series_id, data_gap_interval. +geometry, time_series_id, unit_of_measure, parameter_name, parameter_code, statistic_id, last_modified, begin, end, computation_period_identifier, computation_identifier, thresholds, sublocation_identifier, primary, monitoring_location_id, web_description, parameter_description, parent_time_series_id, data_gap_interval, statistics_begin. The default (\code{NA}) will return all columns of the data.} -\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/statistic-codes/items}. +\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/statistic-codes/items}. Multiple statistic_ids can be requested as a character vector.} From 4273a73110d0b733084f495f580dd35a4c5ef51f Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 6 Oct 2026 13:12:56 -0500 Subject: [PATCH 03/16] more v1 --- man/read_waterdata_combined_meta.Rd | 32 ++++++++++++++--------------- man/read_waterdata_continuous.Rd | 4 ++-- man/read_waterdata_daily.Rd | 4 ++-- 3 files changed, 20 insertions(+), 20 deletions(-) diff --git a/man/read_waterdata_combined_meta.Rd b/man/read_waterdata_combined_meta.Rd index 8f3f01002..111613338 100644 --- a/man/read_waterdata_combined_meta.Rd +++ b/man/read_waterdata_combined_meta.Rd @@ -77,7 +77,7 @@ read_waterdata_combined_meta( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} @@ -86,7 +86,7 @@ Multiple parameter_names can be requested as a character vector.} \item{unit_of_measure}{A human-readable description of the units of measurement associated with an observation.} -\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/statistic-codes/items}. +\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/statistic-codes/items}. Multiple statistic_ids can be requested as a character vector.} @@ -157,7 +157,7 @@ Only features that have a \code{last_modified} that intersects the value of date See also Details below for more information.} -\item{agency_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items}.} +\item{agency_code}{The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/agency-codes/items}.} \item{agency_name}{The name of the agency that is reporting the data.} @@ -175,15 +175,15 @@ See also Details below for more information.} \item{state_name}{The name of the state or state equivalent in which the monitoring location is located.} -\item{county_code}{The code for the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items}.} +\item{county_code}{The code for the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/counties/items}.} -\item{county_name}{The name of the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. [A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items}.} +\item{county_name}{The name of the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. [A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/counties/items}.} \item{minor_civil_division_code}{Codes for primary governmental or administrative divisions of the county or county equivalent in which the monitoring location is located.} -\item{site_type_code}{A code describing the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items}.} +\item{site_type_code}{A code describing the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/site-types/items}.} -\item{site_type}{A description of the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items}.} +\item{site_type}{A description of the hydrologic setting of the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/site-types/items}.} \item{hydrologic_unit_code}{The hydrologic unit code (HUC) for the monitoring location. Supports prefix matching — querying with a shorter HUC (e.g. "04") matches all locations within that hydrologic region.} @@ -197,21 +197,21 @@ See also Details below for more information.} \item{altitude_method_name}{The name of the method used to measure altitude.} -\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items}.} +\item{vertical_datum}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/altitude-datums/items}.} -\item{vertical_datum_name}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items}.} +\item{vertical_datum_name}{The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/altitude-datums/items}.} -\item{horizontal_positional_accuracy_code}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items}.} +\item{horizontal_positional_accuracy_code}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-accuracy-codes/items}.} -\item{horizontal_positional_accuracy}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items}.} +\item{horizontal_positional_accuracy}{Indicates the accuracy of the latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-accuracy-codes/items}.} -\item{horizontal_position_method_code}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items}.} +\item{horizontal_position_method_code}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-method-codes/items}.} -\item{horizontal_position_method_name}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items}.} +\item{horizontal_position_method_name}{Indicates the method used to determine latitude longitude values. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-method-codes/items}.} -\item{original_horizontal_datum}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items}.} +\item{original_horizontal_datum}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-datum-codes/items}.} -\item{original_horizontal_datum_name}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items}.} +\item{original_horizontal_datum_name}{Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/coordinate-datum-codes/items}.} \item{drainage_area}{The area enclosed by a topographic divide from which direct surface runoff from precipitation normally drains by gravity into the stream above that point.} @@ -225,7 +225,7 @@ See also Details below for more information.} \item{aquifer_code}{Local aquifers in the USGS water resources data base are identified by a geohydrologic unit code (a three-digit number related to the age of the formation, followed by a 4 or 5 character abbreviation for the geologic unit or aquifer name).} -\item{national_aquifer_code}{National aquifers are the principal aquifers or aquifer systems in the United States, defined as regionally extensive aquifers or aquifer systems that have the potential to be used as a source of potable water. Not all groundwater monitoring locations can be associated with a National Aquifer. Such monitoring locations will not be retrieved using this search criteria. A list of National aquifer codes and names is available at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/national-aquifer-codes/items}.} +\item{national_aquifer_code}{National aquifers are the principal aquifers or aquifer systems in the United States, defined as regionally extensive aquifers or aquifer systems that have the potential to be used as a source of potable water. Not all groundwater monitoring locations can be associated with a National Aquifer. Such monitoring locations will not be retrieved using this search criteria. A list of National aquifer codes and names is available at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/national-aquifer-codes/items}.} \item{aquifer_type_code}{Describes the confinement status of an aquifer at the monitoring location. A confined aquifer is an aquifer below the land surface that is saturated with water. A water table--or unconfined--aquifer is an aquifer whose upper water surface (water table) is at atmospheric pressure, and thus is able to rise and fall.} diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index 53035a4d3..133032409 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -30,13 +30,13 @@ read_waterdata_continuous( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} \item{properties}{A vector of requested columns to be returned from the query. Available options are: -geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified. +geometry, time_series_id, monitoring_location_id, parameter_code, statistic_id, time, value, unit_of_measure, approval_status, qualifier, last_modified, method_category. The default (\code{NA}) will return all columns of the data.} \item{time_series_id}{A unique identifier representing a single time series. This corresponds to the \code{id} field in the \code{time-series-metadata} endpoint. diff --git a/man/read_waterdata_daily.Rd b/man/read_waterdata_daily.Rd index 4e982ca9c..d8dc445b5 100644 --- a/man/read_waterdata_daily.Rd +++ b/man/read_waterdata_daily.Rd @@ -31,11 +31,11 @@ read_waterdata_daily( Multiple monitoring_location_ids can be requested as a character vector.} -\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items}. +\item{parameter_code}{Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/parameter-codes/items}. Multiple parameter_codes can be requested as a character vector.} -\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v0/collections/statistic-codes/items}. +\item{statistic_id}{A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at \url{https://api.waterdata.usgs.gov/ogcapi/v1/collections/statistic-codes/items}. Multiple statistic_ids can be requested as a character vector.} From 768f2bb46c3032042d870e76b8dbb8d6bab1527d Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 6 Oct 2026 13:37:01 -0500 Subject: [PATCH 04/16] Add some arguments --- NEWS.md | 3 +++ R/read_waterdata_continuous.R | 2 ++ R/read_waterdata_field_measurements.R | 2 ++ R/read_waterdata_field_meta.R | 3 ++- R/renameColumns.R | 13 ------------- man/read_waterdata_continuous.Rd | 3 +++ man/read_waterdata_field_measurements.Rd | 3 +++ man/read_waterdata_field_meta.Rd | 9 ++++++--- man/renameNWISColumns.Rd | 14 -------------- 9 files changed, 21 insertions(+), 31 deletions(-) diff --git a/NEWS.md b/NEWS.md index 064b941ee..6f7e82b37 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,6 +1,9 @@ dataRetrieval 2.7.27 =================== * All NWIS functions will now error out by default. NWIS servers will be taken offline February 22nd, 2027. Use override_error = TRUE to temporarily override this error. +* Added sublocation_identifier parameter to read_waterdata_field_measurements and read_waterdata_field_meta. +* Added method_category parameter to read_waterdata_continuous. +* Updated Water Data API informational links to v1. dataRetrieval 2.7.26 =================== diff --git a/R/read_waterdata_continuous.R b/R/read_waterdata_continuous.R index def389673..cd4ea5c0d 100644 --- a/R/read_waterdata_continuous.R +++ b/R/read_waterdata_continuous.R @@ -27,6 +27,7 @@ #' @param time_series_id `r get_ogc_params("continuous")$time_series_id` #' Multiple time_series_ids can be requested as a character vector. #' @param qualifier `r get_ogc_params("continuous")$qualifier` +#' @param method_category `r get_ogc_params("continuous")$method_category` #' @param properties A vector of requested columns to be returned from the query. #' Available options are: #' `r dataRetrieval:::get_properties_for_docs("continuous", "continuous_id")`. @@ -129,6 +130,7 @@ read_waterdata_continuous <- function( value = NA, last_modified = NA_character_, time = NA_character_, + method_category = NA_character_, skipGeometry = TRUE, bbox = NA, ..., diff --git a/R/read_waterdata_field_measurements.R b/R/read_waterdata_field_measurements.R index 7bea3fc81..fc5ace5d4 100644 --- a/R/read_waterdata_field_measurements.R +++ b/R/read_waterdata_field_measurements.R @@ -25,6 +25,7 @@ #' `read_waterdata_field_meta` endpoint. Collection series are defined as the #' set of field measurements at a given monitoring location for a single parameter #' code using a single reading type. +#' @param sublocation_identifier `r get_ogc_params("field-measurements")$sublocation_identifier` #' #' @param vertical_datum `r get_ogc_params("field-measurements")$vertical_datum` #' @param measuring_agency `r get_ogc_params("field-measurements")$measuring_agency` @@ -111,6 +112,7 @@ read_waterdata_field_measurements <- function( measuring_agency = NA_character_, control_condition = NA_character_, measurement_rated = NA_character_, + sublocation_identifier = NA_character_, skipGeometry = NA, time = NA_character_, bbox = NA, diff --git a/R/read_waterdata_field_meta.R b/R/read_waterdata_field_meta.R index b499c5fbb..5ccc8fe24 100644 --- a/R/read_waterdata_field_meta.R +++ b/R/read_waterdata_field_meta.R @@ -18,7 +18,7 @@ #' #' See also Details below for more information. #' @param end `r get_ogc_params("field-measurements-metadata")$end` -#' +#' @param sublocation_identifier `r get_ogc_params("field-measurements-metadata")$sublocation_identifier` #' See also Details below for more information. #' @param properties A vector of requested columns to be returned from the query. #' Available options are: @@ -77,6 +77,7 @@ read_waterdata_field_meta <- function( end = NA_character_, last_modified = NA_character_, properties = NA_character_, + sublocation_identifier = NA_character_, skipGeometry = NA, bbox = NA, limit = NA, diff --git a/R/renameColumns.R b/R/renameColumns.R index 58439b988..a208064b3 100644 --- a/R/renameColumns.R +++ b/R/renameColumns.R @@ -37,19 +37,6 @@ #' @seealso [readNWISdv()], [readNWISuv()] #' @keywords manip IO #' @export -#' @examples -#' siteWithTwo <- "01480015" -#' startDate <- "2012-09-01" -#' endDate <- "2012-10-01" -#' \donttest{ -#' twoResults <- readNWISdv(siteWithTwo, "00060", startDate, endDate) -#' names(twoResults) -#' renamedCols <- renameNWISColumns(twoResults) -#' names(renamedCols) -#' # Custom names: -#' newNames <- renameNWISColumns(twoResults, p00060 = "Discharge") -#' names(newNames) -#' } renameNWISColumns <- function( rawData, p00010 = "Wtemp", diff --git a/man/read_waterdata_continuous.Rd b/man/read_waterdata_continuous.Rd index 133032409..37e8c46d0 100644 --- a/man/read_waterdata_continuous.Rd +++ b/man/read_waterdata_continuous.Rd @@ -15,6 +15,7 @@ read_waterdata_continuous( value = NA, last_modified = NA_character_, time = NA_character_, + method_category = NA_character_, skipGeometry = TRUE, bbox = NA, ..., @@ -78,6 +79,8 @@ Only features that have a \code{time} that intersects the value of datetime are See also Details below for more information.} +\item{method_category}{The RLMS method category code classifying the method in effect for this interval.} + \item{skipGeometry}{This parameter can be used to skip response geometries for each feature. The returning object will be a data frame with no spatial information. The default \code{NA} will not specify the argument in the request.} diff --git a/man/read_waterdata_field_measurements.Rd b/man/read_waterdata_field_measurements.Rd index 786fa7faa..a9c1021fe 100644 --- a/man/read_waterdata_field_measurements.Rd +++ b/man/read_waterdata_field_measurements.Rd @@ -21,6 +21,7 @@ read_waterdata_field_measurements( measuring_agency = NA_character_, control_condition = NA_character_, measurement_rated = NA_character_, + sublocation_identifier = NA_character_, skipGeometry = NA, time = NA_character_, bbox = NA, @@ -93,6 +94,8 @@ What and where the control of flow is for the gage pool.} Rated measurement based on the hydrologic/hydraulic conditions in which the measurement was made (excellent (2 percent), good (5 percent), fair (8 percent), or poor (more than 8 percent). percent)} +\item{sublocation_identifier}{An optional human-readable identifier used to specify where measurements are recorded at a monitoring location.} + \item{skipGeometry}{This parameter can be used to skip response geometries for each feature. The returning object will be a data frame with no spatial information. The default \code{NA} will not specify the argument in the request.} diff --git a/man/read_waterdata_field_meta.Rd b/man/read_waterdata_field_meta.Rd index 161ef6ee4..46b8069a5 100644 --- a/man/read_waterdata_field_meta.Rd +++ b/man/read_waterdata_field_meta.Rd @@ -13,6 +13,7 @@ read_waterdata_field_meta( end = NA_character_, last_modified = NA_character_, properties = NA_character_, + sublocation_identifier = NA_character_, skipGeometry = NA, bbox = NA, limit = NA, @@ -63,9 +64,7 @@ Examples: \item Duration objects: "P1M" for data from the past month or "PT36H" for the last 36 hours } -Only features that have a \code{end_utc} that intersects the value of datetime are selected. - -See also Details below for more information.} +Only features that have a \code{end_utc} that intersects the value of datetime are selected.} \item{last_modified}{The last time a record was refreshed in our database. This may happen due to regular operational processes and does not necessarily indicate anything about the measurement has changed. You can query this field using date-times or intervals, adhering to RFC 3339, or using ISO 8601 duration objects. Intervals may be bounded or half-bounded (double-dots at start or end). @@ -86,6 +85,10 @@ Available options are: geometry, field_measurement_id, reading_type, monitoring_location_id, parameter_code, parameter_name, parameter_description, begin, end, last_modified, sublocation_identifier. The default (\code{NA}) will return all columns of the data.} +\item{sublocation_identifier}{An optional human-readable identifier used to specify where measurements are recorded at a monitoring location. + +See also Details below for more information.} + \item{skipGeometry}{This parameter can be used to skip response geometries for each feature. The returning object will be a data frame with no spatial information. The default \code{NA} will not specify the argument in the request.} diff --git a/man/renameNWISColumns.Rd b/man/renameNWISColumns.Rd index 55244ecbb..c883b60e4 100644 --- a/man/renameNWISColumns.Rd +++ b/man/renameNWISColumns.Rd @@ -71,20 +71,6 @@ The following statistics codes are converted by \code{renameNWISColumns}. \item{00024}{Tidal low-low value, suffix: LoLoTide} } } -\examples{ -siteWithTwo <- "01480015" -startDate <- "2012-09-01" -endDate <- "2012-10-01" -\donttest{ -twoResults <- readNWISdv(siteWithTwo, "00060", startDate, endDate) -names(twoResults) -renamedCols <- renameNWISColumns(twoResults) -names(renamedCols) -# Custom names: -newNames <- renameNWISColumns(twoResults, p00060 = "Discharge") -names(newNames) -} -} \seealso{ \code{\link[=readNWISdv]{readNWISdv()}}, \code{\link[=readNWISuv]{readNWISuv()}} } From c31db8c28c0f854512a5afad6aaa486e6235609c Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 6 Oct 2026 13:51:37 -0500 Subject: [PATCH 05/16] yaml was funky --- _pkgdown.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_pkgdown.yml b/_pkgdown.yml index 1a58b4ca1..f6fe8cc04 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -97,7 +97,7 @@ reference: - check_waterdata_sample_params - get_monitoring_location_arguments - title: RETIRED FUNCTIONS - Discontinue Using! - desc: USGS WaterServices will be taken offline February 22nd, 2027. These functions will be removed after that date: + desc: These functions will be removed after Feburary 22, 2027 contents: - readNWISdv - readNWISuv From b28852c8be0237ce64f77de7dec186b97732066f Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 6 Oct 2026 13:59:14 -0500 Subject: [PATCH 06/16] ? --- .gitlab-ci.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 660a94752..20bcf827b 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -30,6 +30,7 @@ variables: PAGES_OUTDIR: "$CI_PROJECT_DIR/public" CUSTOM_DR_UA: "GitLab_CI" API_USGS_PAT: "${API_USGS_PAT}" + BUILDX_NO_DEFAULT_ATTESTATIONS: 1 build-package: stage: build-package From 80d1e19ab67a7fe299dc9c1bebc8feacb7a80567 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 7 Oct 2026 09:45:28 -0500 Subject: [PATCH 07/16] will this send the API key to drpy? --- .github/workflows/pkgdown.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 06e731e81..1d5add3c5 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -67,6 +67,7 @@ jobs: python -m pip install --upgrade pip run: | python -m pip install --upgrade pip + export API_USGS_PAT if [ -f requirements.txt ]; then pip install -r requirements.txt; fi - name: Create public directory run: | From d33bce896910d72a34e8a48755c0e9ba99dc3d32 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 7 Oct 2026 14:08:10 -0500 Subject: [PATCH 08/16] debug --- .github/workflows/pkgdown.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 1d5add3c5..228529b72 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -65,10 +65,10 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - run: | - python -m pip install --upgrade pip - export API_USGS_PAT if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + export API_USGS_PAT + from os import environ + print(environ.get("API_USGS_PAT") is None) - name: Create public directory run: | mkdir public From 2e7ae8200c36dcb2e23b7be5f72ad68a95ae0063 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 7 Oct 2026 14:32:32 -0500 Subject: [PATCH 09/16] ? --- .github/workflows/pkgdown.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 228529b72..940055710 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -67,8 +67,10 @@ jobs: python -m pip install --upgrade pip if [ -f requirements.txt ]; then pip install -r requirements.txt; fi export API_USGS_PAT + python -c " from os import environ print(environ.get("API_USGS_PAT") is None) + " - name: Create public directory run: | mkdir public From 47eddf95a55d8300d96125b48f88d8790616cb3d Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Wed, 7 Oct 2026 15:04:41 -0500 Subject: [PATCH 10/16] ?? --- .github/workflows/pkgdown.yaml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 940055710..12537e0e9 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -66,14 +66,10 @@ jobs: run: | python -m pip install --upgrade pip if [ -f requirements.txt ]; then pip install -r requirements.txt; fi - export API_USGS_PAT - python -c " - from os import environ - print(environ.get("API_USGS_PAT") is None) - " - name: Create public directory run: | mkdir public + export API_USGS_PAT - name: Build site run: | pkgdown::build_site(override = list(destination = "public")) | From 07fd47873484ffd567f7e67df5e8f17dbd5a1bc6 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 8 Oct 2026 09:54:04 -0500 Subject: [PATCH 11/16] let's just have fewer python examples run. --- tutorials/basic_slides_deck.qmd | 62 +++++++++++++++++++++++---------- 1 file changed, 44 insertions(+), 18 deletions(-) diff --git a/tutorials/basic_slides_deck.qmd b/tutorials/basic_slides_deck.qmd index ced4c96eb..a8a42e2f3 100644 --- a/tutorials/basic_slides_deck.qmd +++ b/tutorials/basic_slides_deck.qmd @@ -581,6 +581,7 @@ Within your code, add: ```{python} #| eval: false +#| label: osexample import os os.environ["API_USGS_PAT"] = "abc123" ``` @@ -631,6 +632,7 @@ Shift + Tab: ```{r} #| eval: false #| echo: true +#| label: rdischarge discharge <- read_waterdata_daily( parameter_code = "00060", statistic_id = "00003" @@ -764,7 +766,7 @@ site_info <- read_waterdata_monitoring_location( ### Python ```{python} -#| eval: !expr evaluate_python +#| eval: false #| label: pythondanecountysites site_info, md = waterdata.get_monitoring_locations( state_name="Wisconsin", county_name="Dane County" @@ -856,6 +858,7 @@ site_info_refined, md = waterdata.get_monitoring_locations( ```{r} #| output-location: default +#| label: ggplotmap library(ggplot2) ggplot(data = site_info_refined) + @@ -866,6 +869,7 @@ ggplot(data = site_info_refined) + ```{python} #| eval: !expr evaluate_python +#| label: pythonmap import matplotlib.pyplot as plt import geopandas as gpd @@ -888,6 +892,7 @@ site_info_refined.plot() ```{r} #| eval: true #| output-location: slide +#| label: rleafletmap library(leaflet) #default leaflet crs: leaflet_crs <- "+proj=longlat +datum=WGS84" @@ -906,6 +911,7 @@ If you have `geopandas` installed, the function will return a GeoDataFrame with ```{python} #| eval: false +#| label: pyleafletmap site_info_refined.set_crs(crs="WGS84").explore( marker_kwds=dict(radius=7), style_kwds=dict(opacity=1, fillOpacity=1), @@ -928,6 +934,7 @@ Let's get all the time series in Dane County, WI with daily mean (statistic_id = ### R ```{r} +#| label: rcombinedmeta sites_available <- read_waterdata_combined_meta( state_name = "Wisconsin", county_name = "Dane County", @@ -939,6 +946,8 @@ sites_available <- read_waterdata_combined_meta( ### Python ```{python} +#| label: pycombinedmeta +#| eval: false sites_available, md = waterdata.get_combined_metadata( state_name = "Wisconsin", county_name = "Dane County", @@ -956,6 +965,7 @@ Selecting just a few columns: ```{r} #| echo: false +#| label: tablecombined dt_me( sites_available |> sf::st_drop_geometry() |> @@ -989,6 +999,7 @@ When these slides were generated on `{r} Sys.Date()`, the results were: ```{r} #| message: false #| echo: false +#| label: rsolution1 library(dplyr) cat("1. ") tus <- read_waterdata_combined_meta( @@ -1019,6 +1030,7 @@ tus_summary$end[1] ```{r} #| echo: false +#| label: bonussolution leaflet( data = tus_summary |> sf::st_transform(crs = leaflet_crs) @@ -1042,6 +1054,7 @@ Let's get the continuous discharge measurements in Dane County, WI (parameter co ### R ```{r} +#| label: rcombined2 latest_sites <- read_waterdata_combined_meta( state_name = "Wisconsin", county_name = "Dane County", @@ -1059,17 +1072,18 @@ latest_discharge <- read_waterdata_latest_continuous( ### Python ```{python} +#| eval: false +#| label: pycombined2 latest_sites, md = waterdata.get_combined_metadata( - state_name = "Wisconsin", - county_name = "Dane County", - parameter_code = "00060", - last_modified = "P14D", - data_type = "Continuous values" + state_name="Wisconsin", + county_name="Dane County", + parameter_code="00060", + last_modified="P14D", + data_type="Continuous values", ) latest_discharge, md = waterdata.get_latest_continuous( - monitoring_location_id = latest_sites.monitoring_location_id, - parameter_code = "00060" + monitoring_location_id=latest_sites.monitoring_location_id, parameter_code="00060" ) ``` @@ -1086,7 +1100,8 @@ latest_discharge, md = waterdata.get_latest_continuous( ### R ```{r} -#| eval: false +#| label: rmap2 +#| output-location: slide pal <- colorNumeric("viridis", latest_discharge$value) leaflet( @@ -1118,9 +1133,8 @@ leaflet( ### Python ```{python} -#| eval: true -#| output-location: slide - +#| eval: false +#| label: pymap2 latest_discharge.set_crs(crs="WGS84").explore( marker_kwds=dict(radius=7), style_kwds=dict(opacity=1, fillOpacity=1), @@ -1147,6 +1161,7 @@ Let's get daily discharge data for the last 3 years from 2 sites: ### R ```{r} +#| label: rdaily2 daily <- read_waterdata_daily( monitoring_location_id = c("USGS-05406457", "USGS-05427930"), parameter_code = c("00060"), @@ -1158,8 +1173,10 @@ daily <- read_waterdata_daily( ### Python ```{python} +#| eval: !expr evaluate_python +#| label: pydaily2 df, md = waterdata.get_daily( - monitoring_location_id= ["USGS-05406457", "USGS-05427930"], + monitoring_location_id=["USGS-05406457", "USGS-05427930"], parameter_code="00060", statistic_id="00003", time="2022-10-01/2025-10-01", @@ -1175,6 +1192,7 @@ df, md = waterdata.get_daily( ### R ```{r} +#| label: rplot4 ggplot(data = daily) + geom_line(aes(x = time, y = value, color = approval_status)) + facet_grid(monitoring_location_id ~ ., scale = "free_y") @@ -1183,15 +1201,20 @@ ggplot(data = daily) + ### Python ```{python} -#| eval: true +#| eval: false +#| label: pyplot4 import matplotlib.pyplot as plt import pandas as pd import seaborn levels, categories = pd.factorize(df["approval_status"]) graph = seaborn.FacetGrid( - df, row="monitoring_location_id", hue="approval_status", - height=3, aspect=3, sharey=False + df, + row="monitoring_location_id", + hue="approval_status", + height=3, + aspect=3, + sharey=False, ) graph.map(plt.plot, "time", "value").add_legend() ``` @@ -1229,6 +1252,7 @@ Let's get orthophosphate ("00660") data from the Shenandoah River at Front Royal ```{r} #| message: true +#| label: rsamples site <- "USGS-01631000" pcode <- "00660" @@ -1243,7 +1267,7 @@ ncol(qw_data) ### Python ```{python} -#| eval: !expr evaluate_python +#| eval: false site = "USGS-01631000" pcode = "00660" @@ -1254,7 +1278,7 @@ qw_data, md_qw = waterdata.get_samples( profile = "basicphyschem", ) -qw_data.shape[1] + ``` ::: @@ -1291,6 +1315,7 @@ That's a LOT of columns returned. ```{r} #| echo: false +#| label: dataprofile df <- tibble( dataType = c( "results", @@ -1322,6 +1347,7 @@ dt_me(df, escape = FALSE, paging = FALSE) ```{r} #| echo: false +#| label: pyprofile names(df) <- c("service", "Description", "profile") dt_me(df, escape = FALSE, paging = FALSE) From 3b634aa9d5d96ed85dc8899874fb8b377de891fa Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 8 Oct 2026 09:54:04 -0500 Subject: [PATCH 12/16] make fewer samples queries --- tutorials/basic_slides_deck.qmd | 62 +++++++++++++++++++++++---------- vignettes/samples_data.Rmd | 25 +++++-------- 2 files changed, 53 insertions(+), 34 deletions(-) diff --git a/tutorials/basic_slides_deck.qmd b/tutorials/basic_slides_deck.qmd index ced4c96eb..a8a42e2f3 100644 --- a/tutorials/basic_slides_deck.qmd +++ b/tutorials/basic_slides_deck.qmd @@ -581,6 +581,7 @@ Within your code, add: ```{python} #| eval: false +#| label: osexample import os os.environ["API_USGS_PAT"] = "abc123" ``` @@ -631,6 +632,7 @@ Shift + Tab: ```{r} #| eval: false #| echo: true +#| label: rdischarge discharge <- read_waterdata_daily( parameter_code = "00060", statistic_id = "00003" @@ -764,7 +766,7 @@ site_info <- read_waterdata_monitoring_location( ### Python ```{python} -#| eval: !expr evaluate_python +#| eval: false #| label: pythondanecountysites site_info, md = waterdata.get_monitoring_locations( state_name="Wisconsin", county_name="Dane County" @@ -856,6 +858,7 @@ site_info_refined, md = waterdata.get_monitoring_locations( ```{r} #| output-location: default +#| label: ggplotmap library(ggplot2) ggplot(data = site_info_refined) + @@ -866,6 +869,7 @@ ggplot(data = site_info_refined) + ```{python} #| eval: !expr evaluate_python +#| label: pythonmap import matplotlib.pyplot as plt import geopandas as gpd @@ -888,6 +892,7 @@ site_info_refined.plot() ```{r} #| eval: true #| output-location: slide +#| label: rleafletmap library(leaflet) #default leaflet crs: leaflet_crs <- "+proj=longlat +datum=WGS84" @@ -906,6 +911,7 @@ If you have `geopandas` installed, the function will return a GeoDataFrame with ```{python} #| eval: false +#| label: pyleafletmap site_info_refined.set_crs(crs="WGS84").explore( marker_kwds=dict(radius=7), style_kwds=dict(opacity=1, fillOpacity=1), @@ -928,6 +934,7 @@ Let's get all the time series in Dane County, WI with daily mean (statistic_id = ### R ```{r} +#| label: rcombinedmeta sites_available <- read_waterdata_combined_meta( state_name = "Wisconsin", county_name = "Dane County", @@ -939,6 +946,8 @@ sites_available <- read_waterdata_combined_meta( ### Python ```{python} +#| label: pycombinedmeta +#| eval: false sites_available, md = waterdata.get_combined_metadata( state_name = "Wisconsin", county_name = "Dane County", @@ -956,6 +965,7 @@ Selecting just a few columns: ```{r} #| echo: false +#| label: tablecombined dt_me( sites_available |> sf::st_drop_geometry() |> @@ -989,6 +999,7 @@ When these slides were generated on `{r} Sys.Date()`, the results were: ```{r} #| message: false #| echo: false +#| label: rsolution1 library(dplyr) cat("1. ") tus <- read_waterdata_combined_meta( @@ -1019,6 +1030,7 @@ tus_summary$end[1] ```{r} #| echo: false +#| label: bonussolution leaflet( data = tus_summary |> sf::st_transform(crs = leaflet_crs) @@ -1042,6 +1054,7 @@ Let's get the continuous discharge measurements in Dane County, WI (parameter co ### R ```{r} +#| label: rcombined2 latest_sites <- read_waterdata_combined_meta( state_name = "Wisconsin", county_name = "Dane County", @@ -1059,17 +1072,18 @@ latest_discharge <- read_waterdata_latest_continuous( ### Python ```{python} +#| eval: false +#| label: pycombined2 latest_sites, md = waterdata.get_combined_metadata( - state_name = "Wisconsin", - county_name = "Dane County", - parameter_code = "00060", - last_modified = "P14D", - data_type = "Continuous values" + state_name="Wisconsin", + county_name="Dane County", + parameter_code="00060", + last_modified="P14D", + data_type="Continuous values", ) latest_discharge, md = waterdata.get_latest_continuous( - monitoring_location_id = latest_sites.monitoring_location_id, - parameter_code = "00060" + monitoring_location_id=latest_sites.monitoring_location_id, parameter_code="00060" ) ``` @@ -1086,7 +1100,8 @@ latest_discharge, md = waterdata.get_latest_continuous( ### R ```{r} -#| eval: false +#| label: rmap2 +#| output-location: slide pal <- colorNumeric("viridis", latest_discharge$value) leaflet( @@ -1118,9 +1133,8 @@ leaflet( ### Python ```{python} -#| eval: true -#| output-location: slide - +#| eval: false +#| label: pymap2 latest_discharge.set_crs(crs="WGS84").explore( marker_kwds=dict(radius=7), style_kwds=dict(opacity=1, fillOpacity=1), @@ -1147,6 +1161,7 @@ Let's get daily discharge data for the last 3 years from 2 sites: ### R ```{r} +#| label: rdaily2 daily <- read_waterdata_daily( monitoring_location_id = c("USGS-05406457", "USGS-05427930"), parameter_code = c("00060"), @@ -1158,8 +1173,10 @@ daily <- read_waterdata_daily( ### Python ```{python} +#| eval: !expr evaluate_python +#| label: pydaily2 df, md = waterdata.get_daily( - monitoring_location_id= ["USGS-05406457", "USGS-05427930"], + monitoring_location_id=["USGS-05406457", "USGS-05427930"], parameter_code="00060", statistic_id="00003", time="2022-10-01/2025-10-01", @@ -1175,6 +1192,7 @@ df, md = waterdata.get_daily( ### R ```{r} +#| label: rplot4 ggplot(data = daily) + geom_line(aes(x = time, y = value, color = approval_status)) + facet_grid(monitoring_location_id ~ ., scale = "free_y") @@ -1183,15 +1201,20 @@ ggplot(data = daily) + ### Python ```{python} -#| eval: true +#| eval: false +#| label: pyplot4 import matplotlib.pyplot as plt import pandas as pd import seaborn levels, categories = pd.factorize(df["approval_status"]) graph = seaborn.FacetGrid( - df, row="monitoring_location_id", hue="approval_status", - height=3, aspect=3, sharey=False + df, + row="monitoring_location_id", + hue="approval_status", + height=3, + aspect=3, + sharey=False, ) graph.map(plt.plot, "time", "value").add_legend() ``` @@ -1229,6 +1252,7 @@ Let's get orthophosphate ("00660") data from the Shenandoah River at Front Royal ```{r} #| message: true +#| label: rsamples site <- "USGS-01631000" pcode <- "00660" @@ -1243,7 +1267,7 @@ ncol(qw_data) ### Python ```{python} -#| eval: !expr evaluate_python +#| eval: false site = "USGS-01631000" pcode = "00660" @@ -1254,7 +1278,7 @@ qw_data, md_qw = waterdata.get_samples( profile = "basicphyschem", ) -qw_data.shape[1] + ``` ::: @@ -1291,6 +1315,7 @@ That's a LOT of columns returned. ```{r} #| echo: false +#| label: dataprofile df <- tibble( dataType = c( "results", @@ -1322,6 +1347,7 @@ dt_me(df, escape = FALSE, paging = FALSE) ```{r} #| echo: false +#| label: pyprofile names(df) <- c("service", "Description", "profile") dt_me(df, escape = FALSE, paging = FALSE) diff --git a/vignettes/samples_data.Rmd b/vignettes/samples_data.Rmd index 15c731862..1e3f3af19 100644 --- a/vignettes/samples_data.Rmd +++ b/vignettes/samples_data.Rmd @@ -266,7 +266,7 @@ State query parameter. To get a list of available state fips values, run `check_waterdata_sample_params("states")`. The "fips" values can be created using the function `stateCdLookup`. -```{r} +```{r eval=FALSE} state_fip <- stateCdLookup("WI", outputType = "fips") state_sites <- read_waterdata_samples(stateFips = state_fip, @@ -277,9 +277,6 @@ state_sites <- read_waterdata_samples(stateFips = state_fip, ``` -```{r echo=FALSE} -map_it(state_sites) -``` ## Additional Query Parameters @@ -361,21 +358,17 @@ 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_waterdata_samples(stateFips = state_fip, - characteristicUserSupplied = user_char, - dataType = "locations", - activityStartDateLower = "2024-10-01", - activityStartDateUpper = "2024-11-30", - dataProfile = "site") +```{r eval=FALSE} +state_sites_recent <- read_waterdata_samples( + stateFips = stateCdLookup("WI", outputType = "fips"), + characteristicUserSupplied = user_char, + dataType = "locations", + activityStartDateLower = "2024-10-01", + activityStartDateUpper = "2024-11-30", + dataProfile = "site") ``` -Many fewer sites than the original Wisconsin map: - -```{r echo=FALSE} -map_it(state_sites_recent) -``` ## Data Discovery From 0e1b926a2a32af1380061c9bedecf058c06bfe45 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 8 Oct 2026 12:50:11 -0500 Subject: [PATCH 13/16] turn actions off except for canonical repo. --- .github/workflows/R-CMD-check.yaml | 1 + .github/workflows/pkgdown.yaml | 2 ++ 2 files changed, 3 insertions(+) diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml index abbd7aa24..2c374afcd 100644 --- a/.github/workflows/R-CMD-check.yaml +++ b/.github/workflows/R-CMD-check.yaml @@ -12,6 +12,7 @@ permissions: read-all jobs: R-CMD-check: + if: github.repository == 'DOI-USGS/dataRetrieval' runs-on: ${{ matrix.config.os }} name: ${{ matrix.config.os }} (${{ matrix.config.r }}) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 12537e0e9..9496fe868 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -22,6 +22,7 @@ concurrency: jobs: pkgdown: + if: github.repository == 'DOI-USGS/dataRetrieval' runs-on: ubuntu-latest # Only restrict concurrency for non-PR jobs environment: CI_config @@ -86,6 +87,7 @@ jobs: path: ./public # Deployment job deploy: + if: github.repository == 'DOI-USGS/dataRetrieval' environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} From 7f9d5bbb2ab8f0bf265e5fcf62f82be492f65451 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Thu, 8 Oct 2026 12:57:24 -0500 Subject: [PATCH 14/16] How about this.. do the check only on a pull request, and do the pages only after the code is merged. --- .github/workflows/R-CMD-check.yaml | 3 --- .github/workflows/pkgdown.yaml | 3 --- 2 files changed, 6 deletions(-) diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml index 2c374afcd..760fe191f 100644 --- a/.github/workflows/R-CMD-check.yaml +++ b/.github/workflows/R-CMD-check.yaml @@ -1,8 +1,6 @@ # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help on: - push: - branches: [main, develop] pull_request: branches: [main, develop] @@ -12,7 +10,6 @@ permissions: read-all jobs: R-CMD-check: - if: github.repository == 'DOI-USGS/dataRetrieval' runs-on: ${{ matrix.config.os }} name: ${{ matrix.config.os }} (${{ matrix.config.r }}) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 9496fe868..94e9437dd 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -3,8 +3,6 @@ on: push: branches: [main] - pull_request: - branches: [main] name: pkgdown @@ -87,7 +85,6 @@ jobs: path: ./public # Deployment job deploy: - if: github.repository == 'DOI-USGS/dataRetrieval' environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} From 1b5dae9a74ad3fb74ab08c68ecd9e6c921d17376 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Fri, 9 Oct 2026 11:02:57 -0500 Subject: [PATCH 15/16] Clean up WQX3 doc --- DESCRIPTION | 2 +- R/readWQPdata.R | 2 +- man/readWQPdata.Rd | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 2ee3f4a03..1936dfd92 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -72,4 +72,4 @@ BuildVignettes: true VignetteBuilder: knitr BugReports: https://github.com/DOI-USGS/dataRetrieval/issues Roxygen: list(markdown = TRUE) -Config/roxygen2/version: 8.1.0 +Config/roxygen2/version: 8.1.1 diff --git a/R/readWQPdata.R b/R/readWQPdata.R index d8c5ad0d8..dc17919c4 100644 --- a/R/readWQPdata.R +++ b/R/readWQPdata.R @@ -28,7 +28,7 @@ #' Organization Data \tab Organization \tab /data/Organization/search \cr #' } #' -#' There are 4 WQX3 options. These are still in-development, +#' There are 5 WQX3 options. These are still in-development, #' and should be used with caution. #' #' \tabular{llll}{ diff --git a/man/readWQPdata.Rd b/man/readWQPdata.Rd index 72ad71222..3fb77c727 100644 --- a/man/readWQPdata.Rd +++ b/man/readWQPdata.Rd @@ -87,7 +87,7 @@ Biological Habitat Metrics \tab BiologicalMetric \tab /data/BiologicalMetric/sea Organization Data \tab Organization \tab /data/Organization/search \cr } -There are 4 WQX3 options. These are still in-development, +There are 5 WQX3 options. These are still in-development, and should be used with caution. \tabular{llll}{ From 52c37035ec5bb8bb52f0611c558594fd0d13514f Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Tue, 13 Oct 2026 08:53:22 -0500 Subject: [PATCH 16/16] include readNWISdata in updates --- R/readNWISdata.R | 191 +++++++++++++++++++++----------------------- man/readNWISdata.Rd | 13 ++- 2 files changed, 103 insertions(+), 101 deletions(-) diff --git a/R/readNWISdata.R b/R/readNWISdata.R index b50e03d2f..29b661d7a 100644 --- a/R/readNWISdata.R +++ b/R/readNWISdata.R @@ -14,6 +14,10 @@ #' "America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", #' "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also `OlsonNames()` #' for more information on time zones. +#' @param override_error Logical parameter that allows users to run this +#' function during the final stages of NWIS decommission. NWIS servers will be taken +#' offline February 22nd, 2027. Setting this parameter to `TRUE` should only +#' be used as a tool to convert readNWIS to read_waterdata functions. #' @param \dots see for #' a complete list of options. A #' list of arguments can also be supplied. One important argument to include is @@ -76,121 +80,108 @@ readNWISdata <- function( ..., asDateTime = TRUE, convertType = TRUE, - tz = "UTC" + tz = "UTC", + override_error = FALSE ) { - tz <- match.arg(tz, OlsonNames()) - - valuesList <- readNWISdots(...) - - values <- valuesList[["values"]] - values <- values[names(values) != "format"] - format <- valuesList[["values"]][["format"]] - - service <- valuesList$service - if (length(service) > 1) { + if (override_error) { warning( - "Only one service value is allowed. Service: ", - service[1], - " will be used." + "NWIS servers will be taken offline February 22nd, 2027. Update to read_waterdata functions." ) - service <- service[1] - } - if (any(service %in% c("qw", "qwdata"))) { - .Deprecated( - old = "readNWISdata", - package = "dataRetrieval", - new = "readWQPdata", - msg = "NWIS qw web services are being retired. -Please see vignette('qwdata_changes', package = 'dataRetrieval') -for more information. -https://cran.r-project.org/web/packages/dataRetrieval/vignettes/qwdata_changes.html" - ) - } else if (service == "dv") { - .Deprecated( - new = "read_waterdata_daily", - package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_daily." - ) - } else if (service == "site") { - .Deprecated( - new = "read_waterdata_monitoring_location", - package = "dataRetrieval", - msg = "NWIS servers are slated for decommission. Please begin to migrate to read_waterdata_monitoring_location" - ) - } else { - message(new_nwis_message()) - } + tz <- match.arg(tz, OlsonNames()) - baseURL <- httr2::request(pkg.env[[service]]) + valuesList <- readNWISdots(...) - POST <- nchar(paste0(unlist(values), collapse = "")) > 2048 + values <- valuesList[["values"]] + values <- values[names(values) != "format"] + format <- valuesList[["values"]][["format"]] - baseURL <- get_or_post(baseURL, POST = POST, !!!values, .multi = "comma") + service <- valuesList$service + if (length(service) > 1) { + warning( + "Only one service value is allowed. Service: ", + service[1], + " will be used." + ) + service <- service[1] + } - if (service != "rating") { - baseURL <- get_or_post(baseURL, POST = POST, format = format) - } + baseURL <- httr2::request(pkg.env[[service]]) - if (length(grep("rdb", format)) > 0) { - retval <- importRDB1( - baseURL, - tz = tz, - asDateTime = asDateTime, - convertType = convertType - ) - } else { - retval <- importWaterML1(baseURL, tz = tz, asDateTime = asDateTime) - } + POST <- nchar(paste0(unlist(values), collapse = "")) > 2048 + + baseURL <- get_or_post(baseURL, POST = POST, !!!values, .multi = "comma") + + if (service != "rating") { + baseURL <- get_or_post(baseURL, POST = POST, format = format) + } - if ("dv" == service) { - tzLib <- stats::setNames( - c( - "America/New_York", - "America/New_York", - "America/Chicago", - "America/Chicago", - "America/Denver", - "America/Denver", - "America/Los_Angeles", - "America/Los_Angeles", - "America/Anchorage", - "America/Anchorage", - "America/Honolulu", - "America/Honolulu", - "UTC" - ), - c( - "EST", - "EDT", - "CST", - "CDT", - "MST", - "MDT", - "PST", - "PDT", - "AKST", - "AKDT", - "HAST", - "HST", - "UTC" + if (length(grep("rdb", format)) > 0) { + retval <- importRDB1( + baseURL, + tz = tz, + asDateTime = asDateTime, + convertType = convertType ) - ) - # TODO: Think about dates that cross a time zone boundary. - if (format == "waterml,1.1" && nrow(retval) > 0) { - retval$dateTime <- as.POSIXct( - retval$dateTime, - tzLib[tz = retval$tz_cd[1]] + } else { + retval <- importWaterML1(baseURL, tz = tz, asDateTime = asDateTime) + } + + if ("dv" == service) { + tzLib <- stats::setNames( + c( + "America/New_York", + "America/New_York", + "America/Chicago", + "America/Chicago", + "America/Denver", + "America/Denver", + "America/Los_Angeles", + "America/Los_Angeles", + "America/Anchorage", + "America/Anchorage", + "America/Honolulu", + "America/Honolulu", + "UTC" + ), + c( + "EST", + "EDT", + "CST", + "CDT", + "MST", + "MDT", + "PST", + "PDT", + "AKST", + "AKDT", + "HAST", + "HST", + "UTC" + ) ) + # TODO: Think about dates that cross a time zone boundary. + if (format == "waterml,1.1" && nrow(retval) > 0) { + retval$dateTime <- as.POSIXct( + retval$dateTime, + tzLib[tz = retval$tz_cd[1]] + ) + } } - } - if ("iv" == service || "iv_recent" == service) { - if (tz == "") { - retval$tz_cd <- rep("UTC", nrow(retval)) - } else { - retval$tz_cd <- rep(tz, nrow(retval)) + if ("iv" == service || "iv_recent" == service) { + if (tz == "") { + retval$tz_cd <- rep("UTC", nrow(retval)) + } else { + retval$tz_cd <- rep(tz, nrow(retval)) + } } + } else { + stop( + "NWIS servers will be taken offline February 22nd, 2027. Update to read_waterdata functions. +Use override_error = TRUE to temporarily override this error. For more information: +https://doi-usgs.github.io/dataRetrieval/articles/read_waterdata_functions.html" + ) } return(retval) diff --git a/man/readNWISdata.Rd b/man/readNWISdata.Rd index 8e47c060a..2110aff8b 100644 --- a/man/readNWISdata.Rd +++ b/man/readNWISdata.Rd @@ -4,7 +4,13 @@ \alias{readNWISdata} \title{General Data Import from NWIS} \usage{ -readNWISdata(..., asDateTime = TRUE, convertType = TRUE, tz = "UTC") +readNWISdata( + ..., + asDateTime = TRUE, + convertType = TRUE, + tz = "UTC", + override_error = FALSE +) } \arguments{ \item{\dots}{see \url{https://waterservices.usgs.gov/docs/site-service/} for @@ -30,6 +36,11 @@ Possible values to provide are "America/New_York", "America/Chicago", "America/D "America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu", "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". See also \code{OlsonNames()} for more information on time zones.} + +\item{override_error}{Logical parameter that allows users to run this +function during the final stages of NWIS decommission. NWIS servers will be taken +offline February 22nd, 2027. Setting this parameter to \code{TRUE} should only +be used as a tool to convert readNWIS to read_waterdata functions.} } \value{ A data frame with the following columns: