Package {epidatr}

epidatr: 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.

Package options

The delphi.epidata.key option specifies the API key to be used when making requests to the Epidata API.

Author(s)

Maintainer: David Weber davidweb@andrew.cmu.edu [contributor]

Authors:

• Logan Brooks lcbrooks@andrew.cmu.edu

• Dmitry Shemetov dshemeto@andrew.cmu.edu

• Samuel Gratzl sam@sgratzl.com

Other contributors:

• Nat DeFries [contributor]

• Alex Reinhart [contributor]

• Daniel J. McDonald [contributor]

• Kean Ming Tan [contributor]

• Will Townes [contributor]

• George Haff [contributor]

• Kathryn Mazaitis [contributor]

See Also

Useful links:

• https://cmu-delphi.github.io/epidatr/

• https://cmu-delphi.github.io/delphi-epidata/

• https://github.com/cmu-delphi/epidatr

• Report bugs at https://github.com/cmu-delphi/epidatr/issues

Shared Documentation for epidatr Parameters

Description

This is a central text for parameter documentation

Arguments

Data Versioning

Several endpoints support retrieving historical versions of the data. The following parameters control this and are mutually exclusive (only one can be provided at a time).

• as_of: (Date) Retrieve the data as it was on this date.

• issues: timeset Retrieve data from a specific issue date or range of dates.

• lag: (integer) Retrieve data with a specific lag from its issue date.

If none of these is specified, the most recent version of the data is returned.

See vignette("versioned-data") for details and more ways to specify versioned data.

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Allows character vectors

Description

Allows character vectors

Usage

assert_character_param(name, value, len = NULL, required = TRUE)

Allows a vector of date_like params: date, character, or integer-like

Description

Allows a vector of date_like params: date, character, or integer-like

Usage

assert_date_param(name, value, len = NULL, required = TRUE)

Allows integer-like vectors

Description

Allows integer-like vectors

Usage

assert_integerish_param(name, value, len = NULL, required = TRUE)

Allows a timeset param: a date vector, a character vector, an integer-like vector, or a single EpiRange

Description

Allows a timeset param: a date vector, a character vector, an integer-like vector, or a single EpiRange

Usage

assert_timeset_param(name, value, len = NULL, required = TRUE)

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()

Value

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

Examples

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()

Value

list containing the info result as created by cachem

See Also

set_cache to start a new cache (and general caching info), clear_cache to delete the cache and set a new one, and disable_cache to disable without deleting

cast-API snapshot and archive queries

Description

• epidata_snapshot fetches a snapshot of signals as they appeared at a specific date (or the latest available if snapshot_date is omitted).

• epidata_archive fetches the full version history of signals across all available issues.

• epidata is a wrapper that routes to one of the above based on which versioning argument is supplied.

Usage

epidata_snapshot(
  source,
  signals,
  geo_type,
  geo_values = "*",
  reference_time = "*",
  time_values = lifecycle::deprecated(),
  ...,
  fill_method = NULL,
  snapshot_date = NULL,
  as_of = lifecycle::deprecated(),
  fetch_args = fetch_args_list()
)

epidata_archive(
  source,
  signals,
  geo_type,
  geo_values = "*",
  reference_time = "*",
  time_values = lifecycle::deprecated(),
  ...,
  fill_method = NULL,
  report_time = "*",
  issues = lifecycle::deprecated(),
  fetch_args = fetch_args_list()
)

epidata(
  source,
  signals,
  geo_type,
  geo_values = "*",
  reference_time = "*",
  time_values = lifecycle::deprecated(),
  ...,
  fill_method = NULL,
  snapshot_date = NULL,
  as_of = lifecycle::deprecated(),
  report_time = NULL,
  issues = lifecycle::deprecated(),
  fetch_args = fetch_args_list()
)

Arguments

Value

tibble::tibble

Data Versioning

epidata supports two mutually exclusive versioning arguments. Pass snapshot_date to retrieve data as it appeared on a specific date, or report_time to query the archive by when data was reported. If neither is supplied, epidata returns the latest available snapshot.

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

See Also

epidata_meta(), epirange()

Check an API response for epidata-level errors and warnings.

