Merge pull request #166 from cmu-delphi/ds/friendly-docs

docs: make friendly

Author: dshemetov

.github/workflows/document.yaml

@@ -37,6 +37,6 @@ jobs:
           git config --local user.name "$GITHUB_ACTOR"
           git config --local user.email "[email protected]"
           git add man/\* NAMESPACE DESCRIPTION
-          git commit -m "Update documentation" || echo "No changes to commit"
+          git commit -m "docs: document (GHA)" || echo "No changes to commit"
           git pull --rebase
           git push origin

.github/workflows/style.yaml

@@ -65,7 +65,7 @@ jobs:
           then
             git config --local user.name "$GITHUB_ACTOR"
             git config --local user.email "[email protected]"
-            git commit ${FILES_TO_COMMIT[*]} -m "Style code (GHA)"
+            git commit ${FILES_TO_COMMIT[*]} -m "style: styler (GHA)"
             git pull --rebase
             git push origin
           else

DESCRIPTION

@@ -36,6 +36,7 @@ Imports:
 RoxygenNote: 7.2.3
 Suggests:
     dplyr,
+    ggplot2,
     knitr,
     rmarkdown,
     testthat (>= 3.1.5),

Makefile

@@ -1,12 +1,15 @@
 install:
-    Rscript -e "install.packages(c('devtools', 'pkgdown', 'webshot', 'textshaping', 'styler', 'lintr'));devtools::install_deps(dependencies = TRUE)"
+	Rscript -e "install.packages(c('devtools', 'pkgdown', 'webshot', 'textshaping', 'styler', 'lintr'));devtools::install_deps(dependencies = TRUE)"
 lint:
-    Rscript -e "devtools::load_all();lintr::lint_package()"
+	Rscript -e "devtools::load_all();lintr::lint_package()"
 format:
-    Rscript -e "styler::style_pkg()"
+	Rscript -e "styler::style_pkg()"
 test:
-    Rscript -e "devtools::test()"
-build:
-    Rscript -e "devtools::document();devtools::build()"
+	Rscript -e "devtools::test()"
+document:
+	Rscript -e "devtools::document()"
+build: document
+	Rscript -e "devtools::build()"
 check:
-    Rscript -e "devtools::check(args = c('--no-manual', '--as-cran'), error_on = 'error')"
+	Rscript -e "devtools::check(args = c('--no-manual', '--as-cran'), error_on = 'warning')"
+chores: format lint check

README.md

@@ -3,21 +3,26 @@
 [![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://codecov.io/gh/dsweber2/epidatr)
 
-This package provides an R client for the [Delphi Epidata
-API](https://cmu-delphi.github.io/delphi-epidata/).
+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 from both official government sources such as the [Center for Disease Control (CDC)](https://www.cdc.gov/datastatistics/index.html) and private partners such as [Quidel](https://www.quidel.com/), [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)
-epicall <- covidcast(
+# Obtain the smoothed covid-like illness (CLI) signal from the Facebook survey as it was on April 10, 2021 for the US
+epidata <- covidcast(
   source = "fb-survey",
   signals = "smoothed_cli",
   geo_type = "nation",
   time_type = "day",
   geo_values = "us",
-  time_values = epirange(20210405, 20210410)
+  time_values = epirange(20210101, 20210601),
+  as_of = "2021-06-01"
 )
+epidata
 ```
 
 ```
@@ -36,6 +41,19 @@ epicall <- covidcast(
 #   sample_size <dbl>
 ```
 
+```r
+# 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")
+```
+
+<img src="man/figures/fb-cli-signal.png" style="height:750px; width:750px" alt="Smoothed CLI from Facebook Survey">
+
 ## Installation
 
 Install from GitHub:

man/figures/fb-cli-signal.png

@@ -4,6 +4,7 @@ output: rmarkdown::html_vignette
 vignette: >
   %\VignetteIndexEntry{Delphi Epidata R API Client}
   %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteDepends{ggplot2}
   \usepackage[utf8]{inputenc}
 ---
 
@@ -44,10 +45,25 @@ In this case, the `covidcast()` function lets us specify these parameters for
 the endpoint and returns a tibble with the results:
 
 ```{r}
-covidcast(
+epidata <- covidcast(
   "fb-survey", "smoothed_cli", "state", "day", "pa",
-  epirange(20210405, 20210410)
+  epirange(20210105, 20210410)
 )
+epidata
+```
+
+We can then easily plot the data using ggplot2:
+
+```{r, out.height="65%"}
+library(ggplot2)
+ggplot(epidata, aes(x = time_value, y = value)) +
+  geom_line() +
+  labs(
+    title = "Smoothed CLI from Facebook Survey",
+    subtitle = "PA, 2021",
+    x = "Date",
+    y = "CLI"
+  )
 ```
 
 The [Delphi Epidata API documentation](https://cmu-delphi.github.io/delphi-epidata/) has more information on the available endpoints and arguments. You can also use the `avail_endpoints()` function to get a table of endpoint functions: