Merge pull request #2 from cmu-delphi/main

sync

Author: chinandrew

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

@@ -12,6 +12,7 @@ grand_parent: COVIDcast Epidata API
 * **Number of data revisions since 19 May 2020:** 0
 * **Date of last change:** Never
 * **Available for:** county, hrr, msa, state (see [geography coding docs](../covidcast_geography.md))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 * **License:** [LICENSE NAME](../covidcast_licensing.md#APPLICABLE-SECTION)
 
 A brief description of what this source measures.

docs/api/covidcast-signals/chng.md

@@ -12,6 +12,7 @@ grand_parent: COVIDcast Epidata API
 * **Number of data revisions since 19 May 2020:** 0
 * **Date of last change:** Never
 * **Available for:** county, hrr, msa, state (see [geography coding docs](../covidcast_geography.md))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 * **License:** [CC BY-NC](../covidcast_licensing.md#creative-commons-attribution-noncommercial)
 
 This data source is based on Change Healthcare claims data that has been

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

@@ -11,6 +11,7 @@ grand_parent: COVIDcast Epidata API
 * **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))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 * **License:** [CC BY](../covidcast_licensing.md#creative-commons-attribution)
 
 This data source is based on information about outpatient visits, provided to us

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

@@ -11,6 +11,7 @@ grand_parent: COVIDcast Epidata API
 * **Number of data revisions since 19 May 2020:** 1
 * **Date of last change:** [3 June 2020](../covidcast_changelog.md#fb-survey)
 * **Available for:** county, hrr, msa, state (see [geography coding docs](../covidcast_geography.md))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 * **License:** [CC BY](../covidcast_licensing.md#creative-commons-attribution)
 
 This data source is based on symptom surveys run by the Delphi group at Carnegie

docs/api/covidcast-signals/ght.md

@@ -11,6 +11,7 @@ grand_parent: COVIDcast Epidata API
 * **Number of data revisions since 19 May 2020:** 0
 * **Date of last change:** Never
 * **Available for:** dma, hrr, msa, state (see [geography coding docs](../covidcast_geography.md))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 
 This data source (`ght`) is based on Google searches, provided to us by Google
 Health Trends. Using this search data, we estimate the volume of COVID-related

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

@@ -11,6 +11,7 @@ grand_parent: COVIDcast Epidata API
 * **Number of data revisions since 19 May 2020:** 0
 * **Date of last change:** Never
 * **Available for:** county, hrr, msa, state (see [geography coding docs](../covidcast_geography.md))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 * **License:** [CC BY](../covidcast_licensing.md#creative-commons-attribution)
 
 Data source based on Google-run symptom surveys, through publisher websites,

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

@@ -12,6 +12,7 @@ grand_parent: COVIDcast Epidata API
 * **Number of data revisions since 19 May 2020:** 0
 * **Date of last change:** Never
 * **Available for:** county, MSA, HRR, state (see [geography coding docs](../covidcast_geography.md))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 * **License:** [CC BY](../covidcast_licensing.md#creative-commons-attribution)
 
 This data source is based on the [COVID-19 Search Trends symptoms

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

@@ -12,6 +12,7 @@ grand_parent: COVIDcast Epidata API
 * **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))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 * **License:** [CC BY](../covidcast_licensing.md#creative-commons-attribution)
 
 This data source is based on electronic medical records and claims data about

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

@@ -24,6 +24,7 @@ calculated or composed by Delphi. It is not a primary data source.
 * **Number of data revisions since 19 May 2020:** 1
 * **Date of last change:** [3 June 2020](../covidcast_changelog.md#indicator-combination)
 * **Available for:** county, msa, state (see [geography coding docs](../covidcast_geography.md))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 * **License:** [CC BY](../covidcast_licensing.md#creative-commons-attribution)
 
 These signals combine Delphi's indicators---*not* including cases and deaths,
@@ -204,6 +205,7 @@ The resampling method for each input source is as follows:
 * **Number of data revisions since 19 May 2020:** 1
 * **Date of last change:** [12 October 2020](../covidcast_changelog.md#indicator-combination)
 * **Available for:** county, msa, hrr, state (see [geography coding docs](../covidcast_geography.md))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 
 These signals combine the cases and deaths data from JHU and USA Facts. This is
 a straight composition: the signals below use the [JHU signal data](jhu-csse.md)

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

@@ -11,6 +11,7 @@ grand_parent: COVIDcast Epidata API
 * **Number of data revisions since 19 May 2020:** 1
 * **Date of last change:** [7 October 2020](../covidcast_changelog.md#jhu-csse)
 * **Available for:** county, hrr, msa, state (see [geography coding docs](../covidcast_geography.md))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 * **License:** [CC BY](#source-and-licensing)
 
 This data source of confirmed COVID-19 cases and deaths is based on reports made

docs/api/covidcast-signals/nchs-mortality.md

@@ -12,11 +12,16 @@ grand_parent: COVIDcast Epidata API
 * **Number of data revisions since 19 May 2020:** 0
 * **Date of last change:** Never
 * **Available for:** state (see [geography coding docs](../covidcast_geography.md))
+* **Time type:** week (see [date format docs](../covidcast_times.md))
 * **License:** [NCHS Data Use Agreement](https://www.cdc.gov/nchs/data_access/restrictions.htm)
 
 This data source of national provisional death counts is based on death
 certificate data received and coded by the National Center for Health Statistics
-[(NCHS)](https://www.cdc.gov/nchs/nvss/vsrr/COVID19/index.htm).
+[(NCHS)](https://www.cdc.gov/nchs/nvss/vsrr/COVID19/index.htm). This data is
+different from the death data available from [USAFacts](usa-facts.md) and [JHU
+CSSE](jhu-csse.md): deaths are reported by the date they occur, not the date
+they are reported by local health departments, and data is frequently reissued
+as additional death certificates from recent weeks are received and tabulated.
 
 | Signal | Description |
 | --- | --- |
@@ -34,6 +39,14 @@ certificate data received and coded by the National Center for Health Statistics
 |`deaths_pneumonia_or_flu_or_covid_incidence_prop`| Number of weekly new deaths involving Pneumonia, Influenza, or COVID-19, per 100,000 population|
 |`deaths_percent_of_expected`| Number of weekly new deaths for all causes in 2020 compared to the average number across the same week in 2017–2019|
 
+## Table of contents
+{: .no_toc .text-delta}
+
+1. TOC
+{:toc}
+
+## Calculation
+
 These signals are taken directly from [Table
 1](https://www.cdc.gov/nchs/nvss/vsrr/COVID19/index.htm) without
 changes. National provisional death counts include deaths occurring within the
@@ -45,12 +58,6 @@ considered for each signals are described in detail
 [here](https://github.com/cmu-delphi/covidcast-indicators/blob/main/nchs_mortality/DETAILS.md#metrics-level-1-m1). We
 export the state-level data as-is in a weekly format.
 
-## Table of contents
-{: .no_toc .text-delta}
-
-1. TOC
-{:toc}
-
 ## Geographical Exceptions
 
 New York City is listed as its own region in the NCHS Mortality data, but
@@ -59,8 +66,8 @@ York State in our reports.
 
 ## Report Using Epiweeks
 
-We report the NCHS Mortality data in a weekly format (`time_type=week` \&
-`time_value=\{YYYYWW\}`, where `YYYYWW` refers to an epiweek). The CDC defines
+We report the NCHS Mortality data in a weekly format (`time_type=week` &
+`time_value={YYYYWW}`, where `YYYYWW` refers to an epiweek). The CDC defines
 the [epiweek](https://wwwn.cdc.gov/nndss/document/MMWR_Week_overview.pdf) as
 seven days, from Sunday to Saturday. We check the week-ending dates provided in
 the NCHS morality data and use Python package
@@ -79,7 +86,7 @@ potentially misleading.
 
 There is a lag in time between when the death occurred and when the death
 certificate is completed, submitted to NCHS, and processed for reporting
-purposes. The death counts for earlier weeks are continually revised and may
+purposes. The death counts for recent weeks are continually revised and may
 increase or decrease as new and updated death certificate data are received from
 the states by NCHS. This delay can range from 1 to 8 weeks or even more.
 Some states report deaths on a daily basis, while other states report deaths weekly
@@ -95,7 +102,7 @@ and is made available here as a convenience to the forecasting community under
 the terms of the original license. The NCHS places restrictions on how this
 dataset may be used: you may not attempt to identify any individual included in
 the data, whether by itself or through linking to other
-individually=identifiable data; you may only use the dataset for statistical
+individually identifiable data; you may only use the dataset for statistical
 reporting and analysis. The full text of the [NCHS Data Use
 Agreement](https://www.cdc.gov/nchs/data_access/restrictions.htm) is available
 from their website.

docs/api/covidcast-signals/quidel.md

@@ -21,6 +21,7 @@ grand_parent: COVIDcast Epidata API
 * **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))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 * **License:** [CC BY](../covidcast_licensing.md#creative-commons-attribution)
 
 Data source based on COVID-19 Antigen tests, provided to us by Quidel, Inc. When
@@ -140,6 +141,7 @@ June 14th and subsequently revised on June 16th.
 * **Number of data revisions since 19 May 2020:** 0
 * **Date of last change:** Never
 * **Available for:** msa, state (see [geography coding docs](../covidcast_geography.md))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 
 Data source based on flu lab tests, provided to us by Quidel, Inc. When a
 patient (whether at a doctor’s office, clinic, or hospital) has COVID-like

docs/api/covidcast-signals/safegraph.md

@@ -8,6 +8,7 @@ grand_parent: COVIDcast Epidata API
 {: .no_toc}
 * **Source name:** `safegraph`
 * **Available for:** county, MSA, HRR, state (see [geography coding docs](../covidcast_geography.md))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 * **License:** [CC BY](../covidcast_licensing.md#creative-commons-attribution)
 
 This data source uses data reported by [SafeGraph](https://www.safegraph.com/)

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

@@ -11,6 +11,7 @@ grand_parent: COVIDcast Epidata API
 * **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))
+* **Time type:** day (see [date format docs](../covidcast_times.md))
 * **License:** [CC BY](#source-and-licensing)
 
 This data source of confirmed COVID-19 cases and deaths is based on reports made

docs/api/covidcast.md

@@ -108,7 +108,7 @@ and lists.
 | --- | --- | --- |
 | `data_source` | name of upstream data source (e.g., `doctor-visits` or `fb-survey`; [see full list](covidcast_signals.md)) | string |
 | `signal` | name of signal derived from upstream data (see notes below) | string |
-| `time_type` | temporal resolution of the signal (e.g., `day`, `week`) | string |
+| `time_type` | temporal resolution of the signal (e.g., `day`, `week`; see [date coding details](covidcast_times.md)) | string |
 | `geo_type` | spatial resolution of the signal (e.g., `county`, `hrr`, `msa`, `dma`, `state`) | string |
 | `time_values` | time unit (e.g., date) over which underlying events happened | `list` of time values (e.g., 20200401) |
 | `geo_value` | unique code for each location, depending on `geo_type` (see [geographic coding details](covidcast_geography.md)), or `*` for all | string |
@@ -164,7 +164,7 @@ require knowing when an unchanged value was last confirmed, please get in touch.
 | `result` | result code: 1 = success, 2 = too many results, -2 = no results | integer |
 | `epidata` | list of results, 1 per geo/time pair | array of objects |
 | `epidata[].geo_value` | location code, depending on `geo_type` | string |
-| `epidata[].time_value` | time unit (e.g. date) over which underlying events happened | integer |
+| `epidata[].time_value` | time unit (e.g. date) over which underlying events happened (see [date coding details](covidcast_times.md)) | integer |
 | `epidata[].direction` | trend classifier (+1 -> increasing, 0 -> steady or not determined, -1 -> decreasing) | integer |
 | `epidata[].value` | value (statistic) derived from the underlying data source | float |
 | `epidata[].stderr` | approximate standard error of the statistic with respect to its sampling distribution, `null` when not applicable | float |

docs/api/covidcast_geography.md

@@ -23,6 +23,7 @@ whose estimate is being reported. Estimates are available for several possible
   available
   [here](https://hub.arcgis.com/datasets/fedmaps::hospital-referral-regions). We
   report HRRs by their number (non-consecutive, between 1 and 457).
+* `hhs`:  values that are accepted are the numbers 1-10, corresponding to the US [Department of Health & Human Services Regional Offices](https://www.hhs.gov/about/agencies/iea/regional-offices/index.html)
 * `msa`: Metropolitan Statistical Area, as defined by the Office of Management
   and Budget. The Census Bureau provides [detailed definitions of these
   regions](https://www.census.gov/programs-surveys/metro-micro/about.html). We
@@ -33,6 +34,7 @@ whose estimate is being reported. Estimates are available for several possible
 * `state`: The 50 states, identified by their two-digit postal abbreviation (in
   lower case). Estimates for Puerto Rico are available as state `pr`;
   Washington, D.C. is available as state `dc`.
+  * `nation`: accepted values are the ISO 3166-1 alpha-2 [country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Currently the only nation we have data on is `us`.
 
 Some signals are not available for all `geo_type`s, since they may be reported
 by their original sources with different levels of aggregation.

docs/api/covidcast_inactive_signals.md

@@ -2,7 +2,7 @@
 title: Inactive Signals
 parent: COVIDcast Epidata API
 has_children: true
-nav_order: 6
+nav_order: 7
 ---
 
 # COVIDcast Inactive Signals

docs/api/covidcast_meta.md

@@ -1,7 +1,7 @@
 ---
 title: Metadata
 parent: COVIDcast Epidata API
-nav_order: 5
+nav_order: 6
 ---
 
 # COVIDcast Metadata

docs/api/covidcast_times.md

@@ -0,0 +1,47 @@
+---
+title: Date Coding and Revisions
+parent: COVIDcast Epidata API
+nav_order: 5
+---
+
+# Date Coding and Revisions
+
+Every observation in the COVIDcast Epidata API has two dates attached:
+
+* `time_value`: The time the underlying events happened. For example, when a data
+  source reports on COVID test results, the time value is the date the
+  results were recorded by the testing provider.
+* `issue`: The date the estimates were *issued*. For example, a COVID test
+  result might be recorded on October 1st, but it may take several days for
+  that report to be collected, aggregated, received by Delphi, and added to our
+  database.  The *issue date* is when Delphi makes the data available.
+
+For example, consider using our [doctor visits signal](covidcast-signals/doctor-visits.md),
+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_value = "pa"`. This is an estimate for the percentage in Pennsylvania on
+May 1, 2020, which was issued on May 5, 2020. The delay is due to the
+aggregation of data by our source and the time taken by the 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, and would be reported with a new issue
+date.
+
+The format of the `time_value` and `issue` dates depends on the `time_type` API
+parameter. Each data source is available for specified time types; check each
+source's documentation for details on supported time types.
+
+The available time types include:
+
+* `day`: A daily observation. The `time_value` and `issue` are both reported
+  with year, month, and day in `YYYYMMDD` format. (The [API clients](covidcast_clients.md)
+  convert this into convenient date objects.)
+* `week`: A weekly observation, recording events over 7 days. The `time_value`
+  and `issue` are reported with a year and a week number ranging from 1 to 53,
+  in `YYYYWW` format. These weeks are [MMWR
+  weeks](https://wwwn.cdc.gov/nndss/document/MMWR_Week_overview.pdf) as defined
+  by the National Notifiable Diseases Surveillance System, also known as
+  "epiweeks". (The [API clients](covidcast_clients.md) convert these into date
+  objects representing the first day of the MMWR week, and for those not using
+  the clients, packages are available to convert MMWR weeks in many common
+  programming languages.)