Skip to content

Redo landing page and intro doc #230

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 19 commits into from
Dec 11, 2023
Merged

Redo landing page and intro doc #230

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
e6bcee6
remove usage from landing page; add licensing info and more description
nmdefries Dec 8, 2023
637f6f4
move mailing list ad down
nmdefries Dec 8, 2023
3ba3836
move install, api keys to intro vignette; add more examples, take out…
nmdefries Dec 8, 2023
6a8a224
signal discovery blurb and vignette stub
nmdefries Dec 8, 2023
a8b81bb
versioned data blurb and vignette stub
nmdefries Dec 8, 2023
f857d67
add geo info and format avail_endpoint
nmdefries Dec 8, 2023
cf2ed73
list international endpoints
nmdefries Dec 8, 2023
86502a3
rename and reflow text
nmdefries Dec 8, 2023
ade3ea2
flesh out signal discovery vignette
nmdefries Dec 8, 2023
06adbcd
clean up versioned data wording
nmdefries Dec 8, 2023
3872109
pretty print tibbles in signal discovery vignette
nmdefries Dec 8, 2023
06aed90
metadata blurb for signal discovery
nmdefries Dec 8, 2023
12a6e63
silence us-only message
nmdefries Dec 8, 2023
cab8cae
versioned data header
nmdefries Dec 8, 2023
b6b0a6f
choropleth link and example
nmdefries Dec 11, 2023
53d8201
add content to versioned data vignette
nmdefries Dec 11, 2023
7b6b9bd
style: styler (GHA)
nmdefries Dec 11, 2023
433b748
suggest `maps` for vignettes
nmdefries Dec 11, 2023
04c57b7
add example showing use of list of dates with `issues`
nmdefries Dec 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions DESCRIPTION
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,8 @@ Suggests:
dplyr,
ggplot2,
knitr,
maps,
mapproj,
rmarkdown,
rlang,
testthat (>= 3.1.5),
Expand Down
84 changes: 16 additions & 68 deletions README.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,86 +21,34 @@ ggplot2::theme_set(ggplot2::theme_bw())
[![codecov](https://codecov.io/gh/dsweber2/epidatr/branch/dev/graph/badge.svg?token=jVHL9eHZNZ)](https://app.codecov.io/gh/dsweber2/epidatr)
<!-- badges: end -->

The [Delphi Epidatr package](https://cmu-delphi.github.io/epidatr/) is an R front-end for the [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/), which 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

You can find detailed docs here:

```{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
```
The [Delphi `epidatr` package](https://cmu-delphi.github.io/epidatr/) is an R front-end for the [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/), which provides real-time access to epidemiological surveillance data for influenza, COVID-19, and other diseases. `epidatr` is built and maintained by the Carnegie Mellon University [Delphi research group](https://delphi.cmu.edu/).

```{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"
)
```
Data is available for the United States and a handful of other countries at various geographical resolutions, both from official government sources such as the [US Center for Disease Control (CDC)](https://www.cdc.gov/datastatistics/index.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/). The API stores a historical record of all data, including corrections and updates, which is particularly useful for accurately backtesting forecasting models.

`epidatr` is designed to streamline the downloading and usage of data from the Epidata API. The package provides a simple R interface to the API, including functions for downloading data, parsing the results, and converting the data into a tidy format. We also provide the [epiprocess](https://github.com/cmu-delphi/epiprocess) package for downstream data processing and [epipredict](https://github.com/cmu-delphi/epipredict) for modeling.

## Installation
Consult the [Epidata API documentation](https://cmu-delphi.github.io/delphi-epidata/) for details on the data included in the API, API key registration, licensing, and how to cite this data in your work. The documentation lists all the data sources and signals available through this API for [COVID-19](https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html) and for [other diseases](https://cmu-delphi.github.io/delphi-epidata/api/README.html#source-specific-parameters).

You can install the stable version of this package from CRAN:
**To get started** using this package, view the Getting Started guide at `vignette("epidatr")`.

```R
install.packages("epidatr")
pak::pkg_install("epidatr")
renv::install("epidatr")
```
## For users of the `covidcast` R package

Or if you want the development version, install from GitHub:
`epidatr` 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.

```R
# Install the dev version using `pak` or `remotes`
pak::pkg_install("cmu-delphi/epidatr")
remotes::install_github("cmu-delphi/epidatr")
renv::install("cmu-delphi/epidatr")
```
## 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.

### API Keys
## Usage terms and citation

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). See the
`save_api_key()` function documentation for details on how to use your API key.
We request that if you use the `epidatr` package in your work, or use any of the data provided by the Delphi Epidata API through non-`covidcast` endpoints, that you cite us using the citation given by [`citation("epidatr")`](https://cmu-delphi.github.io/epidatr/dev/authors.html#citation). If you use any of the data from the `covidcast` endpoint, please use the [COVIDcast citation](https://cmu-delphi.github.io/covidcast/covidcastR/authors.html#citation) as well. See the [COVIDcast licensing documentation](https://cmu-delphi.github.io/delphi-epidata/api/covidcast_licensing.html) and the [licensing documentation for other endpoints](https://cmu-delphi.github.io/delphi-epidata/api/README.html#data-licensing) for information about citing the datasets provided by the API.

**Warning:** If you use data from the Epidata API to power a product, dashboard, app, or other service, please download the data you need and store it centrally rather than making API requests for every user. Our server resources are limited and cannot support high-volume interactive use.

See also the [Terms of Use](https://delphi.cmu.edu/covidcast/terms-of-use/), noting that the data is a research product and not warranted for a particular purpose.

Note that the private endpoints (i.e. those prefixed with `pvt_`) require a
separate key that needs to be passed as an argument. These endpoints require
specific data use agreements to access.

[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.
174 changes: 64 additions & 110 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,126 +12,80 @@ Actions](https://github.com/cmu-delphi/epidatr/workflows/ci/badge.svg)](https://
[![codecov](https://codecov.io/gh/dsweber2/epidatr/branch/dev/graph/badge.svg?token=jVHL9eHZNZ)](https://app.codecov.io/gh/dsweber2/epidatr)
<!-- badges: end -->

The [Delphi Epidatr package](https://cmu-delphi.github.io/epidatr/) is
The [Delphi `epidatr` package](https://cmu-delphi.github.io/epidatr/) is
an R front-end for the [Delphi Epidata
API](https://cmu-delphi.github.io/delphi-epidata/), which 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
COVID-19, and other diseases. `epidatr` 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
Data is available for the United States and a handful of other countries
at various geographical resolutions, both from official government
sources such as the [US Center for Disease Control
(CDC)](https://www.cdc.gov/datastatistics/index.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/). 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

You can find detailed docs here:

``` 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
#> # A tibble: 151 × 15
#> geo_value signal source geo_type time_type time_value direction issue
#> <chr> <chr> <chr> <fct> <fct> <date> <dbl> <date>
#> 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 <int>, missing_value <int>, missing_stderr <int>,
#> # missing_sample_size <int>, value <dbl>, stderr <dbl>, sample_size <dbl>
```

``` 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"
)
```

<img src="man/figures/README-fb-cli-signal-1.png" width="100%" />

## Installation

You can install the stable version of this package from CRAN:

``` r
install.packages("epidatr")
pak::pkg_install("epidatr")
renv::install("epidatr")
```

Or if you want the development version, install from GitHub:

``` r
# Install the dev version using `pak` or `remotes`
pak::pkg_install("cmu-delphi/epidatr")
remotes::install_github("cmu-delphi/epidatr")
renv::install("cmu-delphi/epidatr")
```

### 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).
See the `save_api_key()` function documentation for details on how to
use your API key.

Note that the private endpoints (i.e. those prefixed with `pvt_`)
require a separate key that needs to be passed as an argument. These
endpoints require specific data use agreements to access.

## 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.
forecasting models.

`epidatr` is designed to streamline the downloading and usage of data
from the Epidata API. The package provides a simple R interface to the
API, including functions for downloading data, parsing the results, and
converting the data into a tidy format. We also provide the
[epiprocess](https://github.com/cmu-delphi/epiprocess) package for
downstream data processing and
[epipredict](https://github.com/cmu-delphi/epipredict) for modeling.

Consult the [Epidata API
documentation](https://cmu-delphi.github.io/delphi-epidata/) for details
on the data included in the API, API key registration, licensing, and
how to cite this data in your work. The documentation lists all the data
sources and signals available through this API for
[COVID-19](https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html)
and for [other
diseases](https://cmu-delphi.github.io/delphi-epidata/api/README.html#source-specific-parameters).

**To get started** using this package, view the Getting Started guide at
`vignette("epidatr")`.

## For users of the `covidcast` R package

The `epidatr` package is a complete rewrite of the [`covidcast`
`epidatr` 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.

## 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.

## Usage terms and citation

We request that if you use the `epidatr` package in your work, or use
any of the data provided by the Delphi Epidata API through
non-`covidcast` endpoints, that you cite us using the citation given by
[`citation("epidatr")`](https://cmu-delphi.github.io/epidatr/dev/authors.html#citation).
If you use any of the data from the `covidcast` endpoint, please use the
[COVIDcast
citation](https://cmu-delphi.github.io/covidcast/covidcastR/authors.html#citation)
as well. See the [COVIDcast licensing
documentation](https://cmu-delphi.github.io/delphi-epidata/api/covidcast_licensing.html)
and the [licensing documentation for other
endpoints](https://cmu-delphi.github.io/delphi-epidata/api/README.html#data-licensing)
for information about citing the datasets provided by the API.

**Warning:** If you use data from the Epidata API to power a product,
dashboard, app, or other service, please download the data you need and
store it centrally rather than making API requests for every user. Our
server resources are limited and cannot support high-volume interactive
use.

See also the [Terms of
Use](https://delphi.cmu.edu/covidcast/terms-of-use/), noting that the
data is a research product and not warranted for a particular purpose.
Loading