Merge pull request #183 from cmu-delphi/ml-182-epi_df-additional-metadata

[Issue 182] Update `epi_df` examples, check `additional_metadata` type at construction

Author: brookslogan

R/epi_df.R

@@ -105,8 +105,9 @@ NULL
 #'   then the current day-time will be used.
 #' @param additional_metadata List of additional metadata to attach to the
 #'   `epi_df` object. The metadata will have `geo_type`, `time_type`, and
-#'   `as_of` fields; named entries from the passed list or will be included as
-#'   well.
+#'   `as_of` fields; named entries from the passed list will be included as
+#'   well. If your tibble has additional keys, be sure to specify them as a
+#'   character vector in the `other_keys` component of `additional_metadata`. 
 #' @param ... Additional arguments passed to methods.
 #' @return An `epi_df` object.
 #' 
@@ -117,7 +118,11 @@ new_epi_df = function(x = tibble::tibble(), geo_type, time_type, as_of,
   if (!is.data.frame(x)) {
     Abort("`x` must be a data frame.")
   }
-  
+    
+  if (!is.list(additional_metadata)) {
+    Abort("`additional_metadata` must be a list type.")
+  }
+
   # If geo type is missing, then try to guess it
   if (missing(geo_type)) {
     geo_type = guess_geo_type(x$geo_value)
@@ -184,8 +189,9 @@ new_epi_df = function(x = tibble::tibble(), geo_type, time_type, as_of,
 #'   then the current day-time will be used.
 #' @param additional_metadata List of additional metadata to attach to the
 #'   `epi_df` object. The metadata will have `geo_type`, `time_type`, and
-#'   `as_of` fields; named entries from the passed list or will be included as
-#'   well.
+#'   `as_of` fields; named entries from the passed list will be included as
+#'   well. If your tibble has additional keys, be sure to specify them as a
+#'   character vector in the `other_keys` component of `additional_metadata`.
 #' @param ... Additional arguments passed to methods.
 #' @return An `epi_df` object.
 #'
@@ -230,7 +236,7 @@ new_epi_df = function(x = tibble::tibble(), geo_type, time_type, as_of,
 #' 
 #' ex2 <- ex2_input %>% dplyr::rename(geo_value = state, time_value = reported_date) %>%
 #'   as_epi_df(geo_type = "state", as_of = "2020-06-03", 
-#'             additional_metadata = c(other_keys = "pol"))
+#'             additional_metadata = list(other_keys = "pol")) 
 #' 
 #' attr(ex2,"metadata")
 #' 
@@ -244,8 +250,13 @@ new_epi_df = function(x = tibble::tibble(), geo_type, time_type, as_of,
 #' 
 #' ex3 <- ex3_input %>% 
 #'   tsibble::as_tsibble() %>% # needed to add the additional metadata
-#'   dplyr::mutate(state = rep("MA",6)) %>%
-#'   as_epi_df(additional_metadata = c(other_keys = "state"))
+#'   # add 2 extra keys
+#'   dplyr::mutate(
+#'     state = rep("MA",6),
+#'     pol = rep(c("blue", "swing", "swing"), each = 2)) %>% 
+#'   # the 2 extra keys we added have to be specified in the other_keys 
+#'   # component of additional_metadata.
+#'   as_epi_df(additional_metadata = list(other_keys = c("state", "pol")))
 #' 
 #' attr(ex3,"metadata")
 as_epi_df = function(x, ...) {

man/as_epi_df.Rd

@@ -24,3 +24,18 @@ test_that("new_epi_df works as intended", {
   expect_identical(attributes(epi_tib)$metadata$time_type, "day")
   expect_true(lubridate::is.POSIXt(attributes(epi_tib)$metadata$as_of))
 })
+
+test_that("as_epi_df errors when additional_metadata is not a list", {
+  # This is the 3rd example from as_epi_df
+  ex_input <- jhu_csse_county_level_subset %>%
+    dplyr::filter(time_value > "2021-12-01", state_name == "Massachusetts") %>%
+    dplyr::slice_tail(n = 6) %>%
+    tsibble::as_tsibble() %>%
+    dplyr::mutate(
+      state = rep("MA",6),
+      pol = rep(c("blue", "swing", "swing"), each = 2))
+  
+  expect_error(
+    as_epi_df(ex_input, additional_metadata = c(other_keys = "state", "pol")), 
+    "`additional_metadata` must be a list type.")
+})

man/new_epi_df.Rd

@@ -8,7 +8,7 @@ toy_epi_df <- tibble::tibble(
   ), times = 2),
   geo_value = rep(c("ca", "hi"), each = 5),
   indicator_var = as.factor(rep(1:2, times = 5)), 
-) %>% as_epi_df(additional_metadata = c(other_keys = "indicator_var"))
+) %>% as_epi_df(additional_metadata = list(other_keys = "indicator_var"))
 
 att_toy = attr(toy_epi_df, "metadata")
 

tests/testthat/test-epi_df.R

@@ -180,7 +180,7 @@ head(ex2)
 
 ex2 <- ex2 %>% rename(geo_value = state, time_value = reported_date) %>%
   as_epi_df(geo_type = "state", as_of = "2020-06-03", 
-            additional_metadata = c(other_keys = "pol"))
+            additional_metadata = list(other_keys = "pol"))
 
 attr(ex2,"metadata")
 ```
@@ -200,17 +200,21 @@ ex3 <- jhu_csse_county_level_subset %>%
 attr(ex3,"metadata") # geo_type is county currently
 ```
 
-Now we add state (MA) as a new column and a key to the metadata. Reminder that lower case state name abbreviations are what we would expect if this were a `geo_value` column.
-```{r}
+Now we add `state` (MA) and `pol` as new columns to the data and as new keys to the metadata. Reminder that lower case state name abbreviations are what we would expect if this were a `geo_value` column. 
 
+```{r}
 ex3 <- ex3 %>% 
   as_tibble() %>% # needed to add the additional metadata
-  mutate(state = rep(tolower("MA"),6)) %>%
-  as_epi_df(additional_metadata = c(other_keys = "state"))
+  mutate(
+    state = rep(tolower("MA"),6),
+    pol = rep(c("blue", "swing", "swing"), each = 2)) %>%
+  as_epi_df(additional_metadata = list(other_keys = c("state", "pol")))
 
 attr(ex3,"metadata")
 ```
 
+Note that the two additional keys we added, `state` and `pol`, are specified as a character vector in the `other_keys` component of the `additional_metadata` list. They must be specified in this manner so that downstream actions on the `epi_df`, like model fitting and prediction, can recognize and use these keys.
+
 Currently `other_keys` metadata in `epi_df` doesn't impact `epi_slide()`, contrary to `other_keys` in `as_epi_archive` which affects how the update data is interpreted.
 
 ## Working with `epi_df` objects downstream