A few more fixes for release

.Rbuildignore

@@ -20,3 +20,5 @@
 ^.venv$
 ^env$
 ^.env$
+^README\.Rmd$
+^CRAN-SUBMISSION$

CRAN-SUBMISSION

@@ -0,0 +1,3 @@
+Version: 1.0.0
+Date: 2023-09-12 08:00:50 UTC
+SHA: 52436eb250eab1f9c70b250bf4ca1ab25cc48316

DESCRIPTION

@@ -2,6 +2,7 @@ Package: epidatr
 Type: Package
 Title: Client for Delphi's 'Epidata' API
 Version: 1.0.0
+Date: 2023-09-11
 Authors@R: 
   c(
     person("Logan", "Brooks", email = "[email protected]", role = c("aut")),
@@ -15,9 +16,9 @@ Authors@R:
     person("George", "Haff", role = c("ctb")),
     person("Kathryn", "Mazaitis", role = c("ctb"))
   )
-URL: https://cmu-delphi.github.io/epidatr/, https://github.com/cmu-delphi/epidatr
+URL: https://cmu-delphi.github.io/epidatr/, https://cmu-delphi.github.io/delphi-epidata/, https://github.com/cmu-delphi/epidatr
 BugReports: https://github.com/cmu-delphi/epidatr/issues
-Description: The Delphi 'Epidata' API provides real-time access to epidemiological surveillance data for influenza, COVID-19, and other diseases for the USA at various geographical resolutions, both from official government sources such as the Center for Disease Control (CDC) and Google Trends and private partners such as Facebook and Change Healthcare. It is built and maintained by the Carnegie Mellon University Delphi research group.
+Description: The Delphi 'Epidata' API provides real-time access to epidemiological surveillance data for influenza, 'COVID-19', and other diseases for the USA at various geographical resolutions, both from official government sources such as the Center for Disease Control (CDC) and Google Trends and private partners such as Facebook and Change 'Healthcare'. It is built and maintained by the Carnegie Mellon University Delphi research group. To cite this API: David C. Farrow, Logan C. Brooks, Aaron 'Rumack', Ryan J. 'Tibshirani', 'Roni' 'Rosenfeld' (2015). Delphi 'Epidata' API. <https://github.com/cmu-delphi/delphi-epidata>.
 Depends: R (>= 3.5.0)
 License: MIT + file LICENSE
 Encoding: UTF-8

NAMESPACE

@@ -7,7 +7,6 @@ S3method(print,covidcast_data_signal_list)
 S3method(print,covidcast_data_source)
 S3method(print,covidcast_epidata)
 S3method(print,epidata_call)
-export("%>%")
 export(avail_endpoints)
 export(cache_info)
 export(clear_cache)

R/cache.R

@@ -68,14 +68,12 @@ cache_environ$epidatr_cache <- NULL
 #'   encoding of the call url. Each file corresponds to a unique epidata-API
 #'   call.
 #' @examples
-#' \dontrun{
 #' set_cache(
-#'   dir = "some/subdir",
+#'   cache_dir = tempdir(),
 #'   days = 14,
 #'   max_size = 512,
-#'   logfile = "some/subdir/logs.txt"
+#'   logfile = "logs.txt"
 #' )
-#' }
 #'
 #' @param cache_dir the directory in which the cache is stored. By default, this
 #'   is `tools::R_user_dir()` if on R 4.0+, but must be specified for earlier
@@ -92,6 +90,8 @@ cache_environ$epidatr_cache <- NULL
 #'   variable is `EPIDATR_CACHE_LOGFILE`.
 #' @param confirm whether to confirm directory creation. default is `TRUE`;
 #'   should only be set in non-interactive scripts
+#' @return [`NULL`] no return value, all effects are stored in the package
+#'         environment
 #' @seealso [`clear_cache`] to delete the old cache while making a new one,
 #'   [`disable_cache`] to disable without deleting, and [`cache_info`]
 #' @export
