Merge branch 'docs/1.11' into safegraph_pattern_api_docs

Author: krivard

README.md

@@ -8,26 +8,22 @@ This is the home of [Delphi](https://delphi.cmu.edu/)'s epidemiological data
 API. See our [API documentation](https://cmu-delphi.github.io/delphi-epidata/)
 for details on the available data sets, APIs, and clients.
 
-# COVID-19 Notice
+## COVIDcast
 
-We are working on collecting several new data sources that may be useful for
-nowcasting and forecasting ILI during the COVID-19 pandemic.  Each of these will
-make these available as soon as individually possible, through our [covidcast
-endpoint](https://cmu-delphi.github.io/delphi-epidata/api/covidcast.html).
+At the present, our primary focus is developing and expanding the
+[COVIDcast API](https://cmu-delphi.github.io/delphi-epidata/api/covidcast.html),
+which offers a number of data streams relating to the ongoing COVID-19
+pandemic and powers the [COVIDcast project](https://covidcast.cmu.edu/).
 
-For a list of many other data sources relevant to COVID-19, publicly available
-through external sites, we have compiled a simple
-[spreadsheet](https://docs.google.com/spreadsheets/d/16Nn_3ZvSLnpxRyA2DkoMMzyrd11-AlGJXasS0owln88/edit#gid=0).
+Our other, non-COVID data sources remain generally available on a best-effort
+basis. However, non-COVID sources should be held to scrutiny at this time since
+they were designed to serve as indicators of typical seasonal ILI
+(influenza-like illness), not pandemic ILI or CLI (COVID-like illness).
 
-**Note:** apart from the COVID-19-specific data sources described above, the
-rest of this repository was built to support modeling and forecasting efforts
-surrounding seasonal influenza (and dengue).  All other data sources than those
-in our covidcast endpoint should be **held to great scrutiny** (if they are even
-to be considered at all in this pandemic period), since they were designed to
-serve as indicators of typical seasonal ILI (influenza-like illness), and
-certainly not pandemic ILI or CLI (covid-like illness).
+For a high-level introduction to the COVIDcast API, see our recent
+[blog post](https://delphi.cmu.edu/blog/2020/10/07/accessing-open-covid-19-data-via-the-covidcast-epidata-api/).
 
-## Contributing
+# Contributing
 
 If you are interested in contributing:
 
@@ -37,36 +33,19 @@ If you are interested in contributing:
   [open an issue](https://github.com/cmu-delphi/delphi-epidata/issues/new)
   describing your idea.
 
-## Citing
+# Citing
 
 We hope that this API is useful to others outside of our group, especially for
 epidemiological and other scientific research. If you use this API and would
 like to cite it, we would gratefully recommend the following copy:
 
 > David C. Farrow,
 > Logan C. Brooks,
-> Aaron Rumack,
 > Ryan J. Tibshirani,
 > Roni Rosenfeld
 > (2015).
 > _Delphi Epidata API_.
 > https://github.com/cmu-delphi/delphi-epidata
 
-# Related work
-
- - Cook, Samantha, et al. "Assessing Google flu trends performance in the United
-   States during the 2009 influenza virus A (H1N1) pandemic." PloS one 6.8
-   (2011): e23610.
- - Broniatowski, David A., Michael J. Paul, and Mark Dredze. "National and local
-   influenza surveillance through Twitter: an analysis of the 2012-2013
-   influenza epidemic." (2013): e83672.
- - Dredze, Mark, et al. "HealthTweets. org: A Platform for Public Health
-   Surveillance using Twitter." AAAI Conference on Artificial
-   Intelligence. 2014.
- - Generous, Nicholas, et al. "Global disease monitoring and forecasting with
-   Wikipedia." (2014): e1003892.
- - Hickmann, Kyle S., et al. "Forecasting the 2013–2014 Influenza Season Using
-   Wikipedia." (2015): e1004239.
- - McIver, David J., and John S. Brownstein. "Wikipedia usage estimates
-   prevalence of influenza-like illness in the United States in near real-time."
-   PLoS Comput Biol 10.4 (2014): e1003581.
+See [related work](docs/related_work.md) for a sample of additional work in
+this area.

docs/api/README.md

@@ -1,13 +1,14 @@
 ---
-title: Delphi Epidata API
+title: Epidata API (Other Epidemics)
 nav_order: 3
 has_children: true
 ---
 
 # Delphi Epidata API
 
 This is the home of [Delphi](https://delphi.cmu.edu/)'s epidemiological data
-API.
+API for tracking epidemics such as influenza, dengue, and norovirus. Note that
+our work on COVID-19 is available in the [COVIDcast Epidata API documentation](covidcast.md).
 
 ## Contributing
 

docs/api/afhsb.md

@@ -1,6 +1,6 @@
 ---
 title: AFHSB
-parent: Delphi Epidata API
+parent: Epidata API (Other Epidemics)
 ---
 
 # AFHSB

docs/api/cdc.md

@@ -1,6 +1,6 @@
 ---
 title: CDC
-parent: Delphi Epidata API
+parent: Epidata API (Other Epidemics)
 ---
 
 # CDC

docs/api/covidcast-signals/_source-template.md

@@ -1,7 +1,7 @@
 ---
 title: SOURCE NAME
 parent: Data Sources and Signals
-grand_parent: COVIDcast API
+grand_parent: COVIDcast Epidata API
 ---
 
 # SOURCE NAME

docs/api/covidcast-signals/doctor-visits.md

@@ -1,15 +1,15 @@
 ---
 title: Doctor Visits
 parent: Data Sources and Signals
-grand_parent: COVIDcast API
+grand_parent: COVIDcast Epidata API
 ---
 
 # Doctor Visits
 {: .no_toc}
 
 * **Source name:** `doctor-visits`
-* **Number of data revisions since 19 May 2020:** 0
-* **Date of last change:** Never
+* **Number of data revisions since 19 May 2020:** 1
+* **Date of last change:** 9 November 2020
 * **Available for:** county, hrr, msa, state (see [geography coding docs](../covidcast_geography.md))
 
 This data source is based on information about outpatient visits, provided to us

docs/api/covidcast-signals/fb-survey.md

@@ -1,7 +1,7 @@
 ---
 title: Symptom Surveys
 parent: Data Sources and Signals
-grand_parent: COVIDcast API
+grand_parent: COVIDcast Epidata API
 ---
 
 # Symptom Surveys
@@ -30,13 +30,6 @@ described in the sections below:
 3. [Testing indicators](#testing-indicators) based on respondent reporting of
    their COVID test results
 
-For most `raw_` signals below, there are additional signals with names beginning
-with `smoothed_`. These estimate the same quantities as the above signals, but
-are smoothed in time to reduce day-to-day sampling noise; see [details
-below](#smoothing). Crucially, because the smoothed signals combine information
-across multiple days, they have larger sample sizes and hence are available for
-more counties and MSAs than the raw signals.
-
 ## Table of contents
 {: .no_toc .text-delta}
 
@@ -84,14 +77,14 @@ influenza-like illness (fever, along with cough or sore throat). Using this
 survey data, we estimate the percentage of people who have a COVID-like illness,
 or influenza-like illness, in a given location, on a given day.
 
-| Signal | Description |
+| Signals | Description |
 | --- | --- |
-| `raw_cli` | Estimated percentage of people with COVID-like illness based on the [criteria below](#ili-and-cli-indicators), with no smoothing or survey weighting |
-| `raw_ili` | Estimated percentage of people with influenza-like illness based on the [criteria below](#ili-and-cli-indicators), with no smoothing or survey weighting |
-| `raw_wcli` | Estimated percentage of people with COVID-like illness; adjusted using survey weights [as described below](#survey-weighting) |
-| `raw_wili` | Estimated percentage of people with influenza-like illness; adjusted using survey weights [as described below](#survey-weighting) |
-| `raw_hh_cmnty_cli` | Estimated percentage of people reporting illness in their local community, as [described below](#estimating-community-cli), including their household, with no smoothing or survey weighting |
-| `raw_nohh_cmnty_cli` | Estimated percentage of people reporting illness in their local community, as [described below](#estimating-community-cli), not including their household, with no smoothing or survey weighting |
+| `raw_cli` and `smoothed_cli` | Estimated percentage of people with COVID-like illness based on the [criteria below](#ili-and-cli-indicators), with no survey weighting |
+| `raw_ili` and `smoothed_ili` | Estimated percentage of people with influenza-like illness based on the [criteria below](#ili-and-cli-indicators), with no survey weighting |
+| `raw_wcli` and `smoothed_wcli` | Estimated percentage of people with COVID-like illness; adjusted using survey weights [as described below](#survey-weighting) |
+| `raw_wili` and `smoothed_wili` | Estimated percentage of people with influenza-like illness; adjusted using survey weights [as described below](#survey-weighting) |
+| `raw_hh_cmnty_cli` and `smoothed_hh_cmnty_cli` | Estimated percentage of people reporting illness in their local community, as [described below](#estimating-community-cli), including their household, with no survey weighting |
+| `raw_nohh_cmnty_cli` and `smoothed_nohh_cmnty_cli` | Estimated percentage of people reporting illness in their local community, as [described below](#estimating-community-cli), not including their household, with no survey weighting |
 
 Note that for `raw_hh_cmnty_cli` and `raw_nohh_cmnty_cli`, the illnesses
 included are broader: a respondent is included if they know someone in their
@@ -115,6 +108,12 @@ can be asymptomatic. Instead, we expect these indicators to be useful for
 comparison across the United States and across time, to determine where symptoms
 appear to be increasing.
 
+**Smoothing.** The signals beginning with `smoothed_` estimate the same quantities as their
+`raw` partners, but are smoothed in time to reduce day-to-day sampling noise;
+see [details below](#smoothing). Crucially, because the smoothed signals combine
+information across multiple days, they have larger sample sizes and hence are
+available for more counties and MSAs than the raw signals.
+
 ### Defining Household ILI and CLI
 
 For a single survey, we are interested in the quantities:
@@ -268,9 +267,9 @@ problematic.
 
 ### Smoothing
 
-The smoothed versions of the signals described above (with `smoothed_` prefix)
-are calculated using seven day pooling. For example, the estimate reported for
-June 7 in a specific geographical area (such as county or MSA) is formed by
+The smoothed versions of all `fb-survey` signals (with `smoothed_` prefix) are
+calculated using seven day pooling. For example, the estimate reported for June
+7 in a specific geographical area (such as county or MSA) is formed by
 collecting all surveys completed between June 1 and 7 (inclusive) and using that
 data in the estimation procedures described above.
 

docs/api/covidcast-signals/ght.md

@@ -1,7 +1,7 @@
 ---
 title: Google Health Trends
 parent: Data Sources and Signals
-grand_parent: COVIDcast API
+grand_parent: COVIDcast Epidata API
 ---
 
 # Google Health Trends

docs/api/covidcast-signals/google-survey.md

@@ -1,7 +1,7 @@
 ---
 title: Google Symptom Surveys
 parent: Inactive Signals
-grand_parent: COVIDcast API
+grand_parent: COVIDcast Epidata API
 ---
 
 # Google Symptom Surveys

docs/api/covidcast-signals/hospital-admissions.md

@@ -1,16 +1,16 @@
 ---
 title: Hospital Admissions
 parent: Data Sources and Signals
-grand_parent: COVIDcast API
+grand_parent: COVIDcast Epidata API
 ---
 
 # Hospital Admissions
 {: .no_toc}
 
 * **Source name:** `hospital-admissions`
 * **First issued:** June 30, 2020
-* **Number of data revisions since 19 May 2020:** 0
-* **Date of last change:** Never
+* **Number of data revisions since 19 May 2020:** 1
+* **Date of last change:** 20 October 2020
 * **Available for:** county, hrr, msa, state (see [geography coding docs](../covidcast_geography.md))
 
 This data source is based on electronic medical records and claims data about

docs/api/covidcast-signals/indicator-combination.md

@@ -1,7 +1,7 @@
 ---
 title: Indicator Combination
 parent: Data Sources and Signals
-grand_parent: COVIDcast API
+grand_parent: COVIDcast Epidata API
 ---
 
 # Indicator Combination

docs/api/covidcast-signals/jhu-csse.md

@@ -1,7 +1,7 @@
 ---
 title: JHU Cases and Deaths
 parent: Data Sources and Signals
-grand_parent: COVIDcast API
+grand_parent: COVIDcast Epidata API
 ---
 
 # JHU Cases and Deaths

docs/api/covidcast-signals/quidel.md

@@ -1,7 +1,7 @@
 ---
 title: Quidel
 parent: Data Sources and Signals
-grand_parent: COVIDcast API
+grand_parent: COVIDcast Epidata API
 ---
 
 # Quidel
@@ -18,8 +18,8 @@ grand_parent: COVIDcast API
 ## COVID-19 Tests
 
 * **First issued:** 27 July 2020 
-* **Number of data revisions since 19 May 2020:** 0
-* **Date of last change:** Never
+* **Number of data revisions since 19 May 2020:** 1
+* **Date of last change:** 22 October 2020
 * **Available for:** hrr, msa, state (see [geography coding docs](../covidcast_geography.md))
 
 Data source based on COVID-19 Antigen tests, provided to us by Quidel, Inc. When

docs/api/covidcast-signals/safegraph.md

@@ -1,7 +1,7 @@
 ---
 title: SafeGraph Mobility
 parent: Data Sources and Signals
-grand_parent: COVIDcast API
+grand_parent: COVIDcast Epidata API
 ---
 
 # SafeGraph
@@ -20,8 +20,8 @@ using anonymized location data from mobile phones. SafeGraph provides several di
 ## SafeGraph Social Distancing Metrics
 
 * **First issued:** 23 June 2020
-* **Number of data revisions since 23 June 2020:** 0
-* **Date of last change:** never
+* **Number of data revisions since 23 June 2020:** 1
+* **Date of last change:** 3 November 2020
 * **Available for:** county, state (see [geography coding docs](../covidcast_geography.md))
 
 Data source based on [social
@@ -43,6 +43,10 @@ documentation](https://docs.safegraph.com/docs/social-distancing-metrics).
 | `full_time_work_prop` | The fraction of mobile devices that spent more than 6 hours at a location other than their home during the daytime (SafeGraph's `full_time_work_behavior_devices / device_count`) |
 | `part_time_work_prop` | The fraction of devices that spent between 3 and 6 hours at a location other than their home during the daytime (SafeGraph's `part_time_work_behavior_devices / device_count`) |
 | `median_home_dwell_time` | The median time spent at home for all devices at this location for this time period, in minutes |
+| `completely_home_prop_7dav` | Offers a 7-day trailing window average of the `completely_home_prop`. |
+| `full_time_work_prop_7dav` | Offers a 7-day trailing window average of the`full_time_work_prop`. |
+| `part_time_work_prop_7dav` | Offers a 7-day trailing window average of the`part_time_work_prop`.|
+| `median_home_dwell_time_7dav` | Offers a 7-day trailing window average of the `median_home_dwell_time`.|
 
 After computing each metric on the census block group (CBG) level, we aggregate
 to the county-level by taking the mean over CBGs in a county to obtain the value
@@ -52,6 +56,11 @@ doing so, we make the simplifying assumption that each CBG contributes an iid
 observation to the county-level distribution. `n` also serves as the sample
 size. The same method is used for aggregation to states.
 
+SafeGraph's signals measure mobility each day, which causes strong day-of-week effects:
+weekends have substantially different values than weekdays. Users interested in long-term
+trends, rather than mobility on one specific day, may prefer the `7dav` signals since
+averaging over the preceding 7 days removes these day-of-week effects.
+
 ### Lag
 
 SafeGraph provides this data with a three-day lag, meaning estimates for a

docs/api/covidcast-signals/usa-facts.md

@@ -1,15 +1,15 @@
 ---
 title: USAFacts Cases and Deaths
 parent: Data Sources and Signals
-grand_parent: COVIDcast API
+grand_parent: COVIDcast Epidata API
 ---
 
 # USAFacts Cases and Deaths
 {: .no_toc}
 
 * **Source name:** `usa-facts`
-* **Number of data revisions since 19 May 2020:** 1
-* **Date of last change:** [12 October 2020](../covidcast_changelog.md#usa-facts)
+* **Number of data revisions since 19 May 2020:** 2
+* **Date of last change:** [3 November 2020](../covidcast_changelog.md#usa-facts)
 * **Available for:** county, hrr, msa, state (see [geography coding docs](../covidcast_geography.md))
 
 This data source of confirmed COVID-19 cases and deaths is based on reports made

docs/api/covidcast.md

@@ -1,10 +1,10 @@
 ---
-title: COVIDcast API
+title: COVIDcast Epidata API
 has_children: true
 nav_order: 1
 ---
 
-# Delphi's COVIDcast API
+# COVIDcast Epidata API
 
 This is the documentation for accessing the Delphi's COVID-19 Surveillance
 Streams (`covidcast`) endpoint of [Delphi](https://delphi.cmu.edu/)'s