Update vignette

R/read_USGS_daily.R

@@ -67,7 +67,6 @@ read_USGS_daily <- function(monitoring_location_id = NA_character_,
                          parameter_code = NA_character_,
                          statistic_id = NA_character_,
                          properties = NA_character_,
-                         bbox = NA,
                          time_series_id = NA_character_,
                          daily_id = NA_character_,
                          approval_status = NA_character_,
@@ -78,6 +77,7 @@ read_USGS_daily <- function(monitoring_location_id = NA_character_,
                          limit = 10000,
                          skipGeometry = NA,
                          time = NA_character_,
+                         bbox = NA,
                          convertType = TRUE){
 
   message("Function in development, use at your own risk.")

R/read_USGS_data.R

@@ -71,7 +71,10 @@ read_USGS_data <- function(service,
 
   if(convertType) return_list <- cleanup_cols(return_list)
 
-  return_list <- return_list[order(return_list$time, return_list$monitoring_location_id), ]
+  # Add other time series services when they come online
+  if(service %in% c("daily")){
+    return_list <- return_list[order(return_list$time, return_list$monitoring_location_id), ]
+  }
 
   return_list <- rejigger_cols(return_list, args[["properties"]], service)
 

README.Rmd

@@ -27,7 +27,7 @@ library(dataRetrieval)
 [![](http://cranlogs.r-pkg.org/badges/dataRetrieval)](https://cran.r-project.org/package=dataRetrieval)
 [![](http://cranlogs.r-pkg.org/badges/grand-total/dataRetrieval)](https://cran.r-project.org/package=dataRetrieval)
 
-The `dataRetrieval` package was created to simplify the process of loading hydrologic data into the R environment. It is designed to retrieve the major data types of U.S. Geological Survey (USGS) hydrology data that are available on the Web, as well as data from the Water Quality Portal (WQP), which currently houses water quality data from the Environmental Protection Agency (EPA), U.S. Department of Agriculture (USDA), and USGS. Direct USGS data is obtained from a service called the National Water Information System (NWIS). 
+The `dataRetrieval` package was created to simplify the process of loading hydrologic data into the R environment. It is designed to retrieve the major data types of U.S. Geological Survey (USGS) hydrology data that are available on the Web, as well as data from the Water Quality Portal (WQP), which currently houses water quality data from the Environmental Protection Agency (EPA), U.S. Department of Agriculture (USDA), and USGS. 
 
 # Introduction
 
@@ -37,17 +37,19 @@ If you have additional questions about these changes, email CompTools@usgs.gov.
 
 # What would you like to do?
 
-1. Get instantaneous USGS discharge data. Start here: `?readNWISuv`
+1. Get instantaneous USGS data (for example, discharge sensor data). Start here: `?readNWISuv`
 
-2. Get daily USGS discharge data. Start here: `?readNWISdv`
+2. Get daily USGS data (for example, mean daily discharge). Start here: `?read_USGS_daily`
 
 3. Get USGS groundwater data. Start here: `?readNWISgwl`
 
-4. Get discrete water quality data. Start here: `?readWQPdata`
+4. Get discrete water quality data from a cooperative service that integrates publicly available water-quality data from the USGS, EPA, and over 400 state, federal, tribal, and local agencies. Start here: `?readWQPdata`
 
-4. Discover USGS data (not including discrete water quality data). Start here: `?whatNWISdata`
+5. Get USGS discrete water quality data. Start here: `?read_USGS_samples`
 
-6. Find Hydro Network-Linked Data Index (NLDI) data. Start here: `?findNLDI`
+6. Discover USGS time series data. Start here: `?read_USGS_ts_meta`
+
+7. Find Hydro Network-Linked Data Index (NLDI) data. Start here: `?findNLDI`
 
 For additional tutorials, see:
 
@@ -70,6 +72,18 @@ install.packages("dataRetrieval")
 
 The USGS is planning to modernize all web services in the near future. For each of these updates, `dataRetrieval` will create a new function to access the new services. 
 
+## API Token
+
+You can register an API key for use with USGS water data APIs. There are now limits on how many queries can be requested per IP address per hour. If you find yourself running into limits, you can request an API token here: <https://api.waterdata.usgs.gov/signup/>
+
+Then save your token in your .Renviron file like this:
+
+```
+API_USGS_PAT = "my_super_secret_token"
+```
+
+You can use `usethis::edit_r_environ()` to edit find and open your .Renviron file. You will need to restart R for that variable to be recognized. 
+
 ## New Features
 
 ### Style
@@ -160,7 +174,7 @@ Water Quality Portal. Washington (DC): National Water Quality Monitoring Council
 
 # Package Support
 
-The Water Mission Area of the USGS supports the development and maintenance of `dataRetrieval`, and most likely further into the future. Resources are available primarily for maintenance and responding to user questions. Priorities on the development of new features are determined by the `dataRetrieval` development team. This software was last released with USGS record: IP-147158.
+The Water Mission Area of the USGS supports the development and maintenance of `dataRetrieval`, and most likely further into the future. Resources are available primarily for maintenance and responding to user questions. Priorities on the development of new features are determined by the `dataRetrieval` development team.
 
 ```{r disclaimer, child="DISCLAIMER.md", eval=TRUE}
 ```

README.md

@@ -11,8 +11,7 @@ retrieve the major data types of U.S. Geological Survey (USGS) hydrology
 data that are available on the Web, as well as data from the Water
 Quality Portal (WQP), which currently houses water quality data from the
 Environmental Protection Agency (EPA), U.S. Department of Agriculture
-(USDA), and USGS. Direct USGS data is obtained from a service called the
-National Water Information System (NWIS).
+(USDA), and USGS.
 
 # Introduction
 
@@ -28,18 +27,25 @@ If you have additional questions about these changes, email
 
 # What would you like to do?
 
-1.  Get instantaneous USGS discharge data. Start here: `?readNWISuv`
+1.  Get instantaneous USGS data (for example, discharge sensor data).
+    Start here: `?readNWISuv`
 
-2.  Get daily USGS discharge data. Start here: `?readNWISdv`
+2.  Get daily USGS data (for example, mean daily discharge). Start here:
+    `?read_USGS_daily`
 
 3.  Get USGS groundwater data. Start here: `?readNWISgwl`
 
-4.  Get discrete water quality data. Start here: `?readWQPdata`
+4.  Get discrete water quality data from a cooperative service that
+    integrates publicly available water-quality data from the USGS, EPA,
+    and over 400 state, federal, tribal, and local agencies. Start here:
+    `?readWQPdata`
 
-5.  Discover USGS data (not including discrete water quality data).
-    Start here: `?whatNWISdata`
+5.  Get USGS discrete water quality data. Start here:
+    `?read_USGS_samples`
 
-6.  Find Hydro Network-Linked Data Index (NLDI) data. Start here:
+6.  Discover USGS time series data. Start here: `?read_USGS_ts_meta`
+
+7.  Find Hydro Network-Linked Data Index (NLDI) data. Start here:
     `?findNLDI`
 
 For additional tutorials, see:
@@ -68,6 +74,21 @@ The USGS is planning to modernize all web services in the near future.
 For each of these updates, `dataRetrieval` will create a new function to
 access the new services.
 
+## API Token
+
+You can register an API key for use with USGS water data APIs. There are
+now limits on how many queries can be requested per IP address per hour.
+If you find yourself running into limits, you can request an API token
+here: <https://api.waterdata.usgs.gov/signup/>
+
+Then save your token in your .Renviron file like this:
+
+    API_USGS_PAT = "my_super_secret_token"
+
+You can use `usethis::edit_r_environ()` to edit find and open your
+.Renviron file. You will need to restart R for that variable to be
+recognized.
+
 ## New Features
 
 ### Style
@@ -170,15 +191,15 @@ NWIScitation <- create_NWIS_bib(dv)
 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 Mar
-#> 25, 2025,
+#> doi:10.5066/F7P55KJN <https://doi.org/10.5066/F7P55KJN>, Accessed Jun
+#> 03, 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 Mar 25, 2025},
+#>   note = {Accessed Jun 03, 2025},
 #>   year = {2025},
 #>   url = {https://waterservices.usgs.gov/nwis/dv/?site=09010500&format=waterml%2C1.1&ParameterCd=00060&StatCd=00003&startDT=1851-01-01},
 #> }
@@ -202,14 +223,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 Mar 25, 2025,
+#> Accessed Jun 03, 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 Mar 25, 2025},
+#>   note = {Accessed Jun 03, 2025},
 #>   year = {2025},
 #>   url = {https://www.waterqualitydata.us/data/Result/search?siteid=USGS-05288705&count=no&pCode=00300&mimeType=csv},
 #> }
@@ -229,8 +250,7 @@ The Water Mission Area of the USGS supports the development and
 maintenance of `dataRetrieval`, and most likely further into the future.
 Resources are available primarily for maintenance and responding to user
 questions. Priorities on the development of new features are determined
-by the `dataRetrieval` development team. This software was last released
-with USGS record: IP-147158.
+by the `dataRetrieval` development team.
 
 # Disclaimer
 

_pkgdown.yml

@@ -40,6 +40,8 @@ navbar:
     menu:
     - text: Tutorial
       href: articles/tutorial.html
+    - text: New USGS Functions
+      href: articles/read_USGS_functions.html
     - text: Background
       href: articles/dataRetrieval.html
     - text: Pivot Data

tests/testthat/tests_userFriendly_fxns.R

@@ -160,16 +160,16 @@ test_that("WQP qw tests", {
   nameToUse <- "Specific conductance"
   pcodeToUse <- "00095"
 
-  # INFO_WQP <- readWQPqw("USGS-04024315", pcodeToUse, 
-  #                       startDate = "", endDate = "", legacy = FALSE)
-  # expect_is(INFO_WQP$Activity_StartDateTime, "POSIXct")
-  # 
-  # INFO2 <- readWQPqw("WIDNR_WQX-10032762", nameToUse, 
-  #                    startDate = "", endDate = "", legacy = FALSE)
-  # expect_is(INFO2$Activity_StartDateTime, "POSIXct")
-  # 
-  # df <- readWQPqw("USGS-04193500", parameterCd = "00665", legacy = FALSE)
-  # expect_true(nrow(df) > 0)
+  INFO_WQP <- readWQPqw("USGS-04024315", pcodeToUse,
+                        startDate = "", endDate = "", legacy = FALSE)
+  expect_is(INFO_WQP$Activity_StartDateTime, "POSIXct")
+
+  INFO2 <- readWQPqw("WIDNR_WQX-10032762", nameToUse,
+                     startDate = "", endDate = "", legacy = FALSE)
+  expect_is(INFO2$Activity_StartDateTime, "POSIXct")
+
+  df <- readWQPqw("USGS-04193500", parameterCd = "00665", legacy = FALSE)
+  expect_true(nrow(df) > 0)
 
   df2 <- readWQPqw("USGS-05427718", parameterCd = "all")
   expect_true(nrow(df2) > 0)