Package 'epidatr'

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

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

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

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

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

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

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

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

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)

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

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.

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

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

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

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

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",
)

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)

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

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

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

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

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

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

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

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)

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").

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

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

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

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

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

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)

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)

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)

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)

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)

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)

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)

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)

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

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