refactor+docs: move complete.epi_df tests to examples

* complete.epi_df now has its own docs page

Author: dshemetov

R/methods-epi_df.R

@@ -241,12 +241,68 @@ group_modify.epi_df <- function(.data, .f, ..., .keep = FALSE) {
   dplyr::dplyr_reconstruct(NextMethod(), .data)
 }
 
-#' @importFrom tidyr complete
-#' @rdname print.epi_df
+#' Complete epi_df
+#'
+#' A [tidyr::complete()] analogue for `epi_df` objects. This function fills in
+#' missing combinations of `geo_value` and `time_value` with `NA` values. See
+#' the examples for usage details.
+#'
 #' @param data an `epi_df`
+#' @param ... see [`tidyr::complete`]
 #' @param fill see [`tidyr::complete`]
 #' @param explicit see [`tidyr::complete`]
+#'
 #' @method complete epi_df
+#' @importFrom tidyr complete
+#'
+#' @examples
+#' start_date <- as.Date("2020-01-01")
+#' daily_edf <- tibble::tribble(
+#'   ~geo_value, ~time_value, ~value,
+#'   1, start_date + 1, 1,
+#'   1, start_date + 3, 3,
+#'   2, start_date + 2, 2,
+#'   2, start_date + 3, 3,
+#' ) %>%
+#'   as_epi_df(as_of = start_date + 3)
+#' # Complete without grouping puts all the geo_values on the same min and max
+#' # time_value index
+#' daily_edf %>%
+#'   complete(geo_value, time_value = full_seq(time_value, period = 1))
+#' # Complete with grouping puts all the geo_values on individual min and max
+#' # time_value indices
+#' daily_edf %>%
+#'   group_by(geo_value) %>%
+#'   complete(time_value = full_seq(time_value, period = 1))
+#' # Complete has explicit=TRUE by default, but if it's FALSE, then complete only fills the implicit gaps
+#' # not those that are explicitly NA
+#' daily_edf <- tibble::tribble(
+#'   ~geo_value, ~time_value, ~value,
+#'   1, start_date + 1, 1,
+#'   1, start_date + 2, NA,
+#'   1, start_date + 3, 3,
+#'   2, start_date + 2, 2,
+#'   2, start_date + 3, 3,
+#' ) %>%
+#'   as_epi_df(as_of = start_date + 3)
+#' daily_edf %>%
+#'   complete(geo_value, time_value = full_seq(time_value, period = 1), fill = list(value = 0), explicit = FALSE)
+#' # Complete works for weekly data and can take a fill value
+#' # No grouping
+#' weekly_edf <- tibble::tribble(
+#'   ~geo_value, ~time_value, ~value,
+#'   1, start_date + 1, 1,
+#'   1, start_date + 15, 3,
+#'   2, start_date + 8, 2,
+#'   2, start_date + 15, 3,
+#' ) %>%
+#'   as_epi_df(as_of = start_date + 3)
+#' weekly_edf %>%
+#'   complete(geo_value, time_value = full_seq(time_value, period = 7), fill = list(value = 0))
+#' # With grouping
+#' weekly_edf %>%
+#'   group_by(geo_value) %>%
+#'   complete(time_value = full_seq(time_value, period = 7), fill = list(value = 0))
 #' @export
 complete.epi_df <- function(data, ..., fill = list(), explicit = TRUE) {
   result <- dplyr::dplyr_reconstruct(NextMethod(), data)

man/complete.epi_df.Rd

@@ -180,76 +180,116 @@ test_that("Renaming columns while grouped gives appropriate colnames and metadat
 
 test_that("complete.epi_df works", {
   start_date <- as.Date("2020-01-01")
-  daily_edf <- tibble::tibble(
-    geo_value = c(1, 2),
-    time_value = start_date + c(1, 2),
-    value = 1
+  daily_edf <- tibble::tribble(
+    ~geo_value, ~time_value, ~value,
+    1, start_date + 1, 1,
+    1, start_date + 3, 3,
+    2, start_date + 2, 2,
+    2, start_date + 3, 3,
   ) %>%
     as_epi_df(as_of = start_date + 3)
+  # Complete without grouping puts all the geo_values on the same min and max
+  # time_value index
   expect_identical(
     daily_edf %>%
-      tidyr::complete(geo_value, time_value = full_seq(time_value, period = 1)),
-    tibble::tibble(
-      geo_value = c(1, 1, 2, 2),
-      time_value = start_date + c(1, 2, 1, 2),
-      value = c(1, NA, NA, 1)
+      complete(geo_value, time_value = full_seq(time_value, period = 1)),
+    tibble::tribble(
+      ~geo_value, ~time_value, ~value,
+      1, start_date + 1, 1,
+      1, start_date + 2, NA,
+      1, start_date + 3, 3,
+      2, start_date + 1, NA,
+      2, start_date + 2, 2,
+      2, start_date + 3, 3,
     ) %>%
       as_epi_df(as_of = start_date + 3)
   )
+  # Complete with grouping puts all the geo_values on individual min and max
+  # time_value indices
   expect_identical(
     daily_edf %>%
       group_by(geo_value) %>%
-      tidyr::complete(time_value = full_seq(time_value, period = 1)),
-    daily_edf %>%
+      complete(time_value = full_seq(time_value, period = 1)),
+    tibble::tribble(
+      ~geo_value, ~time_value, ~value,
+      1, start_date + 1, 1,
+      1, start_date + 2, NA,
+      1, start_date + 3, 3,
+      2, start_date + 2, 2,
+      2, start_date + 3, 3,
+    ) %>%
+      as_epi_df(as_of = start_date + 3) %>%
       group_by(geo_value)
   )
-  weekly_edf <- tibble::tibble(
-    geo_value = c(1, 1, 1, 2),
-    time_value = start_date + c(1, 15, 22, 1),
-    value = 1
+  # Complete has explicit=TRUE by default, but if it's FALSE, then complete only fills the implicit gaps
+  # not those that are explicitly NA
+  daily_edf <- tibble::tribble(
+    ~geo_value, ~time_value, ~value,
+    1, start_date + 1, 1,
+    1, start_date + 2, NA,
+    1, start_date + 3, 3,
+    2, start_date + 2, 2,
+    2, start_date + 3, 3,
   ) %>%
     as_epi_df(as_of = start_date + 3)
   expect_identical(
-    weekly_edf %>%
-      complete(geo_value,
-        time_value = full_seq(time_value, period = 7),
-        fill = list(value = 5)
-      ),
-    tibble::tibble(
-      geo_value = c(1, 1, 1, 1, 2, 2, 2, 2),
-      time_value = start_date + c(1, 8, 15, 22, 1, 8, 15, 22),
-      value = c(1, 5, 1, 1, 1, 5, 5, 5)
+    daily_edf %>%
+      complete(geo_value, time_value = full_seq(time_value, period = 1), fill = list(value = 0), explicit = FALSE),
+    tibble::tribble(
+      ~geo_value, ~time_value, ~value,
+      1, start_date + 1, 1,
+      1, start_date + 2, NA,
+      1, start_date + 3, 3,
+      2, start_date + 1, 0,
+      2, start_date + 2, 2,
+      2, start_date + 3, 3,
     ) %>%
       as_epi_df(as_of = start_date + 3)
   )
+  # Complete works for weekly data and can take a fill value
+  # No grouping
+  weekly_edf <- tibble::tribble(
+    ~geo_value, ~time_value, ~value,
+    1, start_date + 1, 1,
+    1, start_date + 15, 3,
+    2, start_date + 8, 2,
+    2, start_date + 15, 3,
+  ) %>%
+    as_epi_df(as_of = start_date + 3)
   expect_identical(
     weekly_edf %>%
-      group_by(geo_value) %>%
-      complete(
+      complete(geo_value,
         time_value = full_seq(time_value, period = 7),
-        fill = list(value = 5)
-      ) %>%
-      ungroup(),
-    tibble::tibble(
-      geo_value = c(1, 1, 1, 1, 2),
-      time_value = start_date + c(1, 8, 15, 22, 1),
-      value = c(1, 5, 1, 1, 1)
+        fill = list(value = 0)
+      ),
+    tibble::tribble(
+      ~geo_value, ~time_value, ~value,
+      1, start_date + 1, 1,
+      1, start_date + 8, 0,
+      1, start_date + 15, 3,
+      2, start_date + 1, 0,
+      2, start_date + 8, 2,
+      2, start_date + 15, 3,
     ) %>%
       as_epi_df(as_of = start_date + 3)
   )
+  # With grouping
   expect_identical(
     weekly_edf %>%
       group_by(geo_value) %>%
       complete(
-        time_value = full_seq(time_value, period = 1),
-        fill = list(value = 5)
-      ) %>%
-      ungroup(),
-    tibble::tibble(
-      geo_value = c(rep(1, 22), 2),
-      time_value = start_date + c(1:22, 1),
-      value = c(1, rep(5, 13), 1, rep(5, 6), 1, 1)
+        time_value = full_seq(time_value, period = 7),
+        fill = list(value = 0)
+      ),
+    tibble::tribble(
+      ~geo_value, ~time_value, ~value,
+      1, start_date + 1, 1,
+      1, start_date + 8, 0,
+      1, start_date + 15, 3,
+      2, start_date + 8, 2,
+      2, start_date + 15, 3,
     ) %>%
-      as_epi_df(as_of = start_date + 3)
+      as_epi_df(as_of = start_date + 3) %>%
+      group_by(geo_value)
   )
 })