Merge pull request #236 from cmu-delphi/ndefries/combine-timetype-wiki-twitter

nmdefries · web-flow · commit 2657bed68286 · 2024-01-18T17:44:56.000-05:00
Combine timetype wiki twitter
diff --git a/NEWS.md b/NEWS.md
@@ -20,6 +20,7 @@
 - `get_api_key` no longer reads from R options and only uses environment variables (#217).
 - Fix documentation related to CRAN submission.
 - Fix some errors from passing "" as a key.
+- `pvt_twitter` and `pub_wiki` now use `time_type` and `time_values` args instead of mutually exclusive `dates` and `epiweeks` (#236). This matches the interface of the `pub_covidcast` endpoint.
 - All endpoints now support the use of "\*" as a wildcard to fetch all dates or epiweeks (#234).
 
 # epidatr 1.0.0
diff --git a/R/endpoints.R b/R/endpoints.R
@@ -209,8 +209,10 @@ pub_covid_hosp_facility <- function(
     cli::cli_warn(coercion_msg, class = "epidatr__epirange_week_coercion")
     collection_weeks <- reformat_epirange(collection_weeks, to_type = "day")
     # Single week date.
-  } else if ((test_integerish(collection_weeks) || test_character(collection_weeks)) &&
-    nchar(collection_weeks) == 6) {
+  } else if (
+    (test_integerish(collection_weeks) || test_character(collection_weeks)) &&
+      nchar(collection_weeks) == 6
+  ) {
     cli::cli_warn(coercion_msg, class = "epidatr__single_week_coercion")
     collection_weeks <- parse_api_week(collection_weeks)
   }
@@ -2094,15 +2096,17 @@ pvt_sensors <- function(
 #' pvt_twitter(
 #'   auth = Sys.getenv("SECRET_API_AUTH_TWITTER"),
 #'   locations = "CA",
-#'   epiweeks = epirange(201501, 202001)
+#'   time_type = "week",
+#'   time_values = epirange(201501, 202001)
 #' )
 #' }
 #' @param auth string. Restricted access key (not the same as API key).
 #' @param locations character. Locations to fetch.
 #' @param ... not used for values, forces later arguments to bind by name
-#' @param dates [`timeset`]. Dates to fetch. Mutually exclusive with `epiweeks`.
-#' @param epiweeks [`timeset`]. Epiweeks to fetch. Mutually exclusive with
-#' `dates`.
+#' @param time_type string. The temporal resolution of the data (either "day" or
+#'  "week", depending on signal).
+#' @param time_values [`timeset`]. Dates or epiweeks to fetch. Defaults to all
+#'  ("*") dates.
 #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`.
 #' @return [`tibble::tibble`]
 #' @keywords endpoint
@@ -2111,21 +2115,31 @@ pvt_twitter <- function(
     auth,
     locations,
     ...,
-    dates = NULL,
-    epiweeks = NULL,
+    time_type = c("day", "week"),
+    time_values = "*",
     fetch_args = fetch_args_list()) {
   rlang::check_dots_empty()
 
+  time_type <- match.arg(time_type)
+  if (time_type == "day") {
+    dates <- time_values
+    epiweeks <- NULL
+    dates <- get_wildcard_equivalent_dates(dates, "day")
+  } else {
+    dates <- NULL
+    epiweeks <- time_values
+    epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week")
+  }
+
   assert_character_param("auth", auth, len = 1)
   assert_character_param("locations", locations)
+  assert_character_param("time_type", time_type, len = 1)
+  assert_timeset_param("time_values", time_values)
   assert_timeset_param("dates", dates, required = FALSE)
   assert_timeset_param("epiweeks", epiweeks, required = FALSE)
   dates <- parse_timeset_input(dates)
   epiweeks <- parse_timeset_input(epiweeks)
 
-  if (!xor(is.null(dates), is.null(epiweeks))) {
-    stop("exactly one of `dates` and `epiweeks` is required")
-  }
   time_field <- if (!is.null(dates)) {
     create_epidata_field_info("date", "date")
   } else {
@@ -2163,13 +2177,18 @@ pvt_twitter <- function(
 #'
 #' @examples
 #' \dontrun{
-#' pub_wiki(articles = "avian_influenza", epiweeks = epirange(201501, 201601))
+#' pub_wiki(
+#'   articles = "avian_influenza",
+#'   time_type = "week",
+#'   time_values = epirange(201501, 201601)
+#' )
 #' }
 #' @param articles character. Articles to fetch.
 #' @param ... not used for values, forces later arguments to bind by name
-#' @param dates [`timeset`]. Dates to fetch. Mutually exclusive with `epiweeks`.
-#' @param epiweeks [`timeset`]. Epiweeks to fetch. Mutually exclusive with
-#' `dates`.
+#' @param time_type string. The temporal resolution of the data (either "day" or
+#'  "week", depending on signal).
+#' @param time_values [`timeset`]. Dates or epiweeks to fetch. Defaults to all
+#'  ("*") dates.
 #' @param language string. Language to fetch.
 #' @param hours integer. Optionally, the hours to fetch.
 #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`.
@@ -2179,24 +2198,34 @@ pvt_twitter <- function(
 pub_wiki <- function(
     articles,
     ...,
-    dates = NULL,
-    epiweeks = NULL,
+    time_type = c("day", "week"),
+    time_values = "*",
     hours = NULL,
     language = "en",
     fetch_args = fetch_args_list()) {
   rlang::check_dots_empty()
 
+  time_type <- match.arg(time_type)
+  if (time_type == "day") {
+    dates <- time_values
+    epiweeks <- NULL
+    dates <- get_wildcard_equivalent_dates(dates, "day")
+  } else {
+    dates <- NULL
+    epiweeks <- time_values
+    epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week")
+  }
+
   assert_character_param("articles", articles)
+  assert_character_param("time_type", time_type, len = 1)
+  assert_timeset_param("time_values", time_values)
   assert_timeset_param("dates", dates, required = FALSE)
   assert_timeset_param("epiweeks", epiweeks, required = FALSE)
   assert_integerish_param("hours", hours, required = FALSE)
   assert_character_param("language", language, len = 1, required = FALSE)
   dates <- parse_timeset_input(dates)
   epiweeks <- parse_timeset_input(epiweeks)
 
-  if (!xor(is.null(dates), is.null(epiweeks))) {
-    stop("exactly one of `dates` and `epiweeks` is required")
-  }
   time_field <- if (!is.null(dates)) {
     create_epidata_field_info("date", "date")
   } else {
diff --git a/man/pub_wiki.Rd b/man/pub_wiki.Rd
diff --git a/man/pvt_twitter.Rd b/man/pvt_twitter.Rd
diff --git a/tests/testthat/test-endpoints.R b/tests/testthat/test-endpoints.R
@@ -137,12 +137,27 @@ test_that("basic_epidata_call", {
   expect_no_error(pvt_twitter(
     auth = "yourkey",
     locations = "CA",
-    epiweeks = epirange(201501, 202001),
+    time_type = "week",
+    time_values = epirange(201501, 202001),
+    fetch_args = fetch_args_list(dry_run = TRUE)
+  ) %>% request_url())
+  expect_no_error(pvt_twitter(
+    auth = "yourkey",
+    locations = "CA",
+    time_type = "day",
+    time_values = epirange(20150101, 20200101),
     fetch_args = fetch_args_list(dry_run = TRUE)
   ) %>% request_url())
   expect_no_error(pub_wiki(
     articles = "avian_influenza",
-    epiweeks = epirange(201501, 202001),
+    time_type = "week",
+    time_values = epirange(201501, 202001),
+    fetch_args = fetch_args_list(dry_run = TRUE)
+  ) %>% request_url())
+  expect_no_error(pub_wiki(
+    articles = "avian_influenza",
+    time_type = "day",
+    time_values = epirange(20150101, 20200101),
     fetch_args = fetch_args_list(dry_run = TRUE)
   ) %>% request_url())
 })
@@ -322,6 +337,44 @@ test_that("endoints accept wildcard for date parameter", {
   ))
   expect_identical(call$params$epiweeks$from, 100001)
   expect_identical(call$params$epiweeks$to, 300001)
+
+  expect_no_error(call <- pvt_twitter(
+    auth = "yourkey",
+    locations = "CA",
+    time_type = "week",
+    time_values = "*",
+    fetch_args = fetch_args_list(dry_run = TRUE)
+  ))
+  expect_identical(call$params$epiweeks$from, 100001)
+  expect_identical(call$params$epiweeks$to, 300001)
+
+  expect_no_error(call <- pvt_twitter(
+    auth = "yourkey",
+    locations = "CA",
+    time_type = "day",
+    time_values = "*",
+    fetch_args = fetch_args_list(dry_run = TRUE)
+  ))
+  expect_identical(call$params$dates$from, 10000101)
+  expect_identical(call$params$dates$to, 30000101)
+
+  expect_no_error(call <- pub_wiki(
+    articles = "avian_influenza",
+    time_type = "week",
+    time_values = "*",
+    fetch_args = fetch_args_list(dry_run = TRUE)
+  ))
+  expect_identical(call$params$epiweeks$from, 100001)
+  expect_identical(call$params$epiweeks$to, 300001)
+
+  expect_no_error(call <- pub_wiki(
+    articles = "avian_influenza",
+    time_type = "day",
+    time_values = "*",
+    fetch_args = fetch_args_list(dry_run = TRUE)
+  ))
+  expect_identical(call$params$dates$from, 10000101)
+  expect_identical(call$params$dates$to, 30000101)
 })
 
 test_that("endpoints fail when given args via dots", {
@@ -413,13 +466,15 @@ test_that("endpoints fail when given args via dots", {
     pvt_twitter(
       auth = "yourkey",
       locations = "CA",
-      date_range = epirange(201501, 202001)
+      time_type = "week",
+      time_range = epirange(201501, 202001)
     ),
     regexp = dots_error
   )
   expect_error(
     pub_wiki(
       articles = "avian_influenza",
+      time_type = "week",
       date_range = epirange(201501, 202001)
     ),
     regexp = dots_error
diff --git a/vignettes/signal-discovery.Rmd b/vignettes/signal-discovery.Rmd
@@ -282,7 +282,12 @@ pub_paho_dengue(regions = "ca", epiweeks = epirange(200201, 202319))
 API docs: <https://cmu-delphi.github.io/delphi-epidata/api/wiki.html>
 
 ```{r, eval = FALSE}
-pub_wiki(language = "en", articles = "influenza", epiweeks = epirange(202001, 202319))
+pub_wiki(
+  language = "en",
+  articles = "influenza",
+  time_type = "week",
+  time_values = epirange(202001, 202319)
+)
 ```
 
 ### Private methods
@@ -373,7 +378,8 @@ API docs: <https://cmu-delphi.github.io/delphi-epidata/api/twitter.html>
 pvt_twitter(
   auth = Sys.getenv("SECRET_API_AUTH_TWITTER"),
   locations = "nat",
-  epiweeks = epirange(200301, 202105)
+  time_type = "week",
+  time_values = epirange(200301, 202105)
 )
 ```
 