@@ -176,28 +176,23 @@ set_cache <- function(cache_dir = NULL,
 #'   are using a session unique cache, you will have to pass the arguments you
 #'   used for `set_cache` earlier, otherwise the system-wide `.Renviron`-based
 #'   defaults will be used.
-#' @examples
-#' \dontrun{
-#' clear_cache(
-#'   dir = "some/subdir",
-#'   days = 14,
-#'   max_size = 512,
-#'   logfile = "some/subdir/logs.txt",
-#' )
-#' }
 #' @param disable instead of setting a new cache, disable caching entirely;
 #'   defaults to `FALSE`
 #' @inheritDotParams set_cache
+#' @return [`NULL`] no return value, all effects are stored in the package
+#'         environment
 #' @seealso [`set_cache`] to start a new cache (and general caching info),
 #'   [`disable_cache`] to only disable without deleting, and [`cache_info`]
 #' @export
 #' @import cachem
 clear_cache <- function(disable = FALSE, ...) {
-  cache_environ$epidatr_cache$destroy()
-  if (!disable) {
-    set_cache(...)
-  } else {
+  if (any(!is.na(cache_environ$epidatr_cache))) {
+    cache_environ$epidatr_cache$destroy()
+  }
+  if (disable) {
     cache_environ$epidatr_cache <- NULL
+  } else {
+    set_cache(...)
   }
 }
 
@@ -207,6 +202,8 @@ clear_cache <- function(disable = FALSE, ...) {
 #'   the cache are untouched. If you are looking to disable the caching more
 #'   permanently, set `EPIDATR_USE_CACHE=FALSE` as environmental variable in
 #'   your `.Renviron`.
+#' @return [`NULL`] no return value, all effects are stored in the package
+#'         environment
 #' @export
 #' @seealso [`set_cache`] to start a new cache (and general caching info),
 #'   [`clear_cache`] to delete the cache and set a new one, and [`cache_info`]
@@ -220,6 +217,7 @@ disable_cache <- function() {
 #' @description
 #' Print out the information about the cache (as would be returned by cachem's
 #' `info()` method).
+#' @return [`list`] containing the info result as created by cachem
 #'
 #' @seealso [`set_cache`] to start a new cache (and general caching info),
 #'   [`clear_cache`] to delete the cache and set a new one, and [`disable_cache`] to
@@ -239,7 +237,7 @@ cache_info <- function() {
 #' The guts of caching, its interposed between fetch and the specific fetch
 #' methods. Internal method only.
 #'
-#' @param call the `epidata_call` object
+#' @param epidata_call the `epidata_call` object
 #' @param fetch_args the args list for fetch as generated by [`fetch_args_list()`]
 #' @keywords internal
 #' @importFrom openssl md5

R/covidcast.R

@@ -1,20 +1,24 @@
+#' turn a signal into a callable
+#' @param signal the signal of interest
+#' @param base_url the base url
+#' @keywords internal
 parse_signal <- function(signal, base_url) {
   class(signal) <- c("covidcast_data_signal", class(signal))
   signal$key <- paste(signal$source, signal$signal, sep = ":")
 
   #' fetch covidcast data
   #'
-  #' @param data_source data source to fetch
-  #' @param signals data source to fetch
-  #' @param geo_type geo_type to fetch
-  #' @param time_type data source to fetch
-  #' @param geo_values data source to fetch
-  #' @param time_values data source to fetch
-  #' @param as_of data source to fetch
-  #' @param issues data source to fetch
-  #' @param lag data source to fetch
-  #' @return an instance of epidata_call
-  #' @keywords internal
+  #' param data_source data source to fetch
+  #' param signals data source to fetch
+  #' param geo_type geo_type to fetch
+  #' param time_type data source to fetch
+  #' param geo_values data source to fetch
+  #' param time_values data source to fetch
+  #' param as_of data source to fetch
+  #' 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,

R/endpoints.R

@@ -658,7 +658,7 @@ pub_covidcast_meta <- function(fetch_args = fetch_args_list()) {
 #'   signals = "confirmed_7dav_incidence_prop",
 #'   geo_type = "state",
 #'   time_type = "day",
-#'   geo_values = "ca,fl",
+#'   geo_values = c("ca", "fl"),
 #'   time_values = epirange(20200601, 20200801)
 #' )
 #' pub_covidcast(
@@ -1102,11 +1102,13 @@ pub_fluview_meta <- function(fetch_args = fetch_args_list()) {
 #' more information on ILINet, see
 #' <https://gis.cdc.gov/grasp/fluview/fluportaldashboard.html>.
 #'
-#' @details The full list of location inputs can be accsssed at
+#' @details The full list of location inputs can be accessed at
 #'   <https://github.com/cmu-delphi/delphi-epidata/blob/main/src/acquisition/fluview/fluview_locations.py>.
 #'
 #' @examples
-#' pub_fluview(regions = "nat", epiweeks = epirange(201201, 202001))
+#' \dontrun{
+#' pub_fluview(regions = "nat", epiweeks = epirange(201201, 202005))
+#' }
 #' @param regions character. Locations to fetch. Can be any string IDs in
 #'   national, HHS region, census division, most states and territories, and so
 #'   on. Full list link below.
@@ -1492,7 +1494,7 @@ pvt_norostat <- function(auth, locations, epiweeks, fetch_args = fetch_args_list
 #'
 #' Obtains information on outpatient inluenza-like-illness (ILI) from Delphi's
 #'
-#' @details The full list of location inputs can be accsssed at
+#' @details The full list of location inputs can be accessed at
 #' <https://github.com/cmu-delphi/delphi-epidata/blob/main/src/acquisition/fluview/fluview_locations.py>.
 #'
 #' @examples

R/utils-pipe.R

@@ -1,14 +1,2 @@
-#' Pipe operator
-#'
-#' See \code{magrittr::\link[magrittr:pipe]{\%>\%}} for details.
-#'
-#' @name %>%
-#' @rdname pipe
-#' @keywords internal
-#' @export
 #' @importFrom magrittr %>%
-#' @usage lhs \%>\% rhs
-#' @param lhs A value or the magrittr placeholder.
-#' @param rhs A function call using the magrittr semantics.
-#' @return The result of calling `rhs(lhs)`.
 NULL

README.Rmd

@@ -0,0 +1,102 @@
+---
+output: github_document
+---
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  fig.path = "man/figures/README-",
+  out.width = "100%"
+)
+ggplot2::theme_set(ggplot2::theme_bw())
+```
+
+# Delphi Epidata R client
+
+
+<!-- badges: start -->
+[![License: MIT][mit-image]][mit-url] [![Github Actions][github-actions-image]][github-actions-url]
+[![codecov](https://codecov.io/gh/dsweber2/epidatr/branch/dev/graph/badge.svg?token=jVHL9eHZNZ)](https://app.codecov.io/gh/dsweber2/epidatr)
+<!-- badges: end -->
+
+
+
+The [Delphi Epidata API](https://cmu-delphi.github.io/delphi-epidata/) provides real-time access to epidemiological surveillance data for influenza, COVID-19, and other diseases for the USA at various geographical resolutions, both from official government sources such as the [Center for Disease Control (CDC)](https://www.cdc.gov/datastatistics/index.html) and [Google Trends](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/google-symptoms.html) and private partners such as [Facebook](https://delphi.cmu.edu/blog/2020/08/26/covid-19-symptom-surveys-through-facebook/) and [Change Healthcare](https://www.changehealthcare.com/). It is built and maintained by the Carnegie Mellon University [Delphi research group](https://delphi.cmu.edu/).
+
+This package is designed to streamline the downloading and usage of data from the [Delphi Epidata
+API](https://cmu-delphi.github.io/delphi-epidata/). It provides a simple R interface to the API, including functions for downloading data, parsing the results, and converting the data into a tidy format. The API stores a historical record of all data, including corrections and updates, which is particularly useful for accurately backtesting forecasting models. We also provide packages for downstream data processing ([epiprocess](https://github.com/cmu-delphi/epiprocess)) and modeling ([epipredict](https://github.com/cmu-delphi/epipredict)).
+
+## Usage
+
+```{r}
+library(epidatr)
+# Obtain the smoothed covid-like illness (CLI) signal from the
+# Facebook survey as it was on April 10, 2021 for the US
+epidata <- pub_covidcast(
+  source = "fb-survey",
+  signals = "smoothed_cli",
+  geo_type = "nation",
+  time_type = "day",
+  geo_values = "us",
+  time_values = epirange(20210101, 20210601),
+  as_of = "2021-06-01"
+)
+epidata
+```
+
+```{r fb-cli-signal}
+# Plot this data
+library(ggplot2)
+ggplot(epidata, aes(x = time_value, y = value)) +
+  geom_line() +
+  labs(
+    title = "Smoothed CLI from Facebook Survey",
+    subtitle = "US, 2021",
+    x = "Date",
+    y = "CLI"
+  )
+```
+
+
+## Installation
+
+Install from GitHub:
+
+```R
+# Install the dev version using `pak` or `remotes`
+pak::pkg_install("cmu-delphi/epidatr")
+remotes::install_github("cmu-delphi/epidatr")
+```
+
+CRAN version coming soon.
+
+### API Keys
+
+The Delphi API requires a (free) API key for full functionality. To generate
+your key, register for a pseudo-anonymous account
+[here](https://api.delphi.cmu.edu/epidata/admin/registration_form) and see more
+discussion on the [general API
+website](https://cmu-delphi.github.io/delphi-epidata/api/api_keys.html). The
+`epidatr` client will automatically look for this key in the R option
+`delphi.epidata.key` or in the environment variable
+`DELPHI_EPIDATA_KEY`. We recommend storing your key in `.Renviron` file, which R
+will read by default.
+
+Note that for the time being, the private endpoints (i.e. those prefixed with
+`pvt`) will require a separate key that needs to be passed as an argument.
+
+[mit-image]: https://img.shields.io/badge/License-MIT-yellow.svg
+[mit-url]: https://opensource.org/license/mit/
+[github-actions-image]: https://github.com/cmu-delphi/epidatr/workflows/ci/badge.svg
+[github-actions-url]: https://github.com/cmu-delphi/epidatr/actions
+
+## 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.
+
+## For users of the `covidcast` R package
+
+The `epidatr` package is a complete rewrite of the [`covidcast` package](https://cmu-delphi.github.io/covidcast/covidcastR/), with a focus on speed, reliability, and ease of use. The `covidcast` package is deprecated and will no longer be updated.