Merge pull request DOI-USGS#746 from ldecicco-USGS/add_more_wqx3_docs

Add more wqx3 docs

Author: ldecicco-USGS

.github/workflows/R-CMD-check.yaml

@@ -21,10 +21,6 @@ jobs:
       matrix:
         config:
           - {os: macos-latest,   r: 'release'}
-          - {os: windows-latest, r: 'release'}
-          - {os: ubuntu-latest,   r: 'devel', http-user-agent: 'release'}
-          - {os: ubuntu-latest,   r: 'release'}
-          - {os: ubuntu-latest,   r: 'oldrel-1'}
 
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}

R/readWQPdata.R

@@ -43,8 +43,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 "ResultWQX3". One way to figure out how to construct a WQP query is to go to the "Advanced" 
+#' description for this help file. 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"
@@ -86,12 +85,21 @@
 #' @examplesIf is_dataRetrieval_user()
 #' \donttest{
 #' 
+#' # Legacy:
 #' nameToUse <- "pH"
 #' pHData <- readWQPdata(siteid = "USGS-04024315", 
 #'                       characteristicName = nameToUse)
 #' ncol(pHData)
 #' attr(pHData, "siteInfo")
 #' attr(pHData, "queryTime")
+#' attr(pHData, "url")
+#' 
+#' # WQX3:
+#' pHData_wqx3 <- readWQPdata(siteid = "USGS-04024315", 
+#'                       characteristicName = nameToUse,
+#'                       service = "ResultWQX3",
+#'                       dataProfile = "basicPhysChem")
+#' attr(pHData_wqx3, "url")
 #'
 #' # More examples:
 #' # querying by county
@@ -101,11 +109,30 @@
 #'   characteristicName = "Nitrogen"
 #' )
 #' 
+#' attr(DeWitt, "url")
+#' 
+#' DeWitt_wqx3 <- readWQPdata(
+#'   statecode = "Illinois",
+#'   countycode = "DeWitt",
+#'   characteristicName = "Nitrogen",
+#'   service = "ResultWQX3",
+#'   dataProfile = "basicPhysChem",  
+#'   ignore_attributes = TRUE)
+#' 
+#' attr(DeWitt_wqx3, "url")
+#' 
 #' # Data profile: "Sampling Activity"
 #' activity <- readWQPdata(
 #'   siteid = "USGS-04024315",
 #'   service = "Activity"
 #' )
+#' attr(activity, "url")
+#' 
+#' activity_wqx3 <- readWQPdata(
+#'   siteid = "USGS-04024315",
+#'   service = "ActivityWQX3"
+#' )
+#' attr(activity_wqx3, "url")
 #' 
 #' Dane_activity <- readWQPdata(
 #'   statecode = "Wisconsin",
@@ -114,14 +141,20 @@
 #'   startDateHi = "2023-12-31",
 #'   service = "Activity"
 #' )
+#' attr(Dane_activity, "url")
+#' 
+#' Dane_activity_wqx3 <- readWQPdata(
+#'   statecode = "Wisconsin",
+#'   countycode = "Dane",
+#'   startDateLo = "2023-01-01",
+#'   startDateHi = "2023-12-31",
+#'   service = "ActivityWQX3"
+#' )
+#' attr(Dane_activity_wqx3, "url")
 #' 
 #' ########################################################
 #' # Additional examples:
 #'
-#' pHData_legacy <- readWQPdata(siteid = "USGS-04024315", 
-#'                       characteristicName = nameToUse,
-#'                       service = "Result",
-#'                       dataProfile = "narrowResult")
 #'  
 #' # Data profiles: "Organization Data" 
 #' org_data <- readWQPdata(
@@ -157,6 +190,7 @@
 #'   dataProfile = "biological",
 #'   service = "Result"
 #' )
+#' 
 #'
 #' # Data profiles: "Sample Results (narrow)" 
 #' samp_narrow <- readWQPdata(
