# Get started with covidcast

This package provides access to data frames of values from the COVIDcast API. Using the `covidcast_signal()` function, you can fetch any data you may be interested in analyzing, then use `plot.covidcast_signal()` to make plots and maps. Since the data is provided as a simple data frame, you can also wrangle it into whatever form you need to conduct your desired analyses using other packages and functions.

## Basic examples

To obtain smoothed estimates of COVID-like illness from our Facebook survey for every county in the United States between 2020-05-01 and 2020-05-07, we can use `covidcast_signal()`:

    library(covidcast)
    library(dplyr)

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

data_source | signal | geo_value | time_value | issue | lag | value | stderr | sample_size
--- | --- | --- | --- | --- | --- | --- | --- | ---
fb-survey | smoothed_cli | 01000 | 2020-05-01 | 2020-09-03 | 125 | 0.8254101 | 0.1360033 | 1722.4551
fb-survey | smoothed_cli | 01001 | 2020-05-01 | 2020-09-03 | 125 | 1.2994255 | 0.9671356 | 115.8025
fb-survey | smoothed_cli | 01003 | 2020-05-01 | 2020-09-03 | 125 | 0.6965968 | 0.3247531 | 584.3194
fb-survey | smoothed_cli | 01015 | 2020-05-01 | 2020-09-03 | 125 | 0.4282713 | 0.5485655 | 122.5577
fb-survey | smoothed_cli | 01031 | 2020-05-01 | 2020-09-03 | 125 | 0.0255788 | 0.3608268 | 114.8318
fb-survey | smoothed_cli | 01045 | 2020-05-01 | 2020-09-03 | 125 | 1.0495589 | 0.7086324 | 110.6544

`covidcast_signal()` returns a data frame. (Here we’re using `knitr::kable()` to make it more readable.) Each row represents one observation in one county on one day. The county FIPS code is given in the `geo_value` column, the date in the `time_value` column. Here `value` is the requested signal—in this case, the smoothed estimate of the percentage of people with COVID-like illness, based on the symptom surveys, and `stderr` is its standard error. See the `covidcast_signal()` documentation for details on the returned data frame.

Notice the use of `suppressMessages()` to hide progress reporting from the function as it downloads the data; if you download particularly large amounts of data, you may prefer to allow the progress reporting so you know how long to wait.

To get a basic summary of the returned data frame:

    summary(cli)

    ## A `covidcast_signal` dataframe with 7080 rows and 9 columns.
    ##
    ## data_source : fb-survey
    ## signal      : smoothed_cli
    ## geo_type    : county
    ##
    ## first date                          : 2020-05-01
    ## last date                           : 2020-05-07
    ## median number of geo_values per day : 1021

The COVIDcast API makes estimates available at several different geographic levels, and `covidcast_signal()` defaults to requesting county-level data. To request estimates for states instead of counties, we use the `geo_type` argument:

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

data_source | signal | geo_value | time_value | issue | lag | value | stderr | sample_size
--- | --- | --- | --- | --- | --- | --- | --- | ---
fb-survey | smoothed_cli | ak | 2020-05-01 | 2020-09-03 | 125 | 0.4607721 | 0.1591131 | 1606.000
fb-survey | smoothed_cli | al | 2020-05-01 | 2020-09-03 | 125 | 0.6994761 | 0.0826180 | 7540.244
fb-survey | smoothed_cli | ar | 2020-05-01 | 2020-09-03 | 125 | 0.7597720 | 0.1036828 | 4921.483
fb-survey | smoothed_cli | az | 2020-05-01 | 2020-09-03 | 125 | 0.5669361 | 0.0618211 | 11220.959
fb-survey | smoothed_cli | ca | 2020-05-01 | 2020-09-03 | 125 | 0.3649079 | 0.0228051 | 51870.138
fb-survey | smoothed_cli | co | 2020-05-01 | 2020-09-03 | 125 | 0.6458274 | 0.0684792 | 10105.894

One can also select a specific geographic region by its ID. For example, this is the FIPS code for Allegheny County, Pennsylvania:

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