Description

Check an API response for epidata-level errors and warnings.

Usage

check_epidata_result(response_content, allow_empty = FALSE)

Arguments

Check for warnings for the cache

Description

Adds warnings when arguments are potentially too recent to use with the cache.

Usage

check_for_cache_warnings(epidata_call, fetch_args)

Arguments

Helper that checks whether a call is actually cachable

Description

The cacheable endpoints are those with as_of or issues parameters:

• pub_covidcast

• pub_covid_hosp_state_timeseries

• pub_ecdc_ili

• pub_flusurv

• pub_fluview_clinical

• pub_fluview

• pub_kcdc_ili

• pub_nidss_flu

• pub_paho_dengue

Usage

check_is_cachable(epidata_call, fetch_args)

helper that checks whether a call is a somewhat dangerous cache

Description

helper that checks whether a call is a somewhat dangerous cache

Usage

check_is_recent(dates, max_age)

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, the previous settings will be reused. If you pass in new set_cache arguments, they will take precedence over the previous settings.

Usage

clear_cache(..., disable = FALSE)

Arguments

Value

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

See Also

set_cache to start a new cache (and general caching info), disable_cache to only disable without deleting, and cache_info

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: 538 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 chng          7dav_inpatient_covid          Ratio of inpatient hospitalizati~
#>  8 chng          7dav_outpatient_covid         Ratio of outpatient doctor visit~
#>  9 covid-act-now pcr_specimen_positivity_rate  Proportion of PCR specimens test~
#> 10 covid-act-now pcr_specimen_total_tests      Total number of PCR specimens te~
#> # i 528 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)

Arguments

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,
  api_version = c("classic", "cast"),
  response_format = c("classic", "json", "csv")
)

fetch(epidata_call, fetch_args = fetch_args_list())

Arguments

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.

Value

• For create_epidata_call: an epidata_call object

• For fetch: a tibble

Examples

library(magrittr)

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()

Add metadata to an epidata_field

Description

This function annotates the type of the returned API field. This is used by parse_value downstream to determine how to convert the returned data.

Usage

create_epidata_field_info(name, type, description = "", categories = c())

Arguments

Converts a date (integer or character) to an epiweek

Description

Converts a date (integer or character) to an epiweek

Usage

date_to_epiweek(value)

Arguments

Value

an integer representing an epiweek, in the format YYYYWW

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()

Value

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

See Also

set_cache to start a new cache (and general caching info), clear_cache to delete the cache and set a new one, and cache_info

Performs an API request and returns the response body as a string.

Description

Handles authentication, retries, 414 URI Too Long fallback to POST, HTTP errors, and API-level errors. The API returns errors as JSON regardless of the requested format, so for non-classic formats we sniff the body for a JSON error response.

Usage

do_request(
  epidata_call,
  format_type = c("json", "csv", "classic"),
  timeout_seconds,
  fields,
  http_method = c("GET", "POST")
)

Arguments

Value

an httr2_response object

Get cast-API source metadata

Description

epidata_meta returns source-level metadata from the cast-API, including report_time ranges, reference_time ranges, and lists of available signals and geo types.

Usage

epidata_meta(source, fetch_args = fetch_args_list())

Arguments

Value

list

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

See Also

epidata_snapshot(), epidata_archive(), epidata(), epirange()

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)

Arguments

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)

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 = lifecycle::deprecated(),
  format_type = lifecycle::deprecated(),
  refresh_cache = FALSE,
  reference_week_day = 1
)

Arguments

Value

A fetch_args object containing all the specified options

Filter a data frame by a timeset (vector of dates/epiweeks or EpiRange)

Description

Filter a data frame by a timeset (vector of dates/epiweeks or EpiRange)

Usage

filter_by_timeset(df, column, timeset)

Arguments

Helper function to cast values, non-list vectors, and/or EpiRanges to strings

Description

Helper function to cast values, non-list vectors, and/or EpiRanges to strings

Usage

format_item(value)

Helper function to build a list of values and/or ranges

Description

Helper function to build a list of values and/or ranges

Usage

