diff --git a/.Rbuildignore b/.Rbuildignore index 0b4b1542..c6d724be 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -1,3 +1,5 @@ +^renv$ +^renv\.lock$ ^.*\.Rproj$ ^.*\..Rcheck$ ^\.Rproj\.user$ @@ -18,4 +20,4 @@ ^venv$ ^.venv$ ^env$ -^.env$ \ No newline at end of file +^.env$ diff --git a/.gitignore b/.gitignore index 8399e0fd..5325ba8a 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ env .httr-oauth /doc/ /Meta/ +.secrets diff --git a/R/endpoints.R b/R/endpoints.R index 6fdb00ce..d8d50c51 100644 --- a/R/endpoints.R +++ b/R/endpoints.R @@ -6,7 +6,7 @@ #' \dontrun{ #' pvt_cdc( #' auth = "yourkey", -#' "fl,ca", +#' locations = "fl,ca", #' epirange(201501, 201601) #' ) %>% fetch() #' } @@ -62,6 +62,7 @@ pvt_cdc <- function(auth, locations, epiweeks) { #' @examples #' \donttest{ #' covid_hosp_facility_lookup(state = "fl") %>% fetch() +#' covid_hosp_facility_lookup(city = "southlake") %>% fetch() #' } #' @param state string. A two-letter character string state abbreviation. #' @param ccn string. A character string for facility CMS certification number. @@ -583,7 +584,7 @@ covid_hosp_state_timeseries <- function(states, dates, issues = NULL) { #' covidcast_meta() %>% fetch() #' } #' -#' @seealso [covidcast()] +#' @seealso [covidcast()],[covidcast_epidata()] #' @export covidcast_meta <- function() { create_epidata_call( @@ -614,6 +615,7 @@ covidcast_meta <- function() { #' Fetch covidcast data #' #' API docs: +#' #' COVIDcast public dashboard: #' #' @examples @@ -626,11 +628,19 @@ covidcast_meta <- function() { #' geo_values = "ca,fl", #' time_values = epirange(20200601, 20200801) #' ) %>% fetch() +#' covidcast( +#' data_source = "jhu-csse", +#' signals = "confirmed_7dav_incidence_prop", +#' geo_type = "state", +#' time_type = "day", +#' geo_values = "*", +#' time_values = epirange(20200601, 20200801) +#' ) %>% fetch() #' } #' @param data_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 @@ -650,7 +660,7 @@ covidcast_meta <- function() { #' `issues`. #' @return [`epidata_call`] #' -#' @seealso [covidcast_meta()], [epirange()] +#' @seealso [covidcast_meta()], [covidcast_epidata()], [epirange()] #' #' @export covidcast <- function( @@ -770,7 +780,7 @@ delphi <- function(system, epiweek) { #' @examples #' \dontrun{ #' dengue_nowcast( -#' locations = "?", +#' locations = "pr", #' epiweeks = epirange(201501, 202001) #' ) %>% fetch() #' } @@ -806,8 +816,8 @@ dengue_nowcast <- function(locations, epiweeks) { #' \dontrun{ #' pvt_dengue_sensors( #' auth = "yourkey", -#' names = "?", -#' locations = "?", +#' names = "ght", +#' locations = "ag", #' epiweeks = epirange(201501, 202001) #' ) %>% fetch() #' } @@ -1011,6 +1021,10 @@ fluview_clinical <- function(regions, epiweeks, issues = NULL, lag = NULL) { #' Fetch FluView metadata #' #' API docs: https://cmu-delphi.github.io/delphi-epidata/api/fluview_meta.html +#' @examples +#' \donttest{ +#' fluview_meta() %>% fetch() +#' } #' #' @return [`epidata_call`] #' @@ -1150,7 +1164,7 @@ gft <- function(locations, epiweeks) { #' auth = "yourkey", #' locations = "ca", #' epiweeks = epirange(201201, 202001), -#' query = "?" +#' query = "how to get over the flu" #' ) %>% fetch() #' } #' @param auth string. Restricted access key (not the same as API key). @@ -1190,7 +1204,7 @@ pvt_ght <- function(auth, locations, epiweeks, query) { #' TODO: find a non-trivial region #' @examples #' \dontrun{ -#' kcdc_ili(regions = "?", epiweeks = epirange(201201, 202001)) %>% fetch() +#' kcdc_ili(regions = "ROK", epiweeks = 200436) %>% fetch() #' } #' @param regions character vector. The regions to be fetched. #' @param epiweeks [`timeset`]. The epiweeks to be fetched. @@ -1235,6 +1249,10 @@ kcdc_ili <- function(regions, epiweeks, issues = NULL, lag = NULL) { #' #' API docs: https://cmu-delphi.github.io/delphi-epidata/api/meta_norostat.html #' +#' @examples +#' \donttest{ +#' pvt_meta_norostat(auth = "yourkey") %>% fetch() +#' } #' @param auth string. Restricted access key (not the same as API key). #' @return [`epidata_call`] #' @@ -1355,8 +1373,8 @@ nidss_flu <- function(regions, epiweeks, issues = NULL, lag = NULL) { #' \dontrun{ #' pvt_norostat( #' auth = "yourkey", -#' locations = "Minnesota, Ohio, Oregon, Tennessee, and Wisconsin", -#' epiweeks = epirange(201401, 201501) +#' locations = "1", +#' epiweeks = 201233 #' ) %>% fetch() #' } #' @param auth string. Your authentication key. diff --git a/man/covid_hosp_facility_lookup.Rd b/man/covid_hosp_facility_lookup.Rd index b42e7c9d..a1caa5e6 100644 --- a/man/covid_hosp_facility_lookup.Rd +++ b/man/covid_hosp_facility_lookup.Rd @@ -42,6 +42,7 @@ For instance, specifying both city and state are not supported. \examples{ \donttest{ covid_hosp_facility_lookup(state = "fl") \%>\% fetch() +covid_hosp_facility_lookup(city = "southlake") \%>\% fetch() } } \seealso{ diff --git a/man/covidcast.Rd b/man/covidcast.Rd index 09280db5..566f2560 100644 --- a/man/covidcast.Rd +++ b/man/covidcast.Rd @@ -21,7 +21,7 @@ covidcast( \url{https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html}).} \item{signals}{string. The signals to query from a specific source (see: -\url{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals}).} +\url{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals.html}).} \item{geo_type}{string. The geographic resolution of the data (see: \url{https://cmu-delphi.github.io/delphi-epidata/api/covidcast_geography.html}).} @@ -52,6 +52,8 @@ the most recent issue is returned. Mutually exclusive with \code{as_of} or } \description{ API docs: \url{https://cmu-delphi.github.io/delphi-epidata/api/covidcast.html} +} +\details{ COVIDcast public dashboard: \url{https://delphi.cmu.edu/covidcast/} } \examples{ @@ -64,8 +66,16 @@ covidcast( geo_values = "ca,fl", time_values = epirange(20200601, 20200801) ) \%>\% fetch() +covidcast( + data_source = "jhu-csse", + signals = "confirmed_7dav_incidence_prop", + geo_type = "state", + time_type = "day", + geo_values = "*", + time_values = epirange(20200601, 20200801) +) \%>\% fetch() } } \seealso{ -\code{\link[=covidcast_meta]{covidcast_meta()}}, \code{\link[=epirange]{epirange()}} +\code{\link[=covidcast_meta]{covidcast_meta()}}, \code{\link[=covidcast_epidata]{covidcast_epidata()}}, \code{\link[=epirange]{epirange()}} } diff --git a/man/covidcast_meta.Rd b/man/covidcast_meta.Rd index 3f9f8968..d134b674 100644 --- a/man/covidcast_meta.Rd +++ b/man/covidcast_meta.Rd @@ -25,5 +25,5 @@ covidcast_meta() \%>\% fetch() } \seealso{ -\code{\link[=covidcast]{covidcast()}} +\code{\link[=covidcast]{covidcast()}},\code{\link[=covidcast_epidata]{covidcast_epidata()}} } diff --git a/man/delphi.Rd b/man/delphi.Rd index 0361d1dc..abf78c3e 100644 --- a/man/delphi.Rd +++ b/man/delphi.Rd @@ -19,6 +19,6 @@ API docs: https://cmu-delphi.github.io/delphi-epidata/api/delphi.html } \examples{ \donttest{ -delphi(system = "ec", epiweek = 201501) \%>\% fetch() +delphi(system = "ec", epiweek = 202006) \%>\% fetch() } } diff --git a/man/dengue_nowcast.Rd b/man/dengue_nowcast.Rd index 760ac8ed..3cfd087e 100644 --- a/man/dengue_nowcast.Rd +++ b/man/dengue_nowcast.Rd @@ -23,7 +23,7 @@ TODO: what are valid locations here? \examples{ \dontrun{ dengue_nowcast( - locations = "?", + locations = "pr", epiweeks = epirange(201501, 202001) ) \%>\% fetch() } diff --git a/man/fluview_meta.Rd b/man/fluview_meta.Rd index 0cd8eaba..096db329 100644 --- a/man/fluview_meta.Rd +++ b/man/fluview_meta.Rd @@ -12,3 +12,9 @@ fluview_meta() \description{ API docs: https://cmu-delphi.github.io/delphi-epidata/api/fluview_meta.html } +\examples{ +\donttest{ +fluview_meta() \%>\% fetch() +} + +} diff --git a/man/kcdc_ili.Rd b/man/kcdc_ili.Rd index 45aef01e..ea374540 100644 --- a/man/kcdc_ili.Rd +++ b/man/kcdc_ili.Rd @@ -28,6 +28,6 @@ TODO: find a non-trivial region } \examples{ \dontrun{ -kcdc_ili(regions = "?", epiweeks = epirange(201201, 202001)) \%>\% fetch() +kcdc_ili(regions = "ROC", epiweeks = 200436) \%>\% fetch() } } diff --git a/man/pvt_cdc.Rd b/man/pvt_cdc.Rd index 353202c2..7d6b6373 100644 --- a/man/pvt_cdc.Rd +++ b/man/pvt_cdc.Rd @@ -23,7 +23,7 @@ API docs: https://cmu-delphi.github.io/delphi-epidata/api/cdc.html \dontrun{ pvt_cdc( auth = "yourkey", - "fl,ca", + locations = "fl,ca", epirange(201501, 201601) ) \%>\% fetch() } diff --git a/man/pvt_dengue_sensors.Rd b/man/pvt_dengue_sensors.Rd index 78e2facb..6212e04c 100644 --- a/man/pvt_dengue_sensors.Rd +++ b/man/pvt_dengue_sensors.Rd @@ -29,8 +29,8 @@ TODO: what are valid locations and names? \dontrun{ pvt_dengue_sensors( auth = "yourkey", - names = "?", - locations = "?", + names = "ght", + locations = "ag", epiweeks = epirange(201501, 202001) ) \%>\% fetch() } diff --git a/man/pvt_ght.Rd b/man/pvt_ght.Rd index fdfec8bd..89ede2b1 100644 --- a/man/pvt_ght.Rd +++ b/man/pvt_ght.Rd @@ -30,7 +30,7 @@ pvt_ght( auth = "yourkey", locations = "ca", epiweeks = epirange(201201, 202001), - query = "?" + query = "how to get over the flu" ) \%>\% fetch() } } diff --git a/man/pvt_meta_norostat.Rd b/man/pvt_meta_norostat.Rd index 63dbfc55..80af7c96 100644 --- a/man/pvt_meta_norostat.Rd +++ b/man/pvt_meta_norostat.Rd @@ -15,3 +15,8 @@ pvt_meta_norostat(auth) \description{ API docs: https://cmu-delphi.github.io/delphi-epidata/api/meta_norostat.html } +\examples{ +\donttest{ +pvt_meta_norostat(auth = "yourkey") \%>\% fetch() +} +} diff --git a/man/pvt_norostat.Rd b/man/pvt_norostat.Rd index eb706181..5b2fbe32 100644 --- a/man/pvt_norostat.Rd +++ b/man/pvt_norostat.Rd @@ -23,8 +23,8 @@ API docs: https://cmu-delphi.github.io/delphi-epidata/api/norostat.html \dontrun{ pvt_norostat( auth = "yourkey", - locations = "Minnesota, Ohio, Oregon, Tennessee, and Wisconsin", - epiweeks = epirange(201401, 201501) + locations = "1", + epiweeks = 201233 ) \%>\% fetch() } } diff --git a/vignettes/covidcast.Rmd b/vignettes/covidcast.Rmd index 9450d47e..e21d994f 100644 --- a/vignettes/covidcast.Rmd +++ b/vignettes/covidcast.Rmd @@ -21,7 +21,6 @@ library("epidatr") library("magrittr") ``` - ```{r} covidcast_api <- covidcast_epidata() epicall <- covidcast_api$sources$`fb-survey`$signals$smoothed_cli$call("nation", "us", epirange(20210405, 20210410)) diff --git a/vignettes/endpoints.Rmd b/vignettes/endpoints.Rmd new file mode 100644 index 00000000..07968dac --- /dev/null +++ b/vignettes/endpoints.Rmd @@ -0,0 +1,406 @@ +--- +title: "Endpoint Examples" +author: "Delphi Group" +date: "`r Sys.Date()`" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Endpoint Examples} + %\VignetteEngine{knitr::rmarkdown} + \usepackage[utf8]{inputenc} +--- + +```{r setup, include=FALSE} +knitr::opts_chunk$set(echo = TRUE) +``` + +```{r libraries} +library("epidatr") +library("magrittr") +library("dplyr") +``` + +The API endpoints, organized by data sources. +Some endpoints allow for the use of `*` to access data at all locations. Check the help for a given endpoint to see if it supports `*`. + +## COVIDcast Main Endpoint + +All of these signals use the command `covidcast`, with variation in which source and signal are used. + +Data Sources and Signals documentation: + +Function reference: + +To understand the available sources better, use `covidcast_epidata()` and `covidcast_meta()`. + +```{r} +covidcast_epidata() +``` + +For example, let's see what kind of smoothed signals come out of the [facebook survey](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/fb-survey.html) source: + +```{r} +cm <- covidcast_meta() %>% + fetch() %>% + dplyr::filter(grepl("smoothed", signal), data_source == "fb-survey") +``` + +grabbing the first smoothed signal as an example: + +```{r} +cm[1, ] %>% print(width = 100) +cm[1, "signal"] +``` + +and actually fetching some data from this source + +```{r} +covidcast( + data_source = "fb-survey", + signals = "smoothed_accept_covid_vaccine", + geo_type = "county", + time_type = "day", + time_values = epirange(20201221, 20201225), + geo_values = "06059" +) %>% fetch() +``` + +County geo_values are [FIPS codes](https://en.wikipedia.org/wiki/List_of_United_States_FIPS_codes_by_county) and are discussed more here: . The example above is for Orange County, California. +Since `covidcast` is an endpoint which supports `*`, here is an example of its use: + +```{r} +covidcast( + data_source = "fb-survey", + signals = "smoothed_accept_covid_vaccine", + geo_type = "county", + time_type = "day", + time_values = epirange(20201221, 20201225), + geo_values = "*" +) %>% fetch() +``` + +## Other Covid Endpoints + +### COVID-19 Hospitalization: Facility Lookup + +API docs: + +Function reference: + +Example calls: + +```{r} +covid_hosp_facility_lookup(city = "southlake") %>% fetch() +``` + +```{r} +covid_hosp_facility_lookup(state = "WY") %>% fetch() +``` + +A non-example (there is no city called New York in Wyoming); + +```{r} +covid_hosp_facility_lookup(state = "WY", city = "New York") %>% fetch() +``` + +### COVID-19 Hospitalization by Facility + +API docs: + +Function reference: + +Example call: + +```{r} +covid_hosp_facility( + hospital_pks = "100075", + collection_weeks = epirange(20200101, 20200501) +) %>% fetch() +``` + +### COVID-19 Hospitalization by State + +API docs: + +Function reference: + +Example call: + +```{r} +covid_hosp_state_timeseries(states = "MA", dates = "20200510") %>% fetch() +``` + +## Flu Endpoints + +### Delphi's ILINet forecasts + +API docs: + +Function reference: + +Example call: + +```{r} +del <- delphi(system = "ec", epiweek = 201501) %>% fetch() +names(del[[1L]]$forecast) +``` + +### FluSurv hospitalization data + +API docs: + +Function reference: + +Example call: + +```{r} +flusurv(locations = "ca", epiweeks = 202001) %>% fetch() +``` + +### Fluview data + +API docs: + +Function reference: + +Example call: + +```{r} +fluview(regions = "nat", epiweeks = epirange(201201, 202001)) %>% fetch() +``` + +### Fluview virological data from clinical labs + +API docs: + +Function reference: + +Example call: + +```{r} +fluview_clinical(regions = "nat", epiweeks = epirange(201601, 201701)) %>% fetch() +``` + +### Fluview metadata + +Function reference: + +Example call: + +```{r} +fluview_meta() %>% fetch() +``` + +### Google Flu Trends data + +API docs: + +Function reference: + +```{r} +gft(locations = "hhs1", epiweeks = epirange(201201, 202001)) %>% fetch() +``` + +### ECDC ILI + +API docs: + +Function reference: + +```{r} +ecdc_ili(regions = "Armenia", epiweeks = 201840) %>% fetch() +``` + +### KCDC ILI + +API docs: + +Function reference: + +```{r} +kcdc_ili(regions = "ROK", epiweeks = 200436) %>% fetch() +``` + +### NIDSS Flu + +API docs: + +Function reference: + +```{r} +nidss_flu(regions = "taipei", epiweeks = epirange(200901, 201301)) %>% fetch() +``` + +### ILI Nearby Nowcast + +API docs: + +Function reference: + +```{r} +nowcast(locations = "ca", epiweeks = epirange(202201, 202319)) %>% fetch() +``` + +## Dengue Endpoints + +### Delphi's Dengue Nowcast + +API docs: + +Function reference: + +Example call: + +```{r} +dengue_nowcast(locations = "pr", epiweeks = epirange(201401, 202301)) %>% fetch() +``` + +### NIDSS dengue + +API docs: + +Function reference: + +```{r} +nidss_dengue(locations = "taipei", epiweeks = epirange(200301, 201301)) %>% fetch() +``` + +## PAHO Dengue + +API docs: + +Function reference: + +```{r, eval=FALSE} +paho_dengue(regions = "ca", epiweeks = epirange(200201, 202319)) %>% fetch() +``` + +## Other Endpoints + +### Wikipedia Access + +API docs: + +Function reference: + +```{r} +wiki(language = "en", articles = "influenza", epiweeks = epirange(202001, 202319)) %>% fetch() +``` + +# Private methods + +These require private access keys to use. To actually run these locally, you will need to store these secrets in your `.Reviron` file, or set them as environmental variables. + +### CDC + +API docs: + +Function reference: + +Example call: + +```{r, eval=FALSE} +pvt_cdc(auth = Sys.getenv("SECRET_API_AUTH_CDC"), epiweeks = epirange(202003, 202304), locations = "ma") %>% fetch() +``` + +### Dengue Digital Surveillance Sensors + +API docs: + +Function reference: + +Example call: + +```{r, eval=FALSE} +pvt_dengue_sensors( + auth = Sys.getenv("SECRET_API_AUTH_SENSORS"), + names = "ght", + locations = "ag", + epiweeks = epirange(201404, 202004) +) %>% fetch() +``` + +### Google Health Trends + +API docs: + +Function reference: + +Example call: + +```{r, eval=FALSE} +pvt_ght( + auth = Sys.getenv("SECRET_API_AUTH_GHT"), + epiweeks = epirange(199301, 202304), + locations = "ma", + query = "how to get over the flu" +) %>% fetch() +``` + +### NoroSTAT metadata + +API docs: + +Function reference: + +Example call: + +```{r, eval=FALSE} +pvt_meta_norostat(auth = Sys.getenv("SECRET_API_AUTH_NOROSTAT")) %>% fetch() +``` + +### NoroSTAT data + +API docs: + +Function reference: + +Example call: + +```{r, eval=FALSE} +pvt_norostat(auth = Sys.getenv("SECRET_API_AUTH_NOROSTAT"), locations = "1", epiweeks = 201233) %>% fetch() +``` + +### Quidel Covid and Influenza testing + +API docs: + +Function reference: + +Example call: + +```{r, eval=FALSE} +pvt_quidel(auth = Sys.getenv("SECRET_API_AUTH_QUIDEL"), locations = "hhs1", epiweeks = epirange(200301, 202105)) %>% fetch() +``` + +### Sensors + +API docs: + +Function reference: + +Example call: + +```{r, eval=FALSE} +pvt_sensors( + auth = Sys.getenv("SECRET_API_AUTH_SENSORS"), + names = "sar3", + locations = "nat", + epiweeks = epirange(200301, 202105) +) %>% fetch() +``` + +### Twitter + +API docs: + +Function reference: + +Example call: + +```{r, eval=FALSE} +pvt_twitter( + auth = Sys.getenv("SECRET_API_AUTH_TWITTER"), + locations = "nat", + epiweeks = epirange(200301, 202105) +) %>% fetch() +```