Skip to content

Commit b9f064a

Browse files
dshemetovdshemetov
committed
doc: update README with epidatr blog post revisions
1 parent d04e4af commit b9f064a

File tree

2 files changed

+164
-52
lines changed

2 files changed

+164
-52
lines changed

‎README.Rmd‎

Lines changed: 72 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,19 +21,82 @@ ggplot2::theme_set(ggplot2::theme_bw())
2121
[![codecov](https://codecov.io/gh/dsweber2/epidatr/branch/dev/graph/badge.svg?token=jVHL9eHZNZ)](https://app.codecov.io/gh/dsweber2/epidatr)
2222
<!-- badges: end -->
2323

24-
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/).
25-
26-
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.
27-
28-
`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.
24+
The [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/) provides
25+
real-time access to epidemiological surveillance data for influenza, COVID-19,
26+
and other diseases from both official government sources such as the [Centers
27+
for Disease Control and Prevention
28+
(CDC)](https://www.cdc.gov/datastatistics/index.html), private partners such as
29+
[Facebook (now
30+
Meta)](https://delphi.cmu.edu/blog/2020/08/26/covid-19-symptom-surveys-through-facebook/)
31+
and [Change Healthcare](https://www.changehealthcare.com/), and other public
32+
datasets like [Google
33+
Trends](https://console.cloud.google.com/marketplace/product/bigquery-public-datasets/covid19-search-trends).
34+
It is built and maintained by the Carnegie Mellon University [Delphi Research
35+
Group](https://delphi.cmu.edu/).
36+
37+
This package is designed to streamline the downloading and usage of data from
38+
the Delphi Epidata API. It provides a simple R interface to the API, including
39+
functions for downloading data, parsing the results, and converting the data
40+
into a tidy format. The API stores a historical record of all data, including
41+
corrections and updates, which is particularly useful for accurately backtesting
42+
forecasting models. We also provide packages for downstream data processing
43+
([epiprocess](https://github.com/cmu-delphi/epiprocess)) and modeling
44+
([epipredict](https://github.com/cmu-delphi/epipredict)).
45+
46+
## Usage
47+
48+
```{r}
49+
library(epidatr)
50+
# Obtain the smoothed covid-like illness (CLI) signal from Delphi's US COVID-19
51+
# Trends and Impact Survey (CTIS), in partnership with Facebook, as it was on
52+
# April 10, 2021 for the US at the national level
53+
epidata <- pub_covidcast(
54+
source = "fb-survey",
55+
signals = "smoothed_cli",
56+
geo_type = "nation",
57+
time_type = "day",
58+
geo_values = "us",
59+
time_values = epirange(20210101, 20210601),
60+
as_of = 20210601
61+
)
62+
epidata
63+
```
2964

30-
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).
65+
## Installation
3166

32-
**To get started** using this package, view the Getting Started guide at `vignette("epidatr")`.
67+
Installing the package is straightforward.
3368

34-
## For users of the `covidcast` R package
69+
```R
70+
# Install the CRAN version
71+
pak::pkg_install("epidatr")
72+
# Install the development version from the GitHub dev branch
73+
pak::pkg_install("cmu-delphi/epidatr@dev")
74+
```
3575

36-
`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.
76+
### API Keys
77+
78+
The Delphi API requires a (free) API key for full functionality. To generate
79+
your key, register for a pseudo-anonymous account
80+
[here](https://api.delphi.cmu.edu/epidata/admin/registration_form) and see more
81+
discussion on the [general API
82+
website](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html). The
83+
`epidatr` client will automatically look for this key in the environment
84+
variable `DELPHI_EPIDATA_KEY`. We recommend storing your key in your `.Renviron`
85+
file, which R will read by default.
86+
87+
Note that for the time being, the private endpoints (i.e. those prefixed with
88+
`pvt`) will require a separate key that needs to be passed as an argument.
89+
90+
## For users of the covidcast R package
91+
92+
The `covidcast` package is deprecated and will no longer be updated. The
93+
`epidatr` package is a complete rewrite of the [`covidcast`
94+
package](https://cmu-delphi.github.io/covidcast/covidcastR/), with a focus on
95+
speed, reliability, and ease of use. It also supports more endpoints and data
96+
sources than `covidcast`. When migrating from that package, you will need to use
97+
the
98+
[`pub_covidcast`](https://cmu-delphi.github.io/epidatr/reference/pub_covidcast.html)
99+
function in `epidatr`.
37100

38101
## Get updates
39102

‎README.md‎

Lines changed: 92 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -12,51 +12,100 @@ Actions](https://github.com/cmu-delphi/epidatr/workflows/ci/badge.svg)](https://
1212
[![codecov](https://codecov.io/gh/dsweber2/epidatr/branch/dev/graph/badge.svg?token=jVHL9eHZNZ)](https://app.codecov.io/gh/dsweber2/epidatr)
1313
<!-- badges: end -->
1414

15-
The [Delphi `epidatr` package](https://cmu-delphi.github.io/epidatr/) is
16-
an R front-end for the [Delphi Epidata
17-
API](https://cmu-delphi.github.io/delphi-epidata/), which provides
18-
real-time access to epidemiological surveillance data for influenza,
19-
COVID-19, and other diseases. `epidatr` is built and maintained by the
20-
Carnegie Mellon University [Delphi research
21-
group](https://delphi.cmu.edu/).
22-
23-
Data is available for the United States and a handful of other countries
24-
at various geographical resolutions, both from official government
25-
sources such as the [US Center for Disease Control
26-
(CDC)](https://www.cdc.gov/datastatistics/index.html), and private
27-
partners such as
28-
[Facebook](https://delphi.cmu.edu/blog/2020/08/26/covid-19-symptom-surveys-through-facebook/)
29-
and [Change Healthcare](https://www.changehealthcare.com/). The API
30-
stores a historical record of all data, including corrections and
31-
updates, which is particularly useful for accurately backtesting
32-
forecasting models.
33-
34-
`epidatr` is designed to streamline the downloading and usage of data
35-
from the Epidata API. The package provides a simple R interface to the
15+
The [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/)
16+
provides real-time access to epidemiological surveillance data for
17+
influenza, COVID-19, and other diseases from both official government
18+
sources such as the [Centers for Disease Control and Prevention
19+
(CDC)](https://www.cdc.gov/datastatistics/index.html), private partners
20+
such as [Facebook (now
21+
Meta)](https://delphi.cmu.edu/blog/2020/08/26/covid-19-symptom-surveys-through-facebook/)
22+
and [Change Healthcare](https://www.changehealthcare.com/), and other
23+
public datasets like [Google
24+
Trends](https://console.cloud.google.com/marketplace/product/bigquery-public-datasets/covid19-search-trends).
25+
It is built and maintained by the Carnegie Mellon University [Delphi
26+
Research Group](https://delphi.cmu.edu/).
27+
28+
This package is designed to streamline the downloading and usage of data
29+
from the Delphi Epidata API. It provides a simple R interface to the
3630
API, including functions for downloading data, parsing the results, and
37-
converting the data into a tidy format. We also provide the
38-
[epiprocess](https://github.com/cmu-delphi/epiprocess) package for
39-
downstream data processing and
40-
[epipredict](https://github.com/cmu-delphi/epipredict) for modeling.
41-
42-
Consult the [Epidata API
43-
documentation](https://cmu-delphi.github.io/delphi-epidata/) for details
44-
on the data included in the API, API key registration, licensing, and
45-
how to cite this data in your work. The documentation lists all the data
46-
sources and signals available through this API for
47-
[COVID-19](https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html)
48-
and for [other
49-
diseases](https://cmu-delphi.github.io/delphi-epidata/api/README.html#source-specific-parameters).
50-
51-
**To get started** using this package, view the Getting Started guide at
52-
`vignette("epidatr")`.
53-
54-
## For users of the `covidcast` R package
55-
56-
`epidatr` is a complete rewrite of the [`covidcast`
31+
converting the data into a tidy format. The API stores a historical
32+
record of all data, including corrections and updates, which is
33+
particularly useful for accurately backtesting forecasting models. We
34+
also provide packages for downstream data processing
35+
([epiprocess](https://github.com/cmu-delphi/epiprocess)) and modeling
36+
([epipredict](https://github.com/cmu-delphi/epipredict)).
37+
38+
## Usage
39+
40+
``` r
41+
library(epidatr)
42+
# Obtain the smoothed covid-like illness (CLI) signal from Delphi's US COVID-19
43+
# Trends and Impact Survey (CTIS), in partnership with Facebook, as it was on
44+
# April 10, 2021 for the US at the national level
45+
epidata <- pub_covidcast(
46+
source = "fb-survey",
47+
signals = "smoothed_cli",
48+
geo_type = "nation",
49+
time_type = "day",
50+
geo_values = "us",
51+
time_values = epirange(20210101, 20210601),
52+
as_of = 20210601
53+
)
54+
epidata
55+
#> # A tibble: 151 × 15
56+
#> geo_value signal source geo_type time_type time_value direction issue
57+
#> <chr> <chr> <chr> <fct> <fct> <date> <dbl> <date>
58+
#> 1 us smoothed… fb-su… nation day 2021-01-01 NA 2021-01-06
59+
#> 2 us smoothed… fb-su… nation day 2021-01-02 NA 2021-01-07
60+
#> 3 us smoothed… fb-su… nation day 2021-01-03 NA 2021-01-08
61+
#> 4 us smoothed… fb-su… nation day 2021-01-04 NA 2021-01-09
62+
#> 5 us smoothed… fb-su… nation day 2021-01-05 NA 2021-01-10
63+
#> 6 us smoothed… fb-su… nation day 2021-01-06 NA 2021-01-29
64+
#> 7 us smoothed… fb-su… nation day 2021-01-07 NA 2021-01-29
65+
#> 8 us smoothed… fb-su… nation day 2021-01-08 NA 2021-01-29
66+
#> 9 us smoothed… fb-su… nation day 2021-01-09 NA 2021-01-29
67+
#> 10 us smoothed… fb-su… nation day 2021-01-10 NA 2021-01-29
68+
#> # ℹ 141 more rows
69+
#> # ℹ 7 more variables: lag <dbl>, missing_value <dbl>, missing_stderr <dbl>,
70+
#> # missing_sample_size <dbl>, value <dbl>, stderr <dbl>, sample_size <dbl>
71+
```
72+
73+
## Installation
74+
75+
Installing the package is straightforward.
76+
77+
``` r
78+
# Install the CRAN version
79+
pak::pkg_install("epidatr")
80+
# Install the development version from the GitHub dev branch
81+
pak::pkg_install("cmu-delphi/epidatr@dev")
82+
```
83+
84+
### API Keys
85+
86+
The Delphi API requires a (free) API key for full functionality. To
87+
generate your key, register for a pseudo-anonymous account
88+
[here](https://api.delphi.cmu.edu/epidata/admin/registration_form) and
89+
see more discussion on the [general API
90+
website](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html).
91+
The `epidatr` client will automatically look for this key in the
92+
environment variable `DELPHI_EPIDATA_KEY`. We recommend storing your key
93+
in your `.Renviron` file, which R will read by default.
94+
95+
Note that for the time being, the private endpoints (i.e. those prefixed
96+
with `pvt`) will require a separate key that needs to be passed as an
97+
argument.
98+
99+
## For users of the covidcast R package
100+
101+
The `covidcast` package is deprecated and will no longer be updated. The
102+
`epidatr` package is a complete rewrite of the [`covidcast`
57103
package](https://cmu-delphi.github.io/covidcast/covidcastR/), with a
58-
focus on speed, reliability, and ease of use. The `covidcast` package is
59-
deprecated and will no longer be updated.
104+
focus on speed, reliability, and ease of use. It also supports more
105+
endpoints and data sources than `covidcast`. When migrating from that
106+
package, you will need to use the
107+
[`pub_covidcast`](https://cmu-delphi.github.io/epidatr/reference/pub_covidcast.html)
108+
function in `epidatr`.
60109

61110
## Get updates
62111

0 commit comments

Comments
 (0)