Fix a foot-gun and assume all DPIRD open/closed stations and fix docs

R/get_dpird_extremes.R

@@ -11,10 +11,6 @@
 #'   return.  See **Available Values** for a full list of valid values.
 #'   Defaults to `all`, returning the full list of values unless otherwise
 #'   specified.
-#' @param include_closed A `Boolean` value that defaults to `FALSE`.  If set to
-#'   `TRUE` the query returns closed and open stations.  Closed stations are
-#'   those that have been turned off and no longer report data.  They may be
-#'   useful for historical purposes.
 #' @param api_key A `character` string containing your \acronym{API} key from
 #'   \acronym{DPIRD}, <https://www.agric.wa.gov.au/web-apis>, for the
 #'   \acronym{DPIRD} Weather 2.0 \acronym{API}.
@@ -108,7 +104,6 @@
 
 get_dpird_extremes <- function(station_code,
                                 values = "all",
-                                include_closed = FALSE,
                                 api_key) {
   # simplify using the metadata to fetch weather data by converting factors to
   # numeric values
@@ -167,7 +162,7 @@ get_dpird_extremes <- function(station_code,
     offset = 0L,
     select = paste(.values, collapse = ","),
     group = "all",
-    includeClosed = include_closed,
+    includeClosed = TRUE,
     api_key = api_key
   )
 

R/get_dpird_minute.R

@@ -1,5 +1,4 @@
 
-
 #' Get DPIRD Weather Data by the Minute
 #'
 #' Fetch nicely formatted minute weather station data from the \acronym{DPIRD}

R/get_dpird_summaries.R

@@ -40,11 +40,6 @@
 #' @param values A `character` string with the type of summarised weather
 #'   to return.  See **Available Values** for a full list of valid values.
 #'   Defaults to `all` with all available values being returned.
-#' @param include_closed A `Boolean` value that defaults to `FALSE`.  If set to
-#'   `TRUE` the query returns closed and open stations.  Closed stations are
-#'   those that have been turned off and no longer report data.  They may be
-#'   useful for historical purposes.  Only set to `TRUE` to fetch data from
-#'   closed stations.
 #' @param api_key A `character` string containing your \acronym{API} key from
 #'   \acronym{DPIRD}, <https://www.agric.wa.gov.au/web-apis>, for the
 #'   \acronym{DPIRD} Weather 2.0 \acronym{API}.
@@ -188,16 +183,9 @@
 get_dpird_summaries <- function(station_code,
                                 start_date,
                                 end_date = Sys.Date(),
-                                interval = c("daily",
-                                             "15min",
-                                             "30min",
-                                             "hourly",
-                                             "monthly",
-                                             "yearly"),
+                                interval = c("daily", "15min", "30min", "hourly", "monthly", "yearly"),
                                 values = "all",
-                                include_closed = FALSE,
                                 api_key) {
-
   # this section is necessary to double check availability dates of DPIRD
   # stations to give users a better experience. It slows down the first query
   # but avoids confusion when no values are returned for a station that exists
@@ -207,23 +195,26 @@ get_dpird_summaries <- function(station_code,
 
     if (!file.exists(metadata_file)) {
       saveRDS(
-        get_stations_metadata(which_api = "dpird",
-                              api_key = api_key,
-                              include_closed = include_closed),
+        get_stations_metadata(
+          which_api = "dpird",
+          api_key = api_key,
+          include_closed = TRUE
+        ),
         file = metadata_file,
         compress = FALSE
       )
     }
 
   } else {
-
     metadata_file <- file.path(tempdir(), "dpird_metadata.Rda")
 
     if (!file.exists(metadata_file)) {
       saveRDS(
-        get_stations_metadata(which_api = "dpird",
-                              api_key = api_key,
-                              include_closed = include_closed),
+        get_stations_metadata(
+          which_api = "dpird",
+          api_key = api_key,
+          include_closed = TRUE
+        ),
         file = metadata_file,
         compress = FALSE
       )
@@ -237,13 +228,11 @@ get_dpird_summaries <- function(station_code,
   }
 
   if (missing(station_code) | !is.character(station_code)) {
-    stop(call. = FALSE,
-         "Please supply a valid `station_code`.")
+    stop(call. = FALSE, "Please supply a valid `station_code`.")
   }
 
   if (missing(start_date))
-    stop(call. = FALSE,
-         "Please supply a valid start date as `start_date`.")
+    stop(call. = FALSE, "Please supply a valid start date as `start_date`.")
 
   if (any(values == "all")) {
     values <-
@@ -253,8 +242,7 @@ get_dpird_summaries <- function(station_code,
         weatherOz::dpird_summary_values)
   } else {
     if (any(values %notin% weatherOz::dpird_summary_values)) {
-      stop(call. = FALSE,
-           "You have specified invalid weather values.")
+      stop(call. = FALSE, "You have specified invalid weather values.")
     }
     values <-
       c("stationCode", "stationName", "period", values)
@@ -264,50 +252,29 @@ get_dpird_summaries <- function(station_code,
   start_date <- .check_date(start_date)
   end_date <- .check_date(end_date)
   .check_date_order(start_date, end_date)
-  tryCatch(
-    expr = {
-      .check_earliest_available_dpird(station_code, start_date, metadata_file)
-    },
-    error = function(e) {
-      message(
-        "Error: have you perhaps supplied a closed station without specifying,",
-        "`include_closed = TRUE` in `get_dpird_summaries()`?"
-      )
-    }
-  )
+  .check_earliest_available_dpird(station_code, start_date, metadata_file)
 
   # if interval is not set, default to "daily", else check input to be sure
-  approved_intervals <- c("daily",
-                          "15min",
-                          "30min",
-                          "hourly",
-                          "monthly",
-                          "yearly")
+  approved_intervals <- c("daily", "15min", "30min", "hourly", "monthly", "yearly")
 
   if (identical(interval, approved_intervals)) {
     interval <- "daily"
   }
 
-  likely_interval <- agrep(pattern = interval,
-                           x = approved_intervals)
+  likely_interval <- agrep(pattern = interval, x = approved_intervals)
 
   # Match time interval query to user requests
   checked_interval <-
-    try(match.arg(approved_intervals[likely_interval],
-                  approved_intervals,
-                  several.ok = FALSE),
+    try(match.arg(approved_intervals[likely_interval], approved_intervals, several.ok = FALSE),
         silent = TRUE)
 
   # Error if summary interval is not available. API only allows for daily,
   # 15 min, 30 min, hourly, monthly or yearly
   if (methods::is(checked_interval, "try-error")) {
-    stop(call. = FALSE,
-         "\"", interval, "\" is not a supported time interval")
+    stop(call. = FALSE, "\"", interval, "\" is not a supported time interval")
   }
 
-  request_interval <- lubridate::interval(start_date,
-                                          end_date,
-                                          tzone = "Australia/Perth")
+  request_interval <- lubridate::interval(start_date, end_date, tzone = "Australia/Perth")
 
   # Stop if query is for 15 and 30 min intervals and date is more than one
   # year in the past
@@ -363,21 +330,18 @@ get_dpird_summaries <- function(station_code,
 
     if (!file.exists(metadata_file)) {
       saveRDS(
-        get_stations_metadata(which_api = "dpird",
-                             api_key = api_key),
+        get_stations_metadata(which_api = "dpird", api_key = api_key),
         file = metadata_file,
         compress = FALSE
       )
     }
 
   } else {
-
     metadata_file <- file.path(tempdir(), "dpird_metadata.Rda")
 
     if (!file.exists(metadata_file)) {
       saveRDS(
-        get_stations_metadata(which_api = "dpird",
-                             api_key = api_key),
+        get_stations_metadata(which_api = "dpird", api_key = api_key),
         file = metadata_file,
         compress = FALSE
       )
@@ -392,7 +356,7 @@ get_dpird_summaries <- function(station_code,
     end_date_time = end_date,
     interval = checked_interval,
     values = values,
-    include_closed = include_closed,
+    include_closed = TRUE,
     api_key = api_key,
     limit = total_records_req
   )
@@ -566,9 +530,12 @@ get_dpird_summaries <- function(station_code,
 
   # TODO: When Phil gets lat/lon values added to the summary results from the
   # API, remove this bit here and add lat/lon to the list of queried values
-  out <- merge(x = out, y = readRDS(file = metadata_file)[, c(1:2, 5:6)],
-               by.x = c("station_code", "station_name"),
-               by.y = c("station_code", "station_name"))
+  out <- merge(
+    x = out,
+    y = readRDS(file = metadata_file)[, c(1:2, 5:6)],
+    by.x = c("station_code", "station_name"),
+    by.y = c("station_code", "station_name")
+  )
   # END chunk to remove
 
   data.table::setcolorder(out, order(names(out)))
@@ -585,8 +552,7 @@ get_dpird_summaries <- function(station_code,
       lubridate::ymd_hms,
       truncated = 3,
       tz = "Australia/West"
-    )),
-    .SDcols = grep("time", colnames(out))]
+    )), .SDcols = grep("time", colnames(out))]
   }
 
   data.table::setnames(out, gsub("period_", "", names(out)))
@@ -616,8 +582,7 @@ get_dpird_summaries <- function(station_code,
 #' @autoglobal
 #' @keywords Internal
 #'
-.parse_summary <- function(.ret_list,
-                           .values) {
+.parse_summary <- function(.ret_list, .values) {
   x <- vector(mode = "list", length = length(.ret_list))
   for (i in seq_len(length(.ret_list))) {
     y <- jsonlite::fromJSON(.ret_list[[i]]$parse("UTF8"))
@@ -645,8 +610,7 @@ get_dpird_summaries <- function(station_code,
     j <- 1
     for (i in col_lists) {
       new_df_list[[j]] <-
-        data.table::rbindlist(lapply(X = nested_list_objects[[i]],
-                                     FUN = data.table::as.data.table))
+        data.table::rbindlist(lapply(X = nested_list_objects[[i]], FUN = data.table::as.data.table))
 
       # drop the list column from the org data.table
       nested_list_objects[, names(new_df_list[j]) := NULL]
@@ -655,8 +619,7 @@ get_dpird_summaries <- function(station_code,
     }
 
     x <-
-      data.table::setorder(x = data.table::as.data.table(
-        do.call(what = cbind, args = new_df_list)))
+      data.table::setorder(x = data.table::as.data.table(do.call(what = cbind, args = new_df_list)))
 
     return(cbind(nested_list_objects, x))
   }
@@ -674,7 +637,6 @@ get_dpird_summaries <- function(station_code,
 #' @noRd
 
 .check_earliest_available_dpird <- function(.station_code, .start_date, .f) {
-
   y <- readRDS(file = .f)[, c(1, 3)]
   y <- y[y$station_code %in% .station_code]
 
@@ -705,27 +667,25 @@ get_dpird_summaries <- function(station_code,
 
 .set_col_orders <- function(.out, .checked_interval) {
   if (.checked_interval == "monthly") {
-    .out[, date := lubridate::ym(sprintf("%s-%s",
-                                         .out$period_year,
-                                         .out$period_month))]
+    .out[, date := lubridate::ym(sprintf("%s-%s", .out$period_year, .out$period_month))]
 
-    data.table::setcolorder(.out,
-                            c(
-                              "station_code",
-                              "station_name",
-                              "longitude",
-                              "latitude",
-                              "period_year",
-                              "period_month",
-                              "date"
-                            ))
+    data.table::setcolorder(
+      .out,
+      c(
+        "station_code",
+        "station_name",
+        "longitude",
+        "latitude",
+        "period_year",
+        "period_month",
+        "date"
+      )
+    )
 
     .out[, period_day := NULL]
     .out[, period_hour := NULL]
     .out[, period_minute := NULL]
-    data.table::setorder(x = .out,
-                         cols = "period_year",
-                         "period_month")
+    data.table::setorder(x = .out, cols = "period_year", "period_month")
   } else if (.checked_interval == "daily") {
     .out[, date := lubridate::ymd(sprintf(
       "%s-%s-%s",
@@ -827,11 +787,13 @@ get_dpird_summaries <- function(station_code,
     )
   } else {
     data.table::setcolorder(.out,
-                            c("station_code",
+                            c(
+                              "station_code",
                               "station_name",
                               "longitude",
                               "latitude",
-                              "period_year"))
+                              "period_year"
+                            ))
     .out[, period_month := NULL]
     .out[, period_day := NULL]
     .out[, period_hour := NULL]

R/query_dpird_api.R

@@ -19,17 +19,28 @@
 #'   query in the format 'yyyy-mm-dd-hh-mm'.  Defaults to the current system
 #'   date rounded to the nearest minute.  This function does its best to
 #'   decipher many date and time formats but prefers ISO8601.
-#' @param interval Interval to use, one of 'minute', '15min', '30min', 'hourly',
-#'  'daily', 'monthly' or 'yearly'.
+#' @param interval A `string` value providing the time interval to use, one of
+#'   * 'minute',
+#'   * '15min',
+#'   * '30min',
+#'   * 'hourly',
+#'   * 'daily',
+#'   * 'monthly' or
+#'   * 'yearly'.
+#' @param values Values to query from the API
+#' @param api_group A `string` used to filter the stations to a predefined
+#'   group.  These need to be supported on the back end. 'all' returns all
+#'   stations, 'api' returns the default stations in use with the API, 'web'
+#'   returns the list in use by the weather.agric.wa.gov.au and 'rtd' returns
+#'   stations with scientifically complete datasets. Available values: 'api',
+#'   'all', 'web' and 'rtd'.
+#' @param include_closed A `Boolean` value that defaults to `TRUE`.  If set to
+#'   `TRUE` the query returns closed and open stations.  Closed stations are
+#'   those that have been turned off and no longer report data.  They may be
+#'   useful for historical purposes.  Only set to `FALSE` to only fetch data
+#'   from open stations.
 #' @param limit The pagination limit parameter restricts the number of entries
 #'   returned.
-#' @param values Values to query from the API
-#' @param group A `string` used to filter the stations to a predefined group.
-#'   These need to be supported on the back end. 'all' returns all stations,
-#'   'api' returns the default stations in use with the API, 'web' returns the
-#'   list in use by the weather.agric.wa.gov.au and 'rtd' returns stations with
-#'   scientifically complete datasets. Available values: 'api', 'all', 'web' and
-#'   'rtd'.
 #' @param api_key A `character` string containing your \acronym{API} key from
 #'   \acronym{DPIRD}, <https://www.agric.wa.gov.au/web-apis>, for the
 #'   \acronym{DPIRD} Weather 2.0 \acronym{API}.