Merge pull request #236 from cmu-delphi/lcb/fix-various-doc-and-vignette-issues

Fix various documentation bugs noted in #217

Author: brookslogan

NEWS.md

@@ -7,6 +7,7 @@ development versions. A ".9999" suffix indicates a development version.
 ## Cleanup:
 
 * Added a `NEWS.md` file to track changes to the package.
+* Fixed various small documentation issues ([#217](https://github.com/cmu-delphi/epiprocess/issues/217)).
 
 # epiprocess 0.5.0:
 
@@ -19,13 +20,13 @@ development versions. A ".9999" suffix indicates a development version.
 
 ## Improvements:
 
-* Fixed `epix_merge`, `<epi_archive>$merge` always raising error on `sync="truncate"`
+* Fixed `epix_merge`, `<epi_archive>$merge` always raising error on `sync="truncate"`.
 
 ## Cleanup:
 
-* Added `Remotes:` entry for `genlasso`, which was removed from CRAN
-* Added `as_epi_archive` tests
-* Added missing `epix_merge` test for `sync="truncate"`
+* Added `Remotes:` entry for `genlasso`, which was removed from CRAN.
+* Added `as_epi_archive` tests.
+* Added missing `epix_merge` test for `sync="truncate"`.
 
 # epiprocess 0.4.0:
 
@@ -68,7 +69,7 @@ development versions. A ".9999" suffix indicates a development version.
   * `epix_<method>` will not mutate input `epi_archive`s, but may alias them
     or alias their fields (which should not be a worry if a user sticks to
     these `epix_*` functions and "regular" R functions with
-    copy-on-write-like behavior, avoiding mutating functions `[.data.table`)
+    copy-on-write-like behavior, avoiding mutating functions `[.data.table`).
   * `x$<method>` may mutate `x`; if it mutates `x`, it will return `x`
     invisibly (where this makes sense), and, for each of its fields, may
     either mutate the object to which it refers or reseat the reference (but
@@ -109,7 +110,7 @@ development versions. A ".9999" suffix indicates a development version.
 * New function `epix_fill_through_version`, method
   `<epi_archive>$fill_through_version`: non-mutating & mutating way to
   ensure that an archive contains versions at least through some
-  `fill_versions_end`, extrapolating according to `how` if necessary
+  `fill_versions_end`, extrapolating according to `how` if necessary.
 * Example archive data object is now constructed on demand from its
   underlying data, so it will be based on the user's version of
   `epi_archive` rather than an outdated R6 implementation from whenever the
@@ -215,7 +216,7 @@ Classes:
   * `epi_cor` calculates Pearson, Kendall, or Spearman correlations
     between two (optionally time-shifted) variables in an `epi_df` within
     user-specified groups.
-  * Convenience function: `is_epi_df`
+  * Convenience function: `is_epi_df`.
 * `epi_archive`: R6 class for version (patch) data for geotemporal
   epidemiological time series data sets. Comes with S3 methods and regular
   functions that wrap around this functionality for those unfamiliar with R6
@@ -224,23 +225,23 @@ Classes:
     containing snapshots and/or patch data for every available version of
     the data set.
   * `as_of`: extracts a snapshot of the data set as of some requested
-    version, in `epi_df` format
+    version, in `epi_df` format.
   * `epix_slide`, `<epi_archive>$slide`: similar to `epi_slide`, but for
     `epi_archive`s; for each requested `ref_time_value` and group, applies
     a time window and user-specified computation to a snapshot of the data
     as of `ref_time_value`.
   * `epix_merge`, `<epi_archive>$merge`: like `merge` for `epi_archive`s,
     but allowing for the last version of each observation to be carried
     forward to fill in gaps in `x` or `y`.
-  * Convenience function: `is_epi_archive`
+  * Convenience function: `is_epi_archive`.
 
 Additional functions:
 * `growth_rate`: estimates growth rate of a time series using one of a few
   built-in `method`s based on relative change, linear regression,
   smoothing splines, or trend filtering.
 * `detect_outlr`: applies one or more outlier detection methods to a given
   signal variable, and optionally aggregates the outputs to create a
-  consensus result
+  consensus result.
 * `detect_outlr_rm`: outlier detection function based on a
   rolling-median-based outlier detection function; one of the methods
   included in `detect_outlr`.

R/methods-epi_archive.R

@@ -76,7 +76,7 @@ epix_as_of = function(x, max_version, min_time_value = -Inf) {
 #'  `x`), and returns the updated `x` [invisibly][base::invisible].
 #'
 #' @param x An `epi_archive`
-#' @param fill_versions_end Length-1, same class&type as `%s$version`: the
+#' @param fill_versions_end Length-1, same class&type as `x$version`: the
 #'   version through which to fill in missing version history; this will be the
 #'   result's `$versions_end` unless it already had a later
 #'   `$versions_end`.
@@ -397,9 +397,10 @@ epix_merge = function(x, y,
 #' @param new_col_name String indicating the name of the new column that will
 #'   contain the derivative values. Default is "slide_value"; note that setting
 #'   `new_col_name` equal to an existing column name will overwrite this column.
-#' @param as_list_col Should the new column be stored as a list column? Default
-#'   is `FALSE`, in which case a list object returned by `f` would be unnested
-#'   (using `tidyr::unnest()`), and the names of the resulting columns are given
+#' @param as_list_col If the computations return data frames, should the slide
+#'   result hold these in a single list column or try to unnest them? Default is
+#'   `FALSE`, in which case a list object returned by `f` would be unnested
+#'   (using [`tidyr::unnest()`]), and the names of the resulting columns are given
 #'   by prepending `new_col_name` to the names of the list elements.
 #' @param names_sep String specifying the separator to use in `tidyr::unnest()`
 #'   when `as_list_col = FALSE`. Default is "_". Using `NULL` drops the prefix

R/slide.R

@@ -46,9 +46,10 @@
 #' @param new_col_name String indicating the name of the new column that will
 #'   contain the derivative values. Default is "slide_value"; note that setting
 #'   `new_col_name` equal to an existing column name will overwrite this column.
-#' @param as_list_col Should the new column be stored as a list column? Default
-#'   is `FALSE`, in which case a list object returned by `f` would be unnested 
-#'   (using `tidyr::unnest()`), and the names of the resulting columns are given
+#' @param as_list_col If the computations return data frames, should the slide
+#'   result hold these in a single list column or try to unnest them? Default is
+#'   `FALSE`, in which case a list object returned by `f` would be unnested
+#'   (using [`tidyr::unnest()`]), and the names of the resulting columns are given
 #'   by prepending `new_col_name` to the names of the list elements.
 #' @param names_sep String specifying the separator to use in `tidyr::unnest()`
 #'   when `as_list_col = FALSE`. Default is "_". Using `NULL` drops the prefix

README.md

@@ -45,10 +45,10 @@ The second main data structure in the package is called
 wrapped around a data table that stores the archive (version history) of some
 signal variables of interest.
 
-By convention, functions in the `epiprocess` package that operate on `epi_df`
-objects begin with `epix` (the "x" is meant to remind you of "archive"). These
-are just wrapper functions around the public methods for the `epi_archive` R6
-class. For example:
+By convention, functions in the `epiprocess` package that operate on
+`epi_archive` objects begin with `epix` (the "x" is meant to remind you of
+"archive"). These are just wrapper functions around the public methods for the
+`epi_archive` R6 class. For example:
 
 - `epix_as_of()`, for generating a snapshot in `epi_df` from the data archive,
   which represents the most up-to-date values of the signal variables, as of the

_pkgdown.yml

@@ -6,9 +6,11 @@ url: https://cmu-delphi.github.io/epiprocess/
 home:
   links:
   - text: Get the epipredict R package
-    href: https://cmu-delphi.github.io/epiprocess/
+    href: https://cmu-delphi.github.io/epipredict/
   - text: Get the covidcast R package
     href: https://cmu-delphi.github.io/covidcast/covidcastR/
+  - text: Get the epidatr R package
+    href: https://github.com/cmu-delphi/epidatr
 
 articles:
 - title: Using the package
@@ -34,11 +36,11 @@ repo:
 
 
 reference:
-- title: epi_df basics
+- title: "`epi_df` basics"
   desc: Details on `epi_df` format, and basic functionality.
 - contents:
   - matches("epi_df")
-- title: epi_*() functions
+- title: "`epi_*()` functions"
   desc: Functions that act on `epi_df` objects.
 - contents:
   - epi_slide
@@ -50,11 +52,11 @@ reference:
   - detect_outlr
   - detect_outlr_rm
   - detect_outlr_stl
-- title: epi_archive basics
+- title: "`epi_archive` basics"
   desc: Details on `epi_archive`, and basic functionality.
 - contents:
   - matches("archive")
-- title: epix_*() functions
+- title: "`epix_*()` functions"
   desc: Functions that act on an `epi_archive` object.
 - contents:
   - starts_with("epix")

man/epi_slide.Rd

@@ -241,7 +241,7 @@ head(xt_filled_month)
 TODO
 
 ## Attribution
-This document contains dataset that is a modified part of the [COVID-19 Data Repository by the Center for Systems Science and Engineering (CSSE) at Johns Hopkins University](https://github.com/CSSEGISandData/COVID-19) as [republished in the COVIDcast Epidata API](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html). This data set is licensed under the terms of the [Creative Commons Attribution 4.0 International license](https://creativecommons.org/licenses/by/4.0/) by the Johns Hopkins University on behalf of its Center for Systems Science in Engineering. Copyright Johns Hopkins University 2020.
+This document contains a dataset that is a modified part of the [COVID-19 Data Repository by the Center for Systems Science and Engineering (CSSE) at Johns Hopkins University](https://github.com/CSSEGISandData/COVID-19) as [republished in the COVIDcast Epidata API](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html). This data set is licensed under the terms of the [Creative Commons Attribution 4.0 International license](https://creativecommons.org/licenses/by/4.0/) by the Johns Hopkins University on behalf of its Center for Systems Science in Engineering. Copyright Johns Hopkins University 2020.
 
 [From the COVIDcast Epidata API](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html): 
  These signals are taken directly from the JHU CSSE [COVID-19 GitHub repository](https://github.com/CSSEGISandData/COVID-19) without changes. 

man/epix_fill_through_version.Rd

@@ -30,6 +30,8 @@ library(epidatr)
 library(epiprocess)
 library(data.table)
 library(dplyr)
+library(purrr)
+library(ggplot2)
 
 dv <- covidcast(
   data_source = "doctor-visits",
@@ -48,6 +50,8 @@ library(epidatr)
 library(epiprocess)
 library(data.table)
 library(dplyr)
+library(purrr)
+library(ggplot2)
 ```
 
 ## Getting data into `epi_archive` format
@@ -141,15 +145,6 @@ as in `x$geo_type` or `x$time_type`, etc. Just like `as_epi_df()`, the function
 object is instantiated, if they are not explicitly specified in the function
 call (as it did in the case above).
 
-Note that `compactify` is **NOT** metadata and is an argument passed when creating
-the dataset, without being stored in the end:
-
-```{r,message=FALSE}
-# `dt` here is taken from the tests
-as_epi_archive(archive_cases_dv_subset$DT,compactify=TRUE)$geo_type # "state"
-as_epi_archive(archive_cases_dv_subset$DT,compactify=TRUE)$compactify # NULL
-```
-
 ## Producing snapshots in `epi_df` form
 
 A key method of an `epi_archive` class is `as_of()`, which generates a snapshot
@@ -189,8 +184,6 @@ marked by dotted vertical lines, and draw the latest curve in black (from the
 latest snapshot `x_latest` that the archive can provide).
 
 ```{r, fig.width = 8, fig.height = 7}
-library(purrr)
-library(ggplot2)
 theme_set(theme_bw())
 
 self_max = max(x$DT$version)
@@ -203,15 +196,15 @@ snapshots <- map_dfr(versions, function(v) {
 
 ggplot(snapshots %>% filter(!latest),
             aes(x = time_value, y = percent_cli)) +  
-  geom_line(aes(color = factor(version))) + 
+  geom_line(aes(color = factor(version)), na.rm=TRUE) + 
   geom_vline(aes(color = factor(version), xintercept = version), lty = 2) +
   facet_wrap(~ geo_value, scales = "free_y", ncol = 1) +
   scale_x_date(minor_breaks = "month", date_labels = "%b %y") +
   labs(x = "Date", y = "% of doctor's visits with CLI") + 
   theme(legend.position = "none") +
   geom_line(data = snapshots %>% filter(latest),
                aes(x = time_value, y = percent_cli), 
-               inherit.aes = FALSE, color = "black")
+            inherit.aes = FALSE, color = "black", na.rm=TRUE)
 ```
 
 We can see some interesting and highly nontrivial revision behavior: at some
@@ -444,7 +437,7 @@ the vignettes in the current package are only meant to demo the slide
 functionality with some of the most basic forecasting methodology possible.
 
 ## Attribution
-This document contains dataset that is a modified part of the [COVID-19 Data Repository by the Center for Systems Science and Engineering (CSSE) at Johns Hopkins University](https://github.com/CSSEGISandData/COVID-19) as [republished in the COVIDcast Epidata API](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html). This data set is licensed under the terms of the [Creative Commons Attribution 4.0 International license](https://creativecommons.org/licenses/by/4.0/) by the Johns Hopkins University on behalf of its Center for Systems Science in Engineering. Copyright Johns Hopkins University 2020.
+This document contains a dataset that is a modified part of the [COVID-19 Data Repository by the Center for Systems Science and Engineering (CSSE) at Johns Hopkins University](https://github.com/CSSEGISandData/COVID-19) as [republished in the COVIDcast Epidata API](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html). This data set is licensed under the terms of the [Creative Commons Attribution 4.0 International license](https://creativecommons.org/licenses/by/4.0/) by the Johns Hopkins University on behalf of its Center for Systems Science in Engineering. Copyright Johns Hopkins University 2020.
 
 The `percent_cli` data is a modified part of the [COVIDcast Epidata API Doctor Visits data](https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/doctor-visits.html). This dataset is licensed under the terms of the [Creative Commons Attribution 4.0 International license](https://creativecommons.org/licenses/by/4.0/). Copyright Delphi Research Group at Carnegie Mellon University 2020.
 

man/epix_slide.Rd

@@ -28,7 +28,7 @@ For this example, we have one chart using LOCF values, while another doesn't
 use them to illustrate LOCF. Notice how the head of the first dataset differs
 from the second from the third value included.
 
-```{r}
+```{r, message=FALSE}
 library(epiprocess)
 library(dplyr)