format_list(values)

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()

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 open your .Renviron file in a text editor. You will need to write DELPHI_EPIDATA_KEY=yourkeyhere (without quotes) in the file and save it. Once the .Renviron file has been saved as instructed, it will be read 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

• Delphi Epidata API Keys documentation.

• Delphi Epidata API Registration Form.

helper to convert a date wildcard ("*") to an appropriate epirange

Description

helper to convert a date wildcard ("*") to an appropriate epirange

Usage

get_wildcard_equivalent_dates(time_value, time_type = c("day", "week"))

Check if the cache is enabled

Description

Check if the cache is enabled

Usage

is_cache_enabled()

parse_api_week converts an integer to a date

Description

parse_api_week converts an integer to a date

Usage

parse_api_week(value, reference_week_day = 1)

Arguments

Value

a date

turn a signal into a callable

Description

turn a signal into a callable

Usage

parse_signal(signal, base_url)

Arguments

Parse data returned by the API

Description

This function uses the metadata annotations to determine how to parse the incoming data. The data annotation refers to the received API type, rather than the target R type.

Usage

parse_value(info, value, disable_date_parsing = FALSE, reference_week_day = 1)

Arguments

Value

The parsed value.

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()
)

Arguments

Details

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

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

See Also

pub_covid_hosp_facility(), epirange()

Examples

pub_covid_hosp_facility(
  hospital_pks = "100075",
  collection_weeks = epirange(20200101, 20200501)
)

pub_covid_hosp_facility(
  hospital_pks = "050063",
  collection_weeks = epirange(20240101, 20240301)
)

Helper for finding COVID hospitalization facilities

Description

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

Obtains unique identifiers and other metadata for COVID hospitalization facilities of interest. This is a companion endpoint to the pub_covid_hosp_facility() endpoint.

Usage

pub_covid_hosp_facility_lookup(
  ...,
  state = NULL,
  ccn = NULL,
  city = NULL,
  zip = NULL,
  fips_code = NULL,
  fetch_args = fetch_args_list()
)

Arguments

Details

Only one location argument needs to be specified. Combinations of the arguments are not currently supported.

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

See Also

pub_covid_hosp_facility()

Examples

pub_covid_hosp_facility_lookup(state = "fl")
pub_covid_hosp_facility_lookup(city = "southlake")

COVID hospitalizations by state

Description

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

Obtains the COVID-19 reported patient impact and hospital capacity data by state. This dataset is provided by the US Department of Health & Human Services.

Usage

pub_covid_hosp_state_timeseries(
  states,
  dates = "*",
  ...,
  as_of = NULL,
  issues = NULL,
  fetch_args = fetch_args_list()
)

Arguments

Details

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

Value

tibble::tibble

Data Versioning

Several endpoints support retrieving historical versions of the data. The following parameters control this and are mutually exclusive (only one can be provided at a time).

• as_of: (Date) Retrieve the data as it was on this date.

• issues: timeset Retrieve data from a specific issue date or range of dates.

• lag: (integer) Retrieve data with a specific lag from its issue date.

If none of these is specified, the most recent version of the data is returned.

See vignette("versioned-data") for details and more ways to specify versioned data.

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

pub_covid_hosp_state_timeseries(
  states = "fl",
  dates = epirange(20200101, 20200501)
)

Various COVID and flu signals via the COVIDcast endpoint

Description

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

The primary endpoint for fetching COVID-19 data, providing access to a wide variety of signals from a wide variety of sources. See the API documentation link above for more. Delphi's COVIDcast public dashboard is powered by this endpoint.

Usage

pub_covidcast(
  source,
  signals,
  geo_type,
  time_type,
  geo_values = "*",
  time_values = "*",
  ...,
  as_of = NULL,
  issues = NULL,
  lag = NULL,
  fetch_args = fetch_args_list()
)

Arguments

Value

tibble::tibble

Data Versioning

Several endpoints support retrieving historical versions of the data. The following parameters control this and are mutually exclusive (only one can be provided at a time).

• as_of: (Date) Retrieve the data as it was on this date.

• issues: timeset Retrieve data from a specific issue date or range of dates.

• lag: (integer) Retrieve data with a specific lag from its issue date.

If none of these is specified, the most recent version of the data is returned.

