Merge pull request #320 from cmu-delphi/docs/r-api

Minor R package documentation & typo fixes

Author: capnrefsmmat

R-packages/covidcast/R/covidcast.R

@@ -197,8 +197,8 @@ COVIDCAST_BASE_URL <- 'https://api.covidcast.cmu.edu/epidata/api.php'
 #'                  geo_values = name_to_cbsa("Pittsburgh"))
 #' }
 #'
-#' @seealso [plot.covidcast_signal()], [`county_census`], [`msa_census`],
-#'     [`state_census`]
+#' @seealso [plot.covidcast_signal()], [covidcast_signals()], [`county_census`],
+#'   [`msa_census`], [`state_census`]
 #' @export
 #' @importFrom rlang abort
 #' @importFrom dplyr %>%
@@ -359,8 +359,8 @@ summary.covidcast_signal = function(object, ...) {
 #' @examples
 #' \dontrun{
 #' ## Fetch USAFacts confirmed cases and deaths over the same time period
-#' covidcast_signals("usa-facts", signal=c("confirmed_incidence_num",
-#'                                         "deaths_incidence_num"),
+#' covidcast_signals("usa-facts", signal = c("confirmed_incidence_num",
+#'                                           "deaths_incidence_num"),
 #'                    start_day = "2020-08-15", end_day = "2020-10-01")
 #' }
 #' @export

R-packages/covidcast/R/data.R

@@ -20,6 +20,8 @@
 #'
 #' @source United States Census Bureau, at
 #'   \url{https://www2.census.gov/programs-surveys/popest/datasets/2010-2019/counties/totals/co-est2019-alldata.csv}
+#'
+#' @seealso [fips_to_name()], [name_to_fips()]
 "county_census"
 
 #' Metro area population data
@@ -50,6 +52,8 @@
 #'
 #' @source United States Census Bureau, at
 #'   \url{https://www2.census.gov/programs-surveys/popest/datasets/2010-2019/metro/totals/cbsa-est2019-alldata.csv}
+#'
+#' @seealso [cbsa_to_name()], [name_to_cbsa()]
 "msa_census"
 
 #' State population data
@@ -67,6 +71,8 @@
 #'
 #' @source United States Census Bureau, at
 #'   \url{https://www2.census.gov/programs-surveys/popest/datasets/2010-2019/state/detail/SCPRC-EST2019-18+POP-RES.csv}
+#'
+#' @seealso [abbr_to_name()], [name_to_abbr()], [abbr_to_fips()], [fips_to_abbr()]
 "state_census"
 
 #' County latitudes and longitudes

R-packages/covidcast/R/wrangle.R

@@ -256,6 +256,8 @@ aggregate_signals = function(x, dt = NULL, format = c("wide", "long")) {
 #'   `aggregate_signals()` had been called in the first place with that
 #'   `format` argument.
 #'
+#' @seealso [covidcast_signals()]
+#'
 #' @export
 covidcast_longer = function(x) {
   if (!inherits(x, "covidcast_signal_wide")) {

R-packages/covidcast/index.md

@@ -1,25 +1,32 @@
 # covidcast R package
 
-Provides R access to the [COVIDcast
+Provides R access to the [COVIDcast Epidata
 API](https://cmu-delphi.github.io/delphi-epidata/api/covidcast.html) published
 by the [Delphi group](https://delphi.cmu.edu/) at [Carnegie Mellon
 University](https://www.cmu.edu). This API provides daily access to a range of
 COVID-related signals Delphi that builds and maintains, from sources like
 symptom surveys and medical claims data, and also standard signals that we
 simply mirror, like confirmed cases and deaths.
 
-Consult the [COVIDcast API
+Consult the [COVIDcast Epidata API
 documentation](https://cmu-delphi.github.io/delphi-epidata/api/covidcast.html)
 for details on the data included in the API, licensing, and how to cite this
 data in your work. The [signals
 documentation](https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html)
 lists all the data sources and signals available through this API.
 
+**To get started** using this package, view the Getting Started guide at
+`vignette("covidcast")`.
+
+## Get updates
+
 **You should consider subscribing to the [API mailing
 list](https://lists.andrew.cmu.edu/mailman/listinfo/delphi-covidcast-api)** to
 be notified of package updates, new data sources, corrections, and other
 updates.
 
+## Usage terms
+
 **Warning:** If you use data from the COVIDcast API to power a product,
 dashboard, app, or other service, please download the data you need and store it
 centrally rather than making API requests for every user. Our server resources
@@ -28,6 +35,3 @@ are limited and cannot support high-volume interactive use.
 See also the [COVIDcast Terms of
 Use](https://covidcast.cmu.edu/terms-of-use.html), noting that the data is a
 research product and not warranted for a particular purpose.
-
-**To get started** using this package, view the Getting Started guide at
-`vignette("covidcast")`.

R-packages/covidcast/vignettes/correlation-utils.Rmd

@@ -12,7 +12,7 @@ The covidcast package provides some simple utilities for exploring the
 correlations between two signals, over space or time, which may be helpful for
 simple analyses and explorations of data.
 
-For these examples, we'll load confirmed case and death rates. and restrict our
+For these examples, we'll load confirmed case and death rates, and restrict our
 analysis to counties with at least 500 total cases by August 15th.
 
 ```{r, message = FALSE}
@@ -81,18 +81,25 @@ linear relationship. The latter can be addressed using Spearman correlation,
 accomplished by setting `method = "spearman"` in the call to `covidcast_cor()`.
 Spearman correlation is highly robust and invariant to monotone transformations
 (it doesn't rely on any particular functional form for the dependence between 
-two variables). 
+two variables).
 
-We might also interested in interested in how case rates associate with death
-rates in the *future*. Using the `dt_x` parameter in `covidcast_cor()`, we can 
-lag case rates back any number of days we want, before calculating correlations.
+### Lagged correlations
+
+We might also be interested in how case rates associate with death rates in the
+*future*. Using the `dt_x` parameter in `covidcast_cor()`, we can lag case rates
+back any number of days we want, before calculating correlations.
+
+Here we set `dt_x = -10`. This means that `iprop_act` will be lagged by 10 days,
+meaning that cases on June 1st will be correlated with deaths on June 11th. (It
+might help to think of it this way: deaths on a certain day will be correlated
+with cases with an offset of -10 days.)
 
 ```{r, warning = FALSE}
 # Use Spearman correlation, with case rates and 10-day lagged case rates
 df_cor1 <- covidcast_cor(iprop_act, dprop_act, by = "time_value", 
-                        method = "spearman")
+                         method = "spearman")
 df_cor2 <- covidcast_cor(iprop_act, dprop_act, by = "time_value", dt_x = -10,
-                        method = "spearman")
+                         method = "spearman")
 
 # Stack rowwise into one data frame, then plot time series
 df_cor <- rbind(df_cor1, df_cor2)
@@ -106,10 +113,10 @@ ggplot(df_cor, aes(x = time_value, y = value)) +
   theme(legend.position = "bottom")
 ```
 
-We can see that, for the most part, the Spearman measure has bolstered the 
-correlations; and generally, lagging the case rates time series back by 10 days 
-improves correlations, confirming case rates are better correlated with death 
-rates 10 days from now.
+We can see that, for the most part, the Spearman measure has bolstered the
+correlations; and generally, lagging the case rates back by 10 days improves
+correlations, confirming case rates are better correlated with death rates 10
+days from now.
 
 ## Correlations sliced by county
 

R-packages/covidcast/vignettes/multi-signals.Rmd

@@ -43,7 +43,7 @@ be vectors. See the `covidcast_signals()` documentation for details.
 ## Aggregating signals, wide format
 
 To aggregate multiple signals together, we can use the `aggregate_signals()`
-function, which acceps a list of `covidcast_signal` objects, as returned by
+function, which accepts a list of `covidcast_signal` objects, as returned by
 `covidcast_signals()`. With all arguments set to their default values,
 `aggregate_signals()` returns a data frame in "wide" format: 
 
@@ -87,7 +87,8 @@ aggregate_signals(signals[[1]], dt = c(-1, 0, 1)) %>%
 
 ## Aggregating signals, long format
 
-We can also use `aggregate_signals()` in "long" format: 
+We can also use `aggregate_signals()` in "long" format, with one observation
+per row:
 
 ```{r}
 aggregate_signals(signals, format = "long") %>%