diff --git a/.Rbuildignore b/.Rbuildignore index 3f2fc89b..5da1eff9 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -20,4 +20,5 @@ ^.venv$ ^env$ ^.env$ +^README\.Rmd$ ^CRAN-SUBMISSION$ 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/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