See vignette("versioned-data") for details and more ways to specify versioned data.

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

See Also

pub_covidcast_meta(), covidcast_epidata(), epirange()

Examples

pub_covidcast(
  source = "jhu-csse",
  signals = "confirmed_7dav_incidence_prop",
  geo_type = "state",
  time_type = "day",
  geo_values = c("ca", "fl"),
  time_values = epirange(20200601, 20200801)
)
pub_covidcast(
  source = "jhu-csse",
  signals = "confirmed_7dav_incidence_prop",
  geo_type = "state",
  time_type = "day",
  geo_values = "*",
  time_values = epirange(20200601, 20200801)
)

Metadata for the COVIDcast endpoint

Description

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

Fetch a summary of metadata for all sources and signals that are available in the API, along with basic summary statistics such as the dates they are available, the geographic levels at which they are reported, and etc.

The result can be filtered server-side by passing signals, time_type, and/or geo_type. Omitted filters (the default) return metadata for everything.

Usage

pub_covidcast_meta(
  signals = NULL,
  time_type = NULL,
  geo_type = NULL,
  fetch_args = fetch_args_list()
)

Arguments

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

See Also

pub_covidcast(),covidcast_epidata()

Examples

pub_covidcast_meta()
# All signals from the Facebook survey data source
pub_covidcast_meta(
  signals = "fb-survey:*"
)
# All signals with time_type "day".
pub_covidcast_meta(
  time_type = "day",
)
# All signals with geo_type "state".
pub_covidcast_meta(
  geo_type = "state",
)

Delphi's ILINet outpatient doctor visits forecasts

Description

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

Usage

pub_delphi(system, epiweek, fetch_args = fetch_args_list())

Arguments

Value

list

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

pub_delphi(system = "ec", epiweek = 201501)

Delphi's PAHO dengue nowcasts (North and South America)

Description

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

Usage

pub_dengue_nowcast(locations, epiweeks = "*", fetch_args = fetch_args_list())

Arguments

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

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

ECDC ILI incidence (Europe)

Description

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

Obtain information on influenza-like-illness from the European Centre for Disease Prevention and Control.

Usage

pub_ecdc_ili(
  regions,
  epiweeks = "*",
  ...,
  issues = NULL,
  lag = NULL,
  fetch_args = fetch_args_list()
)

Arguments

Details

The list of location argument can be found in https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/ecdc_regions.txt.

Value

tibble::tibble

Data Versioning

Several endpoints support retrieving historical versions of the data. The following parameters control this and are mutually exclusive (only one can be provided at a time).

• as_of: (Date) Retrieve the data as it was on this date.

• issues: timeset Retrieve data from a specific issue date or range of dates.

• lag: (integer) Retrieve data with a specific lag from its issue date.

If none of these is specified, the most recent version of the data is returned.

See vignette("versioned-data") for details and more ways to specify versioned data.

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

pub_ecdc_ili(regions = "austria", epiweeks = epirange(201901, 202001))

CDC FluSurv flu hospitalizations

Description

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

Obtain information on influenza hospitalization rates from the Center of Disease Control.

See also https://gis.cdc.gov/GRASP/Fluview/FluHospRates.html.

Usage

pub_flusurv(
  locations,
  epiweeks = "*",
  ...,
  issues = NULL,
  lag = NULL,
  fetch_args = fetch_args_list()
)

Arguments

Details

The list of location argument can be found in https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/flusurv_locations.txt.

Value

tibble::tibble

Data Versioning

Several endpoints support retrieving historical versions of the data. The following parameters control this and are mutually exclusive (only one can be provided at a time).

• as_of: (Date) Retrieve the data as it was on this date.

• issues: timeset Retrieve data from a specific issue date or range of dates.

• lag: (integer) Retrieve data with a specific lag from its issue date.

If none of these is specified, the most recent version of the data is returned.

See vignette("versioned-data") for details and more ways to specify versioned data.

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

pub_flusurv(locations = "ca", epiweeks = epirange(201701, 201801))

CDC FluView ILINet outpatient doctor visits

Description

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

Obtains information on outpatient inluenza-like-illness (ILI) from U.S. Outpatient Influenza-like Illness Surveillance Network (ILINet).

