feat: add complete.epi_df

* add tests and documentation examples
* complete.epi_df now has its own docs page
* bump version and changelog

Co-authored-by: Dmitry Shemetov <dshemetov@ucdavis.edu>

Author: brookslogan

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: epiprocess
 Title: Tools for basic signal processing in epidemiology
-Version: 0.8.0
+Version: 0.8.1
 Authors@R: c(
     person("Jacob", "Bien", role = "ctb"),
     person("Logan", "Brooks", email = "lcbrooks@andrew.cmu.edu", role = c("aut", "cre")),

NAMESPACE

@@ -11,6 +11,7 @@ S3method(as_tsibble,epi_df)
 S3method(autoplot,epi_df)
 S3method(clone,epi_archive)
 S3method(clone,grouped_epi_archive)
+S3method(complete,epi_df)
 S3method(dplyr_col_modify,col_modify_recorder_df)
 S3method(dplyr_col_modify,epi_df)
 S3method(dplyr_reconstruct,epi_df)
@@ -50,6 +51,7 @@ export(as_epi_df)
 export(as_tsibble)
 export(autoplot)
 export(clone)
+export(complete)
 export(detect_outlr)
 export(detect_outlr_rm)
 export(detect_outlr_stl)
@@ -64,6 +66,7 @@ export(epix_merge)
 export(epix_slide)
 export(epix_truncate_versions_after)
 export(filter)
+export(full_seq)
 export(geo_column_names)
 export(group_by)
 export(group_modify)
@@ -194,6 +197,8 @@ importFrom(stats,median)
 importFrom(tibble,as_tibble)
 importFrom(tibble,new_tibble)
 importFrom(tibble,validate_tibble)
+importFrom(tidyr,complete)
+importFrom(tidyr,full_seq)
 importFrom(tidyr,unnest)
 importFrom(tidyselect,any_of)
 importFrom(tidyselect,eval_select)

NEWS.md

@@ -4,6 +4,11 @@ Pre-1.0.0 numbering scheme: 0.x will indicate releases, while 0.x.y will indicat
 
 # epiprocess 0.9
 
+## Improvements
+
+- Added `complete.epi_df`, which fills in missing values in an `epi_df` with
+  `NA`s. Uses `tidyr::complete` underneath and preserves `epi_df` metadata.
+
 # epiprocess 0.8
 
 ## Breaking changes

R/epi_df.R

@@ -180,6 +180,8 @@ new_epi_df <- function(x = tibble::tibble(), geo_type, time_type, as_of,
 }
 
 #' @rdname epi_df
+#' @param ... used for specifying column names, as in [`dplyr::rename`]. For
+#'   example, `geo_value = STATEFP, time_value = end_date`.
 #' @export
 as_epi_df <- function(x, ...) {
   UseMethod("as_epi_df")

R/methods-epi_df.R

@@ -8,7 +8,8 @@
 #' use `attr(your_epi_df, "decay_to_tibble") <- FALSE` beforehand.
 #'
 #' @template x
-#' @param ... additional arguments to forward to `NextMethod()`
+#'
+#' @inheritParams tibble::as_tibble
 #'
 #' @importFrom tibble as_tibble
 #' @export
@@ -48,9 +49,9 @@ as_tsibble.epi_df <- function(x, key, ...) {
 #' Print and summary functions for an `epi_df` object.
 #'
 #' @template x
-#' @param ... additional arguments to forward to `NextMethod()`
 #'
 #' @method print epi_df
+#' @param ... additional arguments to forward to `NextMethod()`, or unused
 #' @export
 print.epi_df <- function(x, ...) {
   cat(
@@ -76,7 +77,6 @@ print.epi_df <- function(x, ...) {
 #'   Currently unused.
 #'
 #' @method summary epi_df
-#' @rdname print.epi_df
 #' @importFrom rlang .data
 #' @importFrom stats median
 #' @export
@@ -241,6 +241,77 @@ group_modify.epi_df <- function(.data, .f, ..., .keep = FALSE) {
   dplyr::dplyr_reconstruct(NextMethod(), .data)
 }
 
+#' 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)
+  if ("time_value" %in% names(rlang::call_match(dots_expand = FALSE)[["..."]])) {
+    attr(result, "metadata")$time_type <- guess_time_type(result$time_value)
+  }
+  result
+}
+
 #' @method unnest epi_df
 #' @rdname print.epi_df
 #' @param data an `epi_df`

R/reexports.R

@@ -57,6 +57,19 @@ dplyr::slice
 tidyr::unnest
 
 
+#' @importFrom tidyr complete
+#' @export
+tidyr::complete
+
+# We don't provide a method for full_seq, but complete-ing using
+# full_seq(time_value) is still needed to make some downstream things behave
+# nicely.  So make that more ergonomic/discoverable with a re-export:
+
+#' @importFrom tidyr full_seq
+#' @export
+tidyr::full_seq
+
+
 # ggplot2 -----------------------------------------------------------------
 
 #' @importFrom ggplot2 autoplot