Merge pull request #134 from cmu-delphi/98-improve-documentation-experience-for-users-constructing-first-epi_archive

Improved documentation experience for users constructing first `epi_archive`

Author: dajmcdon

.DS_Store

@@ -28,10 +28,12 @@
 #' The data table `DT` has key variables `geo_value`, `time_value`, `version`,
 #'   as well as any others (these can be specified when instantiating the
 #'   `epi_archive` object via the `other_keys` argument, and/or set by operating
-#'   on `DT` directly). There can only be a single row per unique combination of
+#'   on `DT` directly). Refer to the documentation for [as_epi_archive()] for 
+#'   information and examples of relevant parameter names for an `epi_archive` object.
+#'   Note that there can only be a single row per unique combination of
 #'   key variables, and thus the key variables are critical for figuring out how
 #'   to generate a snapshot of data from the archive, as of a given version.
-#' 
+#'  
 #' In general, last observation carried forward (LOCF) is used to data in
 #'   between recorded versions. Currently, deletions must be represented as
 #'   revising a row to a special state (e.g., making the entries `NA` or
@@ -78,6 +80,19 @@
 #' 
 #' @importFrom R6 R6Class
 #' @export
+#' @examples
+#' tib <- tibble::tibble(
+#'   geo_value = rep(c("ca", "hi"), each = 5),
+#'   time_value = rep(seq(as.Date("2020-01-01"), 
+#'                        by = 1, length.out = 5), times = 2),
+#'   version = rep(seq(as.Date("2020-01-02"), 
+#'                     by = 1, length.out = 5), times = 2),
+#'   value = rnorm(10, mean = 2, sd = 1)
+#' )
+#' 
+#' toy_epi_archive <- tib %>% epi_archive$new(geo_type = "state", 
+#'                                            time_type = "day")
+#' toy_epi_archive 
 epi_archive =
   R6::R6Class(
         classname = "epi_archive",
@@ -104,6 +119,10 @@ epi_archive =
 #'   fields; named entries from the passed list or will be included as well.
 #' @return An `epi_archive` object.
 #' @importFrom data.table as.data.table key setkeyv
+#' 
+#' @details 
+#' Refer to the documentation for [as_epi_archive()] for more information 
+#' and examples of parameter names.
           initialize = function(x, geo_type, time_type, other_keys,
                                 additional_metadata) {  
             # Check that we have a data frame
@@ -452,6 +471,21 @@ epi_archive =
 #'
 #' @export
 #' @examples
+#' # Simple ex. with necessary keys
+#' tib <- tibble::tibble(
+#'   geo_value = rep(c("ca", "hi"), each = 5),
+#'   time_value = rep(seq(as.Date("2020-01-01"), 
+#'                        by = 1, length.out = 5), times = 2),
+#'   version = rep(seq(as.Date("2020-01-02"), 
+#'                     by = 1, length.out = 5), times = 2),
+#'   value = rnorm(10, mean = 2, sd = 1)
+#' )
+#' 
+#' toy_epi_archive <- tib %>% as_epi_archive(geo_type = "state", 
+#'                                           time_type = "day")
+#' toy_epi_archive 
+#' 
+#' # Ex. with an additional key for county
 #' df <- data.frame (geo_value  = c(replicate(2, "ca"), replicate(2, "fl")),
 #'                  county = c(1, 3, 2, 5),
 #'                  time_value = c("2020-06-01",