more information on ILINet, see https://gis.cdc.gov/grasp/fluview/fluportaldashboard.html.

Usage

pub_fluview(
  regions,
  epiweeks = "*",
  ...,
  issues = NULL,
  lag = NULL,
  auth = NULL,
  fetch_args = fetch_args_list()
)

Arguments

Details

The full list of location inputs can be accessed at https://github.com/cmu-delphi/delphi-epidata/blob/main/src/acquisition/fluview/fluview_locations.py.

Value

tibble::tibble

Data Versioning

Several endpoints support retrieving historical versions of the data. The following parameters control this and are mutually exclusive (only one can be provided at a time).

• as_of: (Date) Retrieve the data as it was on this date.

• issues: timeset Retrieve data from a specific issue date or range of dates.

• lag: (integer) Retrieve data with a specific lag from its issue date.

If none of these is specified, the most recent version of the data is returned.

See vignette("versioned-data") for details and more ways to specify versioned data.

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

pub_fluview(regions = "nat", epiweeks = epirange(201201, 202005))

CDC FluView flu tests from clinical labs

Description

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

Usage

pub_fluview_clinical(
  regions,
  epiweeks = "*",
  ...,
  issues = NULL,
  lag = NULL,
  fetch_args = fetch_args_list()
)

Arguments

Value

tibble::tibble

Data Versioning

Several endpoints support retrieving historical versions of the data. The following parameters control this and are mutually exclusive (only one can be provided at a time).

• as_of: (Date) Retrieve the data as it was on this date.

• issues: timeset Retrieve data from a specific issue date or range of dates.

• lag: (integer) Retrieve data with a specific lag from its issue date.

If none of these is specified, the most recent version of the data is returned.

See vignette("versioned-data") for details and more ways to specify versioned data.

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

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

Metadata for the FluView endpoint

Description

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

Usage

pub_fluview_meta(fetch_args = fetch_args_list())

Arguments

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

See Also

pub_fluview()

Examples

pub_fluview_meta()

Google Flu Trends flu search volume

Description

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

Obtains estimates of inluenza activity based on volume of certain search queries from Google.

Usage

pub_gft(locations, epiweeks = "*", fetch_args = fetch_args_list())

Arguments

Details

Google has discontinued Flu Trends and this is now a static endpoint. Possibile input for locations can be found in https://cmu-delphi.github.io/delphi-epidata/api/geographic_codes.html#hhs-regions, https://cmu-delphi.github.io/delphi-epidata/api/geographic_codes.html#us-states, and https://cmu-delphi.github.io/delphi-epidata/api/geographic_codes.html#selected-us-cities.

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

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

KCDC ILI incidence (Korea)

Description

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

Usage

pub_kcdc_ili(
  regions,
  epiweeks = "*",
  ...,
  issues = NULL,
  lag = NULL,
  fetch_args = fetch_args_list()
)

Arguments

Value

tibble::tibble

Data Versioning

Several endpoints support retrieving historical versions of the data. The following parameters control this and are mutually exclusive (only one can be provided at a time).

• as_of: (Date) Retrieve the data as it was on this date.

• issues: timeset Retrieve data from a specific issue date or range of dates.

• lag: (integer) Retrieve data with a specific lag from its issue date.

If none of these is specified, the most recent version of the data is returned.

See vignette("versioned-data") for details and more ways to specify versioned data.

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

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

Metadata for the Delphi Epidata API

Description

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

Usage

pub_meta(fetch_args = fetch_args_list())

Arguments

Value

list

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

NIDSS dengue cases (Taiwan)

Description

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

Obtains counts of confirmed dengue cases in Taiwan from Taiwan National Infectious Disease Statistical System.

Usage

pub_nidss_dengue(locations, epiweeks = "*", fetch_args = fetch_args_list())

Arguments

Details

Possible location inputs can be found in https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/nidss_regions.txt and https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/nidss_locations.txt.

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

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

NIDSS flu doctor visits (Taiwan)

Description

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

Obtains information on outpatient inluenza-like-illness from Taiwan National Infectious Disease Statistical System.

Usage

