-
Notifications
You must be signed in to change notification settings - Fork 5
/
signal-discovery.Rmd
386 lines (269 loc) · 10.1 KB
/
signal-discovery.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
---
title: "Finding data sources and signals of interest"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Finding data sources and signals of interest}
%\VignetteEngine{knitr::rmarkdown}
\usepackage[utf8]{inputenc}
---
```{r, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
options(tibble.print_min = 4L, tibble.print_max = 4L, max.print = 4L)
library(epidatr)
library(dplyr)
```
The Epidata API includes numerous data streams -- medical claims data, cases and deaths, mobility, and many others -- covering different geographic regions. This can make it a challenge to find the data stream that you are most interested in.
Example queries with all the endpoint functions available in this package are
given [below](#example-queries).
## Using the documentation
The Epidata documentation lists all the data sources and signals available
through the 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).
The site also includes a search tool if you have a keyword (e.g. "Taiwan") in mind.
## Signal metadata
Some endpoints have partner metadata available that provides information about
the signals that are available, for example, what time ranges they are
available for, and when they have been updated.
```{r, echo = FALSE}
suppressMessages(invisible(capture.output(endpts <- avail_endpoints())))
filter(endpts, endsWith(Endpoint, "_meta()")) %>% knitr::kable()
```
## Interactive tooling
We provide a couple `epidatr` functions to help find data sources and signals.
The `avail_endpoints()` function lists endpoints, each of which, except for
COVIDcast, corresponds to a single data source. `avail_endpoints()` outputs a
`tibble` of endpoints and brief descriptions, which explicitly state when they
cover non-US locations:
```{r, eval = FALSE}
avail_endpoints()
```
```{r, echo = FALSE}
suppressMessages(invisible(capture.output(endpts <- avail_endpoints())))
knitr::kable(endpts)
```
The `covidcast_epidata()` function lets you look more in-depth at the data
sources available through the COVIDcast endpoint. The function describes
all available data sources and signals:
```{r}
covid_sources <- covidcast_epidata()
head(covid_sources$sources, n = 2)
```
Each source is included as an entry in the `covid_sources$sources` list, associated
with a `tibble` describing included signals.
If you use an editor that supports tab completion, such as RStudio, type
`covid_sources$source$` and wait for the tab completion popup. You will be able to
browse the list of data sources.
```{r}
covid_sources$signals
```
If you use an editor that supports tab completion, type
`covid_sources$signals$` and wait for the tab completion popup. You will be
able to type the name of signals and have the autocomplete feature select
them from the list for you. In the tab-completion popup, signal names are
prefixed with the name of the data source for filtering convenience.
_Note_ that some signal names have dashes in them, so to access them
we rely on the backtick operator:
```{r}
covid_sources$signals$`fb-survey:smoothed_cli`
```
These signal objects can be used directly to fetch data, without requiring us to use
the `pub_covidcast()` function. Simply use the `$call` attribute of the object:
```{r}
epidata <- covid_sources$signals$`fb-survey:smoothed_cli`$call(
"state", "pa", epirange(20210405, 20210410)
)
knitr::kable(epidata)
```
## Example Queries
### COVIDcast Main Endpoint
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html>
County geo_values are [FIPS codes](https://en.wikipedia.org/wiki/List_of_United_States_FIPS_codes_by_county) and are discussed in the API docs [here](https://cmu-delphi.github.io/delphi-epidata/api/covidcast_geography.html). The example below is for Orange County, California.
```{r}
pub_covidcast(
source = "fb-survey",
signals = "smoothed_accept_covid_vaccine",
geo_type = "county",
time_type = "day",
time_values = epirange(20201221, 20201225),
geo_values = "06059"
)
```
The `covidcast` endpoint supports `*` in its time and geo fields:
```{r}
pub_covidcast(
source = "fb-survey",
signals = "smoothed_accept_covid_vaccine",
geo_type = "county",
time_type = "day",
time_values = epirange(20201221, 20201225),
geo_values = "*"
)
```
### Other Covid Endpoints
#### COVID-19 Hospitalization: Facility Lookup
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/covid_hosp_facility_lookup.html>
```{r, eval = FALSE}
pub_covid_hosp_facility_lookup(city = "southlake")
pub_covid_hosp_facility_lookup(state = "WY")
# A non-example (there is no city called New York in Wyoming)
pub_covid_hosp_facility_lookup(state = "WY", city = "New York")
```
#### COVID-19 Hospitalization by Facility
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/covid_hosp_facility.html>
```{r, eval = FALSE}
pub_covid_hosp_facility(
hospital_pks = "100075",
collection_weeks = epirange(20200101, 20200501)
)
```
#### COVID-19 Hospitalization by State
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/covid_hosp.html>
```{r, eval = FALSE}
pub_covid_hosp_state_timeseries(states = "MA", dates = "20200510")
```
### Flu Endpoints
#### Delphi's ILINet forecasts
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/delphi.html>
```{r, eval = FALSE}
del <- pub_delphi(system = "ec", epiweek = 201501)
names(del[[1L]]$forecast)
```
#### FluSurv hospitalization data
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/flusurv.html>
```{r, eval = FALSE}
pub_flusurv(locations = "ca", epiweeks = 202001)
```
#### Fluview data
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/fluview.html>
```{r, eval = FALSE}
pub_fluview(regions = "nat", epiweeks = epirange(201201, 202001))
```
#### Fluview virological data from clinical labs
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/fluview_clinical.html>
```{r, eval = FALSE}
pub_fluview_clinical(regions = "nat", epiweeks = epirange(201601, 201701))
```
#### Fluview metadata
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/fluview_meta.html>
```{r, eval = FALSE}
pub_fluview_meta()
```
#### Google Flu Trends data
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/gft.html>
```{r, eval = FALSE}
pub_gft(locations = "hhs1", epiweeks = epirange(201201, 202001))
```
#### ECDC ILI
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/ecdc_ili.html>
```{r, eval = FALSE}
pub_ecdc_ili(regions = "Armenia", epiweeks = 201840)
```
#### KCDC ILI
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/kcdc_ili.html>
```{r, eval = FALSE}
pub_kcdc_ili(regions = "ROK", epiweeks = 200436)
```
#### NIDSS Flu
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/nidss_flu.html>
```{r, eval = FALSE}
pub_nidss_flu(regions = "taipei", epiweeks = epirange(200901, 201301))
```
#### ILI Nearby Nowcast
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/nowcast.html>
```{r, eval = FALSE}
pub_nowcast(locations = "ca", epiweeks = epirange(202201, 202319))
```
### Dengue Endpoints
#### Delphi's Dengue Nowcast
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/dengue_nowcast.html>
```{r, eval = FALSE}
pub_dengue_nowcast(locations = "pr", epiweeks = epirange(201401, 202301))
```
#### NIDSS dengue
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/nidss_dengue.html>
```{r, eval = FALSE}
pub_nidss_dengue(locations = "taipei", epiweeks = epirange(200301, 201301))
```
### PAHO Dengue
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/paho_dengue.html>
```{r, eval=FALSE}
pub_paho_dengue(regions = "ca", epiweeks = epirange(200201, 202319))
```
### Other Endpoints
#### Wikipedia Access
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/wiki.html>
```{r, eval = FALSE}
pub_wiki(
language = "en",
articles = "influenza",
time_type = "week",
time_values = epirange(202001, 202319)
)
```
### Private methods
These require private access keys to use (separate from the Delphi Epidata API key).
To actually run these locally, you will need to store these secrets in your `.Reviron` file, or set them as environmental variables.
<details id="private-endpoints">
<summary>Usage of private endpoints</summary>
#### CDC
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/cdc.html>
```{r, eval=FALSE}
pvt_cdc(auth = Sys.getenv("SECRET_API_AUTH_CDC"), epiweeks = epirange(202003, 202304), locations = "ma")
```
#### Dengue Digital Surveillance Sensors
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/dengue_sensors.html>
```{r, eval=FALSE}
pvt_dengue_sensors(
auth = Sys.getenv("SECRET_API_AUTH_SENSORS"),
names = "ght",
locations = "ag",
epiweeks = epirange(201404, 202004)
)
```
#### Google Health Trends
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/ght.html>
```{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"
)
```
#### NoroSTAT metadata
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/meta_norostat.html>
```{r, eval=FALSE}
pvt_meta_norostat(auth = Sys.getenv("SECRET_API_AUTH_NOROSTAT"))
```
#### NoroSTAT data
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/norostat.html>
```{r, eval=FALSE}
pvt_norostat(auth = Sys.getenv("SECRET_API_AUTH_NOROSTAT"), locations = "1", epiweeks = 201233)
```
#### Quidel Influenza testing
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/quidel.html>
```{r, eval=FALSE}
pvt_quidel(auth = Sys.getenv("SECRET_API_AUTH_QUIDEL"), locations = "hhs1", epiweeks = epirange(200301, 202105))
```
#### Sensors
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/sensors.html>
```{r, eval=FALSE}
pvt_sensors(
auth = Sys.getenv("SECRET_API_AUTH_SENSORS"),
names = "sar3",
locations = "nat",
epiweeks = epirange(200301, 202105)
)
```
#### Twitter
API docs: <https://cmu-delphi.github.io/delphi-epidata/api/twitter.html>
```{r, eval=FALSE}
pvt_twitter(
auth = Sys.getenv("SECRET_API_AUTH_TWITTER"),
locations = "nat",
time_type = "week",
time_values = epirange(200301, 202105)
)
```
</details>