more consistent to use ResultWQX

DOI-USGS · Jun 6, 2024 · a9da420 · a9da420
1 parent 9104c20
commit a9da420
Show file tree

Hide file tree

Showing 8 changed files with 199 additions and 62 deletions.
diff --git a/R/constructNWISURL.R b/R/constructNWISURL.R
@@ -372,7 +372,7 @@ constructWQPURL <- function(siteNumbers,
     } 
 
     siteNumbers <- paste(paste0("siteid=", siteNumbers), collapse = "&")
-    baseURL <- drURL("WQX3", Access = pkg.env$access)
+    baseURL <- drURL("ResultWQX3", Access = pkg.env$access)
     baseURL <- paste0(baseURL, siteNumbers)
   }
 

diff --git a/R/readWQPdata.R b/R/readWQPdata.R
@@ -10,16 +10,16 @@
 #' 
 #' @details
 #'  
-#' There are currently 10 legacy and 3 modern WQX "services"
+#' There are currently 10 legacy and 4 modern WQX "services"
 #' provided by the Water Quality Portal:
 #'  
 #' WQX:
 #' \tabular{llll}{
 #' WQP Radio Button \tab service argument \tab Base URL \tab dataProfile \cr 
 #' Monitoring Locations \tab StationWQX3 \tab /wqx3/Station/search \tab \cr
-#' Full Physical Chemical \tab WQX3 \tab /wqx3/Result/search \tab fullPhysChem \cr
-#' Narrow \tab WQX3 \tab /wqx3/Result/search \tab narrow \cr
-#' Basic Physical Chemical \tab WQX3 \tab /wqx3/Result/search \tab basicPhysChem \cr
+#' Full Physical Chemical \tab ResultWQX3 \tab /wqx3/Result/search \tab fullPhysChem \cr
+#' Narrow \tab ResultWQX3 \tab /wqx3/Result/search \tab narrow \cr
+#' Basic Physical Chemical \tab ResultWQX3 \tab /wqx3/Result/search \tab basicPhysChem \cr
 #' }
 #' 
 #' Legacy:
@@ -41,7 +41,7 @@
 #' @param \dots see \url{https://www.waterqualitydata.us/webservices_documentation} for a complete list of options.
 #' A list of arguments can also be supplied. For more information see the above 
 #' description for this help file. If no "service" argument is supplied, it
-#' will default to "fullPhysChem". One way to figure out how to construct a WQP query is to go to the "Advanced" 
+#' will default to "ResultWQX3". One way to figure out how to construct a WQP query is to go to the "Advanced" 
 #' form in the Water Quality Portal. Use the form to discover what parameters are available. Once the query is 
 #' set in the form, scroll down to the "Query URL". You will see the parameters
 #' after "https://www.waterqualitydata.us/#". For example, if you chose "Nutrient"
@@ -167,7 +167,8 @@
 #' # Data profiles: "Sample Results (narrow)" (legacy)
 #' samp_narrow <- readWQPdata(
 #'   siteid = "USGS-04024315",
-#'   dataProfile = "narrow"
+#'   service = "Result",
+#'   dataProfile = "narrowResult"
 #' )
 #'
 #' # Data profiles: "Sampling Activity"  (legacy)
@@ -200,7 +201,7 @@
 #' )
 #' }
 readWQPdata <- function(...,
-                        service = "WQX3",
+                        service = "ResultWQX3",
                         querySummary = FALSE,
                         tz = "UTC",
                         ignore_attributes = FALSE,
@@ -213,7 +214,7 @@ readWQPdata <- function(...,
                                   "Project", "ProjectMonitoringLocationWeighting",
                                   "ResultDetectionQuantitationLimit",
                                   "BiologicalMetric", "Organization",
-                                  "WQX3", "StationWQX3"),
+                                  "ResultWQX3", "StationWQX3"),
                        several.ok = FALSE)
 
   legacy <- is_legacy(service)

diff --git a/R/readWQPdots.R b/R/readWQPdots.R
@@ -17,7 +17,7 @@ readWQPdots <- function(..., legacy = FALSE) {
     if(legacy){
       service <- "Result"
     } else {
-      service <- "WQX3"
+      service <- "ResultWQX3"
     }
 
   }