pub_nidss_flu(
  regions,
  epiweeks = "*",
  ...,
  issues = NULL,
  lag = NULL,
  fetch_args = fetch_args_list()
)

Arguments

Value

tibble::tibble

Data Versioning

Several endpoints support retrieving historical versions of the data. The following parameters control this and are mutually exclusive (only one can be provided at a time).

• as_of: (Date) Retrieve the data as it was on this date.

• issues: timeset Retrieve data from a specific issue date or range of dates.

• lag: (integer) Retrieve data with a specific lag from its issue date.

If none of these is specified, the most recent version of the data is returned.

See vignette("versioned-data") for details and more ways to specify versioned data.

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

pub_nidss_flu(regions = "taipei", epiweeks = epirange(201501, 201601))

Delphi's ILI Nearby nowcasts

Description

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

Obtains information on outpatient inluenza-like-illness (ILI) from Delphi's

Usage

pub_nowcast(locations, epiweeks = "*", fetch_args = fetch_args_list())

Arguments

Details

The full list of location inputs can be accessed at https://cmu-delphi.github.io/delphi-epidata/api/geographic_codes.html#us-regions-and-states and https://cmu-delphi.github.io/delphi-epidata/api/geographic_codes.html#fluview-cities.

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

pub_nowcast(locations = "ca", epiweeks = epirange(201201, 201301))

PAHO dengue data (North and South America)

Description

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

Usage

pub_paho_dengue(
  regions,
  epiweeks = "*",
  ...,
  issues = NULL,
  lag = NULL,
  fetch_args = fetch_args_list()
)

Arguments

Value

tibble::tibble

Data Versioning

Several endpoints support retrieving historical versions of the data. The following parameters control this and are mutually exclusive (only one can be provided at a time).

• as_of: (Date) Retrieve the data as it was on this date.

• issues: timeset Retrieve data from a specific issue date or range of dates.

• lag: (integer) Retrieve data with a specific lag from its issue date.

If none of these is specified, the most recent version of the data is returned.

See vignette("versioned-data") for details and more ways to specify versioned data.

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

pub_paho_dengue(regions = "ca", epiweeks = epirange(201401, 201501))

Wikipedia webpage counts by article

Description

API docs: https://cmu-delphi.github.io/delphi-epidata/api/wiki.html Number of page visits for selected English, Influenza-related wikipedia articles.

• Source: Wikimedia

• Temporal Resolution: Hourly, daily, and weekly from 2007-12-09 (2007w50)

• Spatial Resolution: N/A

• Other resolution: By article (54)

• Open access

Usage

pub_wiki(
  articles,
  ...,
  time_type = c("day", "week"),
  time_values = "*",
  hours = NULL,
  language = "en",
  fetch_args = fetch_args_list()
)

Arguments

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

pub_wiki(
  articles = "avian_influenza",
  time_type = "week",
  time_values = epirange(201501, 201601)
)

CDC total and by topic webpage visits

Description

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

Usage

pvt_cdc(auth, locations, epiweeks = "*", fetch_args = fetch_args_list())

Arguments

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

## Not run: 
pvt_cdc(
  auth = Sys.getenv("DELPHI_EPIDATA_KEY"),
  locations = "fl,ca",
  epirange(201501, 201601)
)

## End(Not run)

PAHO dengue digital surveillance sensors (North and South America)

Description

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

Usage

pvt_dengue_sensors(
  auth,
  names,
  locations,
  epiweeks = "*",
  fetch_args = fetch_args_list()
)

Arguments

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

## Not run: 
pvt_dengue_sensors(
  auth = Sys.getenv("DELPHI_EPIDATA_KEY"),
  names = "ght",
  locations = "ag",
  epiweeks = epirange(201501, 202001)
)

## End(Not run)

Google Health Trends health topics search volume

Description

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

Estimate of influenza activity based on volume of certain search queries. …

Usage

pvt_ght(auth, locations, epiweeks = "*", query, fetch_args = fetch_args_list())

Arguments

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

## Not run: 
pvt_ght(
  auth = Sys.getenv("DELPHI_EPIDATA_KEY"),
  locations = "ma",
  epiweeks = epirange(199301, 202304),
  query = "how to get over the flu"
)