@@ -165,6 +199,13 @@
 #'   dataProfile = "narrowResult"
 #' )
 #'
+#' samp_narrow_wqx3 <- readWQPdata(
+#'   siteid = "USGS-04024315",
+#'   service = "ResultWQX3",
+#'   dataProfile = "narrow"
+#' )
+#'
+#'
 #' # Data profiles: "Sampling Activity"  
 #' samp_activity <- readWQPdata(
 #'   siteid = "USGS-04024315",

R/readWQPqw.R

@@ -55,13 +55,24 @@
 #' 
 #' attr(rawPcode, "siteInfo")
 #' attr(rawPcode, "queryTime")
-#' 
+#' attr(rawPcode, "url") 
 #' 
 #' rawCharacteristicName <- readWQPqw("WIDNR_WQX-10032762", "Specific conductance", "", "")
-#' rawPHsites <- readWQPqw(c("USGS-05406450", "USGS-05427949", "WIDNR_WQX-133040"), "pH", "", "")
+#' pHsites_legacy <- readWQPqw(c("USGS-05406450", "USGS-05427949", "WIDNR_WQX-133040"),
+#'                         "pH", "", "")
+#' ncol(pHsites_legacy)
+#' attr(pHsites_legacy, "url")
+#'  
+#' pHsites_modern <- readWQPqw(c("USGS-05406450", "USGS-05427949", "WIDNR_WQX-133040"),
+#'                         "pH", "", "", legacy = FALSE)
+#' ncol(pHsites_modern)
+#' attr(pHsites_modern, "url")
+#'           
 #' nwisEx <- readWQPqw("USGS-04024000", c("34247", "30234", "32104", "34220"), "", "2022-12-20")
 #'
