Parameterize key query fields in riem_measures() (#48)

* Parameterize 'data' field in riem_measures()

* Add comment linking field documentation

* Parameterize 'elev' field in riem_measures()

* Parameterize 'latlon' field in riem_measures()

* Parameterize 'report_type' field in riem_measures(); Skip HFMETAR by default

* Choose a safer default date_start

* Speficy nometa = no, since parsing counts on column names

* Update self-documentation for riem_measures()

* Update test fixtures files since default endpoint query changed

* Document

* Preserve order of riem_measures() positional arguments; Remove default values for station, date_start args (thus making them required); Convert elev and latlon to logicals; Update DESCRIPTION and documentation

* Specify the now-required station srgument in test-measures.R

* Correct copy/paste error

* Specify the now-required date_start argument in test-measures.R

* Add call to rlang::check_dots_empty() in riem_measures()

* Add better validation for new riem_measures() args

* Specify the now-required station srgument in test-measures.R

* Correct order of args in documentation

* refactor: use `rlang::is_character()`

* refactor: make report_type's input more readable

* test: add test for new parameters

* Address lintr warnings

* Add new tests; Address lintr warnings

* fix: remove duplicate import

* docs: improve documentation of `report_type`

* refactor: remove unnecessary lambda

* docs: update NEWS.md

* formatting

* latlon

* docs: clarify report

* refactor: validate data

* Permit new 'data' arg validation to accept multiple fields (and add associated test); Add/update comments for clarity

* Update param documentation to contain default values; Correct report_type comment

* Address lintr warnings

---------

Co-authored-by: Maëlle Salmon <maelle.salmon@yahoo.se>

DESCRIPTION

@@ -11,7 +11,9 @@ Authors@R: c(
            comment = "The research leading to these results has received funding from the European Research Council under the ERC Grant Agreement number 336167– the CHAI Project"),
     person("rOpenSci", role = "fnd",
            comment = "https://ropensci.org/"),
-    person("Daryl", "Herzmann", , "akrherz@gmail.com", role = "ctb")
+    person("Daryl", "Herzmann", , "akrherz@gmail.com", role = "ctb"),
+    person("Jonathan", "Elchison", email = "JElchison@gmail.com", role = c("aut"),
+           comment = c(ORCID = "0009-0004-0787-3426"))
   )
 Description: Allows to get weather data from Automated Surface Observing
     System (ASOS) stations (airports) in the whole world thanks to the
@@ -40,4 +42,4 @@ Suggests:
     xts
 Config/testthat/edition: 3
 Encoding: UTF-8
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2

NEWS.md

@@ -1,5 +1,9 @@
 # riem (development version)
 
