| Type: | Package |
| Title: | Client for Delphi's 'Epidata' API |
| Version: | 1.2.1 |
| 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. |
| License: | MIT + file LICENSE |
| URL: | https://cmu-delphi.github.io/epidatr/, https://cmu-delphi.github.io/delphi-epidata/, https://github.com/cmu-delphi/epidatr |
| BugReports: | https://github.com/cmu-delphi/epidatr/issues |
| Depends: | R (≥ 3.5.0) |
| Imports: | cachem, checkmate, cli, glue, httr, jsonlite, magrittr, MMWRweek, openssl, purrr, rappdirs, readr, rlang, tibble, usethis, xml2 |
| Suggests: | dplyr, ggplot2, knitr, mapproj, maps, rmarkdown, testthat (≥ 3.1.5), withr |
| VignetteBuilder: | knitr |
| Config/Needs/website: | cmu-delphi/delphidocs |
| Config/testthat/edition: | 3 |
| Encoding: | UTF-8 |
| Language: | en-US |
| RoxygenNote: | 7.3.2 |
| Collate: | 'auth.R' 'avail_endpoints.R' 'cache.R' 'check.R' 'constants.R' 'covidcast.R' 'endpoints.R' 'epidatacall.R' 'epidatr-package.R' 'model.R' 'request.R' 'utils-pipe.R' 'utils.R' |
| NeedsCompilation: | no |
| Packaged: | 2025-03-20 18:43:51 UTC; dsweber |
| Author: | 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 <davidweb@andrew.cmu.edu> |
| Repository: | CRAN |
| Date/Publication: | 2025-03-20 19:00:02 UTC |
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:
Report bugs at https://github.com/cmu-delphi/epidatr/issues
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:
Endpoint |
Name of the function for accessing this API endpoint. |
Description |
One-sentence description of the data available at the endpoint. |
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
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
epidata_call |
the |
fetch_args |
the args list for fetch as generated by |
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
... |
Arguments passed on to
|
disable |
instead of setting a new cache, disable caching entirely;
defaults to |
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: 468 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 458 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
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())
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 |
fetch_args |
a |
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: anepidata_callobject
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)
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 |
date (integer or character, with format YYYYMMDD) to be converted to an epiweek |
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 the request
Description
You can test the authentication headers like so:
Usage
do_request(url, params, timeout_seconds)
Examples
## Not run:
response <- httr::RETRY(
"GET", "https://httpbin.org/headers",
httr::authenticate("epidata", "fake_key")
)
content(response)$headers$Authorization == paste0(
"Basic ",
base64enc::base64encode(charToRaw("epidata:fake_key"))
)
## End(Not run)
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
from |
The first date to request. Can be specified as a |
to |
The final date to request (inclusive), specified the same way as
|
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 = FALSE,
format_type = c("json", "classic", "csv"),
refresh_cache = FALSE
)
Arguments
... |
not used for values, forces later arguments to bind by name |
fields |
a list of epidata fields to return, or |
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 |
dry_run |
if |
debug |
if |
format_type |
the format to request from the API, one of classic, json,
csv; this is only used by |
refresh_cache |
if |
Value
A fetch_args object containing all the specified options
Fetches the data, raises on epidata errors, and returns the results as a JSON-like list
Description
Fetches the data, raises on epidata errors, and returns the results as a JSON-like list
Usage
fetch_classic(epidata_call, fetch_args = fetch_args_list())
Arguments
epidata_call |
an instance of |
fetch_args |
a |
Value
For
fetch_classic: a JSON-like list
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 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
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)
Arguments
value |
value to be converted to an epiweek |
Value
a date
turn a signal into a callable
Description
turn a signal into a callable
Usage
parse_signal(signal, base_url)
Arguments
signal |
the signal of interest |
base_url |
the base url |
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
hospital_pks |
character. Facility identifiers. |
collection_weeks |
|
... |
not used for values, forces later arguments to bind by name |
publication_dates |
|
fetch_args |
|
Details
Starting October 1, 2022, some facilities are only required to report annually.
Value
See Also
pub_covid_hosp_facility(), epirange()
Examples
## Not run:
pub_covid_hosp_facility(
hospital_pks = "100075",
collection_weeks = epirange(20200101, 20200501)
)
pub_covid_hosp_facility(
hospital_pks = "050063",
collection_weeks = epirange(20240101, 20240301)
)
## End(Not run)
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
... |
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 |
|
Details
Only one location argument needs to be specified. Combinations of the arguments are not currently supported.
Value
See Also
Examples
## Not run:
pub_covid_hosp_facility_lookup(state = "fl")
pub_covid_hosp_facility_lookup(city = "southlake")
## End(Not run)
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
states |
character. Two letter state abbreviations. |
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 |
|
fetch_args |
|
Details
Starting October 1, 2022, some facilities are only required to report annually.
Value
Examples
## Not run:
pub_covid_hosp_state_timeseries(
states = "fl",
dates = epirange(20200101, 20200501)
)
## End(Not run)
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
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 |
|
... |
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 |
|
lag |
integer. Optionally, the lag of the issues to fetch. If not set,
the most recent issue is returned. Mutually exclusive with |
fetch_args |
|
Value
See Also
pub_covidcast_meta(), covidcast_epidata(), epirange()
Examples
## Not run:
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)
)
## End(Not run)
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.
Usage
pub_covidcast_meta(fetch_args = fetch_args_list())
Arguments
fetch_args |
|
Value
See Also
pub_covidcast(),covidcast_epidata()
Examples
## Not run:
pub_covidcast_meta()
## End(Not run)
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
system |
character. System name to fetch. |
epiweek |
|
fetch_args |
|
Value
Examples
## Not run:
pub_delphi(system = "ec", epiweek = 201501)
## End(Not run)
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
locations |
character. Locations to fetch. |
epiweeks |
|
fetch_args |
|
Value
Examples
## Not run:
pub_dengue_nowcast(
locations = "pr",
epiweeks = epirange(201401, 202301)
)
## End(Not run)
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
regions |
character. Regions to fetch. |
epiweeks |
|
... |
not used for values, forces later arguments to bind by name |
issues |
|
lag |
integer. Optionally, the lag of the issues to fetch. If not set,
the most recent issue is returned. Mutually exclusive with |
fetch_args |
|
Details
The list of location argument can be found in https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/ecdc_regions.txt.
Value
Examples
## Not run:
pub_ecdc_ili(regions = "austria", epiweeks = epirange(201901, 202001))
## End(Not run)
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
locations |
character. Character vector indicating location. |
epiweeks |
|
... |
not used for values, forces later arguments to bind by name |
issues |
|
lag |
integer. Optionally, the lag of the issues to fetch. If not set,
the most recent issue is returned. Mutually exclusive with |
fetch_args |
|
Details
The list of location argument can be found in https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/flusurv_locations.txt.
Value
Examples
## Not run:
pub_flusurv(locations = "CA", epiweeks = epirange(201701, 201801))
## End(Not run)
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
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 |
|
... |
not used for values, forces later arguments to bind by name |
issues |
|
lag |
integer. Optionally, the lag of the issues to fetch. If not set,
the most recent issue is returned. Mutually exclusive with |
auth |
string. Optionally, restricted access key (not the same as API key). |
fetch_args |
|
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
Examples
## Not run:
pub_fluview(regions = "nat", epiweeks = epirange(201201, 202005))
## End(Not run)
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
regions |
character. Regions to fetch. |
epiweeks |
|
... |
not used for values, forces later arguments to bind by name |
issues |
|
lag |
integer. Optionally, the lag of the issues to fetch. If not set,
the most recent issue is returned. Mutually exclusive with |
fetch_args |
|
Value
Examples
## Not run:
pub_fluview_clinical(regions = "nat", epiweeks = epirange(201601, 201701))
## End(Not run)
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
fetch_args |
|
Value
See Also
Examples
## Not run:
pub_fluview_meta()
## End(Not run)
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
locations |
character. Locations to fetch. |
epiweeks |
|
fetch_args |
|
Details
Google has discontinued Flu Trends and this is now a static endpoint. Possibile input for locations can be found in https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/regions.txt, https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/states.txt, and https://github.com/cmu-delphi/delphi-epidata/blob/main/labels/cities.txt.
Value
Examples
## Not run:
pub_gft(locations = "hhs1", epiweeks = epirange(201201, 202001))
## End(Not run)
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
regions |
character. Regions to fetch. |
epiweeks |
|
... |
not used for values, forces later arguments to bind by name |
issues |
|
lag |
integer. Optionally, the lag of the issues to fetch. If not set,
the most recent issue is returned. Mutually exclusive with |
fetch_args |
|
Value
Examples
## Not run:
pub_kcdc_ili(regions = "ROK", epiweeks = 200436)
## End(Not run)
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
fetch_args |
|
Value
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
locations |
character. Locations to fetch. |
epiweeks |
|
fetch_args |
|
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
Examples
## Not run:
pub_nidss_dengue(locations = "taipei", epiweeks = epirange(201201, 201301))
## End(Not run)
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
regions |
character. Regions to fetch. |
epiweeks |
|
... |
not used for values, forces later arguments to bind by name |
issues |
|
lag |
integer. Optionally, the lag of the issues to fetch. If not set,
the most recent issue is returned. Mutually exclusive with |
fetch_args |
|
Value
Examples
## Not run:
pub_nidss_flu(regions = "taipei", epiweeks = epirange(201501, 201601))
## End(Not run)
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
locations |
character. Locations to fetch. |
epiweeks |
|
fetch_args |
|
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
Examples
## Not run:
pub_nowcast(locations = "ca", epiweeks = epirange(201201, 201301))
## End(Not run)
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
regions |
character. Regions to fetch. |
epiweeks |
|
... |
not used for values, forces later arguments to bind by name |
issues |
|
lag |
integer. Optionally, the lag of the issues to fetch. If not set,
the most recent issue is returned. Mutually exclusive with |
fetch_args |
|
Value
Examples
## Not run:
pub_paho_dengue(regions = "ca", epiweeks = epirange(201401, 201501))
## End(Not run)
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
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 |
|
hours |
integer. Optionally, the hours to fetch. |
language |
string. Language to fetch. |
fetch_args |
|
Value
Examples
## Not run:
pub_wiki(
articles = "avian_influenza",
time_type = "week",
time_values = epirange(201501, 201601)
)
## End(Not run)
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
auth |
string. Restricted access key (not the same as API key). |
locations |
character. Locations to fetch. |
epiweeks |
|
fetch_args |
|
Value
Examples
## Not run:
pvt_cdc(
auth = Sys.getenv("SECRET_API_AUTH_CDC"),
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
auth |
string. Restricted access key (not the same as API key). |
names |
character. Names to fetch. |
locations |
character. Locations to fetch. |
epiweeks |
|
fetch_args |
|
Value
Examples
## Not run:
pvt_dengue_sensors(
auth = Sys.getenv("SECRET_API_AUTH_SENSORS"),
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
auth |
string. Restricted access key (not the same as API key). |
locations |
character. Locations to fetch. |
epiweeks |
|
query |
string. The query to be fetched. |
fetch_args |
|
Value
Examples
## Not run:
pvt_ght(
auth = Sys.getenv("SECRET_API_AUTH_GHT"),
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
auth |
string. Restricted access key (not the same as API key). |
fetch_args |
|
Value
See Also
Examples
## Not run:
pvt_meta_norostat(auth = Sys.getenv("SECRET_API_AUTH_NOROSTAT"))
## 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
auth |
string. Your authentication key. |
locations |
character. Locations to fetch. |
epiweeks |
|
fetch_args |
|
Value
Examples
## Not run:
pvt_norostat(
auth = Sys.getenv("SECRET_API_AUTH_NOROSTAT"),
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
auth |
string. Restricted access key (not the same as API key). |
locations |
character. Locations to fetch. |
epiweeks |
|
fetch_args |
|
Value
Examples
## Not run:
pvt_quidel(
auth = Sys.getenv("SECRET_API_AUTH_QUIDEL"),
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
auth |
string. Restricted access key (not the same as API key). |
names |
character. Sensor names to fetch. |
locations |
character. Locations to fetch. |
epiweeks |
|
fetch_args |
|
Value
Examples
## Not run:
pvt_sensors(
auth = Sys.getenv("SECRET_API_AUTH_SENSORS"),
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
auth |
string. Restricted access key (not the same as API key). |
locations |
character. Locations 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 |
|
fetch_args |
|
Value
Examples
## Not run:
pvt_twitter(
auth = Sys.getenv("SECRET_API_AUTH_TWITTER"),
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()
Makes a request to the API and returns the response, catching HTTP errors and forwarding the HTTP body in R errors
Description
Makes a request to the API and returns the response, catching HTTP errors and forwarding the HTTP body in R errors
Usage
request_impl(epidata_call, format_type, timeout_seconds, fields)
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
epidata_call |
an instance of |
format_type |
format to return one of classic,json,csv |
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 |
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
cache_dir |
the directory in which the cache is stored. By default, this
is |
days |
the maximum length of time in days to keep any particular cached
call. By default this is |
max_size |
the size of the entire cache, in MB, at which to start
pruning entries. By default this is |
logfile |
where cachem's log of transactions is stored, relative to the
cache directory. By default, it is |
confirm |
whether to confirm directory creation. default is |
startup |
indicates whether the function is being called on
startup. Affects suppressability of the messages. Default is |
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:
Dateinstances.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().
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
epidata_call |
an instance of |
base_url |
base URL to use |
Value
an epidata_call object