data_source | signal | geo_value | time_value | issue | lag | value | stderr | sample_size
--- | --- | --- | --- | --- | --- | --- | --- | ---
fb-survey | smoothed_cli | 42003 | 2020-05-01 | 2020-09-03 | 125 | 0.3990346 | 0.1050942 | 2635.136
fb-survey | smoothed_cli | 42003 | 2020-05-02 | 2020-09-03 | 124 | 0.3804239 | 0.1073435 | 2589.751
fb-survey | smoothed_cli | 42003 | 2020-05-03 | 2020-09-03 | 123 | 0.3370994 | 0.1046873 | 2552.011
fb-survey | smoothed_cli | 42003 | 2020-05-04 | 2020-09-03 | 122 | 0.1359437 | 0.0638714 | 2568.443
fb-survey | smoothed_cli | 42003 | 2020-05-05 | 2020-09-03 | 121 | 0.1438750 | 0.0669286 | 2482.389
fb-survey | smoothed_cli | 42003 | 2020-05-06 | 2020-09-03 | 120 | 0.2492732 | 0.0890122 | 2530.457

### Plotting and mapping

This package provides convenient functions for plotting and mapping these signals. For example, simple line charts are easy to construct:

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

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

### Finding signals of interest

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

The COVIDcast Data Sources and Signals documentation lists all data sources and signals available through COVIDcast. When you find a signal of interest, get the data source name (such as `jhu-csse` or `fb-survey`) and the signal name (such as `confirmed_incidence_num` or `smoothed_wcli`). These are provided as arguments to `covidcast_signal()` to request the data you want.

### Finding counties and metro areas

The COVIDcast API identifies counties by their 5-digit FIPS code and metropolitan areas by their CBSA ID number. (See the geographic coding documentation for details.) This means that to query a specific county or metropolitan area, we must have some way to quickly find its identifier.

This package includes several utilities intended to make the process easier. For example, if we look at `?county_census`, we find that the package provides census data (such as population) on every county in the United States, including its FIPS code. Similarly, by looking at `?msa_census` we can find data about metropolitan statistical areas, their corresponding CBSA IDs, and recent census data.

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

Building on these datasets, the convenience functions `name_to_fips()` and `name_to_cbsa()` conduct `grep()`-based searching of county or metropolitan area names to 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 to construct the `geo_values` argument to `covidcast_signal()` to select specific regions to query.

