Merge pull request #80 from uace-azmet/add-lwdaily-fxn

Add lwdaily fxn

NAMESPACE

@@ -7,5 +7,6 @@ export(az_daily)
 export(az_heat)
 export(az_hourly)
 export(az_lw15min)
+export(az_lwdaily)
 importFrom(magrittr,"%>%")
 importFrom(rlang,.data)

NEWS.md

@@ -1,5 +1,6 @@
 # azmetr (development version)
 
+- Added function `az_lwdaily()` for downloading daily leaf wetness data, which now are available via the API
 - Added function `az_lw15min()` for downloading 15-minute (a.k.a. "real-time") leaf wetness data, which now are available via the API
 - Added function `az_15min()` for downloading 15-minute (a.k.a. "real-time") data, which now are available via the API
 

R/az_15min.R

@@ -1,7 +1,8 @@
 #' Retrieve 15-minute Weather Data from AZMet
 #'
 #' Retrieves 15-minute data from the AZMet (Arizona Meteorological Network) API.
-#' For a list of weather stations and their locations see [station_info].
+#' For a list of weather stations and their locations see [station_info], or
+#' visit https://azmet.arizona.edu/about.
 #'
 #' @param station_id Station ID can be supplied as numeric vector (e.g.
 #'   `station_id = c(8, 37)`) or as character vector with the prefix "az" and
@@ -16,17 +17,17 @@
 #'   Defaults to the current date and time if left blank and `start_date_time`
 #'   is specified.
 #' @details If neither `start_date_time` nor `end_date_time` are supplied, the
-#'   most recent date-time of data will be returned. If only `start_date_time`
+#'   most recent datetime of data will be returned. If only `start_date_time`
 #'   is supplied, then `end_date_time` defaults to the current time. Supplying
 #'   only `end_date_time` will result in an error.
 #' @note If `station_id` is supplied as a vector, multiple successive calls to
 #'   the API will be made. You may find better performance getting data for all
 #'   the stations by leaving `station_id` blank and subsetting the resulting
 #'   dataframe. Only the most recent 48 hours of 15-minute data are stored in
 #'   the AZMet API.
-#' @return a tibble. For units and other metadata, see
+#' @return A tibble. For units and other metadata, see
 #'   <https://azmet.arizona.edu/about>
-#' @seealso [az_daily()], [az_heat()], [az_hourly()], [az_lw15min()]
+#' @seealso [az_daily()], [az_heat()], [az_hourly()], [az_lw15min()], [az_lwdaily()]
 #' @source <https://azmet.arizona.edu/>
 #' @importFrom rlang .data
 #' @export