-#' SC <- readWQPqw(siteNumbers = "USGS-05288705", parameterCd = "00300", convertType = FALSE)
+#' SC <- readWQPqw(siteNumbers = "USGS-05288705", 
+#'                 parameterCd = "00300",
+#'                 convertType = FALSE)
 #' }
 readWQPqw <- function(siteNumbers,
                       parameterCd,

README.Rmd

@@ -33,16 +33,6 @@ The `dataRetrieval` package was created to simplify the process of loading hydro
 
 :warning: USGS discrete water-quality data availability and format are changing. Beginning March 11, 2024 USGS data obtained from legacy services will not include new USGS data or recent updates to existing data. To view the status of changes in data availability and code functionality, visit: <https://doi-usgs.github.io/dataRetrieval/articles/Status.html>
 
-:warning: All documentation on <https://doi-usgs.github.io/dataRetrieval> assume you have the development version of dataRetrieval installed. To do that:
-
-```{r eval=FALSE}
-library(remotes)
-install_github("DOI-USGS/dataRetrieval",
-               build_vignettes = TRUE, 
-               build_opts = c("--no-resave-data",
-                              "--no-manual"))
-```
-
 If you have additional questions about these changes, email [email protected].
 
 # What would you like to do?

README.md

@@ -23,18 +23,6 @@ data. To view the status of changes in data availability and code
 functionality, visit:
 <https://doi-usgs.github.io/dataRetrieval/articles/Status.html>
 
-:warning: All documentation on
-<https://doi-usgs.github.io/dataRetrieval> assume you have the
-development version of dataRetrieval installed. To do that:
-
-``` r
-library(remotes)
-install_github("DOI-USGS/dataRetrieval",
-               build_vignettes = TRUE, 
-               build_opts = c("--no-resave-data",
-                              "--no-manual"))
-```
-
 If you have additional questions about these changes, email
 <[email protected]>.
 
@@ -137,14 +125,14 @@ NWIScitation
 #> U.S. Geological Survey (2025). _National Water Information System data
 #> available on the World Wide Web (USGS Water Data for the Nation)_.
 #> doi:10.5066/F7P55KJN <https://doi.org/10.5066/F7P55KJN>, Accessed Feb
-#> 03, 2025,
+#> 10, 2025,
 #> <https://waterservices.usgs.gov/nwis/dv/?site=09010500&format=waterml%2C1.1&ParameterCd=00060&StatCd=00003&startDT=1851-01-01>.
 print(NWIScitation, style = "Bibtex")
 #> @Manual{,
 #>   title = {National Water Information System data available on the World Wide Web (USGS Water Data for the Nation)},
 #>   author = {{U.S. Geological Survey}},
 #>   doi = {10.5066/F7P55KJN},
-#>   note = {Accessed Feb 03, 2025},
+#>   note = {Accessed Feb 10, 2025},
 #>   year = {2025},
 #>   url = {https://waterservices.usgs.gov/nwis/dv/?site=09010500&format=waterml%2C1.1&ParameterCd=00060&StatCd=00003&startDT=1851-01-01},
 #> }
@@ -168,14 +156,14 @@ WQPcitation <- create_WQP_bib(SC)
 WQPcitation
 #> National Water Quality Monitoring Council (2025). _Water Quality
 #> Portal_. doi:10.5066/P9QRKUVJ <https://doi.org/10.5066/P9QRKUVJ>,
-#> Accessed Feb 03, 2025,
+#> Accessed Feb 10, 2025,
 #> <https://www.waterqualitydata.us/data/Result/search?siteid=USGS-05288705&count=no&pCode=00300&mimeType=csv>.
 print(WQPcitation, style = "Bibtex")
 #> @Manual{,
 #>   title = {Water Quality Portal},
 #>   author = {{National Water Quality Monitoring Council}},
 #>   doi = {10.5066/P9QRKUVJ},
-#>   note = {Accessed Feb 03, 2025},
+#>   note = {Accessed Feb 10, 2025},
 #>   year = {2025},
 #>   url = {https://www.waterqualitydata.us/data/Result/search?siteid=USGS-05288705&count=no&pCode=00300&mimeType=csv},
 #> }

man/readWQPdata.Rd

@@ -155,7 +155,7 @@ The arguments `startDate` and `endDate` have defaults to request the maximum dat
 
 # USGS Web Retrievals
 
-In this section, examples of National Water Information System (NWIS) retrievals show how to get raw data into R. This data includes [site information](#site-information), measured [parameter information](#parameter-information), historical [daily values](#daily-data), [unit values](#unit-data) (which include real-time data but can also include other sensor data stored at regular time intervals), [water quality data](#water-quality-data), [groundwater level data](#groundwater-level-data), [peak flow data](#peak-flow-data), [rating curve data](#rating-curve-data),  [surface-water measurement data](#surface-water-measurement-data), [water use data](#water-use-data), and [statistics data](#statistics-data). The section [Embedded Metadata](#embedded-metadata) shows instructions for getting metadata that is attached to each returned data frame.
+In this section, examples of National Water Information System (NWIS) retrievals show how to get raw data into R. This data includes [site information](#site-information), measured [parameter information](#parameter-information), historical [daily values](#daily-data), [unit values](#unit-data) (which include real-time data but can also include other sensor data stored at regular time intervals), [groundwater level data](#groundwater-level-data), [peak flow data](#peak-flow-data), [rating curve data](#rating-curve-data),  [surface-water measurement data](#surface-water-measurement-data), [water use data](#water-use-data), and [statistics data](#statistics-data). The section [Embedded Metadata](#embedded-metadata) shows instructions for getting metadata that is attached to each returned data frame.
 
 The USGS organizes hydrologic data in a standard structure.  Streamgages are located throughout the United States, and each streamgage has a unique ID (referred in this document and throughout the `dataRetrieval` package as `siteNumber`).  Often (but not always), these ID's are 8 digits for surface-water sites and 15 digits for groundwater sites.  The first step to finding data is discovering this `siteNumber`. There are many ways to do this, one is the [National Water Information System: Mapper](https://maps.waterdata.usgs.gov/mapper/index.html).