You may also want to convert FIPS codes or CBSA IDs back to well-known names, for instance to report in tables or graphics. The package provides inverse mappings `county_fips_to_name()` and `cbsa_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 options for handling matches when counties have the same name).

## Signal metadata

If we are interested in exploring the available signals and their metadata, we can use `covidcast_meta()` to fetch a data frame of the available signals:

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

data_source | signal | time_type | geo_type | min_time | max_time | num_locations | min_value | max_value | mean_value | stdev_value | last_update | max_issue | min_lag | max_lag
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
chng | smoothed_adj_outpatient_cli | day | county | 2020-02-01 | 2021-04-26 | 3063 | 0.001303 | 99.92593 | 4.259104 | 7.234424 | 1619925727 | 2021-05-01 | 3 | 386
chng | smoothed_adj_outpatient_cli | day | hhs | 2020-02-01 | 2021-04-26 | 10 | 0.007255 | 15.21246 | 3.411312 | 2.743890 | 1619925730 | 2021-05-01 | 5 | 386
chng | smoothed_adj_outpatient_cli | day | hrr | 2020-02-01 | 2021-04-26 | 306 | 0.001360 | 50.81590 | 3.319890 | 3.342192 | 1619925730 | 2021-05-01 | 5 | 386
chng | smoothed_adj_outpatient_cli | day | msa | 2020-02-01 | 2021-04-26 | 392 | 0.001350 | 50.94313 | 2.994006 | 3.346190 | 1619925731 | 2021-05-01 | 5 | 386
chng | smoothed_adj_outpatient_cli | day | nation | 2020-02-01 | 2021-04-26 | 1 | 0.016727 | 10.39771 | 3.701778 | 2.395005 | 1619925731 | 2021-05-01 | 5 | 386
chng | smoothed_adj_outpatient_cli | day | state | 2020-02-01 | 2021-04-26 | 55 | 0.002476 | 29.55265 | 3.122229 | 2.908380 | 1619925732 | 2021-05-01 | 5 | 386

The `covidcast_meta()` documentation describes the columns and their meanings. The metadata data frame can be filtered and sliced as desired to obtain information about signals of interest. To get a basic summary of the metadata:

    summary(meta)

(We silenced the evaluation because the output of `summary()` here is still quite long.)

## Tracking issues and updates

The COVIDcast API records not just each signal’s estimate for a given location on a given day, but also when that estimate was made, and all updates to that estimate.

For example, consider using our doctor visits signal, which estimates the percentage of outpatient doctor visits that are COVID-related, and consider a result row with `time_value` 2020-05-01 for `geo_values = "pa"`. This is an estimate for the percentage in Pennsylvania on May 1, 2020. That estimate was issued on May 5, 2020, the delay being due to the aggregation of data by our source and the time taken by the COVIDcast API to ingest the data provided. Later, the estimate for May 1st could be updated, perhaps because additional visit data from May 1st arrived at our source and was reported to us. This constitutes a new issue of the data.

### Data known “as of” a specific date

By default, `covidcast_signal()` fetches the most recent issue available. This is the best option for users who simply want to graph the latest data or construct dashboards. But if we are interested in knowing when data was reported, we can request specific data versions using the `as_of`, `issues`, or `lag` arguments. (Note these are mutually exclusive; only one can be specified at a time.)

First, we can request the data that was available as of a specific date, using the `as_of` argument:

    covidcast_signal(data_source = "doctor-visits", signal = "smoothed_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 9 columns.
    ##
    ## data_source : doctor-visits
    ## signal      : smoothed_cli
    ## geo_type    : state
    ##
    ##     data_source       signal geo_value time_value      issue lag   value stderr
    ## 1 doctor-visits smoothed_cli        pa 2020-05-01 2020-05-07   6 2.32192     NA
    ##   sample_size
    ## 1          NA

This shows that an estimate of about 2.3% was issued on May 7. If we don’t specify `as_of`, we get the most recent estimate available:

    covidcast_signal(data_source = "doctor-visits", signal = "smoothed_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 9 columns.
    ##
    ## data_source : doctor-visits
    ## signal      : smoothed_cli
    ## geo_type    : state
    ##
    ##     data_source       signal geo_value time_value      issue lag    value
    ## 1 doctor-visits smoothed_cli        pa 2020-05-01 2020-07-04  64 5.075015
    ##   stderr sample_size
    ## 1     NA          NA

Note the substantial change in the estimate, to over 5%, reflecting new data that became available after May 7 about visits occurring on May 1. This illustrates the importance of issue date tracking, particularly for forecasting tasks. To backtest a forecasting model on past data, it is important to use the data that would have been available at the time, not data that arrived much later.

### Multiple issues of observations

By using the `issues` argument, we can request all issues in a certain time period:

    covidcast_signal(data_source = "doctor-visits", signal = "smoothed_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()

data_source | signal | geo_value | time_value | issue | lag | value | stderr | sample_size
--- | --- | --- | --- | --- | --- | --- | --- | ---
doctor-visits | smoothed_cli | pa | 2020-05-01 | 2020-05-07 | 6 | 2.321920 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-01 | 2020-05-08 | 7 | 2.897032 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-01 | 2020-05-09 | 8 | 2.956456 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-01 | 2020-05-12 | 11 | 3.190634 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-01 | 2020-05-13 | 12 | 3.220023 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-01 | 2020-05-14 | 13 | 3.231314 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-01 | 2020-05-15 | 14 | 3.239970 | NA | NA

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

After fetching multiple issues of data, we can use the `latest_issue()` or `earliest_issue()` functions to subset the data frame to view only the latest or earliest issue of each observation.

### Observations issued with a specific lag

Finally, we can use the `lag` argument to request only data reported with a certain lag. For example, requesting a lag of 7 days means to request only issues 7 days after the corresponding `time_value`:

    covidcast_signal(data_source = "doctor-visits", signal = "smoothed_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-03, 2020-05-04

data_source | signal | geo_value | time_value | issue | lag | value | stderr | sample_size
--- | --- | --- | --- | --- | --- | --- | --- | ---
doctor-visits | smoothed_cli | pa | 2020-05-01 | 2020-05-08 | 7 | 2.897032 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-02 | 2020-05-09 | 7 | 2.802238 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-05 | 2020-05-12 | 7 | 3.483125 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-06 | 2020-05-13 | 7 | 2.968670 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-07 | 2020-05-14 | 7 | 2.400255 | NA | NA

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

    covidcast_signal(data_source = "doctor-visits", signal = "smoothed_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()

data_source | signal | geo_value | time_value | issue | lag | value | stderr | sample_size
--- | --- | --- | --- | --- | --- | --- | --- | ---
doctor-visits | smoothed_cli | pa | 2020-05-03 | 2020-05-09 | 6 | 2.749537 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-03 | 2020-05-12 | 9 | 2.989626 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-03 | 2020-05-13 | 10 | 3.006860 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-03 | 2020-05-14 | 11 | 2.970561 | NA | NA
doctor-visits | smoothed_cli | pa | 2020-05-03 | 2020-05-15 | 12 | 3.038054 | NA | NA