install.packages("covidcast")

library(covidcast)library(dplyr)cli<-covidcast_signal(data_source="fb-survey", signal="smoothed_wcli",                        start_day="2020-05-01", end_day="2020-05-07",                        geo_type="county")knitr::kable(head(cli))

summary(cli)

cli<-covidcast_signal(data_source="fb-survey", signal="smoothed_wcli",                        start_day="2020-05-01", end_day="2020-05-07",                        geo_type="state")knitr::kable(head(cli))

cli<-covidcast_signal(data_source="fb-survey", signal="smoothed_wcli",                        start_day="2020-05-01", end_day="2020-05-07",                        geo_type="county", geo_value="42003")knitr::kable(head(cli))

API keys

By default, this package submits queries to the API anonymously. Allthe examples in the package documentation are compatible with anonymoususe of the API, butthereare some limits on anonymous queries, including rate limits on thenumber of queries that can be submitted per hour. To lift these limits,see the “API keys” section of thecovidcast_signal()documentation for information on how to register for and use an APIkey.

Plotting and mapping

This package provides convenient functions for plotting and mappingthese signals. For example, simple line charts are easy toconstruct:

plot(cli, plot_type="line",     title="Survey results in Allegheny County, PA")

For more details and examples, including choropleth and bubble maps,seevignette("plotting-signals").

Finding signals of interest

Above we used data fromDelphi’s symptomsurveys, but the COVIDcast API includes numerous data streams:medical claims data, cases and deaths, mobility, and many others; newsignals are added regularly. This can make it a challenge to find thedata stream that you are most interested in.

TheCOVIDcastData Sources and Signals documentation lists all data sources andsignals available through COVIDcast. When you find a signal of interest,get the data source name (such asjhu-csse orfb-survey) and the signal name (such asconfirmed_incidence_num orsmoothed_wcli).These are provided as arguments tocovidcast_signal() torequest the data you want.

Finding counties and metro areas

The COVIDcast API identifies counties by their 5-digit FIPS code andmetropolitan areas by their CBSA ID number. (See thegeographiccoding documentation for details.) This means that to query aspecific county or metropolitan area, we must have some way to quicklyfind its identifier.

This package includes several utilities intended to make the processeasier. For example, if we look at?county_census, we findthat the package provides census data (such as population) on everycounty in the United States, including its FIPS code. Similarly, bylooking at?msa_census we can find data about metropolitanstatistical areas, their corresponding CBSA IDs, and recent censusdata.

(Note: themsa_census data includes types of area beyondmetropolitan statistical areas, including micropolitan statisticalareas. TheLSAD column identifies the type of each area.The COVIDcast API only provides estimates for metropolitan statisticalareas, not for their divisions or for micropolitan areas.)

Building on these datasets, the convenience functionsname_to_fips() andname_to_cbsa() conductgrep()-based searching of county or metropolitan area namesto find FIPS or CBSA codes, respectively:

name_to_fips("Allegheny")

Allegheny County          "42003"

name_to_cbsa("Pittsburgh")

Pittsburgh, PA        "38300"

Since these functions return vectors of IDs, we can use them toconstruct thegeo_values argument tocovidcast_signal() to select specific regions to query.

You may also want to convert FIPS codes or CBSA IDs back towell-known names, for instance to report in tables or graphics. Thepackage provides inverse mappingscounty_fips_to_name() andcbsa_to_name() that work in the analogous way:

county_fips_to_name("42003")

42003"Allegheny County"

cbsa_to_name("38300")

38300"Pittsburgh, PA"

See their documentation for more details (for example, the optionsfor handling matches when counties have the same name).

meta<-covidcast_meta()knitr::kable(head(meta))

summary(meta)

Data known “as of” a specific date

By default,covidcast_signal() fetches the most recentissue available. This is the best option for users who simply want tograph the latest data or construct dashboards. But if we are interestedin knowingwhen data was reported, we can request specific dataversions using theas_of,issues, orlag arguments. (Note these are mutually exclusive; only onecan be specified at a time.)

First, we can request the data that was availableas of aspecific date, using theas_of argument:

covidcast_signal(data_source="doctor-visits", signal="smoothed_adj_cli",                 start_day="2020-05-01", end_day="2020-05-01",                 geo_type="state", geo_values="pa", as_of="2020-05-07")

A `covidcast_signal` dataframe with 1 rows and 15 columns.data_source : doctor-visitssignal      : smoothed_adj_cligeo_type    : state    data_source           signal geo_value time_value        source geo_type1 doctor-visits smoothed_adj_cli        pa 2020-05-01 doctor-visits    state  time_type      issue lag missing_value missing_stderr missing_sample_size1       day 2020-05-07   6             0              5                   5     value stderr sample_size1 2.581509     NA          NA

This shows that an estimate of about 2.3% was issued on May 7. If wedon’t specifyas_of, we get the most recent estimateavailable:

covidcast_signal(data_source="doctor-visits", signal="smoothed_adj_cli",                 start_day="2020-05-01", end_day="2020-05-01",                 geo_type="state", geo_values="pa")

A `covidcast_signal` dataframe with 1 rows and 15 columns.data_source : doctor-visitssignal      : smoothed_adj_cligeo_type    : state    data_source           signal geo_value time_value        source geo_type1 doctor-visits smoothed_adj_cli        pa 2020-05-01 doctor-visits    state  time_type      issue lag missing_value missing_stderr missing_sample_size1       day 2020-07-04  64             0              5                   5     value stderr sample_size1 5.973572     NA          NA

Note the substantial change in the estimate, to over 5%, reflectingnew data that became availableafter May 7 about visitsoccurring on May 1. This illustrates the importance of issue datetracking, particularly for forecasting tasks. To backtest a forecastingmodel on past data, it is important to use the data that would have beenavailableat the time, not data that arrived much later.

Multiple issues of observations

By using theissues argument, we can request all issuesin a certain time period:

covidcast_signal(data_source="doctor-visits", signal="smoothed_adj_cli",                 start_day="2020-05-01", end_day="2020-05-01",                 geo_type="state", geo_values="pa",                 issues=c("2020-05-01","2020-05-15"))%>%knitr::kable()

This estimate was clearly updated many times as new data for May 1starrived. Note that these results include only data issued or updatedbetween 2020-05-01 and 2020-05-15. If a value was first reported on2020-04-15, and never updated, a query for issues between 2020-05-01 and2020-05-15 will not include that value among its results.

After fetching multiple issues of data, we can use thelatest_issue() orearliest_issue() functionsto subset the data frame to view only the latest or earliest issue ofeach observation.

Observations issued with a specific lag

Finally, we can use thelag argument to request onlydata reported with a certain lag. For example, requesting a lag of 7days means to request only issues 7 days after the correspondingtime_value:

covidcast_signal(data_source="doctor-visits", signal="smoothed_adj_cli",                 start_day="2020-05-01", end_day="2020-05-07",                 geo_type="state", geo_values="pa", lag=7)%>%knitr::kable()

Warning: Data not fetched for the following days: 2020-05-01

Note that though this query requested all values between 2020-05-01and 2020-05-07, May 3rd and May 4th werenot included in theresults set. This is because the query will only include a result forMay 3rd if a value were issued on May 10th (a 7-day lag), but in factthe value was not updated on that day:

covidcast_signal(data_source="doctor-visits", signal="smoothed_adj_cli",                 start_day="2020-05-03", end_day="2020-05-03",                 geo_type="state", geo_values="pa",                 issues=c("2020-05-09","2020-05-15"))%>%knitr::kable()