Fix some time issues

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

@@ -34,7 +34,7 @@ jobs:
 
       - uses: r-lib/actions/setup-pandoc@6012817847b5f064d0882d67a7b5e2ca6639afb2
 
-      - uses: r-lib/actions/setup-r@473c68190595b311a74f208fba61a8d8c0d4c247
+      - uses: r-lib/actions/setup-r@cdfe59f7d9ed0bc33451d5e5d5d9dde04246fa59
         with:
           r-version: ${{ matrix.config.r }}
           http-user-agent: ${{ matrix.config.http-user-agent }}

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: dataRetrieval
 Type: Package
 Title: Retrieval Functions for USGS and EPA Hydrology and Water Quality Data
-Version: 2.7.22.9000
+Version: 2.7.22.9001
 Authors@R: c(
     person("Laura", "DeCicco", role = c("aut","cre"),
             email = "ldecicco@usgs.gov",
@@ -26,7 +26,7 @@ Authors@R: c(
             comment=c(ORCID = "0000-0003-2521-5043")),
     person("Lee", "Stanish", role="ctb",
             comment=c(ORCID = "0000-0002-9775-6861")),
-    person("Joseph", "Zemmels", role="ctb",
+    person("Joseph", "Zemmels", role="aut",
             email = "jzemmels@usgs.gov",
             comment=c(ORCID = "0009-0008-1463-6313")),
     person("Elise", "Hinman", role="aut",

NEWS

@@ -1,12 +1,17 @@
 dataRetrieval 2.7.22.9000
 ===================
 * Added data.table to Imports
-* Added data.table importFrom entries to NAMESPACE
 * Added read_waterdata_stats_por and read_waterdata_stats_daterange to access USGS daily data statistics.
 * Updated vignettes, examples, and README to reflect new stats functions.
 * Added tests for read_waterdata_stats functions
 * Updated next_req_url to allow paging through /statistics API output
-* Added deprecate message to readNWISstat function.
+* Added deprecation message to readNWISstat function
+* Specify "UTC" attribute for returned time
+* Added options("dataRetrieval.attach_request" = TRUE) as default to attach the 
+request object as an attribute to the returned data frames. Setting 
+options("dataRetrieval.attach_request" = FALSE) will return a data frame without
+the request attribute
+* Improved time documentation
 
 
 dataRetrieval 2.7.22

R/AAA.R

@@ -4,7 +4,8 @@ pkg.env <- new.env()
   suppressMessages(setAccess("public"))
   pkg.env$nldi_base <- "https://api.water.usgs.gov/nldi/linked-data/"
   pkg.env$local_sf <- requireNamespace("sf", quietly = TRUE)
-  options("dataRetrieval" = list("api_version" = "v0"))
+  options("dataRetrieval.api_version" = "v0")
+  options("dataRetrieval.attach_request" = TRUE)
 
   services <- c("server", "daily", "time-series-metadata",
                "monitoring-locations", "latest-continuous",

R/construct_api_requests.R

@@ -173,7 +173,7 @@ check_limits <- function(args){
 base_url <- function(){
 
   httr2::request("https://api.waterdata.usgs.gov/ogcapi/") |> 
-    httr2::req_url_path_append(getOption("dataRetrieval")$api_version) 
+    httr2::req_url_path_append(getOption("dataRetrieval.api_version")) 
 }
 
 #' Setup the request for a particular endpoint collection
@@ -238,7 +238,7 @@ switch_arg_id <- function(ls, id_name, service){
 #' period requests. 
 #' 
 #' @param datetime character, Date, or POSIX
-#' @param format character
+#' @param date logical, whether to return Date or POSIX
 #' 
 #' @noRd
 #' @return character vector with a length of either 1 or 2.
@@ -260,6 +260,7 @@ switch_arg_id <- function(ls, id_name, service){
 #' 
 #' end <- c(NA, "2021-01-01")
 #' dataRetrieval:::format_api_dates(end)
+#' dataRetrieval:::format_api_dates(end, TRUE)
 #' 
 #' end <- c(NA, as.POSIXct("2021-01-01 12:15:00"))
 #' dataRetrieval:::format_api_dates(end)
@@ -287,57 +288,106 @@ switch_arg_id <- function(ls, id_name, service){
 #' 
 #' time = c("2014-05-01T00:00Z", "2014-05-01T12:00Z")
 #' dataRetrieval:::format_api_dates(time)
+#' 
+#' start <- "2025-10-01"
+#' end <- Sys.Date()
+#' dataRetrieval:::format_api_dates(c(start, end), date = TRUE)
 format_api_dates <- function(datetime, date = FALSE){
 
   if(is.character(datetime)){
     datetime[datetime == ""] <- NA
+    datetime <- toupper(datetime)
   }
 
-  if(!any(isTRUE(all(is.na(datetime))) | isTRUE(is.null(datetime)))){
-    if(length(datetime) == 1){
-      # If the user has "P" or the "/" we assume they know what they are doing
-      if(grepl("P", datetime, ignore.case = TRUE) |
-         grepl("/", datetime)){
-        return(datetime)
-      } else {
-        datetime1 <- tryCatch({
-            lubridate::as_datetime(datetime)
-          },
-          warning = function(w) {
-            strptime(datetime, format = "%Y-%m-%dT%H:%MZ", tz = "UTC")
-        })
-        if(date){
-          datetime <- format(datetime1, "%Y-%m-%d")
-        } else {
-          datetime <- lubridate::format_ISO8601(datetime1, usetz = "Z")
-        }
-      }
-    } else if (length(datetime) == 2) {
-
-      datetime1 <- tryCatch({
-          lubridate::as_datetime(datetime)
-        },
-        warning = function(w) {
-          strptime(datetime, format = "%Y-%m-%dT%H:%MZ", tz = "UTC")
-      })
-
+  if(all(is.na(datetime))){
+    return(NA)
+  }
+
+  if(all(is.null(datetime))){
+    return(NA)
+  }
+
+  if(length(datetime) > 2){
+    stop("datetime should only include 1-2 values")
+  }
+
+  if(length(datetime) == 1){
+    # If the user has "P" or the "/" we assume they know what they are doing
+    if(grepl("P", datetime, ignore.case = TRUE) |
+       grepl("/", datetime)){
+      return(datetime)
+    } else {
+
       if(date){
-        datetime <- paste0(format(datetime1, "%Y-%m-%d"), collapse = "/")
+        datetime <- get_Date(datetime)
       } else {
-        datetime <- paste0(lubridate::format_ISO8601(datetime1, usetz = "Z"), 
-                           collapse = "/")
+        datetime1 <- get_dateTime(datetime)
+        datetime <- lubridate::format_ISO8601(datetime1, usetz = "Z")
       }
+    }
+  } else if (length(datetime) == 2) {
 
-      datetime <- gsub("NA", "..", datetime)
+    if(date){
+      for(i in seq_along(datetime)){
+        datetime[i] <- get_Date(datetime[i])
+      }
+      datetime <- paste0(datetime, collapse = "/")
     } else {
-      stop("datetime should only include 1-2 values")
+      for(i in seq_along(datetime)){
+        datetime1 <- get_dateTime(datetime)
+      }
+      datetime <- paste0(lubridate::format_ISO8601(datetime1, usetz = "Z"), 
+                         collapse = "/")
     }
-  } else {
-    datetime <- NA
-  }
+
+    datetime <- gsub("NA", "..", datetime)
+  } 
+
   return(datetime)
 }
 
+get_dateTime <- function(d){
+
+  temp_date <- tryCatch({
+    strptime(d, format = "%Y-%m-%dT%H:%MZ", tz = "UTC")
+  })
+
+  if(all(is.na(temp_date))){
+    temp_date <- tryCatch({
+      lubridate::as_datetime(d)
+    },
+    error = function(e) {
+      NA
+    })    
+  }
+
+  return(temp_date)
+
+}
+
+get_Date <- function(d){
+  temp_date <- tryCatch({
+    as.Date(d)
+  },
+  error = function(e) {
+    "try again"
+  })
+
+  if(is.na(temp_date)){
+    return("..")
+  } else if(as.character(temp_date) == "try again"){
+    temp_date <- tryCatch({
+      as.Date(as.numeric(d), origin = "1970-01-01")
+    },
+    error = function(e) {
+      "try again"
+    })        
+  }
+
+  return(as.character(temp_date))
+}
+
+
 #' Turn request list into POST body cql
 #' 
 #' @noRd

R/get_ogc_data.R

@@ -61,7 +61,10 @@ get_ogc_data <- function(args,
                                output_id)
   }
 
-  attr(return_list, "request") <- req
+  if(getOption("dataRetrieval.attach_request")){
+    attr(return_list, "request") <- req
+  }
+
   attr(return_list, "queryTime") <- Sys.time()
   return(return_list)
 }

R/importRDB1.R

@@ -119,8 +119,12 @@ importRDB1 <- function(obs_url,
     }
     doc <- obs_url
   } 
-
-  readr.total <- readr::read_lines(doc)
+  if(file.exists(doc)){
+    readr.total <- readr::read_lines(doc)
+  } else {
+    readr.total <- readr::read_lines(I(doc))
+  }
+
   if(readr.total[length(readr.total)] == ""){
     readr.total <- readr.total[-length(readr.total)]
   }

R/read_waterdata_continuous.R

@@ -15,15 +15,16 @@
 #' Multiple monitoring_location_ids can be requested as a character vector.
 #' @param parameter_code `r get_ogc_params("continuous")$parameter_code`
 #' Multiple parameter_codes can be requested as a character vector.
-#' @param time `r get_ogc_params("continuous")$time`. 
-#' You can also use a vector of length 2: the first value being the starting date,
-#' the second value being the ending date. NA's within the vector indicate a
-#' half-bound date. For example, c("2024-01-01", NA) will return all data starting
-#' at 2024-01-01.
+#' @param time `r get_ogc_params("continuous")$time`
+#' 
+#' See also Details below for more information.
+#' 
 #' @param value `r get_ogc_params("continuous")$value`
 #' @param unit_of_measure `r get_ogc_params("continuous")$unit_of_measure`
 #' @param approval_status `r get_ogc_params("continuous")$approval_status`
 #' @param last_modified `r get_ogc_params("continuous")$last_modified`
+#' 
+#' See also Details below for more information.
 #' @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`
@@ -43,16 +44,35 @@
 #' be requested from a native csv format. This can be dangerous because the
 #' data will cut off at 50,000 rows without indication that more data
 #' is available. Use `TRUE` with caution. 
+#' 
+#' @details 
+#' You can also use a vector of length 2 for any time queries (such as time
+#' or last_modified). The first value is the starting date (or datetime), 
+#' the second value is the ending date(or datetime).
+#' NA's within the vector indicate a half-bound date. 
+#' For example, \code{time = c("2024-01-01", NA)} will return all data starting
+#' at 2024-01-01. 
+#' \code{time = c(NA, "2024-01-01")} will return all data from the beginning of 
+#' the timeseries until 2024-01-01.
+#' By default, time is assumed UTC, although time zone attributes
+#' will be accommodated. As an example, setting \code{time = as.POSIXct(c("2021-01-01 12:00:00",
+#' "2021-01-01 14:00"), tz = "America/New_York")} will request data that between
+#' noon and 2pm eastern time on 2021-01-01.
+#' All time values RETURNED from the service are UTC with the exception of 
+#' daily data, which returns time values in local dates.
+#' 
 #' @examplesIf is_dataRetrieval_user()
 #' 
 #' \donttest{
 #' site <- "USGS-451605097071701"
 #' pcode <- "72019"
 #'
 #' uv_data_trim <- read_waterdata_continuous(monitoring_location_id = site,
-#'                           parameter_code = pcode, 
-#'                           properties = c("value",
-#'                                          "time"))
+#'                            parameter_code = pcode, 
+#'                            properties = c("value", "time"),
+#'                            time = as.POSIXct(c("2026-02-07 12:00", 
+#'                                                "2026-02-08 12:00"), 
+#'                                               tz = "America/Chicago"))
 #'
 #' uv_data <- read_waterdata_continuous(monitoring_location_id = site,
 #'                            parameter_code = pcode,
@@ -90,6 +110,7 @@ read_waterdata_continuous <- function(monitoring_location_id = NA_character_,
                               output_id, 
                               service)
 
+  attr(return_list$time, "tzone") <- "UTC"
   return(return_list)
 }
 

R/read_waterdata_daily.R

@@ -10,14 +10,14 @@
 #' @param statistic_id `r get_ogc_params("daily")$statistic_id`
 #' Multiple statistic_ids can be requested as a character vector.
 #' @param time `r get_ogc_params("daily")$time`
-#' You can also use a vector of length 2: the first value being the starting date,
-#' the second value being the ending date. NA's within the vector indicate a
-#' half-bound date. For example, c("2024-01-01", NA) will return all data starting
-#' at 2024-01-01.
+#' 
+#' See also Details below for more information.
 #' @param value `r get_ogc_params("daily")$value`
 #' @param unit_of_measure `r get_ogc_params("daily")$unit_of_measure`
 #' @param approval_status `r get_ogc_params("daily")$approval_status`
 #' @param last_modified `r get_ogc_params("daily")$last_modified`
+#' 
+#' See also Details below for more information.
 #' @param time_series_id `r get_ogc_params("daily")$time_series_id`
 #' Multiple time_series_ids can be requested as a character vector.
 #' @param qualifier `r get_ogc_params("daily")$qualifier`
@@ -45,6 +45,9 @@
 #' be requested from a native csv format. This can be dangerous because the
 #' data will cut off at 50,000 rows without indication that more data
 #' is available. Use `TRUE` with caution. 
+#' 
+#' @inherit read_waterdata_continuous details
+#' 
 #' @examplesIf is_dataRetrieval_user()
 #' 
 #' \donttest{
@@ -82,7 +85,11 @@
 #'                                    
 #' dv_post <- read_waterdata_daily(monitoring_location_id = site,
 #'                                 approval_status = c("Approved", "Provisional"))
-#' 
+#' # Don't attach "request" attribute:
+#' options("dataRetrieval.attach_request" = FALSE)
+#' dv_data_no_request <- read_waterdata_daily(monitoring_location_id = site,
+#'                               parameter_code = "00060", 
+#'                               time = c("2021-01-01", "2022-01-01"))
 #' }
 read_waterdata_daily <- function(monitoring_location_id = NA_character_,
                                  parameter_code = NA_character_,