diff --git a/NEWS.md b/NEWS.md index 0f0f3d81..fe957aa9 100644 --- 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 index a0b3a77e..0146ca64 100644 --- 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,14 +2198,27 @@ 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) @@ -2194,9 +2226,6 @@ pub_wiki <- function( 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 index 2669ff1a..278dca58 100644 --- a/man/pub_wiki.Rd +++ b/man/pub_wiki.Rd @@ -7,8 +7,8 @@ pub_wiki( articles, ..., - dates = NULL, - epiweeks = NULL, + time_type = c("day", "week"), + time_values = "*", hours = NULL, language = "en", fetch_args = fetch_args_list() @@ -19,10 +19,11 @@ pub_wiki( \item{...}{not used for values, forces later arguments to bind by name} -\item{dates}{\code{\link{timeset}}. Dates to fetch. Mutually exclusive with \code{epiweeks}.} +\item{time_type}{string. The temporal resolution of the data (either "day" or +"week", depending on signal).} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Mutually exclusive with -\code{dates}.} +\item{time_values}{\code{\link{timeset}}. Dates or epiweeks to fetch. Defaults to all +("*") dates.} \item{hours}{integer. Optionally, the hours to fetch.} @@ -46,7 +47,11 @@ Number of page visits for selected English, Influenza-related wikipedia articles } \examples{ \dontrun{ -pub_wiki(articles = "avian_influenza", epiweeks = epirange(201501, 201601)) +pub_wiki( + articles = "avian_influenza", + time_type = "week", + time_values = epirange(201501, 201601) +) } } \keyword{endpoint} diff --git a/man/pvt_twitter.Rd b/man/pvt_twitter.Rd index ffee87b2..b6c6e95f 100644 --- a/man/pvt_twitter.Rd +++ b/man/pvt_twitter.Rd @@ -8,8 +8,8 @@ pvt_twitter( auth, locations, ..., - dates = NULL, - epiweeks = NULL, + time_type = c("day", "week"), + time_values = "*", fetch_args = fetch_args_list() ) } @@ -20,10 +20,11 @@ pvt_twitter( \item{...}{not used for values, forces later arguments to bind by name} -\item{dates}{\code{\link{timeset}}. Dates to fetch. Mutually exclusive with \code{epiweeks}.} +\item{time_type}{string. The temporal resolution of the data (either "day" or +"week", depending on signal).} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Mutually exclusive with -\code{dates}.} +\item{time_values}{\code{\link{timeset}}. Dates or epiweeks to fetch. Defaults to all +("*") dates.} \item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} } @@ -42,7 +43,8 @@ Delphi’s epidemiological data. Sourced from pvt_twitter( auth = Sys.getenv("SECRET_API_AUTH_TWITTER"), locations = "CA", - epiweeks = epirange(201501, 202001) + time_type = "week", + time_values = epirange(201501, 202001) ) } } diff --git a/tests/testthat/test-endpoints.R b/tests/testthat/test-endpoints.R index b6da6a25..39194535 100644 --- 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 index 8ed0aac9..70a081ae 100644 --- 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: ```{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: pvt_twitter( auth = Sys.getenv("SECRET_API_AUTH_TWITTER"), locations = "nat", - epiweeks = epirange(200301, 202105) + time_type = "week", + time_values = epirange(200301, 202105) ) ```