Update docs

Author: ldecicco-USGS

NEWS

@@ -1,6 +1,7 @@
 dataRetrieval 2.7.22
 ===================
 * Added read_waterdata_latest_daily to access latest daily USGS water data.
+* Added read_waterdata_continuous to access continuous USGS water data.
 * Added state_name and hydrologic_unit_code to read_waterdata_ts_meta
 
 dataRetrieval 2.7.21

tutorials/basic_slides_deck.qmd

@@ -437,9 +437,9 @@ We're going walk through 3 retrievals:
 
 * **Workflow 4**: Continuous Data
 
-  - Uses the NWIS web services
+  - Uses the new USGS Water Data API 
 
-  - Will be deprecated, this fall we'll have `read_waterdata_continuous`
+  - Modern data access point going forward
 
 * **Workflow 5**: Join Continuous and Discrete
 
@@ -814,10 +814,6 @@ band_instruments |>
 
 * Continuous data is the high-frequency sensor data. 
 
-* The function to get that data today is `readNWISuv`
-
-* As NWIS gets deprecated, we expect to have `read_waterdata_continuous` soon
-
 * We'll look at Suisun Bay a Van Sickle Island NR Pittsburg CA ("USGS-11455508"), with parameter code "99133" which is Nitrate plus Nitrite.
 
 ## Workflow 4: Continuous data for known site
@@ -828,15 +824,14 @@ band_instruments |>
 
 ```{r}
 #| results: markup
-site_id <- "11455508"
+site_id <- "USGS-11455508"
 p_code_rt <- "99133"
 start_date <- "2024-01-01"
 end_date <- "2024-06-01"
 
-continuous_data <- readNWISuv(site_id,
-                              p_code_rt,
-                              start_date,
-                              end_date)
+continuous_data <- read_waterdata_continuous(monitoring_location_id = site_id,
+                                             parameter_code = p_code_rt,
+                                             time = c(start_date, end_date))
                  
 names(continuous_data)
 ```
@@ -846,28 +841,26 @@ names(continuous_data)
 ::: {.column width="30%"}
 
 ```
-[1] "agency_cd"       
-[2] "site_no"         
-[3] "dateTime"        
-[4] "X_99133_00000"   
-[5] "X_99133_00000_cd"
-[6] "tz_cd" 
+ [4] "time"                   "unit_of_measure"        "parameter_code"        
+ [7] "statistic_id"           "value"                  "approval_status"       
+[10] "last_modified"          "qualifier"  
 ```
 :::
 
 ::::
 
 ```
-GET: https://nwis.waterservices.usgs.gov/nwis/iv/?site=11455508&format=waterml%2C1.1&ParameterCd=99133&startDT=2024-01-01&endDT=2024-06-01
+Requesting:
+https://api.waterdata.usgs.gov/ogcapi/v0/collections/continuous/items?f=json&lang=en-US&skipGeometry=TRUE&limit=40000&monitoring_location_id=USGS-11455508&parameter_code=99133&time=2024-01-01T00%3A00%3A00Z%2F2024-06-01T00%3A00%3A00Z
 ```
 
 ## Workflow 4: Inspect
 
 ```{r}
 #| output-location: column
 ggplot(data = continuous_data) +
-  geom_point(aes(x = dateTime, 
-                 y = X_99133_00000))
+  geom_point(aes(x = time, 
+                 y = value))
 ```
 
 ## Workflow 5: Join Discrete and Continuous 
@@ -901,7 +894,7 @@ discrete_data <- read_waterdata_samples(monitoringLocationIdentifier = "USGS-114
 #| code-line-numbers: "1|2-3|5|6|1-6"
 library(data.table)
 setDT(discrete_data)[, join_date := Activity_StartDateTime]
-setDT(continuous_data)[, join_date := dateTime]
+setDT(continuous_data)[, join_date := time]
   
 closest_dt <- continuous_data[discrete_data, on = .(join_date), roll = "nearest"]  
 closest_dt <- data.frame(closest_dt)
@@ -917,7 +910,7 @@ closest_dt <- data.frame(closest_dt)
 #| output-location: column
 ggplot(data = closest_dt) +
   geom_point(aes(x = Result_Measure,
-                 y = X_99133_00000)) +
+                 y = value)) +
   geom_abline() +
   expand_limits(x = 0, y = 0) +
   xlab("Discrete") +

tutorials/changes_slides_deck.qmd

