Merge pull request #555 from cmu-delphi/ds/vignettes

doc: updates from review

Author: dshemetov

DEVELOPMENT.md

@@ -26,16 +26,20 @@ Our CI builds two version of the documentation:
 - https://cmu-delphi.github.io/epiprocess/ from the `main` branch and
 - https://cmu-delphi.github.io/epiprocess/dev from the `dev` branch.
 
-We include the script `pkgdown-watch.R` that will automatically rebuild the
-documentation locally and preview it. It can be used with:
+Commands for developing the documentation site:
 
 ```sh
-# Make sure you have servr installed
-R -e 'renv::install("servr")'
-# Will start a local server
-Rscript pkgdown-watch.R
-# You may need to first build the site with
+# Basic build and preview
+R -e 'pkgdown::clean_site()'
+R -e 'devtools::document()'
+R -e 'pkgdown::build_site()'
+
+# A smart rebuild workflow for non-RStudio users.
+# You may need to first build the site.
 R -e 'pkgdown::build_site(".", examples = FALSE, devel = TRUE, preview = FALSE)'
+R -e 'renv::install("servr")'
+# Will start a local docs server and monitor for changes.
+Rscript inst/pkgdown-watch.R
 ```
 
 ## Versioning

R/methods-epi_archive.R

@@ -627,10 +627,9 @@ epix_detailed_restricted_mutate <- function(.data, ...) {
 #' Slides a given function over variables in an `epi_archive` object. This
 #' behaves similarly to `epi_slide()`, with the key exception that it is
 #' version-aware: the sliding computation at any given reference time t is
-#' performed on **data that would have been available as of t**. See the
-#' [archive
-#' vignette](https://cmu-delphi.github.io/epiprocess/articles/archive.html) for
-#' examples.
+#' performed on **data that would have been available as of t**. This function
+#' is intended for use in accurate backtesting of models; see
+#' `vignette("backtesting", package="epipredict")` for a walkthrough.
 #'
 #' @param .x An [`epi_archive`] or [`grouped_epi_archive`] object. If ungrouped,
 #'   all data in `x` will be treated as part of a single data group.

R/slide.R

@@ -6,12 +6,15 @@
 #' as follows:
 #'
 #' ```
-#' # To compute the 7-day trailing average of cases
-#' epi_slide(edf, cases_7dav = mean(cases), .window_size = 7)
+#' # Create new column `cases_7dm` that contains a 7-day trailing median of cases
+#' epi_slide(edf, cases_7dav = median(cases), .window_size = 7)
 #' ```
 #'
-#' This will create the new column `cases_7dav` that contains a 7-day rolling
-#' average of values in "cases". See `vignette("epi_df")` for more examples.
+#' For two very common use cases, we provide optimized functions that are much
+#' faster than `epi_slide`: `epi_slide_mean()` and `epi_slide_sum()`. We
+#' recommend using these functions when possible.
+#'
+#' See `vignette("epi_df")` for more examples.
 #'
 #' @template basic-slide-params
 #' @param .f Function, formula, or missing; together with `...` specifies the

README.Rmd

@@ -5,7 +5,7 @@ output: github_document
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
 ```{r, include = FALSE}
-source(here::here("vignettes", "_common.R"))
+source(file.path("vignettes", "_common.R"))
 knitr::opts_chunk$set(
   fig.path = "man/figures/README-"
 )
@@ -16,7 +16,7 @@ knitr::opts_chunk$set(
 The `{epiprocess}` package works with epidemiological time series data and
 provides tools to manage, analyze, and process the data in preparation for
 modeling. It is designed to work in tandem with
-[`{epipredict}`](https://cmu-delphi.github.io/epipredict/), which provides
+[epipredict](https://cmu-delphi.github.io/epipredict/), which provides
 pre-built epiforecasting models and as well as tools to build custom models.
 Both packages are designed to lower the barrier to entry and implementation cost
 for epidemiological time series analysis and forecasting.
@@ -25,13 +25,18 @@ for epidemiological time series analysis and forecasting.
 
 - `epi_df()` and `epi_archive()`, two data frame classes (that work like a
 `{tibble}` with `{dplyr}` verbs) for working with epidemiological time
-series data;
+series data
+  - `epi_df` is for working with a snapshot of data at a single point in time
+  - `epi_archive` is for working with histories of data that changes over time
+  - one of the most common uses of `epi_archive` is for accurate backtesting of
+    forecasting models, see `vignette("backtesting", package="epipredict")`
 - signal processing tools building on these data structures such as
-  - `epi_slide()` for sliding window operations;
-  - `epix_slide()` for sliding window operations on archives;
-  - `growth_rate()` for computing growth rates;
-  - `detect_outlr()` for outlier detection;
-  - `epi_cor()` for computing correlations;
+  - `epi_slide()` for sliding window operations (aids with feature creation)
+  - `epix_slide()` for sliding window operations on archives (aids with
+  backtesting)
+  - `growth_rate()` for computing growth rates
+  - `detect_outlr()` for outlier detection
+  - `epi_cor()` for computing correlations
 
 If you are new to this set of tools, you may be interested learning through a
 book format: [Introduction to Epidemiological
@@ -41,7 +46,7 @@ You may also be interested in:
 
 - `{epidatr}`, for accessing wide range
 of epidemiological data sets, including COVID-19 data, flu data, and more.
-- `{rtestim}`, a package for estimating
+- [rtestim](https://github.com/dajmcdon/rtestim), a package for estimating
 the time-varying reproduction number of an epidemic.
 
 This package is provided by the [Delphi group](https://delphi.cmu.edu/) at

README.md

@@ -6,23 +6,32 @@
 The `{epiprocess}` package works with epidemiological time series data
 and provides tools to manage, analyze, and process the data in
 preparation for modeling. It is designed to work in tandem with
-[`{epipredict}`](https://cmu-delphi.github.io/epipredict/), which
-provides pre-built epiforecasting models and as well as tools to build
-custom models. Both packages are designed to lower the barrier to entry
-and implementation cost for epidemiological time series analysis and
+[epipredict](https://cmu-delphi.github.io/epipredict/), which provides
+pre-built epiforecasting models and as well as tools to build custom
+models. Both packages are designed to lower the barrier to entry and
+implementation cost for epidemiological time series analysis and
 forecasting.
 
 `{epiprocess}` contains:
 
   - `epi_df()` and `epi_archive()`, two data frame classes (that work
     like a `{tibble}` with `{dplyr}` verbs) for working with
-    epidemiological time series data;
+    epidemiological time series data
+      - `epi_df` is for working with a snapshot of data at a single
+        point in time
+      - `epi_archive` is for working with histories of data that changes
+        over time
+      - one of the most common uses of `epi_archive` is for accurate
+        backtesting of forecasting models, see `vignette("backtesting",
+        package="epipredict")`
   - signal processing tools building on these data structures such as
-      - `epi_slide()` for sliding window operations;
-      - `epix_slide()` for sliding window operations on archives;
-      - `growth_rate()` for computing growth rates;
-      - `detect_outlr()` for outlier detection;
-      - `epi_cor()` for computing correlations;
+      - `epi_slide()` for sliding window operations (aids with feature
+        creation)
+      - `epix_slide()` for sliding window operations on archives (aids
+        with backtesting)
+      - `growth_rate()` for computing growth rates
+      - `detect_outlr()` for outlier detection
+      - `epi_cor()` for computing correlations
 
 If you are new to this set of tools, you may be interested learning
 through a book format: [Introduction to Epidemiological
@@ -32,8 +41,8 @@ You may also be interested in:
 
   - `{epidatr}`, for accessing wide range of epidemiological data sets,
     including COVID-19 data, flu data, and more.
-  - `{rtestim}`, a package for estimating the time-varying reproduction
-    number of an epidemic.
+  - [rtestim](https://github.com/dajmcdon/rtestim), a package for
+    estimating the time-varying reproduction number of an epidemic.
 
 This package is provided by the [Delphi group](https://delphi.cmu.edu/)
 at Carnegie Mellon University.

pkgdown-watch.R renamed to inst/pkgdown-watch.R

@@ -36,7 +36,7 @@ servr::httw(
     refs <- grep("man.+R(m?d)?$", files, value = TRUE)
     if (length(refs)) {
       # Doesn't work for me, so I run it manually.
-      # pkgdown::build_reference(pkg, preview = FALSE, examples = FALSE, lazy = FALSE)
+      # pkgdown::build_reference(pkg, preview = FALSE, examples = FALSE, lazy = FALSE) # nolint: commented_code_linter
     }
 
     pkgdown <- grep("pkgdown", files, value = TRUE)

man/epi_slide.Rd

@@ -8,7 +8,7 @@ vignette: >
 ---
 
 ```{r, include = FALSE}
-source(here::here("vignettes", "_common.R"))
+source("_common.R")
 ```
 
 ## Removing redundant update data to save space

man/epix_slide.Rd

@@ -8,7 +8,7 @@ vignette: >
 ---
 
 ```{r, include = FALSE}
-source(here::here("vignettes", "_common.R"))
+source("_common.R")
 ```
 
 The `epiprocess` package provides some simple functionality for computing lagged