## End(Not run)

Metadata for the NoroSTAT endpoint

Description

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

Usage

pvt_meta_norostat(auth, fetch_args = fetch_args_list())

Arguments

Value

list

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

See Also

pvt_norostat()

Examples

## Not run: 
pvt_meta_norostat(auth = Sys.getenv("DELPHI_EPIDATA_KEY"))

## End(Not run)

CDC NoroSTAT norovirus outbreaks

Description

This is point data only, and does not include minima or maxima.

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

This is the documentation of the API for accessing the NoroSTAT endpoint of the Delphi’s epidemiological data.

Usage

pvt_norostat(auth, locations, epiweeks = "*", fetch_args = fetch_args_list())

Arguments

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

## Not run: 
pvt_norostat(
  auth = Sys.getenv("DELPHI_EPIDATA_KEY"),
  locations = "Minnesota, Ohio, Oregon, Tennessee, and Wisconsin",
  epiweeks = 201233
)

## End(Not run)

Quidel COVID-19 and influenza testing data

Description

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

Data provided by Quidel Corp., which contains flu lab test results.

Usage

pvt_quidel(auth, locations, epiweeks = "*", fetch_args = fetch_args_list())

Arguments

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

## Not run: 
pvt_quidel(
  auth = Sys.getenv("DELPHI_EPIDATA_KEY"),
  epiweeks = epirange(201201, 202001),
  locations = "hhs1"
)

## End(Not run)

Influenza and dengue digital surveillance sensors

Description

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

This is the documentation of the API for accessing the Digital Surveillance Sensors endpoint of the Delphi’s epidemiological. Note: this repository was built to support modeling and forecasting efforts surrounding seasonal influenza (and dengue). In the current COVID-19 pandemic, syndromic surveillance data, like ILI data (influenza-like illness) through FluView, will likely prove very useful. However, we urge caution to users examining the digital surveillance sensors, like ILI Nearby, Google Flu Trends, etc., during the COVID-19 pandemic, because these were designed to track ILI as driven by seasonal influenza, and were NOT designed to track ILI during the COVID-19 pandemic.

Usage

pvt_sensors(
  auth,
  names,
  locations,
  epiweeks = "*",
  fetch_args = fetch_args_list()
)

Arguments

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

## Not run: 
pvt_sensors(
  auth = Sys.getenv("DELPHI_EPIDATA_KEY"),
  names = "sar3",
  locations = "nat",
  epiweeks = epirange(201501, 202001)
)

## End(Not run)

HealthTweets total and influenza-related tweets

Description

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

This is the API documentation for accessing the Twitter Stream endpoint of Delphi’s epidemiological data. Sourced from Healthtweets

Usage

pvt_twitter(
  auth,
  locations,
  ...,
  time_type = c("day", "week"),
  time_values = "*",
  fetch_args = fetch_args_list()
)

Arguments

Value

tibble::tibble

See also

For example queries showing how to discover signals and build calls, see vignette("signal-discovery", package = "epidatr").

Examples

## Not run: 
pvt_twitter(
  auth = Sys.getenv("DELPHI_EPIDATA_KEY"),
  locations = "CA",
  time_type = "week",
  time_values = epirange(201501, 202001)
)

## End(Not run)

helper to convert an epirange from week to day or vice versa

Description

helper to convert an epirange from week to day or vice versa

Usage

reformat_epirange(epirange, to_type = c("day", "week"))

inserts each string as a bullet at the end of the "Prepare for release" section

Description

inserts each string as a bullet at the end of the "Prepare for release" section

Usage

release_bullets()

Fetches the data.

Description

Raises on errors from the API. Returns JSON.

Usage

request_epidata(epidata_call, fetch_args = fetch_args_list(), simplify = TRUE)

Arguments

Value

• For request_epidata: a JSON-like list

Returns the full request url for the given epidata_call

Description

Returns the full request url for the given epidata_call

Usage

request_url(epidata_call, format_type = "classic", fields = NULL)

Arguments

Value

• For request_url: string containing the URL

Create or renew a cache for this session

Description

