diff --git a/DESCRIPTION b/DESCRIPTION index 3e1fc47e..77db02e0 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -39,7 +39,7 @@ Imports: tibble, usethis, xml2 -RoxygenNote: 7.2.3 +RoxygenNote: 7.3.0 Suggests: dplyr, ggplot2, diff --git a/NAMESPACE b/NAMESPACE index d9630348..d0907cfd 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -51,6 +51,7 @@ export(save_api_key) export(set_cache) import(cachem) import(glue) +importFrom(MMWRweek,MMWRweek) importFrom(MMWRweek,MMWRweek2Date) importFrom(checkmate,assert) importFrom(checkmate,assert_character) diff --git a/NEWS.md b/NEWS.md index e41e8fc6..fe957aa9 100644 --- a/NEWS.md +++ b/NEWS.md @@ -20,6 +20,8 @@ - `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 ebc74fce..0146ca64 100644 --- a/R/endpoints.R +++ b/R/endpoints.R @@ -14,14 +14,20 @@ #' #' @param auth string. Restricted access key (not the same as API key). #' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' See `fetch_args_list()` for details. #' @return [`tibble::tibble`] #' #' @keywords endpoint #' @export -pvt_cdc <- function(auth, locations, epiweeks, fetch_args = fetch_args_list()) { +pvt_cdc <- function( + auth, + locations, + epiweeks = "*", + fetch_args = fetch_args_list()) { + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("auth", auth, len = 1) assert_character_param("locations", locations) assert_timeset_param("epiweeks", epiweeks) @@ -155,32 +161,62 @@ pub_covid_hosp_facility_lookup <- function( #' hospital_pks = "100075", #' collection_weeks = epirange(20200101, 20200501) #' ) +#' +#' pub_covid_hosp_facility( +#' hospital_pks = "100075", +#' collection_weeks = epirange(202001, 202005) +#' ) #' } #' @param hospital_pks character. Facility identifiers. -#' @param collection_weeks [`timeset`]. Epiweeks to fetch. +#' @param collection_weeks [`timeset`]. Dates (corresponding to epiweeks) to +#' fetch. Defaults to all ("*") dates. #' @param ... not used for values, forces later arguments to bind by name #' @param publication_dates [`timeset`]. Publication dates to fetch. #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' @return [`tibble::tibble`] #' +#' @importFrom checkmate test_class test_integerish test_character +#' #' @seealso [`pub_covid_hosp_facility()`], [`epirange()`] #' @keywords endpoint #' @export # pub_covid_hosp_facility <- function( hospital_pks, - collection_weeks, + collection_weeks = "*", ..., publication_dates = NULL, fetch_args = fetch_args_list()) { rlang::check_dots_empty() + collection_weeks <- get_wildcard_equivalent_dates(collection_weeks, "day") + assert_character_param("hospital_pks", hospital_pks) assert_timeset_param("collection_weeks", collection_weeks) assert_timeset_param("publication_dates", publication_dates, required = FALSE) collection_weeks <- parse_timeset_input(collection_weeks) publication_dates <- parse_timeset_input(publication_dates) + # Confusingly, the endpoint expects `collection_weeks` to be in day format, + # but correspond to epiweeks. Allow `collection_weeks` to be provided in + # either day or week format. + coercion_msg <- c( + "`collection_weeks` is in week format but `pub_covid_hosp_facility` + expects day format; dates will be converted to day format but may not + correspond exactly to desired time range" + ) + if (test_class(collection_weeks, "EpiRange") && nchar(collection_weeks$from) == 6) { + 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 + ) { + cli::cli_warn(coercion_msg, class = "epidatr__single_week_coercion") + collection_weeks <- parse_api_week(collection_weeks) + } + create_epidata_call( "covid_hosp_facility/", list( @@ -516,7 +552,7 @@ pub_covid_hosp_facility <- function( #' } #' #' @param states character. Two letter state abbreviations. -#' @param dates [`timeset`]. Dates to fetch. +#' @param dates [`timeset`]. Dates to fetch. Defaults to all ("*") dates. #' @param ... not used for values, forces later arguments to bind by name #' @param as_of Date. Optionally, the as of date for the issues to fetch. If not #' specified, the most recent data is returned. Mutually exclusive with @@ -532,7 +568,7 @@ pub_covid_hosp_facility <- function( # pub_covid_hosp_state_timeseries <- function( states, - dates, + dates = "*", ..., as_of = NULL, issues = NULL, @@ -550,6 +586,8 @@ pub_covid_hosp_state_timeseries <- function( stop("`issues`and `as_of` are mutually exclusive") } + dates <- get_wildcard_equivalent_dates(dates, "day") + assert_character_param("states", states) assert_timeset_param("dates", dates) assert_date_param("as_of", as_of, len = 1, required = FALSE) @@ -925,7 +963,7 @@ pub_covidcast_meta <- function(fetch_args = fetch_args_list()) { #' @param geo_values character. The geographies to return. "*" fetches #' all. (See: #' .) -#' @param time_values [`timeset`]. Dates to fetch. +#' @param time_values [`timeset`]. Dates to fetch. Defaults to all ("*") dates. #' @param ... not used for values, forces later arguments to bind by name #' @param as_of Date. Optionally, the as of date for the issues to fetch. If not #' specified, the most recent data is returned. Mutually exclusive with @@ -947,8 +985,8 @@ pub_covidcast <- function( signals, geo_type, time_type, - geo_values, - time_values, + geo_values = "*", + time_values = "*", ..., as_of = NULL, issues = NULL, @@ -1036,12 +1074,16 @@ pub_covidcast <- function( #' pub_delphi(system = "ec", epiweek = 201501) #' } #' @param system character. System name to fetch. -#' @param epiweek [`timeset`]. Epiweeks to fetch. +#' @param epiweek [`timeset`]. Epiweek to fetch. Does not support multiple dates. +#' Make separate calls to fetch data for multiple epiweeks. #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' @return [`list`] #' @keywords endpoint #' @export -pub_delphi <- function(system, epiweek, fetch_args = fetch_args_list()) { +pub_delphi <- function( + system, + epiweek, + fetch_args = fetch_args_list()) { assert_character_param("system", system) assert_timeset_param("epiweek", epiweek, len = 1) epiweek <- parse_timeset_input(epiweek) @@ -1070,12 +1112,17 @@ pub_delphi <- function(system, epiweek, fetch_args = fetch_args_list()) { #' ) #' } #' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pub_dengue_nowcast <- function(locations, epiweeks, fetch_args = fetch_args_list()) { +pub_dengue_nowcast <- function( + locations, + epiweeks = "*", + fetch_args = fetch_args_list()) { + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("locations", locations) assert_timeset_param("epiweeks", epiweeks) epiweeks <- parse_timeset_input(epiweeks) @@ -1108,12 +1155,19 @@ pub_dengue_nowcast <- function(locations, epiweeks, fetch_args = fetch_args_list #' @param auth string. Restricted access key (not the same as API key). #' @param names character. Names to fetch. #' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pvt_dengue_sensors <- function(auth, names, locations, epiweeks, fetch_args = fetch_args_list()) { +pvt_dengue_sensors <- function( + auth, + names, + locations, + epiweeks = "*", + fetch_args = fetch_args_list()) { + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("auth", auth, len = 1) assert_character_param("names", names) assert_character_param("locations", locations) @@ -1153,7 +1207,7 @@ pvt_dengue_sensors <- function(auth, names, locations, epiweeks, fetch_args = fe #' pub_ecdc_ili(regions = "austria", epiweeks = epirange(201901, 202001)) #' } #' @param regions character. Regions to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param ... not used for values, forces later arguments to bind by name #' @param issues [`timeset`]. Optionally, the issues to fetch. If not set, the #' most recent issue is returned. Mutually exclusive with `lag`. @@ -1163,9 +1217,17 @@ pvt_dengue_sensors <- function(auth, names, locations, epiweeks, fetch_args = fe #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pub_ecdc_ili <- function(regions, epiweeks, ..., issues = NULL, lag = NULL, fetch_args = fetch_args_list()) { +pub_ecdc_ili <- function( + regions, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list()) { rlang::check_dots_empty() + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("regions", regions) assert_timeset_param("epiweeks", epiweeks) assert_timeset_param("issues", issues, required = FALSE) @@ -1212,7 +1274,7 @@ pub_ecdc_ili <- function(regions, epiweeks, ..., issues = NULL, lag = NULL, fetc #' pub_flusurv(locations = "CA", epiweeks = epirange(201701, 201801)) #' } #' @param locations character. Character vector indicating location. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param ... not used for values, forces later arguments to bind by name #' @param issues [`timeset`]. Optionally, the issues to fetch. If not set, the #' most recent issue is returned. Mutually exclusive with `lag`. @@ -1222,9 +1284,17 @@ pub_ecdc_ili <- function(regions, epiweeks, ..., issues = NULL, lag = NULL, fetc #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pub_flusurv <- function(locations, epiweeks, ..., issues = NULL, lag = NULL, fetch_args = fetch_args_list()) { +pub_flusurv <- function( + locations, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list()) { rlang::check_dots_empty() + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("locations", locations) assert_timeset_param("epiweeks", epiweeks) assert_timeset_param("issues", issues, required = FALSE) @@ -1270,7 +1340,7 @@ pub_flusurv <- function(locations, epiweeks, ..., issues = NULL, lag = NULL, fet #' @param regions character. Regions to fetch. #' @param epiweeks [`timeset`]. Epiweeks to fetch in the form #' epirange(startweek,endweek), where startweek and endweek are of the form -#' YYYYWW (string or numeric). +#' YYYYWW (string or numeric). Defaults to all ("*") dates. #' @param ... not used for values, forces later arguments to bind by name #' @param issues [`timeset`]. Optionally, the issues to fetch. If not set, the #' most recent issue is returned. Mutually exclusive with `lag`. @@ -1280,9 +1350,17 @@ pub_flusurv <- function(locations, epiweeks, ..., issues = NULL, lag = NULL, fet #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pub_fluview_clinical <- function(regions, epiweeks, ..., issues = NULL, lag = NULL, fetch_args = fetch_args_list()) { +pub_fluview_clinical <- function( + regions, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list()) { rlang::check_dots_empty() + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("regions", regions) assert_timeset_param("epiweeks", epiweeks) assert_timeset_param("issues", issues, required = FALSE) @@ -1367,7 +1445,7 @@ pub_fluview_meta <- function(fetch_args = fetch_args_list()) { #' on. Full list link below. #' @param epiweeks [`timeset`]. Epiweeks to fetch in the form #' `epirange(startweek, endweek)`, where startweek and endweek are of the form -#' YYYYWW (string or numeric). +#' YYYYWW (string or numeric). Defaults to all ("*") dates. #' @param ... not used for values, forces later arguments to bind by name #' @param issues [`timeset`]. Optionally, the issues to fetch. If not set, the #' most recent issue is returned. Mutually exclusive with `lag`. @@ -1381,7 +1459,7 @@ pub_fluview_meta <- function(fetch_args = fetch_args_list()) { #' @export pub_fluview <- function( regions, - epiweeks, + epiweeks = "*", ..., issues = NULL, lag = NULL, @@ -1389,6 +1467,8 @@ pub_fluview <- function( fetch_args = fetch_args_list()) { rlang::check_dots_empty() + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("regions", regions) assert_timeset_param("epiweeks", epiweeks) assert_timeset_param("issues", issues, required = FALSE) @@ -1451,13 +1531,18 @@ pub_fluview <- function( #' pub_gft(locations = "hhs1", epiweeks = epirange(201201, 202001)) #' } #' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`] Epiweeks to fetch. +#' @param epiweeks [`timeset`] Epiweeks to fetch. Defaults to all ("*") dates. #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pub_gft <- function(locations, epiweeks, fetch_args = fetch_args_list()) { +pub_gft <- function( + locations, + epiweeks = "*", + fetch_args = fetch_args_list()) { + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("locations", locations) assert_timeset_param("epiweeks", epiweeks) epiweeks <- parse_timeset_input(epiweeks) @@ -1491,13 +1576,20 @@ pub_gft <- function(locations, epiweeks, fetch_args = fetch_args_list()) { #' } #' @param auth string. Restricted access key (not the same as API key). #' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param query string. The query to be fetched. #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pvt_ght <- function(auth, locations, epiweeks, query, fetch_args = fetch_args_list()) { +pvt_ght <- function( + auth, + locations, + epiweeks = "*", + query, + fetch_args = fetch_args_list()) { + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("auth", auth, len = 1) assert_character_param("locations", locations) assert_timeset_param("epiweeks", epiweeks) @@ -1529,7 +1621,7 @@ pvt_ght <- function(auth, locations, epiweeks, query, fetch_args = fetch_args_li #' pub_kcdc_ili(regions = "ROK", epiweeks = 200436) #' } #' @param regions character. Regions to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param ... not used for values, forces later arguments to bind by name #' @param issues [`timeset`]. Optionally, the issues to fetch. If not set, the #' most recent issue is returned. Mutually exclusive with `lag`. @@ -1539,9 +1631,17 @@ pvt_ght <- function(auth, locations, epiweeks, query, fetch_args = fetch_args_li #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pub_kcdc_ili <- function(regions, epiweeks, ..., issues = NULL, lag = NULL, fetch_args = fetch_args_list()) { +pub_kcdc_ili <- function( + regions, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list()) { rlang::check_dots_empty() + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("regions", regions) assert_timeset_param("epiweeks", epiweeks) assert_timeset_param("issues", issues, required = FALSE) @@ -1626,13 +1726,18 @@ pub_meta <- function(fetch_args = fetch_args_list()) { #' pub_nidss_dengue(locations = "taipei", epiweeks = epirange(201201, 201301)) #' } #' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pub_nidss_dengue <- function(locations, epiweeks, fetch_args = fetch_args_list()) { +pub_nidss_dengue <- function( + locations, + epiweeks = "*", + fetch_args = fetch_args_list()) { + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("locations", locations) assert_timeset_param("epiweeks", epiweeks) epiweeks <- parse_timeset_input(epiweeks) @@ -1661,7 +1766,7 @@ pub_nidss_dengue <- function(locations, epiweeks, fetch_args = fetch_args_list() #' pub_nidss_flu(regions = "taipei", epiweeks = epirange(201501, 201601)) #' } #' @param regions character. Regions to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param ... not used for values, forces later arguments to bind by name #' @param issues [`timeset`]. Optionally, the issues to fetch. If not set, the #' most recent issue is returned. Mutually exclusive with `lag`. @@ -1671,9 +1776,17 @@ pub_nidss_dengue <- function(locations, epiweeks, fetch_args = fetch_args_list() #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pub_nidss_flu <- function(regions, epiweeks, ..., issues = NULL, lag = NULL, fetch_args = fetch_args_list()) { +pub_nidss_flu <- function( + regions, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list()) { rlang::check_dots_empty() + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("regions", regions) assert_timeset_param("epiweeks", epiweeks) assert_timeset_param("issues", issues, required = FALSE) @@ -1725,12 +1838,18 @@ pub_nidss_flu <- function(regions, epiweeks, ..., issues = NULL, lag = NULL, fet #' } #' @param auth string. Your authentication key. #' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pvt_norostat <- function(auth, locations, epiweeks, fetch_args = fetch_args_list()) { +pvt_norostat <- function( + auth, + locations, + epiweeks = "*", + fetch_args = fetch_args_list()) { + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("auth", auth, len = 1) assert_character_param("locations", locations, len = 1) assert_timeset_param("epiweeks", epiweeks) @@ -1765,12 +1884,17 @@ pvt_norostat <- function(auth, locations, epiweeks, fetch_args = fetch_args_list #' pub_nowcast(locations = "ca", epiweeks = epirange(201201, 201301)) #' } #' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pub_nowcast <- function(locations, epiweeks, fetch_args = fetch_args_list()) { +pub_nowcast <- function( + locations, + epiweeks = "*", + fetch_args = fetch_args_list()) { + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("locations", locations) assert_timeset_param("epiweeks", epiweeks) epiweeks <- parse_timeset_input(epiweeks) @@ -1796,7 +1920,7 @@ pub_nowcast <- function(locations, epiweeks, fetch_args = fetch_args_list()) { #' pub_paho_dengue(regions = "ca", epiweeks = epirange(201401, 201501)) #' } #' @param regions character. Regions to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param ... not used for values, forces later arguments to bind by name #' @param issues [`timeset`]. Optionally, the issues to fetch. If not set, the #' most recent issue is returned. Mutually exclusive with `lag`. @@ -1806,9 +1930,17 @@ pub_nowcast <- function(locations, epiweeks, fetch_args = fetch_args_list()) { #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pub_paho_dengue <- function(regions, epiweeks, ..., issues = NULL, lag = NULL, fetch_args = fetch_args_list()) { +pub_paho_dengue <- function( + regions, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list()) { rlang::check_dots_empty() + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("regions", regions) assert_timeset_param("epiweeks", epiweeks) assert_timeset_param("issues", issues, required = FALSE) @@ -1856,12 +1988,18 @@ pub_paho_dengue <- function(regions, epiweeks, ..., issues = NULL, lag = NULL, f #' } #' @param auth string. Restricted access key (not the same as API key). #' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pvt_quidel <- function(auth, locations, epiweeks, fetch_args = fetch_args_list()) { +pvt_quidel <- function( + auth, + locations, + epiweeks = "*", + fetch_args = fetch_args_list()) { + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("auth", auth, len = 1) assert_character_param("locations", locations) assert_timeset_param("epiweeks", epiweeks) @@ -1909,12 +2047,19 @@ pvt_quidel <- function(auth, locations, epiweeks, fetch_args = fetch_args_list() #' @param auth string. Restricted access key (not the same as API key). #' @param names character. Sensor names to fetch. #' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. #' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' @return [`tibble::tibble`] #' @keywords endpoint #' @export -pvt_sensors <- function(auth, names, locations, epiweeks, fetch_args = fetch_args_list()) { +pvt_sensors <- function( + auth, + names, + locations, + epiweeks = "*", + fetch_args = fetch_args_list()) { + epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") + assert_character_param("auth", auth, len = 1) assert_character_param("names", names) assert_character_param("locations", locations) @@ -1951,32 +2096,50 @@ pvt_sensors <- function(auth, names, locations, epiweeks, fetch_args = fetch_arg #' 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 #' @export -pvt_twitter <- function(auth, locations, ..., dates = NULL, epiweeks = NULL, fetch_args = fetch_args_list()) { +pvt_twitter <- function( + auth, + locations, + ..., + 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 { @@ -2014,13 +2177,18 @@ pvt_twitter <- function(auth, locations, ..., dates = NULL, epiweeks = NULL, fet #' #' @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()`. @@ -2030,14 +2198,27 @@ pvt_twitter <- function(auth, locations, ..., dates = NULL, epiweeks = NULL, fet 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) @@ -2045,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/R/model.R b/R/model.R index a14f8960..38008262 100644 --- a/R/model.R +++ b/R/model.R @@ -61,6 +61,27 @@ epirange <- function(from, to) { structure(list(from = from, to = to), class = "EpiRange") } +#' helper to convert an epirange from week to day or vice versa +#' +#' @keywords internal +reformat_epirange <- function(epirange, to_type = c("day", "week")) { + to_type <- match.arg(to_type) + + # Day format -> week + if (nchar(epirange$from) == 8 && to_type == "week") { + return( + epirange(date_to_epiweek(epirange$from), date_to_epiweek(epirange$to)) + ) + # Week format -> day + } else if (nchar(epirange$from) == 6 && to_type == "day") { + return( + epirange(parse_api_week(epirange$from), parse_api_week(epirange$to)) + ) + } + + return(epirange) +} + #' @export print.EpiRange <- function(x, ...) { if (nchar(x$from) == 8) { @@ -199,6 +220,20 @@ parse_data_frame <- function(epidata_call, df, disable_date_parsing = FALSE) { df } +#' Converts a date (integer or character) to an epiweek +#' @param value date (integer or character, with format YYYYMMDD) to be converted to an epiweek +#' @return an integer representing an epiweek, in the format YYYYWW +#' @importFrom MMWRweek MMWRweek +#' @keywords internal +date_to_epiweek <- function(value) { + date_components <- MMWRweek::MMWRweek(as.Date(as.character(value), "%Y%m%d")) + as.numeric(paste0( + date_components$MMWRyear, + # Pad with zeroes up to 2 digits (x -> 0x) + formatC(date_components$MMWRweek, width = 2, flag = 0) + )) +} + #' @keywords internal parse_api_date <- function(value) { as.Date(as.character(value), tryFormats = c("%Y%m%d", "%Y-%m-%d")) diff --git a/R/utils.R b/R/utils.R index eed7c88f..705ff368 100644 --- a/R/utils.R +++ b/R/utils.R @@ -44,3 +44,20 @@ check_is_cachable <- function(epidata_call, fetch_args) { ) return(is_cachable) } + +#' helper to convert a date wildcard ("*") to an appropriate epirange +#' +#' @keywords internal +get_wildcard_equivalent_dates <- function(time_value, time_type = c("day", "week")) { + time_type <- match.arg(time_type) + + if (identical(time_value, "*")) { + if (time_type == "day") { + # To get all dates, set start and end dates to extreme values. + time_value <- epirange(10000101, 30000101) + } else if (time_type == "week") { + time_value <- epirange(100001, 300001) + } + } + return(time_value) +} diff --git a/man/date_to_epiweek.Rd b/man/date_to_epiweek.Rd new file mode 100644 index 00000000..7f1f4262 --- /dev/null +++ b/man/date_to_epiweek.Rd @@ -0,0 +1,18 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/model.R +\name{date_to_epiweek} +\alias{date_to_epiweek} +\title{Converts a date (integer or character) to an epiweek} +\usage{ +date_to_epiweek(value) +} +\arguments{ +\item{value}{date (integer or character, with format YYYYMMDD) to be converted to an epiweek} +} +\value{ +an integer representing an epiweek, in the format YYYYWW +} +\description{ +Converts a date (integer or character) to an epiweek +} +\keyword{internal} diff --git a/man/get_wildcard_equivalent_dates.Rd b/man/get_wildcard_equivalent_dates.Rd new file mode 100644 index 00000000..590a4745 --- /dev/null +++ b/man/get_wildcard_equivalent_dates.Rd @@ -0,0 +1,12 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{get_wildcard_equivalent_dates} +\alias{get_wildcard_equivalent_dates} +\title{helper to convert a date wildcard ("*") to an appropriate epirange} +\usage{ +get_wildcard_equivalent_dates(time_value, time_type = c("day", "week")) +} +\description{ +helper to convert a date wildcard ("*") to an appropriate epirange +} +\keyword{internal} diff --git a/man/pub_covid_hosp_facility.Rd b/man/pub_covid_hosp_facility.Rd index 46d6f51e..59f4ff9b 100644 --- a/man/pub_covid_hosp_facility.Rd +++ b/man/pub_covid_hosp_facility.Rd @@ -6,7 +6,7 @@ \usage{ pub_covid_hosp_facility( hospital_pks, - collection_weeks, + collection_weeks = "*", ..., publication_dates = NULL, fetch_args = fetch_args_list() @@ -15,7 +15,8 @@ pub_covid_hosp_facility( \arguments{ \item{hospital_pks}{character. Facility identifiers.} -\item{collection_weeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{collection_weeks}{\code{\link{timeset}}. Dates (corresponding to epiweeks) to +fetch. Defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} @@ -45,6 +46,11 @@ pub_covid_hosp_facility( hospital_pks = "100075", collection_weeks = epirange(20200101, 20200501) ) + +pub_covid_hosp_facility( + hospital_pks = "100075", + collection_weeks = epirange(202001, 202005) +) } } \seealso{ diff --git a/man/pub_covid_hosp_state_timeseries.Rd b/man/pub_covid_hosp_state_timeseries.Rd index 2823f6da..246bf7b1 100644 --- a/man/pub_covid_hosp_state_timeseries.Rd +++ b/man/pub_covid_hosp_state_timeseries.Rd @@ -6,7 +6,7 @@ \usage{ pub_covid_hosp_state_timeseries( states, - dates, + dates = "*", ..., as_of = NULL, issues = NULL, @@ -16,7 +16,7 @@ pub_covid_hosp_state_timeseries( \arguments{ \item{states}{character. Two letter state abbreviations.} -\item{dates}{\code{\link{timeset}}. Dates to fetch.} +\item{dates}{\code{\link{timeset}}. Dates to fetch. Defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} diff --git a/man/pub_covidcast.Rd b/man/pub_covidcast.Rd index 0d87bcd6..65fb736f 100644 --- a/man/pub_covidcast.Rd +++ b/man/pub_covidcast.Rd @@ -9,8 +9,8 @@ pub_covidcast( signals, geo_type, time_type, - geo_values, - time_values, + geo_values = "*", + time_values = "*", ..., as_of = NULL, issues = NULL, @@ -35,7 +35,7 @@ pub_covidcast( all. (See: \url{https://cmu-delphi.github.io/delphi-epidata/api/covidcast_geography.html}.)} -\item{time_values}{\code{\link{timeset}}. Dates to fetch.} +\item{time_values}{\code{\link{timeset}}. Dates to fetch. Defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} diff --git a/man/pub_delphi.Rd b/man/pub_delphi.Rd index 4613ad6c..fe278beb 100644 --- a/man/pub_delphi.Rd +++ b/man/pub_delphi.Rd @@ -9,7 +9,8 @@ pub_delphi(system, epiweek, fetch_args = fetch_args_list()) \arguments{ \item{system}{character. System name to fetch.} -\item{epiweek}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweek}{\code{\link{timeset}}. Epiweek to fetch. Does not support multiple dates. +Make separate calls to fetch data for multiple epiweeks.} \item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} } diff --git a/man/pub_dengue_nowcast.Rd b/man/pub_dengue_nowcast.Rd index f3709faf..e1c2573c 100644 --- a/man/pub_dengue_nowcast.Rd +++ b/man/pub_dengue_nowcast.Rd @@ -4,12 +4,12 @@ \alias{pub_dengue_nowcast} \title{Delphi's PAHO dengue nowcasts (North and South America)} \usage{ -pub_dengue_nowcast(locations, epiweeks, fetch_args = fetch_args_list()) +pub_dengue_nowcast(locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ \item{locations}{character. Locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} } diff --git a/man/pub_ecdc_ili.Rd b/man/pub_ecdc_ili.Rd index 7546d28f..d71b5651 100644 --- a/man/pub_ecdc_ili.Rd +++ b/man/pub_ecdc_ili.Rd @@ -6,7 +6,7 @@ \usage{ pub_ecdc_ili( regions, - epiweeks, + epiweeks = "*", ..., issues = NULL, lag = NULL, @@ -16,7 +16,7 @@ pub_ecdc_ili( \arguments{ \item{regions}{character. Regions to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} diff --git a/man/pub_flusurv.Rd b/man/pub_flusurv.Rd index 8d15ccfb..e8fd5bb0 100644 --- a/man/pub_flusurv.Rd +++ b/man/pub_flusurv.Rd @@ -6,7 +6,7 @@ \usage{ pub_flusurv( locations, - epiweeks, + epiweeks = "*", ..., issues = NULL, lag = NULL, @@ -16,7 +16,7 @@ pub_flusurv( \arguments{ \item{locations}{character. Character vector indicating location.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} diff --git a/man/pub_fluview.Rd b/man/pub_fluview.Rd index 30c47449..61ba357a 100644 --- a/man/pub_fluview.Rd +++ b/man/pub_fluview.Rd @@ -6,7 +6,7 @@ \usage{ pub_fluview( regions, - epiweeks, + epiweeks = "*", ..., issues = NULL, lag = NULL, @@ -21,7 +21,7 @@ on. Full list link below.} \item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch in the form \code{epirange(startweek, endweek)}, where startweek and endweek are of the form -YYYYWW (string or numeric).} +YYYYWW (string or numeric). Defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} diff --git a/man/pub_fluview_clinical.Rd b/man/pub_fluview_clinical.Rd index db2eccbf..a4017c76 100644 --- a/man/pub_fluview_clinical.Rd +++ b/man/pub_fluview_clinical.Rd @@ -6,7 +6,7 @@ \usage{ pub_fluview_clinical( regions, - epiweeks, + epiweeks = "*", ..., issues = NULL, lag = NULL, @@ -18,7 +18,7 @@ pub_fluview_clinical( \item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch in the form epirange(startweek,endweek), where startweek and endweek are of the form -YYYYWW (string or numeric).} +YYYYWW (string or numeric). Defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} diff --git a/man/pub_gft.Rd b/man/pub_gft.Rd index ed736232..c80d8d9a 100644 --- a/man/pub_gft.Rd +++ b/man/pub_gft.Rd @@ -4,12 +4,12 @@ \alias{pub_gft} \title{Google Flu Trends flu search volume} \usage{ -pub_gft(locations, epiweeks, fetch_args = fetch_args_list()) +pub_gft(locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ \item{locations}{character. Locations to fetch.} -\item{epiweeks}{\code{\link{timeset}} Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}} Epiweeks to fetch. Defaults to all ("*") dates.} \item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} } diff --git a/man/pub_kcdc_ili.Rd b/man/pub_kcdc_ili.Rd index c6f4ab8e..0c8b70f4 100644 --- a/man/pub_kcdc_ili.Rd +++ b/man/pub_kcdc_ili.Rd @@ -6,7 +6,7 @@ \usage{ pub_kcdc_ili( regions, - epiweeks, + epiweeks = "*", ..., issues = NULL, lag = NULL, @@ -16,7 +16,7 @@ pub_kcdc_ili( \arguments{ \item{regions}{character. Regions to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} diff --git a/man/pub_nidss_dengue.Rd b/man/pub_nidss_dengue.Rd index 2f390ac8..67be9c94 100644 --- a/man/pub_nidss_dengue.Rd +++ b/man/pub_nidss_dengue.Rd @@ -4,12 +4,12 @@ \alias{pub_nidss_dengue} \title{NIDSS dengue cases (Taiwan)} \usage{ -pub_nidss_dengue(locations, epiweeks, fetch_args = fetch_args_list()) +pub_nidss_dengue(locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ \item{locations}{character. Locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} } diff --git a/man/pub_nidss_flu.Rd b/man/pub_nidss_flu.Rd index fc0e7d6d..946a1b87 100644 --- a/man/pub_nidss_flu.Rd +++ b/man/pub_nidss_flu.Rd @@ -6,7 +6,7 @@ \usage{ pub_nidss_flu( regions, - epiweeks, + epiweeks = "*", ..., issues = NULL, lag = NULL, @@ -16,7 +16,7 @@ pub_nidss_flu( \arguments{ \item{regions}{character. Regions to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} diff --git a/man/pub_nowcast.Rd b/man/pub_nowcast.Rd index 13aa1a22..306c37f1 100644 --- a/man/pub_nowcast.Rd +++ b/man/pub_nowcast.Rd @@ -4,12 +4,12 @@ \alias{pub_nowcast} \title{Delphi's ILI Nearby nowcasts} \usage{ -pub_nowcast(locations, epiweeks, fetch_args = fetch_args_list()) +pub_nowcast(locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ \item{locations}{character. Locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} } diff --git a/man/pub_paho_dengue.Rd b/man/pub_paho_dengue.Rd index 773927b7..0d643f44 100644 --- a/man/pub_paho_dengue.Rd +++ b/man/pub_paho_dengue.Rd @@ -6,7 +6,7 @@ \usage{ pub_paho_dengue( regions, - epiweeks, + epiweeks = "*", ..., issues = NULL, lag = NULL, @@ -16,7 +16,7 @@ pub_paho_dengue( \arguments{ \item{regions}{character. Regions to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} 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_cdc.Rd b/man/pvt_cdc.Rd index 74497b29..35cc555b 100644 --- a/man/pvt_cdc.Rd +++ b/man/pvt_cdc.Rd @@ -4,14 +4,14 @@ \alias{pvt_cdc} \title{CDC total and by topic webpage visits} \usage{ -pvt_cdc(auth, locations, epiweeks, fetch_args = fetch_args_list()) +pvt_cdc(auth, locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ \item{auth}{string. Restricted access key (not the same as API key).} \item{locations}{character. Locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}. See \code{fetch_args_list()} for details.} diff --git a/man/pvt_dengue_sensors.Rd b/man/pvt_dengue_sensors.Rd index 560e9e4b..2ff7eb30 100644 --- a/man/pvt_dengue_sensors.Rd +++ b/man/pvt_dengue_sensors.Rd @@ -8,7 +8,7 @@ pvt_dengue_sensors( auth, names, locations, - epiweeks, + epiweeks = "*", fetch_args = fetch_args_list() ) } @@ -19,7 +19,7 @@ pvt_dengue_sensors( \item{locations}{character. Locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} } diff --git a/man/pvt_ght.Rd b/man/pvt_ght.Rd index cfa1038c..7a16f10c 100644 --- a/man/pvt_ght.Rd +++ b/man/pvt_ght.Rd @@ -4,14 +4,14 @@ \alias{pvt_ght} \title{Google Health Trends health topics search volume} \usage{ -pvt_ght(auth, locations, epiweeks, query, fetch_args = fetch_args_list()) +pvt_ght(auth, locations, epiweeks = "*", query, fetch_args = fetch_args_list()) } \arguments{ \item{auth}{string. Restricted access key (not the same as API key).} \item{locations}{character. Locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{query}{string. The query to be fetched.} diff --git a/man/pvt_norostat.Rd b/man/pvt_norostat.Rd index 837e16d8..24ffd778 100644 --- a/man/pvt_norostat.Rd +++ b/man/pvt_norostat.Rd @@ -4,14 +4,14 @@ \alias{pvt_norostat} \title{CDC NoroSTAT norovirus outbreaks} \usage{ -pvt_norostat(auth, locations, epiweeks, fetch_args = fetch_args_list()) +pvt_norostat(auth, locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ \item{auth}{string. Your authentication key.} \item{locations}{character. Locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} } diff --git a/man/pvt_quidel.Rd b/man/pvt_quidel.Rd index 909df751..10ca3c0a 100644 --- a/man/pvt_quidel.Rd +++ b/man/pvt_quidel.Rd @@ -4,14 +4,14 @@ \alias{pvt_quidel} \title{Quidel COVID-19 and influenza testing data} \usage{ -pvt_quidel(auth, locations, epiweeks, fetch_args = fetch_args_list()) +pvt_quidel(auth, locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ \item{auth}{string. Restricted access key (not the same as API key).} \item{locations}{character. Locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} } diff --git a/man/pvt_sensors.Rd b/man/pvt_sensors.Rd index 24073803..35e41bf0 100644 --- a/man/pvt_sensors.Rd +++ b/man/pvt_sensors.Rd @@ -4,7 +4,13 @@ \alias{pvt_sensors} \title{Influenza and dengue digital surveillance sensors} \usage{ -pvt_sensors(auth, names, locations, epiweeks, fetch_args = fetch_args_list()) +pvt_sensors( + auth, + names, + locations, + epiweeks = "*", + fetch_args = fetch_args_list() +) } \arguments{ \item{auth}{string. Restricted access key (not the same as API key).} @@ -13,7 +19,7 @@ pvt_sensors(auth, names, locations, epiweeks, fetch_args = fetch_args_list()) \item{locations}{character. Locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} \item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} } 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/man/reformat_epirange.Rd b/man/reformat_epirange.Rd new file mode 100644 index 00000000..5341c521 --- /dev/null +++ b/man/reformat_epirange.Rd @@ -0,0 +1,12 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/model.R +\name{reformat_epirange} +\alias{reformat_epirange} +\title{helper to convert an epirange from week to day or vice versa} +\usage{ +reformat_epirange(epirange, to_type = c("day", "week")) +} +\description{ +helper to convert an epirange from week to day or vice versa +} +\keyword{internal} diff --git a/tests/testthat/test-endpoints.R b/tests/testthat/test-endpoints.R index 53aca4cf..39194535 100644 --- a/tests/testthat/test-endpoints.R +++ b/tests/testthat/test-endpoints.R @@ -137,16 +137,246 @@ 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()) }) +test_that("endoints accept wildcard for date parameter", { + expect_no_error(call <- pvt_cdc( + auth = "yourkey", + "fl,ca", + "*", + fetch_args = fetch_args_list(dry_run = TRUE) + )) + expect_identical(call$params$epiweeks$from, 100001) + expect_identical(call$params$epiweeks$to, 300001) + + expect_identical(call$params$epiweeks$from, 100001) + expect_identical(call$params$epiweeks$to, 300001) + + expect_no_error(call <- pub_covid_hosp_facility( + hospital_pks = "100075", + collection_weeks = "*", + fetch_args = fetch_args_list(dry_run = TRUE) + )) + expect_identical(call$params$collection_weeks$from, 10000101) + expect_identical(call$params$collection_weeks$to, 30000101) + + expect_no_error(call <- pub_covid_hosp_state_timeseries( + states = "fl", + dates = "*", + 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_covidcast( + source = "jhu-csse", + signals = "confirmed_7dav_incidence_prop", + time_type = "day", + geo_type = "state", + time_values = "*", + geo_values = "ca,fl", + fetch_args = fetch_args_list(dry_run = TRUE) + )) + expect_identical(call$params$time_values, "*") + + expect_no_error(call <- pub_dengue_nowcast( + locations = "ca", + epiweeks = "*", + 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_dengue_sensors( + auth = "yourkey", + names = "ght", + locations = "ag", + epiweeks = "*", + 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_ecdc_ili( + regions = "austria", + epiweeks = "*", + 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_flusurv( + locations = "CA", + epiweeks = "*", + 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_fluview_clinical( + regions = "nat", + epiweeks = "*", + 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_fluview( + regions = "nat", + epiweeks = "*", + 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_gft( + locations = "hhs1", + epiweeks = "*", + 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_ght( + auth = "yourkey", + locations = "ca", + epiweeks = "*", + query = "how to get over the flu", + 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_kcdc_ili( + regions = "ROK", + epiweeks = "*", + 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_nidss_dengue( + locations = "taipei", + epiweeks = "*", + 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_nidss_flu( + regions = "taipei", + epiweeks = "*", + 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_norostat( + auth = "yourkey", + locations = "Minnesota, Ohio, Oregon, Tennessee, and Wisconsin", + epiweeks = "*", + 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_nowcast( + locations = "ca", + epiweeks = "*", + 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_paho_dengue( + regions = "ca", + epiweeks = "*", + 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_quidel( + auth = "yourkey", + locations = "hhs1", + epiweeks = "*", + 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_sensors( + auth = "yourkey", + names = "sar3", + locations = "nat", + epiweeks = "*", + 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 = "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", { dots_error <- "`...` must be empty" @@ -236,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/tests/testthat/test-model.R b/tests/testthat/test-model.R index 9f9b739c..453db0be 100644 --- a/tests/testthat/test-model.R +++ b/tests/testthat/test-model.R @@ -113,3 +113,47 @@ test_that("parse_api_date accepts YYYYMMDD and YYYY-MM-DD", { test_that("parse_api_date handles missing values appropriately", { expect_identical(parse_api_date(NA), as.Date(NA)) }) + +test_that("date_to_epiweek accepts str and int input", { + expect_identical(date_to_epiweek("20200101"), 202001) + expect_identical(date_to_epiweek(20200101), 202001) +}) + +test_that("date_to_epiweek accepts single and double-digit weeks", { + expect_identical(date_to_epiweek(20201101), 202045) + expect_identical(date_to_epiweek(20200109), 202002) +}) + +test_that("reformat_epirange works in basic cases", { + # Week to week + result <- reformat_epirange(epirange(202002, 202013), "week") + expect_identical(result, epirange(202002, 202013)) + + result <- reformat_epirange(epirange("202002", "202013"), "week") + expect_identical(result, epirange("202002", "202013")) + + # Week to day + # Across year boundary + result <- reformat_epirange(epirange(202001, 202013), "day") + expect_identical(result, epirange(20191229, 20200322)) + + result <- reformat_epirange(epirange(202002, 202013), "day") + expect_identical(result, epirange(20200105, 20200322)) + + result <- reformat_epirange(epirange("202002", "202013"), "day") + expect_identical(result, epirange(20200105, 20200322)) + + # Day to week + result <- reformat_epirange(epirange(20200201, 20201031), "week") + expect_identical(result, epirange(202005, 202044)) + + result <- reformat_epirange(epirange("20200201", "20201031"), "week") + expect_identical(result, epirange(202005, 202044)) + + # Day to day + result <- reformat_epirange(epirange(20200201, 20201031), "day") + expect_identical(result, epirange(20200201, 20201031)) + + result <- reformat_epirange(epirange("20200201", "20201031"), "day") + expect_identical(result, epirange("20200201", "20201031")) +}) diff --git a/tests/testthat/test-utils.R b/tests/testthat/test-utils.R index fb5cfbe5..a95fbfe0 100644 --- a/tests/testthat/test-utils.R +++ b/tests/testthat/test-utils.R @@ -64,3 +64,27 @@ test_that("check_is_cachable can handle both str and date inputs of various leng epidata_call$params$issues <- epirange(as.Date("2022-01-01"), as.Date("2022-02-01")) expect_no_error(check_is_cachable(epidata_call, fetch_args)) }) + +test_that("get_wildcard_equivalent_dates works in basic cases", { + # Week date + result <- get_wildcard_equivalent_dates(epirange(202002, 202013), "week") + expect_identical(result, epirange(202002, 202013)) + + result <- get_wildcard_equivalent_dates(epirange("202002", "202013"), "week") + expect_identical(result, epirange("202002", "202013")) + + # Week wildcard + result <- get_wildcard_equivalent_dates("*", "week") + expect_identical(result, epirange(100001, 300001)) + + # Day date + result <- get_wildcard_equivalent_dates(epirange(20200201, 20201031), "day") + expect_identical(result, epirange(20200201, 20201031)) + + result <- get_wildcard_equivalent_dates(epirange("20200201", "20201031"), "day") + expect_identical(result, epirange("20200201", "20201031")) + + # Day wildcard + result <- get_wildcard_equivalent_dates("*", "day") + expect_identical(result, epirange(10000101, 30000101)) +}) diff --git a/vignettes/signal-discovery.Rmd b/vignettes/signal-discovery.Rmd index 8cd7799c..70a081ae 100644 --- a/vignettes/signal-discovery.Rmd +++ b/vignettes/signal-discovery.Rmd @@ -31,9 +31,9 @@ The site also includes a search tool if you have a keyword (e.g. "Taiwan") in mi ## Signal metadata -Some endpoints have partner metadata available that, depending on -the endpoint, provides information about the signals that are available, what -time ranges they are available for, and when they have been updated. +Some endpoints have partner metadata available that provides information about +the signals that are available, for example, what time ranges they are +available for, and when they have been updated. ```{r, echo = FALSE} suppressMessages(invisible(capture.output(endpts <- avail_endpoints()))) @@ -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 @@ -290,6 +295,10 @@ pub_wiki(language = "en", articles = "influenza", epiweeks = epirange(202001, 20 These require private access keys to use (separate from the Delphi Epidata API key). To actually run these locally, you will need to store these secrets in your `.Reviron` file, or set them as environmental variables. +
+ +Usage of private endpoints + #### CDC API docs: @@ -369,6 +378,9 @@ 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) ) ``` + +