Finding data sources and signals of interest

In epidatr: Client for Delphi's 'Epidata' API

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.

Using the documentation

The Epidata documentation lists all the data sources and signals available through the API for COVID-19 and for other diseases. 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.

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:

avail_endpoints()

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:

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.

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:

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:

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 and are discussed in the API docs here. The example below is for Orange County, California.

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:

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

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

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

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

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

pub_flusurv(locations = "ca", epiweeks = 202001)

Fluview data

API docs: https://cmu-delphi.github.io/delphi-epidata/api/fluview.html

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

pub_fluview_clinical(regions = "nat", epiweeks = epirange(201601, 201701))

Fluview metadata

API docs: https://cmu-delphi.github.io/delphi-epidata/api/fluview_meta.html

pub_fluview_meta()

Google Flu Trends data

API docs: https://cmu-delphi.github.io/delphi-epidata/api/gft.html

pub_gft(locations = "hhs1", epiweeks = epirange(201201, 202001))

ECDC ILI

API docs: https://cmu-delphi.github.io/delphi-epidata/api/ecdc_ili.html

pub_ecdc_ili(regions = "Armenia", epiweeks = 201840)

KCDC ILI

API docs: https://cmu-delphi.github.io/delphi-epidata/api/kcdc_ili.html

pub_kcdc_ili(regions = "ROK", epiweeks = 200436)

NIDSS Flu

API docs: https://cmu-delphi.github.io/delphi-epidata/api/nidss_flu.html

pub_nidss_flu(regions = "taipei", epiweeks = epirange(200901, 201301))

ILI Nearby Nowcast

API docs: https://cmu-delphi.github.io/delphi-epidata/api/nowcast.html

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

pub_dengue_nowcast(locations = "pr", epiweeks = epirange(201401, 202301))

NIDSS dengue

API docs: https://cmu-delphi.github.io/delphi-epidata/api/nidss_dengue.html

pub_nidss_dengue(locations = "taipei", epiweeks = epirange(200301, 201301))

PAHO Dengue

API docs: https://cmu-delphi.github.io/delphi-epidata/api/paho_dengue.html

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

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.

Usage of private endpoints

CDC

API docs: https://cmu-delphi.github.io/delphi-epidata/api/cdc.html

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

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

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

pvt_meta_norostat(auth = Sys.getenv("SECRET_API_AUTH_NOROSTAT"))

NoroSTAT data

API docs: https://cmu-delphi.github.io/delphi-epidata/api/norostat.html

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

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

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

pvt_twitter(
  auth = Sys.getenv("SECRET_API_AUTH_TWITTER"),
  locations = "nat",
  time_type = "week",
  time_values = epirange(200301, 202105)
)

epidatr documentation built on June 22, 2024, 9:15 a.m.