Package 'epidatr' reference manual

Title:	Client for Delphi's 'Epidata' API
Description:	The Delphi 'Epidata' API 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) and Google Trends and private partners such as Facebook and Change 'Healthcare'. It is built and maintained by the Carnegie Mellon University Delphi research group. To cite this API: David C. Farrow, Logan C. Brooks, Aaron 'Rumack', Ryan J. 'Tibshirani', 'Roni' 'Rosenfeld' (2015). Delphi 'Epidata' API. <https://github.com/cmu-delphi/delphi-epidata>.
Authors:	Logan Brooks [aut], Dmitry Shemetov [aut], Samuel Gratzl [aut], David Weber [ctb, cre], Nat DeFries [ctb], Alex Reinhart [ctb], Daniel J. McDonald [ctb], Kean Ming Tan [ctb], Will Townes [ctb], George Haff [ctb], Kathryn Mazaitis [ctb]
Maintainer:	David Weber <[email protected]>
License:	MIT + file LICENSE
Version:	1.2.0
Built:	2024-11-14 23:24:29 UTC
Source:	https://github.com/cmu-delphi/epidatr

List all available Epidata API endpoints

Description

Fetches a data frame of all Epidata API endpoints that can be accessed using this package, with a brief description.

Usage

avail_endpoints()
avail_endpoints()

Value

A tibble::tibble of endpoints, with two columns:

`Endpoint`	Name of the function for accessing this API endpoint.
`Description`	One-sentence description of the data available at the endpoint.

Examples

avail_endpoints()
avail_endpoints()

Describe current cache

Description

