diff --git a/DESCRIPTION b/DESCRIPTION index ad1d2f3..b4f195b 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -57,7 +57,8 @@ Suggests: readr, rmarkdown, testthat (>= 3.1.5), - withr + withr, + curl VignetteBuilder: knitr Remotes: @@ -68,7 +69,7 @@ Encoding: UTF-8 Language: en-US LazyData: true Roxygen: list(markdown = TRUE) -RoxygenNote: 7.3.2 +RoxygenNote: 7.3.3 Collate: 'auth.R' 'avail_endpoints.R' diff --git a/R/auth.R b/R/auth.R index 53ff13b..ca5d99f 100644 --- a/R/auth.R +++ b/R/auth.R @@ -11,12 +11,15 @@ #' key](https://api.delphi.cmu.edu/epidata/admin/registration_form). #' #' API keys are strings read from the environment variable `DELPHI_EPIDATA_KEY`. -#' We recommend setting your key with `save_api_key()`, which will modify an -#' applicable `.Renviron` file, which will be read in automatically when you -#' start future R sessions (see [`?Startup`][base::Startup] for details on -#' `.Renviron` files). Alternatively, you can modify the environment variable at -#' the command line before/while launching R, or inside an R session with -#' [`Sys.setenv()`], but these will not persist across sessions. +#' We recommend setting your key with `save_api_key()`, which will open your +#' `.Renviron` file in a text editor. You will need to write +#' `DELPHI_EPIDATA_KEY=yourkeyhere` (without quotes) in the file and save it. +#' Once the `.Renviron` file has been saved as instructed, it will be read +#' automatically when you start future R sessions +#' (see [`?Startup`][base::Startup] for details on `.Renviron` files). +#' Alternatively, you can modify the environment variable at the command line +#' before/while launching R, or inside an R session with [`Sys.setenv()`], +#' but these will not persist across sessions. #' #' Once an API key is set, it is automatically used for all requests made by #' functions in this package. diff --git a/R/endpoints.R b/R/endpoints.R index 1f789d1..3244e42 100644 --- a/R/endpoints.R +++ b/R/endpoints.R @@ -1,31 +1,73 @@ +#' @title Shared Documentation for epidatr Parameters +#' +#' @description This is a central text for parameter documentation +#' +#' @name .epidatr_shared_params +#' @keywords internal +#' +#' @param auth string. Your restricted access key (not the same as API key). +#' @param locations character. Vector of locations to fetch. +#' @param states character. Two letter state abbreviations. +#' @param regions character. Vector of regions to fetch. +#' @param epiweeks [`timeset`]. Epiweeks to fetch. Supports +#' [`epirange()`] and defaults to all ("*") dates. +#' @param time_type string. The temporal resolution of the data (either "day" or +#' "week", depending on signal). +#' @param names character. Names to fetch. +#' [`epirange()`] and defaults to all ("*") dates. +#' @param dates [`timeset`]. Dates to fetch. Supports +#' [`epirange()`] and defaults to all ("*") dates. +#' @param time_values [`timeset`]. Dates or epiweeks to fetch. +#' Supports [`epirange()`] and defaults to all ("*") dates. +#' @param as_of Date. Optionally, the as-of date for the issues to fetch. +#' See the "Data Versioning" section for details. +#' @param issues [`timeset`]. Optionally, the issue(s) of the +#' data to fetch. See the "Data Versioning" section for details. +#' @param lag integer. Optionally, the lag of the issues to fetch. +#' See the "Data Versioning" section for details. +#' @param fetch_args [`fetch_args`]. Additional arguments to pass +#' to `fetch()`. See `fetch_args_list()` for details. +#' @param ... not used for values, forces later arguments to bind by name +#' +#' @section Data Versioning: +#' Several endpoints support retrieving historical versions of the data. +#' The following parameters control this and are mutually exclusive (only +#' one can be provided at a time). +#' \itemize{ +#' \item \code{as_of}: (Date) Retrieve the data as it was on this date. +#' \item \code{issues}: [`timeset`] Retrieve data from a +#' specific issue date or range. +#' \item \code{lag}: (integer) Retrieve data with a specific lag from +#' its issue date. +#' } +#' See `vignette("versioned-data")` for details and more ways to specify +#' versioned data. +NULL + + #' CDC total and by topic webpage visits #' #' @description #' API docs: #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("SECRET_API_AUTH_CDC") != "" #' pvt_cdc( #' auth = Sys.getenv("SECRET_API_AUTH_CDC"), #' locations = "fl,ca", #' epirange(201501, 201601) #' ) -#' } #' -#' @param auth string. Restricted access key (not the same as API key). -#' @param locations character. Locations 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. +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] #' #' @keywords endpoint #' @export pvt_cdc <- function( - auth, - locations, - epiweeks = "*", - fetch_args = fetch_args_list()) { + auth, + locations, + epiweeks = "*", + fetch_args = fetch_args_list() +) { epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") assert_character_param("auth", auth, len = 1) @@ -70,31 +112,31 @@ pvt_cdc <- function( #' @details Only one location argument needs to be specified. #' Combinations of the arguments are not currently supported. #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_covid_hosp_facility_lookup(state = "fl") #' pub_covid_hosp_facility_lookup(city = "southlake") -#' } -#' @param ... not used for values, forces later arguments to bind by name +#' +#' @inheritParams .epidatr_shared_params #' @param state string. A two-letter character state abbreviation. #' @param ccn string. A facility CMS certification number. #' @param city string. A city name. #' @param zip string. A 5-digit zip code. #' @param fips_code string. A 5-digit fips county code, zero-padded. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' @return [`tibble::tibble`] #' #' @seealso [`pub_covid_hosp_facility()`] #' @keywords endpoint #' @export pub_covid_hosp_facility_lookup <- function( - ..., - state = NULL, - ccn = NULL, - city = NULL, - zip = NULL, - fips_code = NULL, - fetch_args = fetch_args_list()) { + ..., + state = NULL, + ccn = NULL, + city = NULL, + zip = NULL, + fips_code = NULL, + fetch_args = fetch_args_list() +) { rlang::check_dots_empty() assert_character_param("state", state, len = 1, required = FALSE) @@ -155,8 +197,8 @@ pub_covid_hosp_facility_lookup <- function( #' @details Starting October 1, 2022, some facilities are only required to #' report annually. #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_covid_hosp_facility( #' hospital_pks = "100075", #' collection_weeks = epirange(20200101, 20200501) @@ -166,13 +208,12 @@ pub_covid_hosp_facility_lookup <- function( #' hospital_pks = "050063", #' collection_weeks = epirange(20240101, 20240301) #' ) -#' } +#' +#' @inheritParams .epidatr_shared_params #' @param hospital_pks character. Facility identifiers. #' @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 @@ -182,11 +223,12 @@ pub_covid_hosp_facility_lookup <- function( #' @export # pub_covid_hosp_facility <- function( - hospital_pks, - collection_weeks = "*", - ..., - publication_dates = NULL, - fetch_args = fetch_args_list()) { + hospital_pks, + collection_weeks = "*", + ..., + publication_dates = NULL, + fetch_args = fetch_args_list() +) { rlang::check_dots_empty() collection_weeks <- get_wildcard_equivalent_dates(collection_weeks, "day") @@ -543,36 +585,30 @@ pub_covid_hosp_facility <- function( #' @details Starting October 1, 2022, some facilities are only required to #' report annually. #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_covid_hosp_state_timeseries( #' states = "fl", #' dates = epirange(20200101, 20200501) #' ) -#' } #' -#' @param states character. Two letter state abbreviations. -#' @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 -#' `issues`. -#' @param issues [`timeset`]. Optionally, the issue of the data to fetch. If not -#' specified, the most recent issue is returned. Mutually exclusive with -#' `as_of` or `lag`. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' @inheritParams .epidatr_shared_params +#' +#' @inheritSection .epidatr_shared_params Data Versioning +#' #' @return [`tibble::tibble`] #' #' @keywords endpoint #' @export # pub_covid_hosp_state_timeseries <- function( - states, - dates = "*", - ..., - as_of = NULL, - issues = NULL, - fetch_args = fetch_args_list()) { + states, + dates = "*", + ..., + as_of = NULL, + issues = NULL, + fetch_args = fetch_args_list() +) { # Check parameters rlang::check_dots_empty() @@ -880,14 +916,13 @@ pub_covid_hosp_state_timeseries <- function( #' the API, along with basic summary statistics such as the dates they are #' available, the geographic levels at which they are reported, and etc. #' -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' @inheritParams .epidatr_shared_params #' #' @return [`tibble::tibble`] #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_covidcast_meta() -#' } #' #' @seealso [pub_covidcast()],[covidcast_epidata()] #' @keywords endpoint @@ -933,8 +968,8 @@ pub_covidcast_meta <- function(fetch_args = fetch_args_list()) { #' link above for more. Delphi's [COVIDcast public #' dashboard](https://delphi.cmu.edu/covidcast/) is powered by this endpoint. #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_covidcast( #' source = "jhu-csse", #' signals = "confirmed_7dav_incidence_prop", @@ -951,48 +986,37 @@ pub_covidcast_meta <- function(fetch_args = fetch_args_list()) { #' geo_values = "*", #' time_values = epirange(20200601, 20200801) #' ) -#' } #' +#' @inheritParams .epidatr_shared_params #' @param source string. The data source to query (see: #' ). #' @param signals string. The signals to query from a specific source (see: #' ). #' @param geo_type string. The geographic resolution of the data (see: #' ). -#' @param time_type string. The temporal resolution of the data (either "day" or -#' "week", depending on signal). #' @param geo_values character. The geographies to return. Defaults to all #' ("*") geographies within requested geographic resolution (see: #' .). -#' @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 -#' `issues` or `lag`. -#' @param issues [`timeset`]. Optionally, the issue of the data to fetch. If not -#' specified, the most recent issue is returned. Mutually exclusive with -#' `as_of` or `lag`. -#' @param lag integer. Optionally, the lag of the issues to fetch. If not set, -#' the most recent issue is returned. Mutually exclusive with `as_of` or -#' `issues`. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. #' @return [`tibble::tibble`] #' +#' @inheritSection .epidatr_shared_params Data Versioning +#' #' @seealso [pub_covidcast_meta()], [covidcast_epidata()], [epirange()] #' @keywords endpoint #' @export pub_covidcast <- function( - source, - signals, - geo_type, - time_type, - geo_values = "*", - time_values = "*", - ..., - as_of = NULL, - issues = NULL, - lag = NULL, - fetch_args = fetch_args_list()) { + source, + signals, + geo_type, + time_type, + geo_values = "*", + time_values = "*", + ..., + as_of = NULL, + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list() +) { rlang::check_dots_empty() # Check parameters @@ -1089,17 +1113,18 @@ pub_covidcast <- function( #' \dontrun{ #' pub_delphi(system = "ec", epiweek = 201501) #' } +#' @inheritParams .epidatr_shared_params #' @param system character. System name 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()) { + system, + epiweek, + fetch_args = fetch_args_list() +) { assert_character_param("system", system) assert_timeset_param("epiweek", epiweek, len = 1) epiweek <- parse_timeset_input(epiweek) @@ -1120,23 +1145,22 @@ pub_delphi <- function( #' @description #' API docs: #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_dengue_nowcast( #' locations = "pr", #' epiweeks = epirange(201401, 202301) #' ) -#' } -#' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] #' @keywords endpoint #' @export pub_dengue_nowcast <- function( - locations, - epiweeks = "*", - fetch_args = fetch_args_list()) { + locations, + epiweeks = "*", + fetch_args = fetch_args_list() +) { epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") assert_character_param("locations", locations) @@ -1159,29 +1183,26 @@ pub_dengue_nowcast <- function( #' @description #' API docs: #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("SECRET_API_AUTH_SENSORS") != "" +#' #' pvt_dengue_sensors( #' auth = Sys.getenv("SECRET_API_AUTH_SENSORS"), #' names = "ght", #' locations = "ag", #' epiweeks = epirange(201501, 202001) #' ) -#' } -#' @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. Defaults to all ("*") dates. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] #' @keywords endpoint #' @export pvt_dengue_sensors <- function( - auth, - names, - locations, - epiweeks = "*", - fetch_args = fetch_args_list()) { + auth, + names, + locations, + epiweeks = "*", + fetch_args = fetch_args_list() +) { epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") assert_character_param("auth", auth, len = 1) @@ -1218,28 +1239,25 @@ pvt_dengue_sensors <- function( #' @details The list of location argument can be found in #' . #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_ecdc_ili(regions = "austria", epiweeks = epirange(201901, 202001)) -#' } -#' @param regions character. Regions 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`. -#' @param lag integer. Optionally, the lag of the issues to fetch. If not set, -#' the most recent issue is returned. Mutually exclusive with `issues`. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] +#' +#' @inheritSection .epidatr_shared_params Data Versioning +#' #' @keywords endpoint #' @export pub_ecdc_ili <- function( - regions, - epiweeks = "*", - ..., - issues = NULL, - lag = NULL, - fetch_args = fetch_args_list()) { + regions, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list() +) { rlang::check_dots_empty() epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") @@ -1289,24 +1307,21 @@ pub_ecdc_ili <- function( #' \dontrun{ #' pub_flusurv(locations = "CA", epiweeks = epirange(201701, 201801)) #' } -#' @param locations character. Character vector indicating location. -#' @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`. -#' @param lag integer. Optionally, the lag of the issues to fetch. If not set, -#' the most recent issue is returned. Mutually exclusive with `issues`. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] +#' +#' @inheritSection .epidatr_shared_params Data Versioning +#' #' @keywords endpoint #' @export pub_flusurv <- function( - locations, - epiweeks = "*", - ..., - issues = NULL, - lag = NULL, - fetch_args = fetch_args_list()) { + locations, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list() +) { rlang::check_dots_empty() epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") @@ -1349,30 +1364,31 @@ pub_flusurv <- function( #' @description #' API docs: #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_fluview_clinical(regions = "nat", epiweeks = epirange(201601, 201701)) -#' } -#' @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). 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`. -#' @param lag integer. Optionally, the lag of the issues to fetch. If not set, -#' the most recent issue is returned. Mutually exclusive with `issues`. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params +#' @param regions character. Vector of location IDs to fetch. Can be +#' "nat" for national, "hhs1"--"hhs10" for HHS Regions, "cen1"--"cen9" for +#' census divisions, lowercase two-letter state or territory abbreviations +#' for most states and territories,"jfk" for New York City, or "ny_minus_jfk" +#' for upstate New York. Full list of locations is available +#' [here](https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/regions.txt). #' @return [`tibble::tibble`] +#' +#' @inheritSection .epidatr_shared_params Data Versioning +#' #' @keywords endpoint #' @export pub_fluview_clinical <- function( - regions, - epiweeks = "*", - ..., - issues = NULL, - lag = NULL, - fetch_args = fetch_args_list()) { + regions, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list() +) { rlang::check_dots_empty() epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") @@ -1415,12 +1431,11 @@ pub_fluview_clinical <- function( #' @description #' API docs: #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_fluview_meta() -#' } #' -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' @inheritParams .epidatr_shared_params #' #' @return [`tibble::tibble`] #' @seealso [`pub_fluview()`] @@ -1452,35 +1467,27 @@ pub_fluview_meta <- function(fetch_args = fetch_args_list()) { #' @details The full list of location inputs can be accessed at #' . #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_fluview(regions = "nat", epiweeks = epirange(201201, 202005)) -#' } -#' @param regions character. Locations to fetch. Can be any string IDs in -#' national, HHS region, census division, most states and territories, and so -#' 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). 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`. -#' @param lag integer. Optionally, the lag of the issues to fetch. If not set, -#' the most recent issue is returned. Mutually exclusive with `issues`. -#' @param auth string. Optionally, restricted access key (not the same as API -#' key). -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams pub_fluview_clinical +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] +#' +#' @inheritSection .epidatr_shared_params Data Versioning +#' #' @keywords endpoint #' @export pub_fluview <- function( - regions, - epiweeks = "*", - ..., - issues = NULL, - lag = NULL, - auth = NULL, - fetch_args = fetch_args_list()) { + regions, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + auth = NULL, + fetch_args = fetch_args_list() +) { rlang::check_dots_empty() epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") @@ -1542,21 +1549,20 @@ pub_fluview <- function( #' and #' . #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_gft(locations = "hhs1", epiweeks = epirange(201201, 202001)) -#' } -#' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`] Epiweeks to fetch. Defaults to all ("*") dates. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params #' #' @return [`tibble::tibble`] #' @keywords endpoint #' @export pub_gft <- function( - locations, - epiweeks = "*", - fetch_args = fetch_args_list()) { + locations, + epiweeks = "*", + fetch_args = fetch_args_list() +) { epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") assert_character_param("locations", locations) @@ -1581,29 +1587,27 @@ pub_gft <- function( #' #' Estimate of influenza activity based on volume of certain search queries. … #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("SECRET_API_AUTH_GHT") != "" +#' #' pvt_ght( #' auth = Sys.getenv("SECRET_API_AUTH_GHT"), #' locations = "ma", #' epiweeks = epirange(199301, 202304), #' query = "how to get over the flu" #' ) -#' } -#' @param auth string. Restricted access key (not the same as API key). -#' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. +#' +#' @inheritParams .epidatr_shared_params #' @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()) { + auth, + locations, + epiweeks = "*", + query, + fetch_args = fetch_args_list() +) { epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") assert_character_param("auth", auth, len = 1) @@ -1632,28 +1636,25 @@ pvt_ght <- function( #' @description #' API docs: #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_kcdc_ili(regions = "ROK", epiweeks = 200436) -#' } -#' @param regions character. Regions 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`. -#' @param lag integer. Optionally, the lag of the issues to fetch. If not set, -#' the most recent issue is returned. Mutually exclusive with `issues`. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] +#' +#' @inheritSection .epidatr_shared_params Data Versioning +#' #' @keywords endpoint #' @export pub_kcdc_ili <- function( - regions, - epiweeks = "*", - ..., - issues = NULL, - lag = NULL, - fetch_args = fetch_args_list()) { + regions, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list() +) { rlang::check_dots_empty() epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") @@ -1695,8 +1696,7 @@ pub_kcdc_ili <- function( #' \dontrun{ #' pvt_meta_norostat(auth = Sys.getenv("SECRET_API_AUTH_NOROSTAT")) #' } -#' @param auth string. Restricted access key (not the same as API key). -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' @inheritParams .epidatr_shared_params #' @return [`list`] #' @seealso [`pvt_norostat()`] #' @keywords endpoint @@ -1715,7 +1715,7 @@ pvt_meta_norostat <- function(auth, fetch_args = fetch_args_list()) { #' @description #' API docs: #' -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' @inheritParams .epidatr_shared_params #' #' @return [`list`] #' @keywords endpoint @@ -1737,21 +1737,20 @@ pub_meta <- function(fetch_args = fetch_args_list()) { #' and #' . #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_nidss_dengue(locations = "taipei", epiweeks = epirange(201201, 201301)) -#' } -#' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params #' #' @return [`tibble::tibble`] #' @keywords endpoint #' @export pub_nidss_dengue <- function( - locations, - epiweeks = "*", - fetch_args = fetch_args_list()) { + locations, + epiweeks = "*", + fetch_args = fetch_args_list() +) { epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") assert_character_param("locations", locations) @@ -1777,28 +1776,25 @@ pub_nidss_dengue <- function( #' Infectious Disease Statistical System. #' #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_nidss_flu(regions = "taipei", epiweeks = epirange(201501, 201601)) -#' } -#' @param regions character. Regions 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`. -#' @param lag integer. Optionally, the lag of the issues to fetch. If not set, -#' the most recent issue is returned. Mutually exclusive with `issues`. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] +#' +#' @inheritSection .epidatr_shared_params Data Versioning +#' #' @keywords endpoint #' @export pub_nidss_flu <- function( - regions, - epiweeks = "*", - ..., - issues = NULL, - lag = NULL, - fetch_args = fetch_args_list()) { + regions, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list() +) { rlang::check_dots_empty() epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") @@ -1844,26 +1840,27 @@ pub_nidss_flu <- function( #' This is the documentation of the API for accessing the NoroSTAT endpoint of #' the Delphi’s epidemiological data. #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("SECRET_API_AUTH_NOROSTAT") != "" +#' #' pvt_norostat( #' auth = Sys.getenv("SECRET_API_AUTH_NOROSTAT"), #' locations = "Minnesota, Ohio, Oregon, Tennessee, and Wisconsin", #' epiweeks = 201233 #' ) -#' } -#' @param auth string. Your authentication key. -#' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params +#' @param locations character. Locations to fetch. Only a specific list of +#' full state names are permitted. See the `locations` column in the +#' output of `pvt_meta_norostat()` for the allowed values. #' @return [`tibble::tibble`] #' @keywords endpoint #' @export pvt_norostat <- function( - auth, - locations, - epiweeks = "*", - fetch_args = fetch_args_list()) { + auth, + locations, + epiweeks = "*", + fetch_args = fetch_args_list() +) { epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") assert_character_param("auth", auth, len = 1) @@ -1895,20 +1892,19 @@ pvt_norostat <- function( #' @details The full list of location inputs can be accessed at #' . #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_nowcast(locations = "ca", epiweeks = epirange(201201, 201301)) -#' } -#' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] #' @keywords endpoint #' @export pub_nowcast <- function( - locations, - epiweeks = "*", - fetch_args = fetch_args_list()) { + locations, + epiweeks = "*", + fetch_args = fetch_args_list() +) { epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") assert_character_param("locations", locations) @@ -1931,28 +1927,25 @@ pub_nowcast <- function( #' @description #' API docs: #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_paho_dengue(regions = "ca", epiweeks = epirange(201401, 201501)) -#' } -#' @param regions character. Regions 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`. -#' @param lag integer. Optionally, the lag of the issues to fetch. If not set, -#' the most recent issue is returned. Mutually exclusive with `issues`. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] +#' +#' @inheritSection .epidatr_shared_params Data Versioning +#' #' @keywords endpoint #' @export pub_paho_dengue <- function( - regions, - epiweeks = "*", - ..., - issues = NULL, - lag = NULL, - fetch_args = fetch_args_list()) { + regions, + epiweeks = "*", + ..., + issues = NULL, + lag = NULL, + fetch_args = fetch_args_list() +) { rlang::check_dots_empty() epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") @@ -1994,26 +1987,24 @@ pub_paho_dengue <- function( #' #' Data provided by Quidel Corp., which contains flu lab test results. #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("SECRET_API_AUTH_QUIDEL") != "" +#' #' pvt_quidel( #' auth = Sys.getenv("SECRET_API_AUTH_QUIDEL"), #' epiweeks = epirange(201201, 202001), #' locations = "hhs1" #' ) -#' } -#' @param auth string. Restricted access key (not the same as API key). -#' @param locations character. Locations to fetch. -#' @param epiweeks [`timeset`]. Epiweeks to fetch. Defaults to all ("*") dates. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] #' @keywords endpoint #' @export pvt_quidel <- function( - auth, - locations, - epiweeks = "*", - fetch_args = fetch_args_list()) { + auth, + locations, + epiweeks = "*", + fetch_args = fetch_args_list() +) { epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") assert_character_param("auth", auth, len = 1) @@ -2051,29 +2042,26 @@ pvt_quidel <- function( #' these were designed to track ILI as driven by seasonal influenza, and were #' NOT designed to track ILI during the COVID-19 pandemic. #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("SECRET_API_AUTH_SENSORS") != "" +#' #' pvt_sensors( #' auth = Sys.getenv("SECRET_API_AUTH_SENSORS"), #' names = "sar3", #' locations = "nat", #' epiweeks = epirange(201501, 202001) #' ) -#' } -#' @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. Defaults to all ("*") dates. -#' @param fetch_args [`fetch_args`]. Additional arguments to pass to `fetch()`. +#' +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] #' @keywords endpoint #' @export pvt_sensors <- function( - auth, - names, - locations, - epiweeks = "*", - fetch_args = fetch_args_list()) { + auth, + names, + locations, + epiweeks = "*", + fetch_args = fetch_args_list() +) { epiweeks <- get_wildcard_equivalent_dates(epiweeks, "week") assert_character_param("auth", auth, len = 1) @@ -2107,33 +2095,27 @@ pvt_sensors <- function( #' Delphi’s epidemiological data. Sourced from #' [Healthtweets](http://www.healthtweets.org/) #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("SECRET_API_AUTH_TWITTER") != "" +#' #' pvt_twitter( #' auth = Sys.getenv("SECRET_API_AUTH_TWITTER"), #' locations = "CA", #' 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 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()`. +#' +#' @inheritParams .epidatr_shared_params #' @return [`tibble::tibble`] #' @keywords endpoint #' @export pvt_twitter <- function( - auth, - locations, - ..., - time_type = c("day", "week"), - time_values = "*", - fetch_args = fetch_args_list()) { + auth, + locations, + ..., + time_type = c("day", "week"), + time_values = "*", + fetch_args = fetch_args_list() +) { rlang::check_dots_empty() time_type <- match.arg(time_type) @@ -2191,34 +2173,30 @@ pvt_twitter <- function( #' * Other resolution: By article (54) #' * Open access #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' pub_wiki( #' articles = "avian_influenza", #' time_type = "week", #' time_values = epirange(201501, 201601) #' ) -#' } +#' +#' @inheritParams .epidatr_shared_params #' @param articles character. Articles to fetch. -#' @param ... not used for values, forces later arguments to bind by name -#' @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()`. #' @return [`tibble::tibble`] #' @keywords endpoint #' @export pub_wiki <- function( - articles, - ..., - time_type = c("day", "week"), - time_values = "*", - hours = NULL, - language = "en", - fetch_args = fetch_args_list()) { + articles, + ..., + 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) diff --git a/R/epidatacall.R b/R/epidatacall.R index c97a6d1..fcc3611 100644 --- a/R/epidatacall.R +++ b/R/epidatacall.R @@ -19,8 +19,9 @@ #' `request_url` (for debugging): outputs the request URL from which data #' would be fetched (note additional parameters below) #' -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' library(magrittr) +#' #' call <- pub_covidcast( #' source = "jhu-csse", #' signals = "confirmed_7dav_incidence_prop", @@ -31,7 +32,6 @@ #' fetch_args = fetch_args_list(dry_run = TRUE) #' ) #' call %>% fetch() -#' } #' #' @param endpoint the epidata endpoint to call #' @param params the parameters to pass to the epidata endpoint @@ -161,17 +161,18 @@ print.epidata_call <- function(x, ...) { #' @aliases fetch_args #' @importFrom checkmate assert_character assert_logical assert_numeric fetch_args_list <- function( - ..., - fields = NULL, - disable_date_parsing = FALSE, - disable_data_frame_parsing = FALSE, - return_empty = FALSE, - timeout_seconds = 15 * 60, - base_url = NULL, - dry_run = FALSE, - debug = FALSE, - format_type = c("json", "classic", "csv"), - refresh_cache = FALSE) { + ..., + fields = NULL, + disable_date_parsing = FALSE, + disable_data_frame_parsing = FALSE, + return_empty = FALSE, + timeout_seconds = 15 * 60, + base_url = NULL, + dry_run = FALSE, + debug = FALSE, + format_type = c("json", "classic", "csv"), + refresh_cache = FALSE +) { rlang::check_dots_empty() assert_character(fields, null.ok = TRUE, any.missing = FALSE) diff --git a/R/request.R b/R/request.R index 603e7bd..cf8ef4e 100644 --- a/R/request.R +++ b/R/request.R @@ -8,8 +8,8 @@ join_url <- function(url, endpoint) { #' performs the request #' #' You can test the authentication headers like so: -#' @examples -#' \dontrun{ +#' @examplesIf curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "" +#' #' response <- httr::RETRY( #' "GET", "https://httpbin.org/headers", #' httr::authenticate("epidata", "fake_key") @@ -18,7 +18,6 @@ join_url <- function(url, endpoint) { #' "Basic ", #' base64enc::base64encode(charToRaw("epidata:fake_key")) #' ) -#' } #' #' @importFrom httr RETRY #' @keywords internal diff --git a/man/covidcast_epidata.Rd b/man/covidcast_epidata.Rd index fbf3f1c..e3a997a 100644 --- a/man/covidcast_epidata.Rd +++ b/man/covidcast_epidata.Rd @@ -27,7 +27,7 @@ an object containing fields for every signal: \if{html}{\out{
}}\preformatted{epidata <- covidcast_epidata() epidata$signals -#> # A tibble: 468 x 3 +#> # A tibble: 508 x 3 #> source signal short_description #> #> 1 chng smoothed_outpatient_cli Estimated percentage of outpatie~ @@ -40,7 +40,7 @@ epidata$signals #> 8 chng 7dav_outpatient_covid Ratio of outpatient doctor visit~ #> 9 covid-act-now pcr_specimen_positivity_rate Proportion of PCR specimens test~ #> 10 covid-act-now pcr_specimen_total_tests Total number of PCR specimens te~ -#> # i 458 more rows +#> # i 498 more rows }\if{html}{\out{
}} If you use an editor that supports tab completion, such as RStudio, type diff --git a/man/do_request.Rd b/man/do_request.Rd index e5cd799..d81558f 100644 --- a/man/do_request.Rd +++ b/man/do_request.Rd @@ -10,7 +10,8 @@ do_request(url, params, timeout_seconds) You can test the authentication headers like so: } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + response <- httr::RETRY( "GET", "https://httpbin.org/headers", httr::authenticate("epidata", "fake_key") @@ -19,7 +20,6 @@ content(response)$headers$Authorization == paste0( "Basic ", base64enc::base64encode(charToRaw("epidata:fake_key")) ) -} - +\dontshow{\}) # examplesIf} } \keyword{internal} diff --git a/man/dot-epidatr_shared_params.Rd b/man/dot-epidatr_shared_params.Rd new file mode 100644 index 0000000..d064344 --- /dev/null +++ b/man/dot-epidatr_shared_params.Rd @@ -0,0 +1,63 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/endpoints.R +\name{.epidatr_shared_params} +\alias{.epidatr_shared_params} +\title{Shared Documentation for epidatr Parameters} +\arguments{ +\item{auth}{string. Your restricted access key (not the same as API key).} + +\item{locations}{character. Vector of locations to fetch.} + +\item{states}{character. Two letter state abbreviations.} + +\item{regions}{character. Vector of regions to fetch.} + +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} + +\item{time_type}{string. The temporal resolution of the data (either "day" or +"week", depending on signal).} + +\item{names}{character. Names to fetch. +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} + +\item{dates}{\code{\link{timeset}}. Dates to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} + +\item{time_values}{\code{\link{timeset}}. Dates or epiweeks to fetch. +Supports \code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} + +\item{as_of}{Date. Optionally, the as-of date for the issues to fetch. +See the "Data Versioning" section for details.} + +\item{issues}{\code{\link{timeset}}. Optionally, the issue(s) of the +data to fetch. See the "Data Versioning" section for details.} + +\item{lag}{integer. Optionally, the lag of the issues to fetch. +See the "Data Versioning" section for details.} + +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} + +\item{...}{not used for values, forces later arguments to bind by name} +} +\description{ +This is a central text for parameter documentation +} +\section{Data Versioning}{ + +Several endpoints support retrieving historical versions of the data. +The following parameters control this and are mutually exclusive (only +one can be provided at a time). +\itemize{ +\item \code{as_of}: (Date) Retrieve the data as it was on this date. +\item \code{issues}: \code{\link{timeset}} Retrieve data from a +specific issue date or range. +\item \code{lag}: (integer) Retrieve data with a specific lag from +its issue date. +} +See \code{vignette("versioned-data")} for details and more ways to specify +versioned data. +} + +\keyword{internal} diff --git a/man/epidata_call.Rd b/man/epidata_call.Rd index c2ef4b6..8d8456e 100644 --- a/man/epidata_call.Rd +++ b/man/epidata_call.Rd @@ -60,7 +60,9 @@ endpoints only support the JSON classic format (\code{pub_delphi}, JSON-like nested list structure is returned instead. } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} +library(magrittr) + call <- pub_covidcast( source = "jhu-csse", signals = "confirmed_7dav_incidence_prop", @@ -71,6 +73,5 @@ call <- pub_covidcast( fetch_args = fetch_args_list(dry_run = TRUE) ) call \%>\% fetch() -} - +\dontshow{\}) # examplesIf} } diff --git a/man/get_api_key.Rd b/man/get_api_key.Rd index 2fd9b1b..e1a33ee 100644 --- a/man/get_api_key.Rd +++ b/man/get_api_key.Rd @@ -24,12 +24,15 @@ including a rate limit. If you regularly request large amounts of data, please consider \href{https://api.delphi.cmu.edu/epidata/admin/registration_form}{registering for an API key}. API keys are strings read from the environment variable \code{DELPHI_EPIDATA_KEY}. -We recommend setting your key with \code{save_api_key()}, which will modify an -applicable \code{.Renviron} file, which will be read in automatically when you -start future R sessions (see \code{\link[base:Startup]{?Startup}} for details on -\code{.Renviron} files). Alternatively, you can modify the environment variable at -the command line before/while launching R, or inside an R session with -\code{\link[=Sys.setenv]{Sys.setenv()}}, but these will not persist across sessions. +We recommend setting your key with \code{save_api_key()}, which will open your +\code{.Renviron} file in a text editor. You will need to write +\code{DELPHI_EPIDATA_KEY=yourkeyhere} (without quotes) in the file and save it. +Once the \code{.Renviron} file has been saved as instructed, it will be read +automatically when you start future R sessions +(see \code{\link[base:Startup]{?Startup}} for details on \code{.Renviron} files). +Alternatively, you can modify the environment variable at the command line +before/while launching R, or inside an R session with \code{\link[=Sys.setenv]{Sys.setenv()}}, +but these will not persist across sessions. Once an API key is set, it is automatically used for all requests made by functions in this package. diff --git a/man/pub_covid_hosp_facility.Rd b/man/pub_covid_hosp_facility.Rd index c71f21c..c326cc6 100644 --- a/man/pub_covid_hosp_facility.Rd +++ b/man/pub_covid_hosp_facility.Rd @@ -22,7 +22,8 @@ fetch. Defaults to all ("*") dates.} \item{publication_dates}{\code{\link{timeset}}. Publication dates to fetch.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -41,7 +42,8 @@ Starting October 1, 2022, some facilities are only required to report annually. } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_covid_hosp_facility( hospital_pks = "100075", collection_weeks = epirange(20200101, 20200501) @@ -51,7 +53,7 @@ pub_covid_hosp_facility( hospital_pks = "050063", collection_weeks = epirange(20240101, 20240301) ) -} +\dontshow{\}) # examplesIf} } \seealso{ \code{\link[=pub_covid_hosp_facility]{pub_covid_hosp_facility()}}, \code{\link[=epirange]{epirange()}} diff --git a/man/pub_covid_hosp_facility_lookup.Rd b/man/pub_covid_hosp_facility_lookup.Rd index 718d153..06d7f80 100644 --- a/man/pub_covid_hosp_facility_lookup.Rd +++ b/man/pub_covid_hosp_facility_lookup.Rd @@ -27,7 +27,8 @@ pub_covid_hosp_facility_lookup( \item{fips_code}{string. A 5-digit fips county code, zero-padded.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -45,10 +46,11 @@ Only one location argument needs to be specified. Combinations of the arguments are not currently supported. } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_covid_hosp_facility_lookup(state = "fl") pub_covid_hosp_facility_lookup(city = "southlake") -} +\dontshow{\}) # examplesIf} } \seealso{ \code{\link[=pub_covid_hosp_facility]{pub_covid_hosp_facility()}} diff --git a/man/pub_covid_hosp_state_timeseries.Rd b/man/pub_covid_hosp_state_timeseries.Rd index 246bf7b..7fae0f1 100644 --- a/man/pub_covid_hosp_state_timeseries.Rd +++ b/man/pub_covid_hosp_state_timeseries.Rd @@ -16,19 +16,19 @@ pub_covid_hosp_state_timeseries( \arguments{ \item{states}{character. Two letter state abbreviations.} -\item{dates}{\code{\link{timeset}}. Dates to fetch. Defaults to all ("*") dates.} +\item{dates}{\code{\link{timeset}}. Dates to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} -\item{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 -\code{issues}.} +\item{as_of}{Date. Optionally, the as-of date for the issues to fetch. +See the "Data Versioning" section for details.} -\item{issues}{\code{\link{timeset}}. Optionally, the issue of the data to fetch. If not -specified, the most recent issue is returned. Mutually exclusive with -\code{as_of} or \code{lag}.} +\item{issues}{\code{\link{timeset}}. Optionally, the issue(s) of the +data to fetch. See the "Data Versioning" section for details.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -44,13 +44,29 @@ Services. Starting October 1, 2022, some facilities are only required to report annually. } +\section{Data Versioning}{ + +Several endpoints support retrieving historical versions of the data. +The following parameters control this and are mutually exclusive (only +one can be provided at a time). +\itemize{ +\item \code{as_of}: (Date) Retrieve the data as it was on this date. +\item \code{issues}: \code{\link{timeset}} Retrieve data from a +specific issue date or range. +\item \code{lag}: (integer) Retrieve data with a specific lag from +its issue date. +} +See \code{vignette("versioned-data")} for details and more ways to specify +versioned data. +} + \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_covid_hosp_state_timeseries( states = "fl", dates = epirange(20200101, 20200501) ) -} - +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pub_covidcast.Rd b/man/pub_covidcast.Rd index 2f6a2ba..b22219e 100644 --- a/man/pub_covidcast.Rd +++ b/man/pub_covidcast.Rd @@ -35,23 +35,22 @@ pub_covidcast( ("*") geographies within requested geographic resolution (see: \url{https://cmu-delphi.github.io/delphi-epidata/api/covidcast_geography.html}.).} -\item{time_values}{\code{\link{timeset}}. Dates to fetch. Defaults to all ("*") dates.} +\item{time_values}{\code{\link{timeset}}. Dates or epiweeks to fetch. +Supports \code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} -\item{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 -\code{issues} or \code{lag}.} +\item{as_of}{Date. Optionally, the as-of date for the issues to fetch. +See the "Data Versioning" section for details.} -\item{issues}{\code{\link{timeset}}. Optionally, the issue of the data to fetch. If not -specified, the most recent issue is returned. Mutually exclusive with -\code{as_of} or \code{lag}.} +\item{issues}{\code{\link{timeset}}. Optionally, the issue(s) of the +data to fetch. See the "Data Versioning" section for details.} -\item{lag}{integer. Optionally, the lag of the issues to fetch. If not set, -the most recent issue is returned. Mutually exclusive with \code{as_of} or -\code{issues}.} +\item{lag}{integer. Optionally, the lag of the issues to fetch. +See the "Data Versioning" section for details.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -63,8 +62,25 @@ The primary endpoint for fetching COVID-19 data, providing access to a wide variety of signals from a wide variety of sources. See the API documentation link above for more. Delphi's \href{https://delphi.cmu.edu/covidcast/}{COVIDcast public dashboard} is powered by this endpoint. } +\section{Data Versioning}{ + +Several endpoints support retrieving historical versions of the data. +The following parameters control this and are mutually exclusive (only +one can be provided at a time). +\itemize{ +\item \code{as_of}: (Date) Retrieve the data as it was on this date. +\item \code{issues}: \code{\link{timeset}} Retrieve data from a +specific issue date or range. +\item \code{lag}: (integer) Retrieve data with a specific lag from +its issue date. +} +See \code{vignette("versioned-data")} for details and more ways to specify +versioned data. +} + \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_covidcast( source = "jhu-csse", signals = "confirmed_7dav_incidence_prop", @@ -81,8 +97,7 @@ pub_covidcast( geo_values = "*", time_values = epirange(20200601, 20200801) ) -} - +\dontshow{\}) # examplesIf} } \seealso{ \code{\link[=pub_covidcast_meta]{pub_covidcast_meta()}}, \code{\link[=covidcast_epidata]{covidcast_epidata()}}, \code{\link[=epirange]{epirange()}} diff --git a/man/pub_covidcast_meta.Rd b/man/pub_covidcast_meta.Rd index 6b7b183..395f5e2 100644 --- a/man/pub_covidcast_meta.Rd +++ b/man/pub_covidcast_meta.Rd @@ -7,7 +7,8 @@ pub_covidcast_meta(fetch_args = fetch_args_list()) } \arguments{ -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -21,10 +22,10 @@ the API, along with basic summary statistics such as the dates they are available, the geographic levels at which they are reported, and etc. } \examples{ -\dontrun{ -pub_covidcast_meta() -} +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} +pub_covidcast_meta() +\dontshow{\}) # examplesIf} } \seealso{ \code{\link[=pub_covidcast]{pub_covidcast()}},\code{\link[=covidcast_epidata]{covidcast_epidata()}} diff --git a/man/pub_delphi.Rd b/man/pub_delphi.Rd index fe278be..5df3ea6 100644 --- a/man/pub_delphi.Rd +++ b/man/pub_delphi.Rd @@ -12,7 +12,8 @@ pub_delphi(system, epiweek, fetch_args = fetch_args_list()) \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()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link{list}} diff --git a/man/pub_dengue_nowcast.Rd b/man/pub_dengue_nowcast.Rd index e1c2573..8bf5ad9 100644 --- a/man/pub_dengue_nowcast.Rd +++ b/man/pub_dengue_nowcast.Rd @@ -7,11 +7,13 @@ pub_dengue_nowcast(locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ -\item{locations}{character. Locations to fetch.} +\item{locations}{character. Vector of locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -20,11 +22,12 @@ pub_dengue_nowcast(locations, epiweeks = "*", fetch_args = fetch_args_list()) API docs: \url{https://cmu-delphi.github.io/delphi-epidata/api/dengue_nowcast.html} } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_dengue_nowcast( locations = "pr", epiweeks = epirange(201401, 202301) ) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pub_ecdc_ili.Rd b/man/pub_ecdc_ili.Rd index d71b565..d568106 100644 --- a/man/pub_ecdc_ili.Rd +++ b/man/pub_ecdc_ili.Rd @@ -14,19 +14,21 @@ pub_ecdc_ili( ) } \arguments{ -\item{regions}{character. Regions to fetch.} +\item{regions}{character. Vector of regions to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} -\item{issues}{\code{\link{timeset}}. Optionally, the issues to fetch. If not set, the -most recent issue is returned. Mutually exclusive with \code{lag}.} +\item{issues}{\code{\link{timeset}}. Optionally, the issue(s) of the +data to fetch. See the "Data Versioning" section for details.} -\item{lag}{integer. Optionally, the lag of the issues to fetch. If not set, -the most recent issue is returned. Mutually exclusive with \code{issues}.} +\item{lag}{integer. Optionally, the lag of the issues to fetch. +See the "Data Versioning" section for details.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -41,9 +43,26 @@ Disease Prevention and Control. The list of location argument can be found in \url{https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/ecdc_regions.txt}. } +\section{Data Versioning}{ + +Several endpoints support retrieving historical versions of the data. +The following parameters control this and are mutually exclusive (only +one can be provided at a time). +\itemize{ +\item \code{as_of}: (Date) Retrieve the data as it was on this date. +\item \code{issues}: \code{\link{timeset}} Retrieve data from a +specific issue date or range. +\item \code{lag}: (integer) Retrieve data with a specific lag from +its issue date. +} +See \code{vignette("versioned-data")} for details and more ways to specify +versioned data. +} + \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_ecdc_ili(regions = "austria", epiweeks = epirange(201901, 202001)) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pub_flusurv.Rd b/man/pub_flusurv.Rd index e8fd5bb..319fb4f 100644 --- a/man/pub_flusurv.Rd +++ b/man/pub_flusurv.Rd @@ -14,19 +14,21 @@ pub_flusurv( ) } \arguments{ -\item{locations}{character. Character vector indicating location.} +\item{locations}{character. Vector of locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} -\item{issues}{\code{\link{timeset}}. Optionally, the issues to fetch. If not set, the -most recent issue is returned. Mutually exclusive with \code{lag}.} +\item{issues}{\code{\link{timeset}}. Optionally, the issue(s) of the +data to fetch. See the "Data Versioning" section for details.} -\item{lag}{integer. Optionally, the lag of the issues to fetch. If not set, -the most recent issue is returned. Mutually exclusive with \code{issues}.} +\item{lag}{integer. Optionally, the lag of the issues to fetch. +See the "Data Versioning" section for details.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -43,6 +45,22 @@ See also \url{https://gis.cdc.gov/GRASP/Fluview/FluHospRates.html}. The list of location argument can be found in \url{https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/flusurv_locations.txt}. } +\section{Data Versioning}{ + +Several endpoints support retrieving historical versions of the data. +The following parameters control this and are mutually exclusive (only +one can be provided at a time). +\itemize{ +\item \code{as_of}: (Date) Retrieve the data as it was on this date. +\item \code{issues}: \code{\link{timeset}} Retrieve data from a +specific issue date or range. +\item \code{lag}: (integer) Retrieve data with a specific lag from +its issue date. +} +See \code{vignette("versioned-data")} for details and more ways to specify +versioned data. +} + \examples{ \dontrun{ pub_flusurv(locations = "CA", epiweeks = epirange(201701, 201801)) diff --git a/man/pub_fluview.Rd b/man/pub_fluview.Rd index 61ba357..952bc54 100644 --- a/man/pub_fluview.Rd +++ b/man/pub_fluview.Rd @@ -15,26 +15,28 @@ pub_fluview( ) } \arguments{ -\item{regions}{character. Locations to fetch. Can be any string IDs in -national, HHS region, census division, most states and territories, and so -on. Full list link below.} +\item{regions}{character. Vector of location IDs to fetch. Can be +"nat" for national, "hhs1"--"hhs10" for HHS Regions, "cen1"--"cen9" for +census divisions, lowercase two-letter state or territory abbreviations +for most states and territories,"jfk" for New York City, or "ny_minus_jfk" +for upstate New York. Full list of locations is available +\href{https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/regions.txt}{here}.} -\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). Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} -\item{issues}{\code{\link{timeset}}. Optionally, the issues to fetch. If not set, the -most recent issue is returned. Mutually exclusive with \code{lag}.} +\item{issues}{\code{\link{timeset}}. Optionally, the issue(s) of the +data to fetch. See the "Data Versioning" section for details.} -\item{lag}{integer. Optionally, the lag of the issues to fetch. If not set, -the most recent issue is returned. Mutually exclusive with \code{issues}.} +\item{lag}{integer. Optionally, the lag of the issues to fetch. +See the "Data Versioning" section for details.} -\item{auth}{string. Optionally, restricted access key (not the same as API -key).} +\item{auth}{string. Your restricted access key (not the same as API key).} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -52,9 +54,26 @@ more information on ILINet, see The full list of location inputs can be accessed at \url{https://github.com/cmu-delphi/delphi-epidata/blob/main/src/acquisition/fluview/fluview_locations.py}. } +\section{Data Versioning}{ + +Several endpoints support retrieving historical versions of the data. +The following parameters control this and are mutually exclusive (only +one can be provided at a time). +\itemize{ +\item \code{as_of}: (Date) Retrieve the data as it was on this date. +\item \code{issues}: \code{\link{timeset}} Retrieve data from a +specific issue date or range. +\item \code{lag}: (integer) Retrieve data with a specific lag from +its issue date. +} +See \code{vignette("versioned-data")} for details and more ways to specify +versioned data. +} + \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_fluview(regions = "nat", epiweeks = epirange(201201, 202005)) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pub_fluview_clinical.Rd b/man/pub_fluview_clinical.Rd index a4017c7..b38c7b8 100644 --- a/man/pub_fluview_clinical.Rd +++ b/man/pub_fluview_clinical.Rd @@ -14,21 +14,26 @@ pub_fluview_clinical( ) } \arguments{ -\item{regions}{character. Regions to fetch.} +\item{regions}{character. Vector of location IDs to fetch. Can be +"nat" for national, "hhs1"--"hhs10" for HHS Regions, "cen1"--"cen9" for +census divisions, lowercase two-letter state or territory abbreviations +for most states and territories,"jfk" for New York City, or "ny_minus_jfk" +for upstate New York. Full list of locations is available +\href{https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/regions.txt}{here}.} -\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). Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} -\item{issues}{\code{\link{timeset}}. Optionally, the issues to fetch. If not set, the -most recent issue is returned. Mutually exclusive with \code{lag}.} +\item{issues}{\code{\link{timeset}}. Optionally, the issue(s) of the +data to fetch. See the "Data Versioning" section for details.} -\item{lag}{integer. Optionally, the lag of the issues to fetch. If not set, -the most recent issue is returned. Mutually exclusive with \code{issues}.} +\item{lag}{integer. Optionally, the lag of the issues to fetch. +See the "Data Versioning" section for details.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -36,9 +41,26 @@ the most recent issue is returned. Mutually exclusive with \code{issues}.} \description{ API docs: \url{https://cmu-delphi.github.io/delphi-epidata/api/fluview_clinical.html} } +\section{Data Versioning}{ + +Several endpoints support retrieving historical versions of the data. +The following parameters control this and are mutually exclusive (only +one can be provided at a time). +\itemize{ +\item \code{as_of}: (Date) Retrieve the data as it was on this date. +\item \code{issues}: \code{\link{timeset}} Retrieve data from a +specific issue date or range. +\item \code{lag}: (integer) Retrieve data with a specific lag from +its issue date. +} +See \code{vignette("versioned-data")} for details and more ways to specify +versioned data. +} + \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_fluview_clinical(regions = "nat", epiweeks = epirange(201601, 201701)) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pub_fluview_meta.Rd b/man/pub_fluview_meta.Rd index ab0c0b1..7e3be56 100644 --- a/man/pub_fluview_meta.Rd +++ b/man/pub_fluview_meta.Rd @@ -7,7 +7,8 @@ pub_fluview_meta(fetch_args = fetch_args_list()) } \arguments{ -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -16,10 +17,10 @@ pub_fluview_meta(fetch_args = fetch_args_list()) API docs: \url{https://cmu-delphi.github.io/delphi-epidata/api/fluview_meta.html} } \examples{ -\dontrun{ -pub_fluview_meta() -} +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} +pub_fluview_meta() +\dontshow{\}) # examplesIf} } \seealso{ \code{\link[=pub_fluview]{pub_fluview()}} diff --git a/man/pub_gft.Rd b/man/pub_gft.Rd index c80d8d9..608984e 100644 --- a/man/pub_gft.Rd +++ b/man/pub_gft.Rd @@ -7,11 +7,13 @@ pub_gft(locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ -\item{locations}{character. Locations to fetch.} +\item{locations}{character. Vector of locations to fetch.} -\item{epiweeks}{\code{\link{timeset}} Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -31,8 +33,9 @@ and \url{https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/cities.txt}. } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_gft(locations = "hhs1", epiweeks = epirange(201201, 202001)) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pub_kcdc_ili.Rd b/man/pub_kcdc_ili.Rd index 0c8b70f..f3dbec6 100644 --- a/man/pub_kcdc_ili.Rd +++ b/man/pub_kcdc_ili.Rd @@ -14,19 +14,21 @@ pub_kcdc_ili( ) } \arguments{ -\item{regions}{character. Regions to fetch.} +\item{regions}{character. Vector of regions to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} -\item{issues}{\code{\link{timeset}}. Optionally, the issues to fetch. If not set, the -most recent issue is returned. Mutually exclusive with \code{lag}.} +\item{issues}{\code{\link{timeset}}. Optionally, the issue(s) of the +data to fetch. See the "Data Versioning" section for details.} -\item{lag}{integer. Optionally, the lag of the issues to fetch. If not set, -the most recent issue is returned. Mutually exclusive with \code{issues}.} +\item{lag}{integer. Optionally, the lag of the issues to fetch. +See the "Data Versioning" section for details.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -34,9 +36,26 @@ the most recent issue is returned. Mutually exclusive with \code{issues}.} \description{ API docs: \url{https://cmu-delphi.github.io/delphi-epidata/api/kcdc_ili.html} } +\section{Data Versioning}{ + +Several endpoints support retrieving historical versions of the data. +The following parameters control this and are mutually exclusive (only +one can be provided at a time). +\itemize{ +\item \code{as_of}: (Date) Retrieve the data as it was on this date. +\item \code{issues}: \code{\link{timeset}} Retrieve data from a +specific issue date or range. +\item \code{lag}: (integer) Retrieve data with a specific lag from +its issue date. +} +See \code{vignette("versioned-data")} for details and more ways to specify +versioned data. +} + \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_kcdc_ili(regions = "ROK", epiweeks = 200436) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pub_meta.Rd b/man/pub_meta.Rd index 202d3cf..b06b853 100644 --- a/man/pub_meta.Rd +++ b/man/pub_meta.Rd @@ -7,7 +7,8 @@ pub_meta(fetch_args = fetch_args_list()) } \arguments{ -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link{list}} diff --git a/man/pub_nidss_dengue.Rd b/man/pub_nidss_dengue.Rd index 67be9c9..3ed07b7 100644 --- a/man/pub_nidss_dengue.Rd +++ b/man/pub_nidss_dengue.Rd @@ -7,11 +7,13 @@ pub_nidss_dengue(locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ -\item{locations}{character. Locations to fetch.} +\item{locations}{character. Vector of locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -29,8 +31,9 @@ and \url{https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/nidss_locations.txt}. } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_nidss_dengue(locations = "taipei", epiweeks = epirange(201201, 201301)) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pub_nidss_flu.Rd b/man/pub_nidss_flu.Rd index 946a1b8..05b8fc9 100644 --- a/man/pub_nidss_flu.Rd +++ b/man/pub_nidss_flu.Rd @@ -14,19 +14,21 @@ pub_nidss_flu( ) } \arguments{ -\item{regions}{character. Regions to fetch.} +\item{regions}{character. Vector of regions to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} -\item{issues}{\code{\link{timeset}}. Optionally, the issues to fetch. If not set, the -most recent issue is returned. Mutually exclusive with \code{lag}.} +\item{issues}{\code{\link{timeset}}. Optionally, the issue(s) of the +data to fetch. See the "Data Versioning" section for details.} -\item{lag}{integer. Optionally, the lag of the issues to fetch. If not set, -the most recent issue is returned. Mutually exclusive with \code{issues}.} +\item{lag}{integer. Optionally, the lag of the issues to fetch. +See the "Data Versioning" section for details.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -37,9 +39,26 @@ API docs: \url{https://cmu-delphi.github.io/delphi-epidata/api/nidss_flu.html} Obtains information on outpatient inluenza-like-illness from Taiwan National Infectious Disease Statistical System. } +\section{Data Versioning}{ + +Several endpoints support retrieving historical versions of the data. +The following parameters control this and are mutually exclusive (only +one can be provided at a time). +\itemize{ +\item \code{as_of}: (Date) Retrieve the data as it was on this date. +\item \code{issues}: \code{\link{timeset}} Retrieve data from a +specific issue date or range. +\item \code{lag}: (integer) Retrieve data with a specific lag from +its issue date. +} +See \code{vignette("versioned-data")} for details and more ways to specify +versioned data. +} + \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_nidss_flu(regions = "taipei", epiweeks = epirange(201501, 201601)) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pub_nowcast.Rd b/man/pub_nowcast.Rd index 306c37f..8c5157b 100644 --- a/man/pub_nowcast.Rd +++ b/man/pub_nowcast.Rd @@ -7,11 +7,13 @@ pub_nowcast(locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ -\item{locations}{character. Locations to fetch.} +\item{locations}{character. Vector of locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -26,8 +28,9 @@ The full list of location inputs can be accessed at \url{https://github.com/cmu-delphi/delphi-epidata/blob/main/src/acquisition/fluview/fluview_locations.py}. } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_nowcast(locations = "ca", epiweeks = epirange(201201, 201301)) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pub_paho_dengue.Rd b/man/pub_paho_dengue.Rd index 0d643f4..0c4fb5c 100644 --- a/man/pub_paho_dengue.Rd +++ b/man/pub_paho_dengue.Rd @@ -14,19 +14,21 @@ pub_paho_dengue( ) } \arguments{ -\item{regions}{character. Regions to fetch.} +\item{regions}{character. Vector of regions to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} \item{...}{not used for values, forces later arguments to bind by name} -\item{issues}{\code{\link{timeset}}. Optionally, the issues to fetch. If not set, the -most recent issue is returned. Mutually exclusive with \code{lag}.} +\item{issues}{\code{\link{timeset}}. Optionally, the issue(s) of the +data to fetch. See the "Data Versioning" section for details.} -\item{lag}{integer. Optionally, the lag of the issues to fetch. If not set, -the most recent issue is returned. Mutually exclusive with \code{issues}.} +\item{lag}{integer. Optionally, the lag of the issues to fetch. +See the "Data Versioning" section for details.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -34,9 +36,26 @@ the most recent issue is returned. Mutually exclusive with \code{issues}.} \description{ API docs: \url{https://cmu-delphi.github.io/delphi-epidata/api/paho_dengue.html} } +\section{Data Versioning}{ + +Several endpoints support retrieving historical versions of the data. +The following parameters control this and are mutually exclusive (only +one can be provided at a time). +\itemize{ +\item \code{as_of}: (Date) Retrieve the data as it was on this date. +\item \code{issues}: \code{\link{timeset}} Retrieve data from a +specific issue date or range. +\item \code{lag}: (integer) Retrieve data with a specific lag from +its issue date. +} +See \code{vignette("versioned-data")} for details and more ways to specify +versioned data. +} + \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_paho_dengue(regions = "ca", epiweeks = epirange(201401, 201501)) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pub_wiki.Rd b/man/pub_wiki.Rd index 278dca5..b40746c 100644 --- a/man/pub_wiki.Rd +++ b/man/pub_wiki.Rd @@ -22,14 +22,15 @@ pub_wiki( \item{time_type}{string. The temporal resolution of the data (either "day" or "week", depending on signal).} -\item{time_values}{\code{\link{timeset}}. Dates or epiweeks to fetch. Defaults to all -("*") dates.} +\item{time_values}{\code{\link{timeset}}. Dates or epiweeks to fetch. +Supports \code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} \item{hours}{integer. Optionally, the hours to fetch.} \item{language}{string. Language to fetch.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -46,12 +47,13 @@ Number of page visits for selected English, Influenza-related wikipedia articles } } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("DELPHI_EPIDATA_KEY") != "") withAutoprint(\{ # examplesIf} + pub_wiki( articles = "avian_influenza", time_type = "week", time_values = epirange(201501, 201601) ) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pvt_cdc.Rd b/man/pvt_cdc.Rd index 35cc555..9e87963 100644 --- a/man/pvt_cdc.Rd +++ b/man/pvt_cdc.Rd @@ -7,14 +7,15 @@ pvt_cdc(auth, locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ -\item{auth}{string. Restricted access key (not the same as API key).} +\item{auth}{string. Your restricted access key (not the same as API key).} -\item{locations}{character. Locations to fetch.} +\item{locations}{character. Vector of locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and 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.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -23,13 +24,12 @@ See \code{fetch_args_list()} for details.} API docs: \url{https://cmu-delphi.github.io/delphi-epidata/api/cdc.html} } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("SECRET_API_AUTH_CDC") != "") withAutoprint(\{ # examplesIf} pvt_cdc( auth = Sys.getenv("SECRET_API_AUTH_CDC"), locations = "fl,ca", epirange(201501, 201601) ) -} - +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pvt_dengue_sensors.Rd b/man/pvt_dengue_sensors.Rd index 2ff7eb3..8d38e4f 100644 --- a/man/pvt_dengue_sensors.Rd +++ b/man/pvt_dengue_sensors.Rd @@ -13,15 +13,18 @@ pvt_dengue_sensors( ) } \arguments{ -\item{auth}{string. Restricted access key (not the same as API key).} +\item{auth}{string. Your restricted access key (not the same as API key).} -\item{names}{character. Names to fetch.} +\item{names}{character. Names to fetch. +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} -\item{locations}{character. Locations to fetch.} +\item{locations}{character. Vector of locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -30,13 +33,14 @@ pvt_dengue_sensors( API docs: \url{https://cmu-delphi.github.io/delphi-epidata/api/dengue_sensors.html} } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("SECRET_API_AUTH_SENSORS") != "") withAutoprint(\{ # examplesIf} + pvt_dengue_sensors( auth = Sys.getenv("SECRET_API_AUTH_SENSORS"), names = "ght", locations = "ag", epiweeks = epirange(201501, 202001) ) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pvt_ght.Rd b/man/pvt_ght.Rd index 7a16f10..e6bbccf 100644 --- a/man/pvt_ght.Rd +++ b/man/pvt_ght.Rd @@ -7,15 +7,17 @@ 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{auth}{string. Your restricted access key (not the same as API key).} -\item{locations}{character. Locations to fetch.} +\item{locations}{character. Vector of locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} \item{query}{string. The query to be fetched.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -26,13 +28,14 @@ API docs: \url{https://cmu-delphi.github.io/delphi-epidata/api/ght.html} Estimate of influenza activity based on volume of certain search queries. … } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("SECRET_API_AUTH_GHT") != "") withAutoprint(\{ # examplesIf} + pvt_ght( auth = Sys.getenv("SECRET_API_AUTH_GHT"), locations = "ma", epiweeks = epirange(199301, 202304), query = "how to get over the flu" ) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pvt_meta_norostat.Rd b/man/pvt_meta_norostat.Rd index 491c721..49bac8e 100644 --- a/man/pvt_meta_norostat.Rd +++ b/man/pvt_meta_norostat.Rd @@ -7,9 +7,10 @@ pvt_meta_norostat(auth, fetch_args = fetch_args_list()) } \arguments{ -\item{auth}{string. Restricted access key (not the same as API key).} +\item{auth}{string. Your restricted access key (not the same as API key).} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link{list}} diff --git a/man/pvt_norostat.Rd b/man/pvt_norostat.Rd index 180182e..449ae21 100644 --- a/man/pvt_norostat.Rd +++ b/man/pvt_norostat.Rd @@ -7,13 +7,17 @@ pvt_norostat(auth, locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ -\item{auth}{string. Your authentication key.} +\item{auth}{string. Your restricted access key (not the same as API key).} -\item{locations}{character. Locations to fetch.} +\item{locations}{character. Locations to fetch. Only a specific list of +full state names are permitted. See the \code{locations} column in the +output of \code{pvt_meta_norostat()} for the allowed values.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -27,12 +31,13 @@ This is the documentation of the API for accessing the NoroSTAT endpoint of the Delphi’s epidemiological data. } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("SECRET_API_AUTH_NOROSTAT") != "") withAutoprint(\{ # examplesIf} + pvt_norostat( auth = Sys.getenv("SECRET_API_AUTH_NOROSTAT"), locations = "Minnesota, Ohio, Oregon, Tennessee, and Wisconsin", epiweeks = 201233 ) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pvt_quidel.Rd b/man/pvt_quidel.Rd index 10ca3c0..5b4f2cc 100644 --- a/man/pvt_quidel.Rd +++ b/man/pvt_quidel.Rd @@ -7,13 +7,15 @@ pvt_quidel(auth, locations, epiweeks = "*", fetch_args = fetch_args_list()) } \arguments{ -\item{auth}{string. Restricted access key (not the same as API key).} +\item{auth}{string. Your restricted access key (not the same as API key).} -\item{locations}{character. Locations to fetch.} +\item{locations}{character. Vector of locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -24,12 +26,13 @@ API docs: \url{https://cmu-delphi.github.io/delphi-epidata/api/quidel.html} Data provided by Quidel Corp., which contains flu lab test results. } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("SECRET_API_AUTH_QUIDEL") != "") withAutoprint(\{ # examplesIf} + pvt_quidel( auth = Sys.getenv("SECRET_API_AUTH_QUIDEL"), epiweeks = epirange(201201, 202001), locations = "hhs1" ) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pvt_sensors.Rd b/man/pvt_sensors.Rd index 35e41bf..5e57a4c 100644 --- a/man/pvt_sensors.Rd +++ b/man/pvt_sensors.Rd @@ -13,15 +13,18 @@ pvt_sensors( ) } \arguments{ -\item{auth}{string. Restricted access key (not the same as API key).} +\item{auth}{string. Your restricted access key (not the same as API key).} -\item{names}{character. Sensor names to fetch.} +\item{names}{character. Names to fetch. +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} -\item{locations}{character. Locations to fetch.} +\item{locations}{character. Vector of locations to fetch.} -\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Defaults to all ("*") dates.} +\item{epiweeks}{\code{\link{timeset}}. Epiweeks to fetch. Supports +\code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -41,13 +44,14 @@ these were designed to track ILI as driven by seasonal influenza, and were NOT designed to track ILI during the COVID-19 pandemic. } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("SECRET_API_AUTH_SENSORS") != "") withAutoprint(\{ # examplesIf} + pvt_sensors( auth = Sys.getenv("SECRET_API_AUTH_SENSORS"), names = "sar3", locations = "nat", epiweeks = epirange(201501, 202001) ) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/man/pvt_twitter.Rd b/man/pvt_twitter.Rd index b6c6e95..72d7c15 100644 --- a/man/pvt_twitter.Rd +++ b/man/pvt_twitter.Rd @@ -14,19 +14,20 @@ pvt_twitter( ) } \arguments{ -\item{auth}{string. Restricted access key (not the same as API key).} +\item{auth}{string. Your restricted access key (not the same as API key).} -\item{locations}{character. Locations to fetch.} +\item{locations}{character. Vector of locations to fetch.} \item{...}{not used for values, forces later arguments to bind by name} \item{time_type}{string. The temporal resolution of the data (either "day" or "week", depending on signal).} -\item{time_values}{\code{\link{timeset}}. Dates or epiweeks to fetch. Defaults to all -("*") dates.} +\item{time_values}{\code{\link{timeset}}. Dates or epiweeks to fetch. +Supports \code{\link[=epirange]{epirange()}} and defaults to all ("*") dates.} -\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass to \code{fetch()}.} +\item{fetch_args}{\code{\link{fetch_args}}. Additional arguments to pass +to \code{fetch()}. See \code{fetch_args_list()} for details.} } \value{ \code{\link[tibble:tibble]{tibble::tibble}} @@ -39,13 +40,14 @@ Delphi’s epidemiological data. Sourced from \href{http://www.healthtweets.org/}{Healthtweets} } \examples{ -\dontrun{ +\dontshow{if (curl::has_internet() && Sys.getenv("SECRET_API_AUTH_TWITTER") != "") withAutoprint(\{ # examplesIf} + pvt_twitter( auth = Sys.getenv("SECRET_API_AUTH_TWITTER"), locations = "CA", time_type = "week", time_values = epirange(201501, 202001) ) -} +\dontshow{\}) # examplesIf} } \keyword{endpoint} diff --git a/vignettes/epidatr.Rmd b/vignettes/epidatr.Rmd index 4078016..c18e4df 100644 --- a/vignettes/epidatr.Rmd +++ b/vignettes/epidatr.Rmd @@ -138,8 +138,8 @@ pub_covidcast( The Epidata API stores a historical record of all data, including corrections and updates, which is particularly useful for accurately backtesting -forecasting models. To fetch versioned data, we can use the `as_of` -argument. +forecasting models. To retrieve versioned data, we can use the `as_of` +argument, which fetch the data as it was known on a specific date. ```{r, eval = FALSE} # Obtain the smoothed covid-like illness (CLI) signal from the COVID-19 @@ -155,6 +155,38 @@ pub_covidcast( ) ``` +We can also request all versions of the data issued within a specific time period using the `issues` argument. + +```{r, eval = FALSE} +# See how the estimate for a SINGLE day (March 1, 2021) evolved +# by fetching all issues reported between March and April 2021. +pub_covidcast( + source = "fb-survey", + signals = "smoothed_cli", + geo_type = "state", + time_type = "day", + geo_values = "pa", + time_values = "2021-03-01", + issues = epirange("2021-03-01", "2021-04-30") +) +``` + +Finally, we can use the `lag` argument to request only data that was reported a certain number of days after the event. + +```{r, eval = FALSE} +# Fetch survey data for January 2021, but ONLY include data +# that was issued exactly 2 days after it was collected. +pub_covidcast( + source = "fb-survey", + signals = "smoothed_cli", + geo_type = "state", + time_type = "day", + geo_values = "pa", + time_values = epirange(20210101, 20210131), + lag = 2 +) +``` + See `vignette("versioned-data")` for details and more ways to specify versioned data.