+* Breaking change: `date_start` and `station` no longer have default values.
+
+* New arguments `data`, `latlon`, `report_type`, `elev` (#49, @JElchison).
+
 # riem 0.3.2
 
 * Remove last usage of vcr as the choice was made to use httptest2 instead.

R/measures.R

@@ -2,8 +2,19 @@
 #'
 #'
 #' @param station station ID, see riem_stations()
-#' @param date_start date of start of the desired data, e.g. "2000-01-01"
-#' @param date_end date of end of the desired data, e.g. "2016-04-22"
+#' @param date_start date of start of the desired data, e.g. "2016-01-01"
+#' @inheritParams rlang::args_dots_empty
+#' @param date_end date of end of the desired data, e.g. "2016-04-22". Default value is today. # nolint: line_length_linter
+#' @param data A vector of strings, representing the data columns to return.
+#' The available options are: all, tmpf, dwpf, relh, drct, sknt, p01i, alti, mslp, vsby, gust, skyc1, skyc2, skyc3, skyc4, skyl1, skyl2, skyl3, skyl4, wxcodes, ice_accretion_1hr, ice_accretion_3hr, ice_accretion_6hr, peak_wind_gust, peak_wind_drct, peak_wind_time, feel, metar, snowdepth # nolint: line_length_linter
+#' Default value is `all`.
+#' @param elev If TRUE, the elevation (m) of the station will be included in the output, in an `elevation` column. # nolint: line_length_linter
+#' Default value is `FALSE`.
+#' @param latlon If TRUE, the latitude and longitude of the station will be included in the output, in `lat` and `lon` columns. # nolint: line_length_linter
+#' Default value is `TRUE`.
+#' @param report_type A vector of strings, representing report types to query.
+#' The available options are `"hfmetar"`, `"routine"`, `"specials"`.
+#' Default value is `c("routine", "specials")`.
 #'
 #' @return a data.frame (tibble tibble) with measures,
 #' the number of columns can vary from station to station,
@@ -63,28 +74,92 @@
 #' )
 #' }
 riem_measures <- function(
-    station = "VOHY",
-    date_start = "2014-01-01",
-    date_end = as.character(Sys.Date())) {
+    station,
+    date_start,
+    ...,
+    date_end = as.character(Sys.Date()),
+    data = "all",
+    elev = FALSE,
+    latlon = TRUE,
+    report_type = NULL) {
+  # validate 'station' arg
+  if (!rlang::is_character(station, n = 1L)) {
+    cli::cli_abort("{.arg station} must be a string.")
+  }
+
+  # validate 'date_start' arg
   date_start <- format_and_check_date(date_start, "date_start")
+
+  # validate dots
+  rlang::check_dots_empty()
+
+  # validate 'date_end' arg
   date_end <- format_and_check_date(date_end, "date_end")
   if (date_end < date_start) {
     cli::cli_abort("{.arg date_end} must be bigger than {.arg date_start}.")
   }
 
+  # validate 'data' arg
+  data <- tolower(data) # not case-sensitive
+  data <- rlang::arg_match(
+    data,
+    values = c(
+      "all", "tmpf", "dwpf", "relh", "drct", "sknt", "p01i", "alti", "mslp",
+      "vsby", "gust", "skyc1", "skyc2", "skyc3", "skyc4", "skyl1", "skyl2",
+      "skyl3", "skyl4", "wxcodes", "ice_accretion_1hr", "ice_accretion_3hr",
+      "ice_accretion_6hr", "peak_wind_gust", "peak_wind_drct", "peak_wind_time",
+      "feel", "metar", "snowdepth"
+    ),
+    multiple = TRUE
+  )
+  data <- paste(data, collapse = ",")
+
+  # validate 'elev' arg
+  if (!is.logical(elev)) {
+    cli::cli_abort("{.arg elev} must be a logical (TRUE/FALSE)") # nolint: nonportable_path_linter
+  }
+
+  # validate 'latlon' arg
+  if (!is.logical(latlon)) {
+    cli::cli_abort("{.arg latlon} must be a logical (TRUE/FALSE)") # nolint: nonportable_path_linter
+  }
+
+  # validate 'report_type' arg
+  report_type <- report_type %||% c("routine", "specials")
+  report_type <- tolower(report_type) # not case-sensitive
+  report_type <- rlang::arg_match(
+    report_type,
+    values = c("hfmetar", "routine", "specials"),
+    multiple = TRUE
+  )
+  report_type <- purrr::map_int(
+    report_type,
+    switch,
+    hfmetar = 1L,
+    routine = 3L,
+    specials = 4L
+  )
+  report_type <- paste(report_type, collapse = ",")
+
+  # args have been validated.
+
   resp <- perform_riem_request(
     path = "cgi-bin/request/asos.py/", # nolint: nonportable_path_linter
+    # query fields per https://mesonet.agron.iastate.edu/cgi-bin/request/asos.py?help # nolint: line_length_linter
     query = list(
       station = station,
-      data = "all",
+      data = data,
+      elev = ifelse(elev, "yes", "no"),
+      latlon = ifelse(latlon, "yes", "no"),
       year1 = lubridate::year(date_start),
       month1 = lubridate::month(date_start),
       day1 = lubridate::day(date_start),
       year2 = lubridate::year(date_end),
       month2 = lubridate::month(date_end),
       day2 = lubridate::day(date_end),
+      report_type = report_type,
       format = "tdf",
-      latlon = "yes",
+      nometa = "no",
       tz = "UTC"
     )
   )

tests/testthat/_snaps/measures.md

@@ -1,16 +1,32 @@
-# riem_measures checks dates
+# riem_measures fails if required 'station' param is absent
+
+    argument "station" is missing, with no default
+
+# riem_measures fails if required 'date_start' param is absent
+
+    argument "date_start" is missing, with no default
+
+# riem_measures validates 'station' param
+
+    `station` must be a string.
+
+---
+
+    HTTP 422 Unprocessable Entity.
+
+# riem_measures validates dates
 
     x Invalid `date_start`: somethingelse.
     i Correct format is YYYY-MM-DD.
 
 ---
 
-    x Invalid `date_end`: somethingelse.
+    x Invalid `date_start`: 2015 31 01.
     i Correct format is YYYY-MM-DD.
 
 ---
 
-    x Invalid `date_start`: 2015 31 01.
+    x Invalid `date_end`: somethingelse.
     i Correct format is YYYY-MM-DD.
 
 ---
@@ -22,3 +38,31 @@
 
     `date_end` must be bigger than `date_start`.
 
+# riem_measures validates 'elev' param
+
+    `elev` must be a logical (TRUE/FALSE)
+
+---
+
+    `elev` must be a logical (TRUE/FALSE)
+
+# riem_measures validates 'latlon' param
+
+    `latlon` must be a logical (TRUE/FALSE)
+
+---
+
+    `latlon` must be a logical (TRUE/FALSE)
+
+# riem_measures validates 'report_type' param
+
+    `report_type` must be one of "hfmetar", "routine", or "specials", not "11111".
+
+---
+
+    `report_type` must be one of "hfmetar", "routine", or "specials", not "zzzzz".
+
+---
+
+    `report_type` must be one of "hfmetar", "routine", or "specials", not "zzzzz".
+