Print out the information about the cache (as would be returned by cachem's info() method).

Usage

cache_info()
cache_info()

Value

list containing the info result as created by cachem

Manually reset the cache, deleting all currently saved data and starting afresh

Description

Deletes the current cache and resets a new cache. Deletes local data! If you are using a session unique cache, you will have to pass the arguments you used for set_cache earlier, otherwise the system-wide .Renviron-based defaults will be used.

Usage

clear_cache(..., disable = FALSE)
clear_cache(..., disable = FALSE)

Arguments

...

Arguments passed on to set_cache

cache_dir: the directory in which the cache is stored. By default, this is rappdirs::user_cache_dir("R", version = "epidatr"). The path can be either relative or absolute. The environmental variable is EPIDATR_CACHE_DIR.
days: the maximum length of time in days to keep any particular cached call. By default this is 1. The environmental variable is EPIDATR_CACHE_MAX_AGE_DAYS.
max_size: the size of the entire cache, in MB, at which to start pruning entries. By default this is 1024, or 1GB. The environmental variable is EPIDATR_CACHE_MAX_SIZE_MB.
logfile: where cachem's log of transactions is stored, relative to the cache directory. By default, it is "logfile.txt". The environmental variable is EPIDATR_CACHE_LOGFILE.
confirm: whether to confirm directory creation. default is TRUE; should only be set in non-interactive scripts
startup: indicates whether the function is being called on startup. Affects suppressability of the messages. Default is FALSE.

disable

instead of setting a new cache, disable caching entirely; defaults to FALSE

Value

NULL no return value, all effects are stored in the package environment

Creates the COVIDcast Epidata autocomplete helper

Description

Creates a helper object that can use auto-complete to help find COVIDcast sources and signals. The COVIDcast endpoint of the Epidata API contains many separate data sources and signals. It can be difficult to find the name of the signal you're looking for, so you can use covidcast_epidata to get help with finding sources and functions without leaving R.

The covidcast_epidata() function fetches a list of all signals, and returns an object containing fields for every signal:

epidata <- covidcast_epidata()
epidata$signals
#> # A tibble: 451 x 3
#>    source        signal                        short_description                
#>    <chr>         <chr>                         <chr>                            
#>  1 chng          smoothed_outpatient_cli       Estimated percentage of outpatie~
#>  2 chng          smoothed_adj_outpatient_cli   Estimated percentage of outpatie~
#>  3 chng          smoothed_outpatient_covid     COVID-Confirmed Doctor Visits    
#>  4 chng          smoothed_adj_outpatient_covid COVID-Confirmed Doctor Visits    
#>  5 chng          smoothed_outpatient_flu       Estimated percentage of outpatie~
#>  6 chng          smoothed_adj_outpatient_flu   Estimated percentage of outpatie~
#>  7 covid-act-now pcr_specimen_positivity_rate  Proportion of PCR specimens test~
#>  8 covid-act-now pcr_specimen_total_tests      Total number of PCR specimens te~
#>  9 doctor-visits smoothed_cli                  Percentage of daily doctor visit~
#> 10 doctor-visits smoothed_adj_cli              Percentage of daily doctor visit~
#> # i 441 more rows

If you use an editor that supports tab completion, such as RStudio, type ⁠epidata$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. Note that some signal names have dashes in them, so to access them we rely on the backtick operator:

epidata$signals$`fb-survey:smoothed_cli`
#> [1] "COVID-Like Symptoms (Unweighted 7-day average)"
#> [1] "fb-survey:smoothed_cli"
#> [1] "Estimated percentage of people with COVID-like illness "

These 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$signals$`fb-survey:smoothed_cli`$call("state", "pa",
                                              epirange(20210405, 20210410))
#> # A tibble: 6 x 15
#>   geo_value signal     source geo_type time_type time_value direction issue     
#>   <chr>     <chr>      <chr>  <fct>    <fct>     <date>         <dbl> <date>    
#> 1 pa        smoothed_~ fb-su~ state    day       2021-04-05        NA 2021-04-10
#> 2 pa        smoothed_~ fb-su~ state    day       2021-04-06        NA 2021-04-11
#> 3 pa        smoothed_~ fb-su~ state    day       2021-04-07        NA 2021-04-12
#> 4 pa        smoothed_~ fb-su~ state    day       2021-04-08        NA 2021-04-13
#> 5 pa        smoothed_~ fb-su~ state    day       2021-04-09        NA 2021-04-14
#> 6 pa        smoothed_~ fb-su~ state    day       2021-04-10        NA 2021-04-15
#> # i 7 more variables: lag <dbl>, missing_value <dbl>, missing_stderr <dbl>,
#> #   missing_sample_size <dbl>, value <dbl>, stderr <dbl>, sample_size <dbl>

Usage

covidcast_epidata(base_url = global_base_url, timeout_seconds = 30)
covidcast_epidata(base_url = global_base_url, timeout_seconds = 30)

Arguments

`base_url`	optional alternative API base url
`timeout_seconds`	the maximum amount of time to wait for a response

Value

An instance of covidcast_epidata

An abstraction that holds information needed to make an epidata request

Description

epidata_call objects are generated internally by endpoint functions like pub_covidcast; by default, they are piped directly into the fetch function to fetch and format the data. For most endpoints this will return a tibble, but a few non-COVIDCAST endpoints will return a JSON-like list instead.

Usage

create_epidata_call(
  endpoint,
  params,
  meta = NULL,
  only_supports_classic = FALSE
)

fetch(epidata_call, fetch_args = fetch_args_list())
create_epidata_call(
  endpoint,
  params,
  meta = NULL,
  only_supports_classic = FALSE
)

fetch(epidata_call, fetch_args = fetch_args_list())

Arguments

`endpoint`	the epidata endpoint to call
`params`	the parameters to pass to the epidata endpoint
`meta`	meta data to attach to the epidata call
`only_supports_classic`	if true only classic format is supported
`epidata_call`	an instance of `epidata_call`
`fetch_args`	a `fetch_args` object

Details

create_epidata_call is the constructor for epidata_call objects, but you should not need to use it directly; instead, use an endpoint function, e.g., pub_covidcast, to generate an epidata_call for the data of interest.

There are some other functions available for debugging and advanced usage: - request_url (for debugging): outputs the request URL from which data would be fetched (note additional parameters below)

fetch usually returns the data in tibble format, but a few of the endpoints only support the JSON classic format (pub_delphi, pvt_meta_norostat, and pub_meta). In that case a JSON-like nested list structure is returned instead.

Value

For create_epidata_call: an epidata_call object

For fetch: a tibble or a JSON-like list

Examples

## Not run: 
call <- pub_covidcast(
  source = "jhu-csse",
  signals = "confirmed_7dav_incidence_prop",
  time_type = "day",
  geo_type = "state",
  time_values = epirange(20200601, 20200801),
  geo_values = c("ca", "fl"),
  fetch_args = fetch_args_list(dry_run = TRUE)
)
call %>% fetch()

## End(Not run)

## Not run: 
call <- pub_covidcast(
  source = "jhu-csse",
  signals = "confirmed_7dav_incidence_prop",
  time_type = "day",
  geo_type = "state",
  time_values = epirange(20200601, 20200801),
  geo_values = c("ca", "fl"),
  fetch_args = fetch_args_list(dry_run = TRUE)
)
call %>% fetch()

## End(Not run)

Turn off the caching for this session

Description

Disable caching until you call set_cache or restart R. The files defining the cache are untouched. If you are looking to disable the caching more permanently, set EPIDATR_USE_CACHE=FALSE as environmental variable in your .Renviron.

Usage

disable_cache()
disable_cache()

Value

NULL no return value, all effects are stored in the package environment

Specify a range of days or weeks for API requests

Description

Specify a date range (in days or epiweeks) for an API request.

Usage

epirange(from, to)
epirange(from, to)

Arguments

`from`	The first date to request. Can be specified as a `Date` or as an integer or integer-like string in the format YYYYMMDD for dates or YYYYWW for epiweeks.
`to`	The final date to request (inclusive), specified the same way as `from`.

Details

Epiweeks, also known as MMWR weeks number the weeks of the year from 1 to 53, each week spanning from Sunday to Saturday. The numbering is defined by the CDC.

Value

An EpiRange object.

Examples

# Represents 2021-01-01 to 2021-01-07, inclusive
epirange(20210101, 20210107)

# The same, but using Date objects
epirange(as.Date("2021-01-01"), as.Date("2021-01-07"))

# Represents epiweeks 2 through 4 of 2022, inclusive
epirange(202202, 202204)
# Represents 2021-01-01 to 2021-01-07, inclusive
epirange(20210101, 20210107)

# The same, but using Date objects
epirange(as.Date("2021-01-01"), as.Date("2021-01-07"))

# Represents epiweeks 2 through 4 of 2022, inclusive
epirange(202202, 202204)

Set custom API request parameters

Description

Used to specify custom options when making API requests, such as to set timeouts or change data formats. These options are used by fetch() when it makes calls to the Epidata API.

Usage

fetch_args_list(
  ...,
  fields = NULL,
  disable_date_parsing = FALSE,
  disable_data_frame_parsing = FALSE,
  return_empty = FALSE,
  timeout_seconds = 15 * 60,
  base_url = NULL,
  dry_run = FALSE,
  debug = FALSE,
  format_type = c("json", "classic", "csv")
)
fetch_args_list(
  ...,
  fields = NULL,
  disable_date_parsing = FALSE,
  disable_data_frame_parsing = FALSE,
  return_empty = FALSE,
  timeout_seconds = 15 * 60,
  base_url = NULL,
  dry_run = FALSE,
  debug = FALSE,
  format_type = c("json", "classic", "csv")
)

Arguments

`...`	not used for values, forces later arguments to bind by name
`fields`	a list of epidata fields to return, or `NULL` to return all fields (default). e.g. `c("time_value", "value")` to return only the `time_value` and `value` fields or `c("-direction")` to return everything except the direction field
`disable_date_parsing`	disable automatic date parsing
`disable_data_frame_parsing`	disable automatic conversion to data frame; this is only supported by endpoints that only support the 'classic' format (non-tabular)
`return_empty`	boolean that allows returning an empty tibble if there is no data
`timeout_seconds`	the maximum amount of time (in seconds) to wait for a response from the API server
`base_url`	base URL to use; by default `NULL`, which means the global base URL `"https://api.delphi.cmu.edu/epidata/"`
`dry_run`	if `TRUE`, skip the call to the API and instead return the `epidata_call` object (useful for debugging)
`debug`	if `TRUE`, return the raw response from the API
`format_type`	the format to request from the API, one of classic, json, csv; this is only used by `fetch_debug`, and by default is `"json"`

Value

A fetch_args object containing all the specified options

Get and set API keys

Description

Get and set the API key used to make requests to the Epidata API. Without a key, requests may be subject to rate limits and other limitations.

Usage

get_api_key()

save_api_key()
get_api_key()

save_api_key()

Details

We recommend you register for an API key. While most endpoints are available without one, there are limits on API usage for anonymous users, including a rate limit. If you regularly request large amounts of data, please consider registering for an API key.

API keys are strings read from the environment variable DELPHI_EPIDATA_KEY. We recommend setting your key with save_api_key(), which will modify an applicable .Renviron file, which will be read in automatically when you start future R sessions (see ?Startup for details on .Renviron files). Alternatively, you can modify the environment variable at the command line before/while launching R, or inside an R session with Sys.setenv(), but these will not persist across sessions.

Once an API key is set, it is automatically used for all requests made by functions in this package.

Value

For get_api_key(), returns the current API key as a string, or "" if none is set.

References

COVID hospitalizations by facility

Description

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

Obtains the COVID-19 reported patient impact and hospital capacity data by facility. This dataset is provided by the US Department of Health & Human Services. The companion function pub_covid_hosp_facility_lookup() can be used to look up facility identifiers in a variety of ways.

Usage

pub_covid_hosp_facility(
  hospital_pks,
  collection_weeks = "*",
  ...,
  publication_dates = NULL,
  fetch_args = fetch_args_list()
)
pub_covid_hosp_facility(
  hospital_pks,
  collection_weeks = "*",
  ...,
  publication_dates = NULL,
  fetch_args = fetch_args_list()
)

Arguments

`hospital_pks`	character. Facility identifiers.
`collection_weeks`	`timeset`. Dates (corresponding to epiweeks) to fetch. Defaults to all ("*") dates.
`...`	not used for values, forces later arguments to bind by name
`publication_dates`	`timeset`. Publication dates to fetch.
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`.

Details

Starting October 1, 2022, some facilities are only required to report annually.

`...`	not used for values, forces later arguments to bind by name
`state`	string. A two-letter character state abbreviation.
`ccn`	string. A facility CMS certification number.
`city`	string. A city name.
`zip`	string. A 5-digit zip code.
`fips_code`	string. A 5-digit fips county code, zero-padded.
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`.

`states`	character. Two letter state abbreviations.
`dates`	`timeset`. Dates to fetch. Defaults to all ("*") dates.
`...`	not used for values, forces later arguments to bind by name
`as_of`	Date. Optionally, the as of date for the issues to fetch. If not specified, the most recent data is returned. Mutually exclusive with `issues`.
`issues`	`timeset`. Optionally, the issue of the data to fetch. If not specified, the most recent issue is returned. Mutually exclusive with `as_of` or `lag`.
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`.

`source`	string. The data source to query (see: https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html).
`signals`	string. The signals to query from a specific source (see: https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html).
`geo_type`	string. The geographic resolution of the data (see: https://cmu-delphi.github.io/delphi-epidata/api/covidcast_geography.html).
`time_type`	string. The temporal resolution of the data (either "day" or "week", depending on signal).
`geo_values`	character. The geographies to return. Defaults to all ("*") geographies within requested geographic resolution (see: https://cmu-delphi.github.io/delphi-epidata/api/covidcast_geography.html.).
`time_values`	`timeset`. Dates to fetch. Defaults to all ("*") dates.
`...`	not used for values, forces later arguments to bind by name
`as_of`	Date. Optionally, the as of date for the issues to fetch. If not specified, the most recent data is returned. Mutually exclusive with `issues` or `lag`.
`issues`	`timeset`. Optionally, the issue of the data to fetch. If not specified, the most recent issue is returned. Mutually exclusive with `as_of` or `lag`.
`lag`	integer. Optionally, the lag of the issues to fetch. If not set, the most recent issue is returned. Mutually exclusive with `as_of` or `issues`.
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`.

`system`	character. System name to fetch.
`epiweek`	`timeset`. Epiweek to fetch. Does not support multiple dates. Make separate calls to fetch data for multiple epiweeks.
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`.

`locations`	character. Locations to fetch.
`epiweeks`	`timeset`. Epiweeks to fetch. Defaults to all ("*") dates.
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`.

`regions`	character. Regions to fetch.
`epiweeks`	`timeset`. Epiweeks to fetch. Defaults to all ("*") dates.
`...`	not used for values, forces later arguments to bind by name
`issues`	`timeset`. Optionally, the issues to fetch. If not set, the most recent issue is returned. Mutually exclusive with `lag`.
`lag`	integer. Optionally, the lag of the issues to fetch. If not set, the most recent issue is returned. Mutually exclusive with `issues`.
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`.

`locations`	character. Character vector indicating location.
`epiweeks`	`timeset`. Epiweeks to fetch. Defaults to all ("*") dates.
`...`	not used for values, forces later arguments to bind by name
`issues`	`timeset`. Optionally, the issues to fetch. If not set, the most recent issue is returned. Mutually exclusive with `lag`.
`lag`	integer. Optionally, the lag of the issues to fetch. If not set, the most recent issue is returned. Mutually exclusive with `issues`.
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`.

`regions`	character. Locations to fetch. Can be any string IDs in national, HHS region, census division, most states and territories, and so on. Full list link below.
`epiweeks`	`timeset`. Epiweeks to fetch in the form `epirange(startweek, endweek)`, where startweek and endweek are of the form YYYYWW (string or numeric). Defaults to all ("*") dates.
`...`	not used for values, forces later arguments to bind by name
`issues`	`timeset`. Optionally, the issues to fetch. If not set, the most recent issue is returned. Mutually exclusive with `lag`.
`lag`	integer. Optionally, the lag of the issues to fetch. If not set, the most recent issue is returned. Mutually exclusive with `issues`.
`auth`	string. Optionally, restricted access key (not the same as API key).
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`.

`articles`	character. Articles to fetch.
`...`	not used for values, forces later arguments to bind by name
`time_type`	string. The temporal resolution of the data (either "day" or "week", depending on signal).
`time_values`	`timeset`. Dates or epiweeks to fetch. Defaults to all ("*") dates.
`hours`	integer. Optionally, the hours to fetch.
`language`	string. Language to fetch.
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`.

`auth`	string. Restricted access key (not the same as API key).
`locations`	character. Locations to fetch.
`epiweeks`	`timeset`. Epiweeks to fetch. Defaults to all ("*") dates.
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`. See `fetch_args_list()` for details.

`cache_dir`	the directory in which the cache is stored. By default, this is `rappdirs::user_cache_dir("R", version = "epidatr")`. The path can be either relative or absolute. The environmental variable is `EPIDATR_CACHE_DIR`.
`days`	the maximum length of time in days to keep any particular cached call. By default this is `1`. The environmental variable is `EPIDATR_CACHE_MAX_AGE_DAYS`.
`max_size`	the size of the entire cache, in MB, at which to start pruning entries. By default this is `1024`, or 1GB. The environmental variable is `EPIDATR_CACHE_MAX_SIZE_MB`.
`logfile`	where cachem's log of transactions is stored, relative to the cache directory. By default, it is `"logfile.txt"`. The environmental variable is `EPIDATR_CACHE_LOGFILE`.
`confirm`	whether to confirm directory creation. default is `TRUE`; should only be set in non-interactive scripts
`startup`	indicates whether the function is being called on startup. Affects suppressability of the messages. Default is `FALSE`.

`auth`	string. Restricted access key (not the same as API key).
`names`	character. Names to fetch.
`locations`	character. Locations to fetch.
`epiweeks`	`timeset`. Epiweeks to fetch. Defaults to all ("*") dates.
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`.

`auth`	string. Your authentication key.
`locations`	character. Locations to fetch.
`epiweeks`	`timeset`. Epiweeks to fetch. Defaults to all ("*") dates.
`fetch_args`	`fetch_args`. Additional arguments to pass to `fetch()`.

Package 'epidatr'

Help Index

List all available Epidata API endpoints

Description

Usage

Value

Examples

Describe current cache

Description

Usage

Value

See Also

Manually reset the cache, deleting all currently saved data and starting afresh

Description

Usage

Arguments

Value

See Also

Creates the COVIDcast Epidata autocomplete helper

Description

Usage

Arguments

Value

An abstraction that holds information needed to make an epidata request

Description

Usage

Arguments

Details

Value

Examples

Turn off the caching for this session

Description

Usage

Value

See Also

Specify a range of days or weeks for API requests

Description

Usage

Arguments

Details

Value

Examples

Set custom API request parameters

Description

Usage

Arguments

Value

Get and set API keys

Description

Usage

Details

Value

References

COVID hospitalizations by facility

Description

Usage

Arguments

Details

Value

See Also

Examples

Helper for finding COVID hospitalization facilities

Description

Usage

Arguments

Details

Value

See Also

Examples

COVID hospitalizations by state

Description

Usage

Arguments

Details

Value

Examples

Various COVID and flu signals via the COVIDcast endpoint

Description

Usage

Arguments