@@ -31,7 +31,7 @@ readWQPdots <- function(..., legacy = FALSE) {
       service <- "Result"
       matchReturn$service <- NULL
     } else if(profile %in% c("fullPhysChem", "narrow")){
-      service <- "WQX3"
+      service <- "ResultWQX3"
       matchReturn$service <- NULL      
     } 
   } 
@@ -41,7 +41,7 @@ readWQPdots <- function(..., legacy = FALSE) {
     "ActivityMetric", "SiteSummary",
     "Project", "ProjectMonitoringLocationWeighting",
     "ResultDetectionQuantitationLimit", "BiologicalMetric",
-    "WQX3", "StationWQX3"
+    "ResultWQX3", "StationWQX3"
   ))
 
   names(matchReturn)[names(matchReturn) == "bbox"] <- "bBox"

diff --git a/R/setAccess.R b/R/setAccess.R
@@ -63,7 +63,7 @@ setAccess <- function(access = "public") {
   pkg.env$ResultDetectionQuantitationLimit <- "https://www.waterqualitydata.us/data/ResultDetectionQuantitationLimit/search"
   pkg.env$BiologicalMetric <- "https://www.waterqualitydata.us/data/BiologicalMetric/search"
   pkg.env$Organization <- "https://www.waterqualitydata.us/data/Organization/search"
-  pkg.env$WQX3 <- "https://www.waterqualitydata.us/wqx3/Result/search"
+  pkg.env$ResultWQX3 <- "https://www.waterqualitydata.us/wqx3/Result/search"
   pkg.env$StationWQX3 <- "https://www.waterqualitydata.us/wqx3/Station/search"
   pkg.env$samplesData <- "https://api.waterdata.usgs.gov/samples-data/summary"
   pkg.env$status <- "https://www.waterqualitydata.us/wqx3/status/"

diff --git a/man/readWQPdata.Rd b/man/readWQPdata.Rd
diff --git a/tests/testthat/tests_general.R b/tests/testthat/tests_general.R
@@ -504,7 +504,7 @@ test_that("profiles", {
   # Data profiles: "narrow":
   samp_data <- readWQPdata(
     siteid = "USGS-04024315",
-    service = "WQX3",
+    service = "ResultWQX3",
     dataProfile = "narrow"
   )
 

diff --git a/vignettes/Status.Rmd b/vignettes/Status.Rmd
@@ -37,7 +37,7 @@ If you have additional questions about the NWIS qw data service, email CompTools
 
 **New USGS data** _are_ accessible in a pre-release (*beta*) version of the [WQP web page](https://www.waterqualitydata.us/beta/) and new [wqx3 web services](https://waterqualitydata.us/wqx3/). Data are available in the "WQX version 3.0 format" (WQX = [Water Quality Exchange](https://exchangenetwork.net/data-exchange/wqx/)) for three new "Data Profiles" (how the data is formatted by the WQP):
 
-* Monitoring Location (a.k.a. 'Site' or 'Station')
+* Monitoring Location
 * Narrow results
 * Full Physical Chemical results
 * Basic Physical Chemical
@@ -73,8 +73,162 @@ knitr::kable(df)
 
 ```
 
+## readWQPqw
 
+This function is generally advertised as a user-friendly function since it only works with a known list of sites, parameter codes or characterisitic names, and start/end dates. 
 
+As of `dataRetrieval` 2.7.15.1, this function will use the WQX 3.0 "narrow" dataProfile. There is an argument "legacy" that allows the user to switch back to the WQX 2.0 profile. Keep in mind the 2.0 profiles will eventually be retired. For any more flexibility, users will need to use the "readWQPdata" function.
+
+An example of a WQX 3.0 return:
+
+```{r}
+library(dataRetrieval)
+rawPcode <- readWQPqw(siteNumbers = "USGS-01594440",
+                      parameterCd = "01075")
+attr(rawPcode, "url")
+```
+
+Compared to using the WQX 2.0 legacy results:
+
+```{r}
+rawPcode_legacy <- readWQPqw(siteNumbers = "USGS-01594440",
+                      parameterCd = "01075",
+                      legacy = TRUE)
+attr(rawPcode_legacy, "url")
+
+```
+
+## readWQPdata
+
+The "readWQPdata" function is the most flexible function to get WQP data. Currently there are 4 options that use the new WQX 3.0 profiles, and 11 legacy options.
+
+### WQX 3.0
+
+There are now 2 "services" available: StationWQX and ResultWQX. The "ResultWQX" service has multiple available "dataProfiles".  
+
+| Service        | dataProfile |
+| -------------- | ----------  |
+| StationWQX     |             |
+| ResultWQX      | fullPhysChem |
+| ResultWQX      | basicPhysChem |
+| ResultWQX      | narrow |
+
+Examples:
+
+```{r}
+data_full <- readWQPdata(siteid = "USGS-04024315",
+                         characteristicName = "pH",
+                         dataProfile = "fullPhysChem",
+                         service = "ResultWQX3")
+ncol(data_full)
+attr(data_full, "url")
+
+data_basic <- readWQPdata(siteid = "USGS-04024315",
+                          characteristicName = "pH",
+                          dataProfile = "basicPhysChem",
+                          service = "ResultWQX3")
+ncol(data_basic)
+attr(data_basic, "url")
+
+data_narrow <- readWQPdata(siteid = "USGS-04024315",
+                           characteristicName = "pH",
+                           dataProfile = "narrow",
+                           service = "ResultWQX3")
+ncol(data_narrow)
+attr(data_narrow, "url")
+
+data_sites <- readWQPdata(siteid = "USGS-04024315",
+                          characteristicName = "pH",
+                          service = "StationWQX3")
+ncol(data_sites)
+attr(data_sites, "url")
+
+```
+
+### WQX 2.0 - Legacy
+
+There are 8 services available from the legacy WQP. The Station and Result legacy services can still be accessed, but users should move to StationWQX and ResultWQX. As other former services become available in WQX 3.0, we will update these documents.
+
+| Service        | dataProfile | WQX 3.0 option? |
+| -------------- | ----------  | ----------  |
+| Station     |             | StationWQX |
+| Result      | resultPhysChem | ResultWQX |
+| Result      | biological |
+| Result      | narrowResult | ResultWQX |
+| Activity    | activityAll  |   |
+| ActivityMetric |           |   |
+| Project     |            |   |
+| ProjectMonitoringLocationWeighting |           |   |
+| ResultDetectionQuantitationLimit |         |   |
+| BiologicalMetric |     |   |
+
+Examples: 
+
+```{r eval=FALSE}
+# Data profiles: "Organization Data" (legacy)
+org_data <- readWQPdata(
+  statecode = "WI",
+  countycode = "Dane",
+  service = "Organization"
+)
+
+# Data profiles: "Project Data"  (legacy)
+project_data <- readWQPdata(
+  statecode = "WI",
+  countycode = "Dane",
+  service = "Project"
+)
+
+# Data profiles: "Project Monitoring Location Weighting Data"  (legacy)
+proj_mlwd <- readWQPdata(
+  statecode = "WI",
+  countycode = "Dane",
+  service = "ProjectMonitoringLocationWeighting"
+)
+
+# Data profiles: "Sample Results (physical/chemical metadata)"  (legacy)
+samp_data <- readWQPdata(
+  siteid = "USGS-04024315",
+  dataProfile = "resultPhysChem",
+  service = "Result"
+)
+
+# Data profiles: "Sample Results (biological metadata)"  (legacy)
+samp_bio <- readWQPdata(
+  siteid = "USGS-04024315",
+  dataProfile = "biological",
+  service = "Result"
+)
+
+# Data profiles: "Sample Results (narrow)" (legacy)
+samp_narrow <- readWQPdata(
+  siteid = "USGS-04024315",
+  dataProfile = "narrowResult",
+  service = "Result"
+)
+
+# Data profiles: "Sampling Activity"  (legacy)
+samp_activity <- readWQPdata(
+  siteid = "USGS-04024315",
+  dataProfile = "activityAll",
+  service = "Activity"
+)
+
+
+# Data profile: "Sampling Activity Metrics"  (legacy)
+act_metrics <- readWQPdata(
+  statecode = "WI",
+  countycode = "Dane",
+  service = "ActivityMetric"
+)
+
+# Data profile: "Result Detection Quantitation Limit Data"  (legacy)
+dl_data <- readWQPdata(
+  siteid = "USGS-04024315",
+  service = "ResultDetectionQuantitationLimit"
+)
+
+```
 
 ## whatNWISdata