By default, epidatr re-requests data from the API on every call of fetch. In case you find yourself repeatedly calling the same data, you can enable the cache using either this function for a given session, or environmental variables for a persistent cache. The typical recommended workflow for using the cache is to set the environmental variables EPIDATR_USE_CACHE=TRUE and EPIDATR_CACHE_DIRECTORY="/your/directory/here"in your .Renviron, for example by calling usethis::edit_r_environ(). See the parameters below for some more configurables if you're so inclined.

set_cache (re)defines the cache to use in a particular R session. This does not clear existing data at any previous location, but instead creates a handle to the new cache using cachem that seamlessly handles caching for you. Say your cache is normally stored in some default directory, but for the current session you want to save your results in ⁠~/my/temporary/savedirectory⁠, then you would call set_cache(dir = "~/my/temporary/savedirectory"). Or if you know the data from 2 days ago is wrong, you could call set_cache(days = 1) to clear older data whenever the cache is referenced. In both cases, these changes would only last for a single session (though the deleted data would be gone permanently!).

An important feature of the caching in this package is that only calls which specify either issues before a certain date, or as_of before a certain date will actually cache. For example the call

pub_covidcast(
  source = "jhu-csse",
  signals = "confirmed_7dav_incidence_prop",
  geo_type = "state",
  time_type = "day",
  geo_values = "ca,fl",
  time_values = epirange(20200601, 20230801)
)

won't cache, since it is possible for the cache to be invalidated by new releases with no warning. On the other hand, the call

pub_covidcast(
  source = "jhu-csse",
  signals = "confirmed_7dav_incidence_prop",
  geo_type = "state",
  time_type = "day",
  geo_values = "ca,fl",
  time_values = epirange(20200601, 20230801),
  as_of = "2023-08-01"
)

will cache, since normal new versions of data can't invalidate it (since they would be as_of a later date). It is still possible that Delphi may patch such data, but the frequency is on the order of months rather than days. We are working on creating a public channel to communicate such updates. While specifying issues will usually cache, a call with issues="*" won't cache, since its subject to cache invalidation by normal versioning.

On the backend, the cache uses cachem, with filenames generated using an md5 encoding of the call url. Each file corresponds to a unique epidata-API call.

Usage

set_cache(
  cache_dir = NULL,
  days = NULL,
  max_size = NULL,
  logfile = NULL,
  confirm = TRUE,
  startup = FALSE
)

Arguments

Value

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

See Also

clear_cache to delete the old cache while making a new one, disable_cache to disable without deleting, and cache_info

Examples

set_cache(
  cache_dir = tempdir(),
  days = 14,
  max_size = 512,
  logfile = "logs.txt"
)

Timeset formats for specifying dates

Description

Many API calls accept timesets to specify the time ranges of data being requested. Timesets can be specified with epirange(), as Date objects, or with wildcards.

Details

Timesets are not special R types; the term simply describes any value that is accepted by epidatr to specify the time value of an epidata query:

• Dates: Date instances.

• Date strings or integers: Strings or integers in the format YYYYMMDD.

• Epiweeks: Strings or integers in the format YYYYWW, where WW is the epiweek number.

• EpiRanges: A range returned by epirange(), or a list of multiple ranges.

• Wildcard: The string "*", which requests all available time values.

Refer to the specific endpoint documentation for guidance on using dates vs weeks. Most endpoints support only one or the other. Some (less commonly used) endpoints may not accept the "*" wildcard, but this can be simulated with a large epirange().

Validate and parse a date parameter

Description

Validate and parse a date parameter

Usage

validate_date_input(name, value, len = NULL, required = TRUE)

Validate and parse a timeset parameter

Description

Validate and parse a timeset parameter

Usage

validate_timeset_input(name, value, len = NULL, required = TRUE)

Helper to format the 'version' argument for the CAST API version_query

Description

Helper to format the 'version' argument for the CAST API version_query

Usage

validate_version_query(version)

Arguments

Value

a formatted version_query string (e.g., "<2025-10-16", "=2025-10-16")

epidata_call object using a different base URL

Description

epidata_call object using a different base URL

Usage

with_base_url(epidata_call, base_url)

Arguments

Value

an epidata_call object