@@ -71,7 +72,7 @@ az_15min <- function(station_id = NULL, start_date_time = NULL, end_date_time =
   # Query API ------------------------------------------------------------------
 
   if (is.null(start_date_time) & is.null(end_date_time)) {
-    message("Querying most recent date-time of 15-minute data ...")
+    message("Querying most recent datetime of 15-minute data ...")
   } else {
     message(
       "Querying data from ", format(params$start, "%Y-%m-%d %H:%M:%S")," through ", format(params$end, "%Y-%m-%d %H:%M:%S"), " ..."
@@ -110,7 +111,7 @@ az_15min <- function(station_id = NULL, start_date_time = NULL, end_date_time =
   }
 
   if (nrow(out) == 0) {
-    warning("No data retrieved from API.")
+    warning("No data retrieved from API")
     # Return 0x0 tibble
     return(tibble::tibble())
   }

R/az_add_units.R

@@ -3,9 +3,9 @@
 #' Assigns correct units to the output of `az_hourly()`, `az_daily()`, and
 #' `az_heat()` using the `units` package.
 #'
-#' @param x a tibble output by [az_hourly()], [az_daily()], or [az_heat()]
+#' @param x A tibble output by [az_hourly()], [az_daily()], or [az_heat()]
 #'
-#' @return a tibble with columns of class "units"
+#' @return A tibble with columns of class "units"
 #' @export
 #'
 #' @examples

R/az_daily.R

@@ -1,31 +1,35 @@
 #' Retrieve Daily Weather Data from AZMET
 #'
 #' Retrieves daily data from the Arizona Meteorological Network API. For a list
-#' of weather stations and their locations see [station_info].
+#' of weather stations and their locations see [station_info], or visit
+#' https://azmet.arizona.edu/about.
 #'
 #' @param station_id station ID can be supplied as numeric vector (e.g.
-#'   `station_id = c(8, 37)`) or as character vector with the prefix "az" and 2
-#'   digits (e.g. `station_id = c("az08", "az37")`) If left blank data for all
-#'   stations will be returned
+#'   `station_id = c(8, 37)`) or as character vector with the prefix "az" and
+#'   two digits (e.g. `station_id = c("az08", "az37")`). If left blank, data for all
+#'   stations will be returned.
 #' @param start_date A length-1 vector of class Date, POSIXct, or character in
-#'   YYYY-MM-DD format.  Will be rounded **down** to the nearest day if more
-#'   precision is supplied.
+#'   YYYY-MM-DD format. Will be rounded **down** to the nearest day if more
+#'   precision is supplied. Defaults to the day before the current date (i.e.,
+#'   the most recent complete day) if left blank.
 #' @param end_date A length-1 vector of class Date, POSIXct, or character in
-#'   YYYY-MM-DD format.  Will be rounded **down** to the nearest day if more
-#'   precision is supplied.  Defaults to the current date if left blank.
+#'   YYYY-MM-DD format. Will be rounded **down** to the nearest day if more
+#'   precision is supplied. Defaults to the day before the current date (i.e.,
+#'   the most recent complete day) if left blank.
 #' @details If neither `start_date` nor `end_date` are supplied, the most recent
-#'   day of data will be returned.  If only `start_date` is supplied, then the
-#'   end date defaults to the current date.  Supplying only `end_date` will
+#'   day of data will be returned. If only `start_date` is supplied, then the
+#'   end date defaults to the day before the current date (i.e.,
+#'   the most recent complete day). Supplying only `end_date` will
 #'   result in an error.
 #' @note If `station_id` is supplied as a vector, multiple successive calls to
 #'   the API will be made. You may find better performance getting data for all
 #'   the stations by leaving `station_id` blank and subsetting the resulting
 #'   dataframe. Requests for data from all stations for more than 6-12 months
 #'   may take considerable time.
-#' @return a tibble. For units and other metadata, see
-#'   <https://ag.arizona.edu/azmet/raw2003.htm>
-#' @seealso [az_15min()], [az_heat()], [az_hourly()], [az_lw15min()]
-#' @source <https://ag.arizona.edu/azmet/>
+#' @return A tibble. For units and other metadata, see
+#'   <https://azmet.arizona.edu/about>
+#' @seealso [az_15min()], [az_heat()], [az_hourly()], [az_lw15min()], [az_lwdaily()]
+#' @source <https://azmet.arizona.edu/>
 #'
 #' @importFrom rlang .data
 #' @export
@@ -43,18 +47,31 @@
 #' az_daily(start_date = "2022-09-25")
 #' az_daily(start_date = "2022-09-25", end_date = "2022-09-26")
 #' }
-#'
+
+
 az_daily <- function(station_id = NULL, start_date = NULL, end_date = NULL) {
 
-  #TODO: check for valid station IDs
+  # TODO: check for valid station IDs
   check_internet()
+
   if(!is.null(end_date) & is.null(start_date)) {
     stop("If you supply `end_date`, you must also supply `start_date`")
   }
+
   params <-
-    parse_params(station_id = station_id, start = start_date, end = end_date)
+    parse_params(
+      station_id = station_id,
+      start = start_date,
+      end = end_date,
+      hour = FALSE,
+      real_time = FALSE
+    )
+
+  tz = "America/Phoenix"
+
+
+  # Query API  -----------------------------------------------------------------
 
-  # Query API  --------------------------------------------
   if (is.null(start_date) & is.null(end_date)) {
     message("Querying data from ", params$start)
   } else {
@@ -63,50 +80,56 @@ az_daily <- function(station_id = NULL, start_date = NULL, end_date = NULL) {
 
   if (length(station_id) <= 1) {
     out <-
-      retrieve_data(params$station_id,
-                    params$start_f,
-                    params$time_interval,
-                    endpoint = "daily")
+      retrieve_data(
+        params$station_id,
+        params$start_f,
+        params$time_interval,
+        endpoint = "daily"
+      )
   } else if (length(station_id) > 1) {
     out <-
       purrr::map_df(
         params$station_id,
         function(x) {
-          retrieve_data(x,
-                        params$start_f,
-                        params$time_interval,
-                        endpoint = "daily")
+          retrieve_data(
+            x,
+            params$start_f,
+            params$time_interval,
+            endpoint = "daily"
+          )
         }
       )
   }
 
   if (nrow(out) == 0) {
     warning("No data retrieved from API")
-    #return 0x0 tibble for type consistency
+    # Return 0x0 tibble for type consistency
     return(tibble::tibble())
   }
 
-  #Check if any data is missing
+  # Check if any data are missing
   n_obs <- out %>%
     dplyr::summarise(n = dplyr::n(), .by = dplyr::all_of("meta_station_id")) %>%
     dplyr::filter(.data$n < as.numeric(lubridate::period(params$time_interval), "day") + 1)
   if (nrow(n_obs) != 0 |
      # Also warn if the missing data is just at the end
-     lubridate::ymd(max(out$datetime), tz = "America/Phoenix") < params$end) {
-    warning("Some requested data were unavailable")
+     lubridate::ymd(max(out$datetime), tz = tz) < params$end) {
+    warning("Some requested data were unavailable.")
   }
 
-  # Wrangle output ----------------------------------------------------------
+
+  # Wrangle output -------------------------------------------------------------
+
   out <- out %>%
-    #move metadata to beginning
+    # Move metadata to beginning
     dplyr::select(dplyr::starts_with("meta_"), dplyr::everything()) %>%
     dplyr::mutate(dplyr::across(
       c(-"meta_station_id", -"meta_station_name", -"datetime", -"wind_2min_timestamp"),
       as.numeric
     )) %>%
     dplyr::filter(.data$meta_station_id != "az99") %>%
     dplyr::mutate(datetime = lubridate::ymd(.data$datetime)) %>%
-    #convert NAs
+    # Convert NAs
     dplyr::mutate(
       dplyr::across(
         tidyselect::where(is.numeric),
@@ -124,7 +147,7 @@ az_daily <- function(station_id = NULL, start_date = NULL, end_date = NULL) {
     dplyr::mutate(
       wind_2min_timestamp = lubridate::with_tz(
         lubridate::parse_date_time(.data$wind_2min_timestamp, orders = "ymdHMSz"),
-        tzone = "America/Phoenix"
+        tzone = tz
       )
     )
 

R/az_heat.R

@@ -1,9 +1,10 @@
 #' Retrieve Accumulated Heat Units and Evapotranspiration
 #'
 #' Retrieves accumulated heat units and reference evapotranspiration units from
-#' the Arizona Meteorological Network API.  By default, returned values are
+#' the Arizona Meteorological Network API. By default, returned values are
 #' cumulative since January 1 of the current year. For a list of weather
-#' stations and their locations see [station_info].
+#' stations and their locations see [station_info], or visit
+#' https://azmet.arizona.edu/about.
 #'
 #' @param station_id station ID can be supplied as numeric vector (e.g.
 #'   `station_id = c(8, 37)`) or as character vector with the prefix "az" and 2
@@ -24,10 +25,10 @@
 #'   the API will be made.  You may find better performance getting data for all
 #'   the stations by leaving `station_id` blank and subsetting the resulting
 #'   dataframe.
-#' @return a tibble. For units and other metadata, see
-#'   <https://ag.arizona.edu/azmet/raw2003.htm>
-#' @seealso [az_15min()], [az_daily()], [az_hourly()], [az_lw15min()]
-#' @source <https://ag.arizona.edu/azmet/>
+#' @return A tibble. For units and other metadata, see
+#'   <https://azmet.arizona.edu/about>
+#' @seealso [az_15min()], [az_daily()], [az_hourly()], [az_lw15min()], [az_lwdaily()]
+#' @source <https://azmet.arizona.edu/>
 #' @importFrom rlang .data
 #' @export
 #'
@@ -52,8 +53,8 @@
 #'
 az_heat <- function(station_id = NULL, start_date = NULL, end_date = NULL) {
   tz <- "America/Phoenix"
-  #TODO: document output columns or link to API docs if appropriate
-  #TODO: check for valid station IDs
+  # TODO: document output columns or link to API docs if appropriate
+  # TODO: check for valid station IDs
   check_internet()
   # If no start date supplied, default is Jan 1 of current year.
   if (is.null(start_date)) {

R/az_hourly.R

@@ -1,11 +1,12 @@
 #' Retrieve Hourly Weather Data
 #'
 #' Retrieves hourly weather data from the Arizona Meteorological Network API.
-#' For a list of weather stations and their locations see [station_info].
+#' For a list of weather stations and their locations see [station_info], or
+#' visit https://azmet.arizona.edu/about.
 #'
 #' @param station_id station ID can be supplied as numeric vector (e.g.
 #'   `station_id = c(8, 37)`) or as character vector with the prefix "az" and 2
-#'   digits (e.g. `station_id = c("az08", "az37")`) If left blank data for all
+#'   digits (e.g. `station_id = c("az08", "az37")`) If left blank, data for all
 #'   stations will be returned
 #' @param start_date_time A length-1 vector of class POSIXct or character in
 #'   YYYY-MM-DD HH format, in AZ time.  Will be rounded **down** to the nearest
@@ -26,10 +27,10 @@
 #'   the stations by leaving `station_id` blank and subsetting the resulting
 #'   dataframe. Requests for data from all stations for more than 10-15 days may
 #'   take considerable time.
-#' @return a tibble. For units and other metadata, see
-#'   <https://ag.arizona.edu/azmet/raw2003.htm>
-#' @seealso [az_15min()], [az_daily()], [az_heat()], [az_lw15min()]
-#' @source <https://ag.arizona.edu/azmet/>
+#' @return A tibble. For units and other metadata, see
+#'   <https://azmet.arizona.edu/about>
+#' @seealso [az_15min()], [az_daily()], [az_heat()], [az_lw15min()], [az_lwdaily()]
+#' @source <https://azmet.arizona.edu/>
 #' @importFrom rlang .data
 #' @export
 #'
@@ -49,7 +50,7 @@
 #'
 az_hourly <- function(station_id = NULL, start_date_time = NULL, end_date_time = NULL) {
 
-  #TODO: check for valid station IDs
+  # TODO: check for valid station IDs
   check_internet()
   if(!is.null(end_date_time) & is.null(start_date_time)) {
     stop("If you supply `end_date_time`, you must also supply `start_date_time`")

R/az_lw15min.R

@@ -1,8 +1,9 @@
 #' Retrieve 15-minute Leaf Wetness Data from AZMet
 #'
 #' Retrieves 15-minute leaf-wetness data from the AZMet (Arizona Meteorological
-#' Network) API. Currently, these data only are available from stations in the
-#' Yuma area. For a list of stations and their locations see [station_info].
+#' Network) API. Currently, these data only are available from weather stations
+#' in the Yuma area. For a list of stations and their locations see
+#' [station_info], or visit https://azmet.arizona.edu/about.
 #'
 #' @param station_id Station ID can be supplied as numeric vector (e.g.
 #'   `station_id = c(8, 37)`) or as character vector with the prefix "az" and
@@ -17,17 +18,17 @@
 #'   Defaults to the current date and time if left blank and `start_date_time`
 #'   is specified.
 #' @details If neither `start_date_time` nor `end_date_time` are supplied, the
-#'   most recent date-time of data will be returned. If only `start_date_time`
+#'   most recent datetime of data will be returned. If only `start_date_time`
 #'   is supplied, then `end_date_time` defaults to the current time. Supplying
 #'   only `end_date_time` will result in an error.
 #' @note If `station_id` is supplied as a vector, multiple successive calls to
 #'   the API will be made. You may find better performance getting data for all
 #'   the stations by leaving `station_id` blank and subsetting the resulting
 #'   dataframe. Only the most recent 48 hours of 15-minute data are stored in
 #'   the AZMet API.
-#' @return a tibble. For units and other metadata, see
+#' @return A tibble. For units and other metadata, see
 #'   <https://azmet.arizona.edu/about>
-#' @seealso [az_15min()], [az_daily()], [az_heat()], [az_hourly()]
+#' @seealso [az_15min()], [az_daily()], [az_heat()], [az_hourly()], [az_lwdaily()]
 #' @source <https://azmet.arizona.edu/>
 #' @importFrom rlang .data
 #' @export
@@ -72,7 +73,7 @@ az_lw15min <- function(station_id = NULL, start_date_time = NULL, end_date_time
   # Query API ------------------------------------------------------------------
 
   if (is.null(start_date_time) & is.null(end_date_time)) {
-    message("Querying most recent date-time of leaf wetness 15-minute data ...")
+    message("Querying most recent datetime of leaf wetness 15-minute data ...")
   } else {
     message(
       "Querying data from ", format(params$start, "%Y-%m-%d %H:%M:%S")," through ", format(params$end, "%Y-%m-%d %H:%M:%S"), " ..."
@@ -111,7 +112,7 @@ az_lw15min <- function(station_id = NULL, start_date_time = NULL, end_date_time
   }
 
   if (nrow(out) == 0) {
-    warning("No data retrieved from API.")
+    warning("No data retrieved from API")
     # Return 0x0 tibble
     return(tibble::tibble())
   }