Merge pull request #149 from cmu-delphi/docs-review

Docs review

Author: dshemetov

DESCRIPTION

@@ -9,7 +9,7 @@ Authors@R:
     person("David", "Weber", email = "[email protected]", role = c("ctb")),
     person("Samuel", "Gratzl", email = "[email protected]", role = c("aut"))
   )
-URL: https://github.com/cmu-delphi/epidatr
+URL: https://cmu-delphi.github.io/epidatr/, https://github.com/cmu-delphi/epidatr
 BugReports: https://github.com/cmu-delphi/epidatr/issues
 Description: R Client for Delphi's Epidata API. Tools for fetching data in various forms.
 Depends: R (>= 3.5.0)

NAMESPACE

@@ -10,6 +10,7 @@ export(covid_hosp_facility)
 export(covid_hosp_facility_lookup)
 export(covid_hosp_state_timeseries)
 export(covidcast)
+export(covidcast_epidata)
 export(covidcast_meta)
 export(delphi)
 export(dengue_nowcast)

R/check.R

@@ -34,6 +34,7 @@ assert_date_param <- function(name, value, len = NULL, required = TRUE) {
 #' Allows a timeset param: a date vector, a character vector, an integer-like
 #' vector, or a single EpiRange
 #' @importFrom checkmate assert check_character check_date check_integerish check_class check_list check_names
+#' @keywords internal
 assert_timeset_param <- function(name, value, len = NULL, required = TRUE) {
   null.ok <- !required
   assert_integerish(len, len = 1L, null.ok = TRUE, .var.name = "len")

R/covidcast.R

@@ -14,6 +14,7 @@ parse_signal <- function(signal, base_url) {
   #' @param issues data source to fetch
   #' @param lag data source to fetch
   #' @return an instance of epidata_call
+  #' @keywords internal
   signal$call <- function(geo_type,
                           geo_values,
                           time_values,
@@ -31,10 +32,10 @@ parse_signal <- function(signal, base_url) {
 }
 
 #' @export
-print.covidcast_data_signal <- function(signal, ...) {
-  print(signal$name)
-  print(signal$key)
-  print(signal$short_description)
+print.covidcast_data_signal <- function(x, ...) {
+  print(x$name)
+  print(x$key)
+  print(x$short_description)
 }
 
 parse_source <- function(source, base_url) {
@@ -78,26 +79,26 @@ as.data.frame.covidcast_data_signal_list <- function(signals, ...) {
 }
 
 #' @export
-print.covidcast_data_source <- function(source, ...) {
-  print(source$name, ...)
-  print(source$source, ...)
-  print(source$description, ...)
-  signals <- as.data.frame(source$signals)
+print.covidcast_data_source <- function(x, ...) {
+  print(x$name, ...)
+  print(x$source, ...)
+  print(x$description, ...)
+  signals <- as.data.frame(x$signals)
   print(signals[, c("signal", "name", "short_description")], ...)
 }
 
-#' creates the covidcast epidata helper
+#' Creates the COVIDcast Epidata autocomplete helper
 #'
-#' Creates a helper object that can use auto-complete to help find covidcast
+#' Creates a helper object that can use auto-complete to help find COVIDcast
 #' sources and signals.
 #'
 #' @param base_url optional alternative API base url
 #' @param timeout_seconds the maximum amount of time to wait for a response
 #' @importFrom httr stop_for_status content http_type
 #' @importFrom jsonlite fromJSON
 #' @importFrom xml2 read_html xml_find_all xml_text
-#' @return an instance of covidcast_epidata
-#'
+#' @return An instance of `covidcast_epidata`
+#' @export
 covidcast_epidata <- function(base_url = global_base_url, timeout_seconds = 30) {
   url <- join_url(base_url, "covidcast/meta")
   response <- do_request(url, list(), timeout_seconds)
@@ -154,16 +155,16 @@ as.data.frame.covidcast_data_source_list <- function(sources, ...) {
   }), ...)
 }
 
-print.covidcast_epidata <- function(epidata, ...) {
+print.covidcast_epidata <- function(x, ...) {
   print("COVIDcast Epidata Fetcher")
   print("Sources:")
-  sources <- as.data.frame(epidata$sources)
+  sources <- as.data.frame(x$sources)
   print(sources[1:5, c("source", "name")], ...)
   if (nrow(sources) > 5) {
     print(paste0((nrow(sources) - 5), " more..."))
   }
   print("Signals")
-  signals <- as.data.frame(epidata$signals)
+  signals <- as.data.frame(x$signals)
   print(signals[1:5, c("source", "signal", "name")], ...)
   if (nrow(signals) > 5) {
     print(paste0((nrow(signals) - 5), " more..."))

R/endpoints.R

@@ -1,6 +1,6 @@
 #' Fetch CDC page hits
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/cdc.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/cdc.html>
 #'
 #' @examples
 #' \dontrun{
@@ -640,10 +640,10 @@ covidcast_meta <- function() {
 #'   time_values = epirange(20200601, 20200801)
 #' ) %>% fetch()
 #' }
-#' @param data_source string. The data source to query (see:
+#' @param source string. The data source to query (see:
 #'   <https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html>).
 #' @param signals string. The signals to query from a specific source (see:
-#'   <https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals.html>).
+#'   <https://cmu-delphi.github.io/delphi-epidata/api/covidcast_signals.html>).
 #' @param geo_type string. The geographic resolution of the data (see:
 #'   <https://cmu-delphi.github.io/delphi-epidata/api/covidcast_geography.html>).
 #' @param time_type string. The temporal resolution of the data (either "day" or
@@ -685,7 +685,7 @@ covidcast <- function(
       missing(time_values) || missing(geo_values)
   ) {
     stop(
-      "`data_source`, `signals`, `time_type`, `geo_type`, `time_values`, and `geo_value` are all required"
+      "`source`, `signals`, `time_type`, `geo_type`, `time_values`, and `geo_value` are all required"
     )
   }
 
@@ -748,7 +748,7 @@ covidcast <- function(
 
 #' Fetch Delphi's ILINet forecasts
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/delphi.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/delphi.html>
 #'
 #' @examples
 #' \dontrun{
@@ -778,7 +778,7 @@ delphi <- function(system, epiweek) {
 
 #' Fetch Delphi's PAHO Dengue nowcast
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/dengue_nowcast.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/dengue_nowcast.html>
 #'
 #' TODO: what are valid locations here?
 #' @examples
@@ -813,7 +813,7 @@ dengue_nowcast <- function(locations, epiweeks) {
 #' Fetch Delphi's digital surveillance sensors for dengue in PAHO member
 #' countries
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/dengue_sensors.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/dengue_sensors.html>
 #'
 #' TODO: what are valid locations and names?
 #' @examples
@@ -970,7 +970,7 @@ flusurv <- function(locations, epiweeks, issues = NULL, lag = NULL) {
 
 #' Fetch FluView virological data from clinical labs
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/fluview_clinical.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/fluview_clinical.html>
 #'
 #' @examples
 #' \dontrun{
@@ -1024,7 +1024,7 @@ fluview_clinical <- function(regions, epiweeks, issues = NULL, lag = NULL) {
 
 #' Fetch FluView metadata
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/fluview_meta.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/fluview_meta.html>
 #' @examples
 #' \dontrun{
 #' fluview_meta() %>% fetch()
@@ -1159,7 +1159,7 @@ gft <- function(locations, epiweeks) {
 
 #' Fetch Google Health Trends data
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/ght.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/ght.html>
 #'
 #' TODO: find a non-trivial query
 #' @examples
@@ -1203,7 +1203,7 @@ pvt_ght <- function(auth, locations, epiweeks, query) {
 
 #' Fetch KCDC data
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/kcdc_ili.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/kcdc_ili.html>
 #'
 #' TODO: find a non-trivial region
 #' @examples
@@ -1251,7 +1251,7 @@ kcdc_ili <- function(regions, epiweeks, issues = NULL, lag = NULL) {
 
 #' Fetch NoroSTAT metadata
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/meta_norostat.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/meta_norostat.html>
 #'
 #' @examples
 #' \dontrun{
@@ -1269,7 +1269,7 @@ pvt_meta_norostat <- function(auth) {
 
 #' Fetch api metadata
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/meta.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/meta.html>
 #'
 #' @return [`epidata_call`]
 #'
@@ -1371,7 +1371,7 @@ nidss_flu <- function(regions, epiweeks, issues = NULL, lag = NULL) {
 
 #' Fetch NoroSTAT data (point data, no min/max)
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/norostat.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/norostat.html>
 #'
 #' @examples
 #' \dontrun{
@@ -1446,7 +1446,7 @@ nowcast <- function(locations, epiweeks) {
 
 #' Fetch PAHO Dengue
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/paho_dengue.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/paho_dengue.html>
 #'
 #' @examples
 #' \dontrun{
@@ -1495,7 +1495,7 @@ paho_dengue <- function(regions, epiweeks, issues = NULL, lag = NULL) {
 
 #' Fetch Quidel COVID-19 and influenza testing data
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/quidel.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/quidel.html>
 #'
 #' @examples
 #' \dontrun{
@@ -1534,7 +1534,7 @@ pvt_quidel <- function(auth, locations, epiweeks) {
 
 #' Fetch Delphi's digital surveillance sensors
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/sensors.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/sensors.html>
 #'
 #' @examples
 #' \dontrun{
@@ -1578,7 +1578,7 @@ pvt_sensors <- function(auth, names, locations, epiweeks) {
 
 #' Fetch HealthTweets data
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/twitter.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/twitter.html>
 #'
 #' @examples
 #' \dontrun{
@@ -1628,7 +1628,7 @@ pvt_twitter <- function(auth, locations, dates = NULL, epiweeks = NULL) {
 
 #' Fetch Wikipedia access data
 #'
-#' API docs: https://cmu-delphi.github.io/delphi-epidata/api/wiki.html
+#' API docs: <https://cmu-delphi.github.io/delphi-epidata/api/wiki.html>
 #'
 #' @examples
 #' \dontrun{

R/epidatacall.R

@@ -89,12 +89,12 @@ request_arguments <- function(epidata_call, format_type, fields = NULL) {
 }
 
 #' @export
-print.epidata_call <- function(epidata_call) {
-  stopifnot(inherits(epidata_call, "epidata_call"))
+print.epidata_call <- function(x, ...) {
+  stopifnot(inherits(x, "epidata_call"))
   cli::cli_h1("<epidata_call> object:")
   cli::cli_bullets(c(
     "*" = "Pipe this object into `fetch()` to actually fetch the data",
-    "*" = paste0("Request URL: ", request_url(epidata_call))
+    "*" = paste0("Request URL: ", request_url(x))
   ))
 }
 
@@ -264,6 +264,7 @@ with_base_url <- function(epidata_call, base_url) {
 #' HTTP errors and forwarding the HTTP body in R errors
 #' @importFrom httr stop_for_status content http_type
 #' @importFrom xml2 read_html xml_find_all xml_text
+#' @keywords internal
 request_impl <- function(epidata_call, format_type, fields = NULL, timeout_seconds = 30) {
   stopifnot(inherits(epidata_call, "epidata_call"))
   stopifnot(format_type %in% c("json", "csv", "classic"))

R/epidatr-package.R

@@ -1,7 +1,2 @@
-#' Delphi Epidata
-#'
-#' TODO
-#'
-#' @docType package
-#' @name epidatr
-NULL
+#' @keywords internal
+"_PACKAGE"

R/model.R

@@ -1,12 +1,25 @@
-#' builds a new EpiRange instances
+#' Specify a date range (in days or epiweeks) for an API request.
 #'
-#' @param from A Date, integer-like value, or integer-like string that takes the
-#'   form YYYYMMDD for dates or YYYYMM for epiweeks.
-#' @param to A Date, integer-like value, or integer-like string that takes the
-#'  form YYYYMMDD for dates or YYYYMM for epiweeks.
+#' Epiweeks, also known as MMWR weeks number the weeks of the year from 1 to 53,
+#' each week spanning from Sunday to Saturday. The numbering is [defined by the
+#' CDC](https://ndc.services.cdc.gov/wp-content/uploads/MMWR_Week_overview.pdf).
+#'
+#' @param from A `Date`, integer-like value, or integer-like string that takes the
+#'   form YYYYMMDD for dates or YYYYWW for epiweeks.
+#' @param to A `Date`, integer-like value, or integer-like string that takes the
+#'  form YYYYMMDD for dates or YYYYWW for epiweeks.
 #' @return EpiRange instance
 #' @importFrom checkmate check_integerish check_character check_date assert
 #'
+#' @examples
+#' # Represents 2021-01-01 to 2021-01-07, inclusive
+#' epirange(20210101, 20210107)
+#'
+#' # The same, but using Date objects
+#' epirange(as.Date("2021-01-01"), as.Date("2021-01-07"))
+#'
+#' # Represents epiweeks 2 through 4 of 2022, inclusive
+#' epirange(202202, 202204)
 #' @export
 epirange <- function(from, to) {
   assert(
@@ -47,21 +60,25 @@ epirange <- function(from, to) {
 
 #' timeset
 #'
-#' A collection of date-like values, including dates, epiweeks, and ranges of
-#' dates or epiweeks ([`epirange`]). This is often used to specify the time
-#' dimension for an epidata query. The allowed values are:
+#' Many API calls accept timesets to specify the time ranges of data being
+#' requested. Timesets can be specified with `epirange()`, as `Date` objects, or
+#' with wildcards.
+#'
+#' Timesets are not special R types; the term simply describes any value that
+#' would be accepted by epidatr to specify the time value of an epidata query.
+#' The allowed values are:
 #'
 #' - Dates: `Date` instances, integer-like values, or integer-like strings that
-#'   take the form YYYYMMDD,
-#' - Epiweeks: integer-like values or integer-like strings that take the form
-#'   YYYYMM,
-#' - EpiRanges: a list of [`epirange`] instances.
-#' - Wildcard: "*" (requests all available values for this dimension)
+#'   take the form YYYYMMDD.
+#' - Epiweeks: Integer-like values or integer-like strings that take the form
+#'   YYYYWW.
+#' - EpiRanges: A range returned by `epirange()`, or a list of multiple ranges
+#' - Wildcard: The string `"*"`, which request all available time values
 #'
 #' Please refer to the specific endpoint documentation for guidance on using
 #' dates vs weeks. Most endpoints support only one or the other. Some (less
 #' commonly used) endpoints may not accept the `"*"` wildcard, but this can be
-#' simulated with a large [`epirange`].
+#' simulated with a large `epirange()`.
 #'
 #' @name timeset
 NULL

R/request.R

@@ -21,6 +21,7 @@ join_url <- function(url, endpoint) {
 #' }
 #'
 #' @importFrom httr RETRY
+#' @keywords internal
 do_request <- function(url, params, timeout_seconds = 30) {
   # don't retry in case of certain status codes
   res <- httr::RETRY("GET",