@@ -137,7 +137,9 @@ Open Geospatial Consortium (OGC), a non-profit international organization that d
 
 * [read_waterdata_field_measurements](https://doi-usgs.github.io/dataRetrieval/reference/read_waterdata_field_measurements.html) - Discrete hydrologic data (gage height, discharge, and readings of groundwater levels)
 
-* [read_waterdata](https://doi-usgs.github.io/dataRetrieval/reference/read_waterdata.html) - Generalized function
+* [read_waterdata_continuous](https://doi-usgs.github.io/dataRetrieval/reference/read_waterdata_continuous.html) - Continuous data are collected via automated sensors installed at a monitoring location.
+
+* [read_waterdata](https://doi-usgs.github.io/dataRetrieval/reference/read_waterdata.html) - Generalized function.
 
 * [read_waterdata_metadata](https://doi-usgs.github.io/dataRetrieval/reference/read_waterdata_metadata.html) - Metadata 
 
@@ -622,6 +624,25 @@ leaflet(data = latest_dane_county_daily |>
               values = ~value)
 ```
 
+## read_waterdata_continuous
+
+Replaces `readNWISuv`:
+
+```{r}
+this_week <- read_waterdata_continuous(monitoring_location_id = c("USGS-05406457",
+                                                         "USGS-05427930"),
+                              parameter_code = c("00060", "00010"),
+                              time = "P7D")
+```
+
+Currently only allows 3 years of data to be queried at once. 
+
+::: footer
+
+:::
+
+
+
 ## read_waterdata
 
 * This function is totally different!

vignettes/dataRetrieval.Rmd

@@ -60,7 +60,7 @@ Table 1 describes the functions available in the `dataRetrieval` package.
 Functions <- c(
   "read_waterdata",
   "read_waterdata_daily",
-  "readNWISuv",
+  "read_waterdata_continuous",
   "readNWISrating",
   "read_waterdata_field_measurements",
   "readNWISpeak",
@@ -108,7 +108,8 @@ Description <- c(
 )
 Source <- c("USGS Water Data API",
             "USGS Water Data API",
-            rep("NWIS",2),
+            "USGS Water Data API",
+            "NWIS",
             "USGS Water Data API",
             "NWIS",
             "USGS Water Data API",
@@ -352,32 +353,21 @@ Any data collected at regular time intervals (such as 15-minute or hourly) are k
 parameterCd <- "00060" # Discharge
 startDate <- "2012-05-12"
 endDate <- "2012-05-13"
-dischargeUnit <- readNWISuv(siteNumber, parameterCd, startDate, endDate)
-dischargeUnit <- renameNWISColumns(dischargeUnit)
+dischargeUnit <- read_waterdata_continuous(monitoring_location_id = siteNumber,
+                                           parameter_code = parameterCd,
+                                           time = c(startDate, endDate))
+
 ```
 
 The retrieval produces a data frame that contains 96 rows (one for every 15 minute period in the day).  They include all data collected from the `startDate` through the `endDate` (starting and ending with midnight locally-collected time). The dateTime column is converted to UTC (Coordinated Universal Time), so midnight EST will be 5 hours earlier in the dateTime column (the previous day, at 7pm).
 
-To override the UTC timezone, specify a valid timezone in the tz argument. Default is "", which will keep the dateTime column in UTC. Other valid timezones are:
 
-```
-America/New_York
-America/Chicago
-America/Denver
-America/Los_Angeles
-America/Anchorage
-America/Honolulu
-America/Jamaica
-America/Managua
-America/Phoenix
-America/Metlakatla
-```
 
-Data are retrieved from [https://waterservices.usgs.gov/docs/instantaneous-values/](https://waterservices.usgs.gov/docs/instantaneous-values/). There are occasions where NWIS values are not reported as numbers, instead a common example is "Ice".  Any value that cannot be converted to a number will be reported as NA in this package. Site information and measured parameter information is attached to the data frame as attributes. This is discussed further in [metadata](#embedded-metadata) section.
+Data are retrieved from <https://api.waterdata.usgs.gov/ogcapi/v0/>. Site information and measured parameter information is attached to the data frame as attributes. This is discussed further in [metadata](#embedded-metadata) section.
 
 ## Groundwater Level Data
 
-Groundwater level measurements can be obtained with the `readNWISgwl` function. Information on the returned data can be found with the `comment` function, and attached attributes as described in the [metadata](#embedded-metadata) section.
+Groundwater level measurements can be obtained with the `read_waterdata_field_measurements` function. 
 
 ```{r gwlexample, echo=TRUE, eval=FALSE}
 siteNumber <- "USGS-434400121275801"
@@ -411,7 +401,7 @@ attr(ratingData, "RATING")
 
 These data are the discrete measurements of discharge that are made for the purpose of developing or revising the rating curve.  Information on the returned data can be found with the `comment` function and attached attributes as described in the [metadata](#embedded-metadata) section.
 
-Surface-water measurement data can be obtained with the `readNWISmeas` function.
+Surface-water measurement data can be obtained with the `read_waterdata_field_measurements`` function.
 
 ```{r surfexample, echo=TRUE, eval=FALSE}
 surfaceData <- read_waterdata_field_measurements(monitoring_location_id = "USGS-01594440")

vignettes/join_by_closest.Rmd

@@ -9,8 +9,8 @@ output:
 vignette: >
   %\VignetteIndexEntry{Join by closest date}
   \usepackage[utf8]{inputenc}
-  %\VignetteEngine{knitr::rmarkdown}
   %\VignetteDepends{dplyr}
+  %\VignetteEngine{knitr::rmarkdown}
 editor_options: 
   chunk_output_type: console
 ---
@@ -40,7 +40,7 @@ Let's look at site "01646500", and a nearby site with a real-time nitrate-plus-n
 ```{r getData}
 library(dataRetrieval)
 
-site_uv <- "01646500"
+site_uv <- "USGS-01646500"
 site_qw <- "USGS-01646580"
 pcode_uv <- "99133"
 pcode_qw <- "00631"
@@ -50,31 +50,11 @@ qw_data <- readWQPqw(site_qw, pcode_qw,
                      startDate = start_date,
                      endDate = end_date)
 
-uv_data <- readNWISuv(siteNumbers = site_uv, 
-                      parameterCd = c(pcode_uv, "00060"),
-                      startDate = start_date,
-                     endDate = end_date)
-```
-
-
-The sensor data ("uv" data) at this particular site has 2 columns of data that are important. The first task is to combine those columns. This is rather unique to this particular site and probably won't need to be done generally.
-
-```{r trimUVdata}
-library(dplyr)
-
-uv_trim <- uv_data |> 
-  select(uv_date = dateTime, 
-         val1 = X_SUNA...Discontinued._99133_00000,
-         val2 = X_SUNA_99133_00000,
-         flow = X_00060_00000) |> 
-  mutate(val_uv = if_else(is.na(val1), val2, val1)) |> 
-  select(-val1, -val2)
-
+uv_data <- read_waterdata_continuous(monitoring_location_id = site_uv,
+                                     parameter_code =  c(pcode_uv),
+                                     time = c(start_date, end_date))
 ```
 
-```{r showuvTrim, echo=FALSE}
-knitr::kable(head(uv_trim))
-```
 
 Next we'll clean up the discrete water quality "qw" data to make it easy to follow in this tutorial. 
 
@@ -98,9 +78,9 @@ library(data.table)
 
 setDT(qw_trim)[, join_date := qw_date]
 
-setDT(uv_trim)[, join_date := uv_date]
+setDT(uv_data)[, join_date := time]
 
-closest_dt <- uv_trim[qw_trim, on = .(join_date), roll = "nearest"]
+closest_dt <- uv_data[qw_trim, on = .(join_date), roll = "nearest"]
 ```
 
 `closest_dt` is a `data.table` object. It similar to a data.frame, but not identical. We can convert it to a data.frame and then use `dplyr` commands. Note: the whole analysis can be done via `data.table`, but most examples in `dataRetrieval` have used `dplyr`, which is why we bring it back to data.frame. `dplyr` also has a `join_by(closest())` option, but it is more complicated because you can only specify the closeness in either the forward or backwards direction (and we want either direction).
@@ -109,9 +89,9 @@ We can calculate "delta_time" - the difference in time between the uv and qw dat
 
 ```{r}
 qw_closest <- data.frame(closest_dt) |> 
-  mutate(delta_time = difftime(qw_date, uv_date, 
+  mutate(delta_time = difftime(qw_date, time, 
                                units = "hours"),
-         val_uv = if_else(abs(as.numeric(delta_time)) >= 24, NA, val_uv)) |> 
+         val_uv = if_else(abs(as.numeric(delta_time)) >= 24, NA, value)) |> 
   select(-join_date)
 
 ```
@@ -134,21 +114,11 @@ ggplot(data = qw_closest) +
 
 ```
 
-```{r}
-ggplot(data = qw_closest) +
-  geom_point(aes(x = flow, y = val_qw)) +
-  theme_bw() +
-  xlab("Discharge") +
-  ylab("Concentration") +
-  scale_x_log10() +
-  scale_y_log10()
-
-```
 
 ```{r}
 ggplot() +
-  geom_line(data = uv_trim,
-            aes(x = uv_date, val_uv),
+  geom_line(data = uv_data,
+            aes(x = time, value),
             color = "lightgrey") +
   geom_point(data = qw_closest,
              aes(x = qw_date, y = val_qw),

vignettes/read_waterdata_functions.Rmd

@@ -181,6 +181,23 @@ ggplot(data = daily_modern) +
 
 ```
 
+## Continuous
+
+The `read_waterdata_continuous` function replaces the `readNWISuv` function.
+
+`r dataRetrieval:::get_description("continuous")`
+
+To access these services on a web browser, go to <https://api.waterdata.usgs.gov/ogcapi/v0/collections/continuous>.
+
+```{r}
+sensor_data <- read_waterdata_continuous(monitoring_location_id = "USGS-01491000",
+                                parameter_code = c("00060", "00010"),
+                                statistic_id = "00003",
+                                time = c("2023-10-01", "2024-09-30"))
+```
+
+Currently this service only allows up to 3 years of data to be requested at once. If no time is specified in the query, the latest year of data is returned.
+
 ## Field Measurements
 
 The `read_waterdata_field_measurements` replaces both the `readNWISgwl` and `readNWISmeas` functions.