diff --git a/.Rbuildignore b/.Rbuildignore index d8980c48..5da1eff9 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -20,3 +20,5 @@ ^.venv$ ^env$ ^.env$ +^README\.Rmd$ +^CRAN-SUBMISSION$ diff --git a/CRAN-SUBMISSION b/CRAN-SUBMISSION new file mode 100644 index 00000000..a0b6ffc6 --- /dev/null +++ b/CRAN-SUBMISSION @@ -0,0 +1,3 @@ +Version: 1.0.0 +Date: 2023-09-12 08:00:50 UTC +SHA: 52436eb250eab1f9c70b250bf4ca1ab25cc48316 diff --git a/DESCRIPTION b/DESCRIPTION index 7c79ddb4..6f00eb30 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,6 +2,7 @@ Package: epidatr Type: Package Title: Client for Delphi's 'Epidata' API Version: 1.0.0 +Date: 2023-09-11 Authors@R: c( person("Logan", "Brooks", email = "lcbrooks@andrew.cmu.edu", role = c("aut")), @@ -15,9 +16,9 @@ Authors@R: person("George", "Haff", role = c("ctb")), person("Kathryn", "Mazaitis", role = c("ctb")) ) -URL: https://cmu-delphi.github.io/epidatr/, https://github.com/cmu-delphi/epidatr +URL: https://cmu-delphi.github.io/epidatr/, https://cmu-delphi.github.io/delphi-epidata/, https://github.com/cmu-delphi/epidatr BugReports: https://github.com/cmu-delphi/epidatr/issues -Description: The Delphi 'Epidata' API provides real-time access to epidemiological surveillance data for influenza, COVID-19, and other diseases for the USA at various geographical resolutions, both from official government sources such as the Center for Disease Control (CDC) and Google Trends and private partners such as Facebook and Change Healthcare. It is built and maintained by the Carnegie Mellon University Delphi research group. +Description: The Delphi 'Epidata' API provides real-time access to epidemiological surveillance data for influenza, 'COVID-19', and other diseases for the USA at various geographical resolutions, both from official government sources such as the Center for Disease Control (CDC) and Google Trends and private partners such as Facebook and Change 'Healthcare'. It is built and maintained by the Carnegie Mellon University Delphi research group. To cite this API: David C. Farrow, Logan C. Brooks, Aaron 'Rumack', Ryan J. 'Tibshirani', 'Roni' 'Rosenfeld' (2015). Delphi 'Epidata' API. . Depends: R (>= 3.5.0) License: MIT + file LICENSE Encoding: UTF-8 diff --git a/NAMESPACE b/NAMESPACE index 6f454611..5e0849a0 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -7,7 +7,6 @@ S3method(print,covidcast_data_signal_list) S3method(print,covidcast_data_source) S3method(print,covidcast_epidata) S3method(print,epidata_call) -export("%>%") export(avail_endpoints) export(cache_info) export(clear_cache) diff --git a/R/cache.R b/R/cache.R index c481f794..dda3d15f 100644 --- a/R/cache.R +++ b/R/cache.R @@ -68,14 +68,12 @@ cache_environ$epidatr_cache <- NULL #' encoding of the call url. Each file corresponds to a unique epidata-API #' call. #' @examples -#' \dontrun{ #' set_cache( -#' dir = "some/subdir", +#' cache_dir = tempdir(), #' days = 14, #' max_size = 512, -#' logfile = "some/subdir/logs.txt" +#' logfile = "logs.txt" #' ) -#' } #' #' @param cache_dir the directory in which the cache is stored. By default, this #' is `tools::R_user_dir()` if on R 4.0+, but must be specified for earlier @@ -92,6 +90,8 @@ cache_environ$epidatr_cache <- NULL #' variable is `EPIDATR_CACHE_LOGFILE`. #' @param confirm whether to confirm directory creation. default is `TRUE`; #' should only be set in non-interactive scripts +#' @return [`NULL`] no return value, all effects are stored in the package +#' environment #' @seealso [`clear_cache`] to delete the old cache while making a new one, #' [`disable_cache`] to disable without deleting, and [`cache_info`] #' @export @@ -176,28 +176,23 @@ set_cache <- function(cache_dir = NULL, #' are using a session unique cache, you will have to pass the arguments you #' used for `set_cache` earlier, otherwise the system-wide `.Renviron`-based #' defaults will be used. -#' @examples -#' \dontrun{ -#' clear_cache( -#' dir = "some/subdir", -#' days = 14, -#' max_size = 512, -#' logfile = "some/subdir/logs.txt", -#' ) -#' } #' @param disable instead of setting a new cache, disable caching entirely; #' defaults to `FALSE` #' @inheritDotParams set_cache +#' @return [`NULL`] no return value, all effects are stored in the package +#' environment #' @seealso [`set_cache`] to start a new cache (and general caching info), #' [`disable_cache`] to only disable without deleting, and [`cache_info`] #' @export #' @import cachem clear_cache <- function(disable = FALSE, ...) { - cache_environ$epidatr_cache$destroy() - if (!disable) { - set_cache(...) - } else { + if (any(!is.na(cache_environ$epidatr_cache))) { + cache_environ$epidatr_cache$destroy() + } + if (disable) { cache_environ$epidatr_cache <- NULL + } else { + set_cache(...) } } @@ -207,6 +202,8 @@ clear_cache <- function(disable = FALSE, ...) { #' the cache are untouched. If you are looking to disable the caching more #' permanently, set `EPIDATR_USE_CACHE=FALSE` as environmental variable in #' your `.Renviron`. +#' @return [`NULL`] no return value, all effects are stored in the package +#' environment #' @export #' @seealso [`set_cache`] to start a new cache (and general caching info), #' [`clear_cache`] to delete the cache and set a new one, and [`cache_info`] @@ -220,6 +217,7 @@ disable_cache <- function() { #' @description #' Print out the information about the cache (as would be returned by cachem's #' `info()` method). +#' @return [`list`] containing the info result as created by cachem #' #' @seealso [`set_cache`] to start a new cache (and general caching info), #' [`clear_cache`] to delete the cache and set a new one, and [`disable_cache`] to @@ -239,7 +237,7 @@ cache_info <- function() { #' The guts of caching, its interposed between fetch and the specific fetch #' methods. Internal method only. #' -#' @param call the `epidata_call` object +#' @param epidata_call the `epidata_call` object #' @param fetch_args the args list for fetch as generated by [`fetch_args_list()`] #' @keywords internal #' @importFrom openssl md5 diff --git a/R/covidcast.R b/R/covidcast.R index 2107b636..66263be1 100644 --- a/R/covidcast.R +++ b/R/covidcast.R @@ -1,20 +1,24 @@ +#' turn a signal into a callable +#' @param signal the signal of interest +#' @param base_url the base url +#' @keywords internal parse_signal <- function(signal, base_url) { class(signal) <- c("covidcast_data_signal", class(signal)) signal$key <- paste(signal$source, signal$signal, sep = ":") #' fetch covidcast data #' - #' @param data_source data source to fetch - #' @param signals data source to fetch - #' @param geo_type geo_type to fetch - #' @param time_type data source to fetch - #' @param geo_values data source to fetch - #' @param time_values data source to fetch - #' @param as_of data source to fetch - #' @param issues data source to fetch - #' @param lag data source to fetch - #' @return an instance of epidata_call - #' @keywords internal + #' param data_source data source to fetch + #' param signals data source to fetch + #' param geo_type geo_type to fetch + #' param time_type data source to fetch + #' param geo_values data source to fetch + #' param time_values data source to fetch + #' param as_of data source to fetch + #' param issues data source to fetch + #' param lag data source to fetch + #' return an instance of epidata_call + #' keywords internal signal$call <- function(geo_type, geo_values, time_values, diff --git a/R/endpoints.R b/R/endpoints.R index 321a15f8..da14c2bb 100644 --- a/R/endpoints.R +++ b/R/endpoints.R @@ -658,7 +658,7 @@ pub_covidcast_meta <- function(fetch_args = fetch_args_list()) { #' signals = "confirmed_7dav_incidence_prop", #' geo_type = "state", #' time_type = "day", -#' geo_values = "ca,fl", +#' geo_values = c("ca", "fl"), #' time_values = epirange(20200601, 20200801) #' ) #' pub_covidcast( @@ -1102,11 +1102,13 @@ pub_fluview_meta <- function(fetch_args = fetch_args_list()) { #' more information on ILINet, see #' . #' -#' @details The full list of location inputs can be accsssed at +#' @details The full list of location inputs can be accessed at #' . #' #' @examples -#' pub_fluview(regions = "nat", epiweeks = epirange(201201, 202001)) +#' \dontrun{ +#' 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. @@ -1492,7 +1494,7 @@ pvt_norostat <- function(auth, locations, epiweeks, fetch_args = fetch_args_list #' #' Obtains information on outpatient inluenza-like-illness (ILI) from Delphi's #' -#' @details The full list of location inputs can be accsssed at +#' @details The full list of location inputs can be accessed at #' . #' #' @examples diff --git a/R/utils-pipe.R b/R/utils-pipe.R index fd0b1d13..6bd13bc4 100644 --- a/R/utils-pipe.R +++ b/R/utils-pipe.R @@ -1,14 +1,2 @@ -#' Pipe operator -#' -#' See \code{magrittr::\link[magrittr:pipe]{\%>\%}} for details. -#' -#' @name %>% -#' @rdname pipe -#' @keywords internal -#' @export #' @importFrom magrittr %>% -#' @usage lhs \%>\% rhs -#' @param lhs A value or the magrittr placeholder. -#' @param rhs A function call using the magrittr semantics. -#' @return The result of calling `rhs(lhs)`. NULL diff --git a/README.Rmd b/README.Rmd new file mode 100644 index 00000000..821c6690 --- /dev/null +++ b/README.Rmd @@ -0,0 +1,102 @@ +--- +output: github_document +--- + + + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>", + fig.path = "man/figures/README-", + out.width = "100%" +) +ggplot2::theme_set(ggplot2::theme_bw()) +``` + +# Delphi Epidata R client + + + +[![License: MIT][mit-image]][mit-url] [![Github Actions][github-actions-image]][github-actions-url] +[![codecov](https://codecov.io/gh/dsweber2/epidatr/branch/dev/graph/badge.svg?token=jVHL9eHZNZ)](https://app.codecov.io/gh/dsweber2/epidatr) + + + + +The [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/) provides real-time access to epidemiological surveillance data for influenza, COVID-19, and other diseases for the USA at various geographical resolutions, both from official government sources such as the [Center for Disease Control (CDC)](https://www.cdc.gov/datastatistics/index.html) and [Google Trends](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/google-symptoms.html) and private partners such as [Facebook](https://delphi.cmu.edu/blog/2020/08/26/covid-19-symptom-surveys-through-facebook/) and [Change Healthcare](https://www.changehealthcare.com/). It is built and maintained by the Carnegie Mellon University [Delphi research group](https://delphi.cmu.edu/). + +This package is designed to streamline the downloading and usage of data from the [Delphi Epidata +API](https://cmu-delphi.github.io/delphi-epidata/). It provides a simple R interface to the API, including functions for downloading data, parsing the results, and converting the data into a tidy format. The API stores a historical record of all data, including corrections and updates, which is particularly useful for accurately backtesting forecasting models. We also provide packages for downstream data processing ([epiprocess](https://github.com/cmu-delphi/epiprocess)) and modeling ([epipredict](https://github.com/cmu-delphi/epipredict)). + +## Usage + +```{r} +library(epidatr) +# Obtain the smoothed covid-like illness (CLI) signal from the +# Facebook survey as it was on April 10, 2021 for the US +epidata <- pub_covidcast( + source = "fb-survey", + signals = "smoothed_cli", + geo_type = "nation", + time_type = "day", + geo_values = "us", + time_values = epirange(20210101, 20210601), + as_of = "2021-06-01" +) +epidata +``` + +```{r fb-cli-signal} +# Plot this data +library(ggplot2) +ggplot(epidata, aes(x = time_value, y = value)) + + geom_line() + + labs( + title = "Smoothed CLI from Facebook Survey", + subtitle = "US, 2021", + x = "Date", + y = "CLI" + ) +``` + + +## Installation + +Install from GitHub: + +```R +# Install the dev version using `pak` or `remotes` +pak::pkg_install("cmu-delphi/epidatr") +remotes::install_github("cmu-delphi/epidatr") +``` + +CRAN version coming soon. + +### API Keys + +The Delphi API requires a (free) API key for full functionality. To generate +your key, register for a pseudo-anonymous account +[here](https://api.delphi.cmu.edu/epidata/admin/registration_form) and see more +discussion on the [general API +website](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html). The +`epidatr` client will automatically look for this key in the R option +`delphi.epidata.key` or in the environment variable +`DELPHI_EPIDATA_KEY`. We recommend storing your key in `.Renviron` file, which R +will read by default. + +Note that for the time being, the private endpoints (i.e. those prefixed with +`pvt`) will require a separate key that needs to be passed as an argument. + +[mit-image]: https://img.shields.io/badge/License-MIT-yellow.svg +[mit-url]: https://opensource.org/license/mit/ +[github-actions-image]: https://github.com/cmu-delphi/epidatr/workflows/ci/badge.svg +[github-actions-url]: https://github.com/cmu-delphi/epidatr/actions + +## Get updates + +You should consider subscribing to the [API mailing list](https://lists.andrew.cmu.edu/mailman/listinfo/delphi-covidcast-api) to be notified of package updates, new data sources, corrections, and other updates. + +## For users of the `covidcast` R package + +The `epidatr` package is a complete rewrite of the [`covidcast` package](https://cmu-delphi.github.io/covidcast/covidcastR/), with a focus on speed, reliability, and ease of use. The `covidcast` package is deprecated and will no longer be updated. diff --git a/README.md b/README.md index 643ec3f0..b3423f1f 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,47 @@ -# Delphi Epidata R client -[![License: MIT][mit-image]][mit-url] [![Github Actions][github-actions-image]][github-actions-url] -[![codecov](https://codecov.io/gh/dsweber2/epidatr/branch/dev/graph/badge.svg?token=jVHL9eHZNZ)](https://app.codecov.io/gh/dsweber2/epidatr) + -The [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/) provides real-time access to epidemiological surveillance data for influenza, COVID-19, and other diseases for the USA at various geographical resolutions, both from official government sources such as the [Center for Disease Control (CDC)](https://www.cdc.gov/datastatistics/index.html) and [Google Trends](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/google-symptoms.html) and private partners such as [Facebook](https://delphi.cmu.edu/blog/2020/08/26/covid-19-symptom-surveys-through-facebook/) and [Change Healthcare](https://www.changehealthcare.com/). It is built and maintained by the Carnegie Mellon University [Delphi research group](https://delphi.cmu.edu/). +# Delphi Epidata R client -This package is designed to streamline the downloading and usage of data from the [Delphi Epidata -API](https://cmu-delphi.github.io/delphi-epidata/). It provides a simple R interface to the API, including functions for downloading data, parsing the results, and converting the data into a tidy format. The API stores a historical record of all data, including corrections and updates, which is particularly useful for accurately backtesting forecasting models. We also provide packages for downstream data processing ([epiprocess](https://github.com/cmu-delphi/epiprocess)) and modeling ([epipredict](https://github.com/cmu-delphi/epipredict)). + + +[![License: +MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit/) +[![Github +Actions](https://github.com/cmu-delphi/epidatr/workflows/ci/badge.svg)](https://github.com/cmu-delphi/epidatr/actions) +[![codecov](https://codecov.io/gh/dsweber2/epidatr/branch/dev/graph/badge.svg?token=jVHL9eHZNZ)](https://app.codecov.io/gh/dsweber2/epidatr) + + +The [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/) +provides real-time access to epidemiological surveillance data for +influenza, COVID-19, and other diseases for the USA at various +geographical resolutions, both from official government sources such as +the [Center for Disease Control +(CDC)](https://www.cdc.gov/datastatistics/index.html), public sources such as [Google +Trends](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/google-symptoms.html), +and private partners such as +[Facebook](https://delphi.cmu.edu/blog/2020/08/26/covid-19-symptom-surveys-through-facebook/) +and [Change Healthcare](https://www.changehealthcare.com/). It is built +and maintained by the Carnegie Mellon University [Delphi research +group](https://delphi.cmu.edu/). + +This package is designed to streamline the downloading and usage of data +from the [Delphi Epidata +API](https://cmu-delphi.github.io/delphi-epidata/). It provides a simple +R interface to the API, including functions for downloading data, +parsing the results, and converting the data into a tidy format. The API +stores a historical record of all data, including corrections and +updates, which is particularly useful for accurately backtesting +forecasting models. We also provide packages for downstream data +processing ([epiprocess](https://github.com/cmu-delphi/epiprocess)) and +modeling ([epipredict](https://github.com/cmu-delphi/epipredict)). ## Usage -```R +``` r library(epidatr) -# Obtain the smoothed covid-like illness (CLI) signal from the Facebook survey as it was on April 10, 2021 for the US +# Obtain the smoothed covid-like illness (CLI) signal from the +# Facebook survey as it was on April 10, 2021 for the US epidata <- pub_covidcast( source = "fb-survey", signals = "smoothed_cli", @@ -23,42 +52,44 @@ epidata <- pub_covidcast( as_of = "2021-06-01" ) epidata +#> # A tibble: 151 × 15 +#> geo_value signal source geo_type time_type time_value direction issue +#> +#> 1 us smoothed… fb-su… nation day 2021-01-01 NA 2021-01-06 +#> 2 us smoothed… fb-su… nation day 2021-01-02 NA 2021-01-07 +#> 3 us smoothed… fb-su… nation day 2021-01-03 NA 2021-01-08 +#> 4 us smoothed… fb-su… nation day 2021-01-04 NA 2021-01-09 +#> 5 us smoothed… fb-su… nation day 2021-01-05 NA 2021-01-10 +#> 6 us smoothed… fb-su… nation day 2021-01-06 NA 2021-01-29 +#> 7 us smoothed… fb-su… nation day 2021-01-07 NA 2021-01-29 +#> 8 us smoothed… fb-su… nation day 2021-01-08 NA 2021-01-29 +#> 9 us smoothed… fb-su… nation day 2021-01-09 NA 2021-01-29 +#> 10 us smoothed… fb-su… nation day 2021-01-10 NA 2021-01-29 +#> # ℹ 141 more rows +#> # ℹ 7 more variables: lag , missing_value , missing_stderr , +#> # missing_sample_size , value , stderr , sample_size ``` -``` -# A tibble: 6 × 15 - geo_value signal source geo_type time_type time_value - -1 us smoothed_cli fb-surv… nation day 2021-04-05 -2 us smoothed_cli fb-surv… nation day 2021-04-06 -3 us smoothed_cli fb-surv… nation day 2021-04-07 -4 us smoothed_cli fb-surv… nation day 2021-04-08 -5 us smoothed_cli fb-surv… nation day 2021-04-09 -6 us smoothed_cli fb-surv… nation day 2021-04-10 -# ℹ 9 more variables: direction , issue , -# lag , missing_value , missing_stderr , -# missing_sample_size , value , stderr , -# sample_size -``` - -```r +``` r # Plot this data library(ggplot2) ggplot(epidata, aes(x = time_value, y = value)) + geom_line() + - labs(title = "Smoothed CLI from Facebook Survey", - subtitle = "US, 2021", - x = "Date", - y = "CLI") + labs( + title = "Smoothed CLI from Facebook Survey", + subtitle = "US, 2021", + x = "Date", + y = "CLI" + ) ``` -![Smoothed CLI from Facebook Survey](man/figures/fb-cli-signal.png) + ## Installation Install from GitHub: -```R +``` r # Install the dev version using `pak` or `remotes` pak::pkg_install("cmu-delphi/epidatr") remotes::install_github("cmu-delphi/epidatr") @@ -68,28 +99,30 @@ CRAN version coming soon. ### API Keys -The Delphi API requires a (free) API key for full functionality. To generate -your key, register for a pseudo-anonymous account -[here](https://api.delphi.cmu.edu/epidata/admin/registration_form) and see more -discussion on the [general API -website](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html). The -`epidatr` client will automatically look for this key in the R option -`delphi.epidata.key` or in the environment variable -`DELPHI_EPIDATA_KEY`. We recommend storing your key in `.Renviron` file, which R -will read by default. - -Note that for the time being, the private endpoints (i.e. those prefixed with -`pvt`) will require a separate key that needs to be passed as an argument. +The Delphi API requires a (free) API key for full functionality. To +generate your key, register for a pseudo-anonymous account +[here](https://api.delphi.cmu.edu/epidata/admin/registration_form) and +see more discussion on the [general API +website](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html). +The `epidatr` client will automatically look for this key in the R +option `delphi.epidata.key` or in the environment variable +`DELPHI_EPIDATA_KEY`. We recommend storing your key in `.Renviron` file, +which R will read by default. -[mit-image]: https://img.shields.io/badge/License-MIT-yellow.svg -[mit-url]: https://opensource.org/license/mit/ -[github-actions-image]: https://github.com/cmu-delphi/epidatr/workflows/ci/badge.svg -[github-actions-url]: https://github.com/cmu-delphi/epidatr/actions +Note that for the time being, the private endpoints (i.e. those prefixed +with `pvt`) will require a separate key that needs to be passed as an +argument. ## Get updates -You should consider subscribing to the [API mailing list](https://lists.andrew.cmu.edu/mailman/listinfo/delphi-covidcast-api) to be notified of package updates, new data sources, corrections, and other updates. +You should consider subscribing to the [API mailing +list](https://lists.andrew.cmu.edu/mailman/listinfo/delphi-covidcast-api) +to be notified of package updates, new data sources, corrections, and +other updates. ## For users of the `covidcast` R package -The `epidatr` package is a complete rewrite of the [`covidcast` package](https://cmu-delphi.github.io/covidcast/covidcastR/), with a focus on speed, reliability, and ease of use. The `covidcast` package is deprecated and will no longer be updated. +The `epidatr` package is a complete rewrite of the [`covidcast` +package](https://cmu-delphi.github.io/covidcast/covidcastR/), with a +focus on speed, reliability, and ease of use. The `covidcast` package is +deprecated and will no longer be updated. diff --git a/_pkgdown.yml b/_pkgdown.yml index 7b5c1c3b..26cf0d2b 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -1,3 +1,17 @@ +template: + bootstrap: 5 + bootswatch: cosmo + bslib: + font_scale: 1.0 + primary: '#C41230' + link-color: '#C41230' + navbar-bg: '#C41230' + navbar-fg: '#f8f8f8' + +navbar: + bg: '#C41230' + fg: '#f8f8f8' + home: links: - text: Get the Python client @@ -5,6 +19,18 @@ home: - text: View the Delphi Website href: https://delphi.cmu.edu/ + + - text: Introduction to Delphi's Tooling Work + href: https://cmu-delphi.github.io/delphi-tooling-book/ + + - text: The epiprocess R package + href: https://cmu-delphi.github.io/epiprocess/ + + - text: The epipredict R package + href: https://cmu-delphi.github.io/epipredict/ + + - text: The epidatasets R package + href: https://cmu-delphi.github.io/epidatasets/ reference: - title: Configuration and utilities diff --git a/cran-comments.md b/cran-comments.md index e69de29b..a615e834 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -0,0 +1,4 @@ +- Calls in the following files call an API which if queried too frequently without a key would result in CRAN being temporarily locked out of running API calls (so a soft-API key problem) + - [`epidatr/R/epidatacall.R`] + - [`epidatr/R/request.R`] + - [`epidatr/R/endpoints.R`] diff --git a/inst/CITATION b/inst/CITATION new file mode 100644 index 00000000..e7e9c3c6 --- /dev/null +++ b/inst/CITATION @@ -0,0 +1,7 @@ +bibentry( + "Misc", + title = "Delphi Epidata API", + author = "David C. Farrow, Logan C. Brooks, Aaron Rumack, Ryan J. Tibshirani, Roni Rosenfeld", + year = 2015, + url = "https://github.com/cmu-delphi/delphi-epidata" +) diff --git a/man/cache_epidata_call.Rd b/man/cache_epidata_call.Rd index d53bd55c..5d3c3f8b 100644 --- a/man/cache_epidata_call.Rd +++ b/man/cache_epidata_call.Rd @@ -7,9 +7,9 @@ cache_epidata_call(epidata_call, fetch_args = fetch_args_list()) } \arguments{ -\item{fetch_args}{the args list for fetch as generated by \code{\link[=fetch_args_list]{fetch_args_list()}}} +\item{epidata_call}{the \code{epidata_call} object} -\item{call}{the \code{epidata_call} object} +\item{fetch_args}{the args list for fetch as generated by \code{\link[=fetch_args_list]{fetch_args_list()}}} } \description{ The guts of caching, its interposed between fetch and the specific fetch diff --git a/man/cache_info.Rd b/man/cache_info.Rd index 2d8f05de..36e62efc 100644 --- a/man/cache_info.Rd +++ b/man/cache_info.Rd @@ -6,6 +6,9 @@ \usage{ cache_info() } +\value{ +\code{\link{list}} containing the info result as created by cachem +} \description{ Print out the information about the cache (as would be returned by cachem's \code{info()} method). diff --git a/man/clear_cache.Rd b/man/clear_cache.Rd index 1aa5ba9b..c377c612 100644 --- a/man/clear_cache.Rd +++ b/man/clear_cache.Rd @@ -30,22 +30,16 @@ variable is \code{EPIDATR_CACHE_LOGFILE}.} should only be set in non-interactive scripts} }} } +\value{ +\code{\link{NULL}} no return value, all effects are stored in the package +environment +} \description{ Deletes the current cache and resets a new cache. Deletes local data! If you are using a session unique cache, you will have to pass the arguments you used for \code{set_cache} earlier, otherwise the system-wide \code{.Renviron}-based defaults will be used. } -\examples{ -\dontrun{ -clear_cache( - dir = "some/subdir", - days = 14, - max_size = 512, - logfile = "some/subdir/logs.txt", -) -} -} \seealso{ \code{\link{set_cache}} to start a new cache (and general caching info), \code{\link{disable_cache}} to only disable without deleting, and \code{\link{cache_info}} diff --git a/man/disable_cache.Rd b/man/disable_cache.Rd index 580c30dd..63eacc48 100644 --- a/man/disable_cache.Rd +++ b/man/disable_cache.Rd @@ -6,6 +6,10 @@ \usage{ disable_cache() } +\value{ +\code{\link{NULL}} no return value, all effects are stored in the package +environment +} \description{ Disable caching until you call \code{set_cache} or restart R. The files defining the cache are untouched. If you are looking to disable the caching more diff --git a/man/epidatr-package.Rd b/man/epidatr-package.Rd index 72c3e789..b2e49714 100644 --- a/man/epidatr-package.Rd +++ b/man/epidatr-package.Rd @@ -6,12 +6,13 @@ \alias{epidatr-package} \title{epidatr: Client for Delphi's 'Epidata' API} \description{ -The Delphi 'Epidata' API provides real-time access to epidemiological surveillance data for influenza, COVID-19, and other diseases for the USA at various geographical resolutions, both from official government sources such as the Center for Disease Control (CDC) and Google Trends and private partners such as Facebook and Change Healthcare. It is built and maintained by the Carnegie Mellon University Delphi research group. +The Delphi 'Epidata' API provides real-time access to epidemiological surveillance data for influenza, 'COVID-19', and other diseases for the USA at various geographical resolutions, both from official government sources such as the Center for Disease Control (CDC) and Google Trends and private partners such as Facebook and Change 'Healthcare'. It is built and maintained by the Carnegie Mellon University Delphi research group. To cite this API: David C. Farrow, Logan C. Brooks, Aaron 'Rumack', Ryan J. 'Tibshirani', 'Roni' 'Rosenfeld' (2015). Delphi 'Epidata' API. \url{https://github.com/cmu-delphi/delphi-epidata}. } \seealso{ Useful links: \itemize{ \item \url{https://cmu-delphi.github.io/epidatr/} + \item \url{https://cmu-delphi.github.io/delphi-epidata/} \item \url{https://github.com/cmu-delphi/epidatr} \item Report bugs at \url{https://github.com/cmu-delphi/epidatr/issues} } diff --git a/man/figures/README-fb-cli-signal-1.png b/man/figures/README-fb-cli-signal-1.png new file mode 100644 index 00000000..5a76514d Binary files /dev/null and b/man/figures/README-fb-cli-signal-1.png differ diff --git a/man/parse_signal.Rd b/man/parse_signal.Rd index 31a51a14..0d8ce67e 100644 --- a/man/parse_signal.Rd +++ b/man/parse_signal.Rd @@ -2,33 +2,37 @@ % Please edit documentation in R/covidcast.R \name{parse_signal} \alias{parse_signal} -\title{fetch covidcast data} +\title{turn a signal into a callable} \usage{ parse_signal(signal, base_url) } \arguments{ -\item{data_source}{data source to fetch} +\item{signal}{the signal of interest} -\item{signals}{data source to fetch} - -\item{geo_type}{geo_type to fetch} - -\item{time_type}{data source to fetch} - -\item{geo_values}{data source to fetch} - -\item{time_values}{data source to fetch} - -\item{as_of}{data source to fetch} - -\item{issues}{data source to fetch} - -\item{lag}{data source to fetch} -} -\value{ -an instance of epidata_call +\item{base_url}{the base url} } \description{ -fetch covidcast data +turn a signal into a callable } +\keyword{an} +\keyword{as_of} +\keyword{covidcast} +\keyword{data} +\keyword{data_source} +\keyword{epidata_call} +\keyword{fetch} +\keyword{geo_type} +\keyword{geo_values} +\keyword{instance} \keyword{internal} +\keyword{issues} +\keyword{keywords} +\keyword{lag} +\keyword{of} +\keyword{param} +\keyword{return} +\keyword{signals} +\keyword{source} +\keyword{time_type} +\keyword{time_values} +\keyword{to} diff --git a/man/pipe.Rd b/man/pipe.Rd deleted file mode 100644 index a648c296..00000000 --- a/man/pipe.Rd +++ /dev/null @@ -1,20 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils-pipe.R -\name{\%>\%} -\alias{\%>\%} -\title{Pipe operator} -\usage{ -lhs \%>\% rhs -} -\arguments{ -\item{lhs}{A value or the magrittr placeholder.} - -\item{rhs}{A function call using the magrittr semantics.} -} -\value{ -The result of calling \code{rhs(lhs)}. -} -\description{ -See \code{magrittr::\link[magrittr:pipe]{\%>\%}} for details. -} -\keyword{internal} diff --git a/man/pub_covidcast.Rd b/man/pub_covidcast.Rd index 87013fc3..c530bc03 100644 --- a/man/pub_covidcast.Rd +++ b/man/pub_covidcast.Rd @@ -70,7 +70,7 @@ pub_covidcast( signals = "confirmed_7dav_incidence_prop", geo_type = "state", time_type = "day", - geo_values = "ca,fl", + geo_values = c("ca", "fl"), time_values = epirange(20200601, 20200801) ) pub_covidcast( diff --git a/man/pub_fluview.Rd b/man/pub_fluview.Rd index c79cc42b..6dd15c31 100644 --- a/man/pub_fluview.Rd +++ b/man/pub_fluview.Rd @@ -49,10 +49,12 @@ more information on ILINet, see \url{https://gis.cdc.gov/grasp/fluview/fluportaldashboard.html}. } \details{ -The full list of location inputs can be accsssed at +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{ -pub_fluview(regions = "nat", epiweeks = epirange(201201, 202001)) +\dontrun{ +pub_fluview(regions = "nat", epiweeks = epirange(201201, 202005)) +} } \keyword{endpoint} diff --git a/man/pub_nowcast.Rd b/man/pub_nowcast.Rd index 4bf9484d..508d4fc1 100644 --- a/man/pub_nowcast.Rd +++ b/man/pub_nowcast.Rd @@ -22,7 +22,7 @@ API docs: \url{https://cmu-delphi.github.io/delphi-epidata/api/nowcast.html}. Obtains information on outpatient inluenza-like-illness (ILI) from Delphi's } \details{ -The full list of location inputs can be accsssed at +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{ diff --git a/man/set_cache.Rd b/man/set_cache.Rd index 56eb77f3..87c147f0 100644 --- a/man/set_cache.Rd +++ b/man/set_cache.Rd @@ -33,6 +33,10 @@ variable is \code{EPIDATR_CACHE_LOGFILE}.} \item{confirm}{whether to confirm directory creation. default is \code{TRUE}; should only be set in non-interactive scripts} } +\value{ +\code{\link{NULL}} no return value, all effects are stored in the package +environment +} \description{ By default, epidatr re-requests data from the API on every call of \code{fetch}. In case you find yourself repeatedly calling the same data, you can enable @@ -97,14 +101,12 @@ encoding of the call url. Each file corresponds to a unique epidata-API call. } \examples{ -\dontrun{ set_cache( - dir = "some/subdir", + cache_dir = tempdir(), days = 14, max_size = 512, - logfile = "some/subdir/logs.txt" + logfile = "logs.txt" ) -} } \seealso{