Merge pull request #205 from cmu-delphi/docs/copyedits

General documentation improvements

Author: capnrefsmmat

docs/api/covidcast.md

@@ -42,8 +42,8 @@ as, in [R](https://www.r-project.org/):
 ```r
 library(covidcast)
 
-data <- covidcast_signal("fb-survey", "smoothed_cli", start_day = "20200501",
-                         end_day = "20200507")
+data <- covidcast_signal("fb-survey", "smoothed_cli", start_day = "2020-05-01",
+                         end_day = "2020-05-07")
 ```
 
 or, in [Python](https://www.python.org):
@@ -56,8 +56,11 @@ data = covidcast.signal("fb-survey", "smoothed_cli", date(2020, 5, 1), date(2020
                         "county")
 ```
 
-Alternately, for full API access, [see below](#constructing-api-queries) for
-details on how to construct URLs and parse responses to access data manually.
+[The API clients](covidcast_clients.md) have extensive documentation providing
+further examples.
+
+Alternately, to construct URLs and parse responses to access data manually, [see
+below](#constructing-api-queries) for details.
 
 ## Data Sources and Signals
 

docs/api/covidcast_clients.md

@@ -12,8 +12,9 @@ Dedicated COVIDcast clients are available for several languages:
 * Python: [covidcast](https://cmu-delphi.github.io/covidcast/covidcast-py/html/)
 
 These packages provide a convenient way to obtain COVIDcast data as a data frame
-ready to be used in further analyses. For installation instructions and
-examples, consult their respective webpages.
+ready to be used in further analyses, and provide convenient mapping and
+analysis functions. For installation instructions and examples, consult their
+respective webpages.
 
 ## Generic Epidata Clients
 

docs/api/covidcast_geography.md

@@ -14,8 +14,10 @@ whose estimate is being reported. Estimates are available for several possible
 * `county`: County-level estimates are reported by the county's five-digit [FIPS
   code](https://en.wikipedia.org/wiki/FIPS_county_code). All FIPS codes are
   reported using pre-2015 FIPS code assignments, *except* for FIPS codes used by
-  the `jhu-csse` source. These are reported exactly as JHU reports their data;
-  [see below](#fips-exceptions-in-jhu-data).
+  the `jhu-csse` and `usa-facts` sources. These are reported exactly as the
+  sources report their data; [see below](#coding-exceptions). FIPS codes ending
+  in `000` are not valid counties, and instead represent "megacounties" we
+  construct; [see below](#small-sample-sizes-and-megacounties).
 * `hrr`: Hospital Referral Region, units designed to represent regional health
   care markets. There are roughly 300 HRRs in the United States. A map is
   available
@@ -29,10 +31,11 @@ whose estimate is being reported. Estimates are available for several possible
   media markets, as [defined by
   Nielsen](https://www.nielsen.com/us/en/intl-campaigns/dma-maps/).
 * `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`.
+  lower case). Estimates for Puerto Rico are available as state `pr`;
+  Washington, D.C. is available as state `dc`.
 
 Some signals are not available for all `geo_type`s, since they may be reported
-from their original sources with different levels of aggregation.
+by their original sources with different levels of aggregation.
 
 ## Table of contents
 {: .no_toc .text-delta}
@@ -50,18 +53,27 @@ identification of respondents, violating privacy and confidentiality agreements.
 Additional considerations for specific signals are discussed in the [source and
 signal documentation](covidcast_signals.md).
 
-In each state, we collect together the data from all counties with insufficient
-data to be individually reported. These counties are combined into a single
-"megacounty". For example, if only five counties in a state have sufficient data
-to be reported, the remaining counties will form one megacounty representing the
-rest of that state. As sample sizes vary from day to day, the counties composing
-the megacounty can vary daily; the geographic area covered by the megacounty is
-simply the state minus the counties reported for that day.
+On each day, in each state, we collect together the data from all counties with
+insufficient data to be individually reported. These counties are combined into
+a single "megacounty". For example, if only five counties in a state have
+sufficient data to be reported, the remaining counties will form one megacounty
+representing the rest of that state. Megacounty estimates are reported with a
+FIPS code ending with `000`, which is never a FIPS code for a real county. For
+example, megacounty estimates for the state of New York are reported with FIPS
+code `36000`, since `36` is the FIPS code prefix for New York.
 
-Megacounty estimates are reported with a FIPS code ending with 000, which is
-never a FIPS code for a real county. For example, megacounty estimates for the
-state of New York are reported with FIPS code 36000, since 36 is the FIPS code
-prefix for New York.
+These megacounty estimates are used on our COVIDcast map and in the county maps
+produced by our [API clients](covidcast_clients.md), to color in the background
+of states and graphically represent the "rest of" states whose counties are not
+all individually reported.
+
+**Warning:** As sample sizes vary from day to day, the counties composing the
+megacounty can vary daily; the geographic area covered by the megacounty is
+simply the state minus the counties reported for that day. The megacounty
+construction also depends on the specific source and signal, so on one day,
+megacounty `36000` can cover a different geographic area for the `doctor-visits`
+source than it does for the `fb-survey` source. Do not try to compare megacounty
+estimates across time or between signals.
 
 ## Coding Exceptions