Rename versions_end_conflict -> sync, "stop" -> "forbid"

Author: lcbrooks

R/archive.R

@@ -555,11 +555,11 @@ epi_archive =
 #'   of the non-R6-method version, which does not mutate either archive, and
 #'   does not alias either archive's `DT`.
 #' @param y as in [`epix_merge`]
-#' @param versions_end_conflict as in [`epix_merge`]
+#' @param sync as in [`epix_merge`]
 #' @param compactify as in [`epix_merge`]
-          merge = function(y, versions_end_conflict = c("stop","na","locf","truncate"), compactify=TRUE) {
+          merge = function(y, sync = c("forbid","na","locf","truncate"), compactify = TRUE) {
             result = epix_merge(self, y,
-                                versions_end_conflict = versions_end_conflict,
+                                sync = sync,
                                 compactify = compactify)
 
             if (length(epi_archive$private_fields) != 0L) {

R/methods-epi_archive.R

@@ -105,7 +105,7 @@ epix_fill_through_version = function(x, fill_versions_end,
 #' `y` individually, then performing a full join of the `DT`s on the non-version
 #' key columns (potentially consolidating multiple warnings about clobberable
 #' versions). If the `versions_end` values differ, the
-#' `versions_end_conflict` parameter controls what is done.
+#' `sync` parameter controls what is done.
 #'
 #' This function, [`epix_merge`], does not mutate its inputs and will not alias
 #' either archive's `DT`, but may alias other fields; `x$merge` will overwrite
@@ -115,16 +115,20 @@ epix_fill_through_version = function(x, fill_versions_end,
 #' old `DT` in another object).
 #'
 #' @param x,y Two `epi_archive` objects to join together.
-#' @param versions_end_conflict Optional; `"stop"`, `"na"`, `"locf"`,
-#'   or `"truncate"`; in the case that `x$versions_end` doesn't match
-#'   `y$versions_end`, what do we do?: `"stop"`: emit an error; "na":
-#'   use `max(x$versions_end, y$versions_end)`, but in the
-#'   less up-to-date input archive, imagine there was an update immediately
-#'   after its last observed version which revised all observations to be `NA`;
-#'   `"locf"`: use `max(x$versions_end, y$versions_end)`,
-#'   allowing the last version of each observation to be carried forward to
-#'   extrapolate unavailable versions for the less up-to-date input archive; or
-#'   `"truncate"`: use `min(x$versions_end, y$versions_end)`
+#' @param sync Optional; `"forbid"`, `"na"`, `"locf"`, or `"truncate"`; in the
+#'   case that `x$versions_end` doesn't match `y$versions_end`, what do we do?:
+#'   `"forbid"`: emit an error; "na": use `max(x$versions_end, y$versions_end)`
+#'   as the result's `versions_end`, but ensure that, if we request a snapshot
+#'   as of a version after `min(x$versions_end, y$versions_end)`, the
+#'   observation columns from the less up-to-date archive will be all NAs (i.e.,
+#'   imagine there was an update immediately after its `versions_end` which
+#'   revised all observations to be `NA`); `"locf"`: use `max(x$versions_end,
+#'   y$versions_end)` as the result's `versions_end`, allowing the last version
+#'   of each observation to be carried forward to extrapolate unavailable
+#'   versions for the less up-to-date input archive (i.e., imagining that in the
+#'   less up-to-date archive's data set remained unchanged between its actual
+#'   `versions_end` and the other archive's `versions_end`); or `"truncate"`:
+#'   use `min(x$versions_end, y$versions_end)` as the result's `versions_end`,
 #'   and discard any rows containing update rows for later versions.
 #' @param compactify Optional; `TRUE`, `FALSE`, or `NULL`; should the result be
 #'   compactified? See [`as_epi_archive`] for an explanation of what this means.
@@ -151,7 +155,7 @@ epix_fill_through_version = function(x, fill_versions_end,
 #' @importFrom data.table key set
 #' @export
 epix_merge = function(x, y,
-                      versions_end_conflict = c("stop","na","locf","truncate"),
+                      sync = c("forbid","na","locf","truncate"),
                       compactify = TRUE) {
   if (!inherits(x, "epi_archive")) {
     Abort("`x` must be of class `epi_archive`.")
@@ -161,7 +165,7 @@ epix_merge = function(x, y,
     Abort("`y` must be of class `epi_archive`.")
   }
 
-  versions_end_conflict <- rlang::arg_match(versions_end_conflict)
+  sync <- rlang::arg_match(sync)
 
   if (!identical(x$geo_type, y$geo_type)) {
     Abort("`x` and `y` must have the same `$geo_type`")
@@ -192,24 +196,24 @@ epix_merge = function(x, y,
   # preprocessing using non-mutating (but potentially aliasing) functions. This
   # approach potentially uses more memory, but won't leave behind a
   # partially-mutated `x` on failure.
-  if (versions_end_conflict == "stop") {
+  if (sync == "forbid") {
     if (!identical(x$versions_end, y$versions_end)) {
       Abort(paste(
         "`x` and `y` were not equally up to date version-wise:",
         "`x$versions_end` was not identical to `y$versions_end`;",
         "either ensure that `x` and `y` are equally up to date before merging,",
-        "or specify how to deal with this using `versions_end_conflict`"
-      ), class="epiprocess__epix_merge_unresolved_versions_end_conflict")
+        "or specify how to deal with this using `sync`"
+      ), class="epiprocess__epix_merge_unresolved_sync")
     } else {
       new_versions_end = x$versions_end
       x_DT = x$DT
       y_DT = y$DT
     }
-  } else if (versions_end_conflict %in% c("na", "locf")) {
+  } else if (sync %in% c("na", "locf")) {
     new_versions_end = max(x$versions_end, y$versions_end)
-    x_DT = epix_fill_through_version(x, new_versions_end, versions_end_conflict)$DT
-    y_DT = epix_fill_through_version(y, new_versions_end, versions_end_conflict)$DT
-  } else if (versions_end_conflict == "truncate") {
+    x_DT = epix_fill_through_version(x, new_versions_end, sync)$DT
+    y_DT = epix_fill_through_version(y, new_versions_end, sync)$DT
+  } else if (sync == "truncate") {
     new_versions_end = min(x$versions_end, y$versions_end)
     x_DT = x$DT[x[["DT"]][["version"]] <= new_versions_end, with=FALSE]
     y_DT = y$DT[y[["DT"]][["version"]] <= new_versions_end, with=FALSE]

data-raw/archive_cases_dv_subset.R

@@ -32,7 +32,7 @@ case_rate_subset <- covidcast(
   as_epi_archive(compactify=FALSE)
 
 archive_cases_dv_subset = epix_merge(dv_subset, case_rate_subset,
-                                     versions_end_conflict="locf",
+                                     sync="locf",
                                      compactify=FALSE)
 
 # If we directly store an epi_archive R6 object as data, it will store its class

man/epi_archive.Rd

@@ -1,5 +1,5 @@
 
-test_that("epix_merge requires stops on invalid `y`",{
+test_that("epix_merge requires forbids on invalid `y`",{
   ea = archive_cases_dv_subset$clone()
   expect_error(epix_merge(ea, data.frame(x=1)))
 })
@@ -62,7 +62,7 @@ test_that("epix_merge merges and carries forward updates properly", {
   expect_identical(xy, xy_expected)
 })
 
-test_that('epix_merge stops and warns on metadata and naming issues', {
+test_that('epix_merge forbids and warns on metadata and naming issues', {
   expect_error(
     epix_merge(
       as_epi_archive(tibble::tibble(geo_value="tx", time_value=1L, version=1L, x_value=1L)),
@@ -123,16 +123,16 @@ local({
 local({
   x = as_epi_archive(tibble::tibble(geo_value=1L, time_value=1L, version=1L, x_value=10L))
   y = as_epi_archive(tibble::tibble(geo_value=1L, time_value=1L, version=5L, y_value=20L))
-  print(epix_merge(x,y, versions_end_conflict = "na"))
-  test_that('epix_merge stops on versions_end_conflict default or "stop"', {
+  print(epix_merge(x,y, sync = "na"))
+  test_that('epix_merge forbids on sync default or "forbid"', {
     expect_error(epix_merge(x,y),
-                 class="epiprocess__epix_merge_unresolved_versions_end_conflict")
-    expect_error(epix_merge(x,y, versions_end_conflict = "stop"),
-                 class="epiprocess__epix_merge_unresolved_versions_end_conflict")
+                 class="epiprocess__epix_merge_unresolved_sync")
+    expect_error(epix_merge(x,y, sync = "forbid"),
+                 class="epiprocess__epix_merge_unresolved_sync")
   })
-  test_that('epix_merge versions_end_conflict="na" works', {
+  test_that('epix_merge sync="na" works', {
     expect_equal(
-      epix_merge(x,y, versions_end_conflict = "na"),
+      epix_merge(x,y, sync = "na"),
       as_epi_archive(tibble::tribble(
         ~geo_value, ~time_value, ~version, ~x_value, ~y_value,
         1L, 1L, 1L, 10L, NA_integer_,         # x updated, y not observed yet
@@ -141,9 +141,9 @@ local({
         ), clobberable_versions_start=1L)
     )
   })
-  test_that('epix_merge versions_end_conflict="locf" works', {
+  test_that('epix_merge sync="locf" works', {
     expect_equal(
-      epix_merge(x,y, versions_end_conflict = "locf"),
+      epix_merge(x,y, sync = "locf"),
       as_epi_archive(tibble::tribble(
         ~geo_value, ~time_value, ~version, ~x_value, ~y_value,
         1L, 1L, 1L, 10L, NA_integer_,  # x updated, y not observed yet
@@ -157,36 +157,36 @@ local({
     ~geo_value, ~time_value, ~version, ~x_value, ~y_value,
     1L, 1L, 1L, 10L, 20L,         # x updated, y not observed yet
     ))
-  test_that('epix_merge versions_end_conflict="stop" on no-conflict works', {
+  test_that('epix_merge sync="forbid" on no-conflict works', {
     expect_equal(
-      epix_merge(x_no_conflict, y_no_conflict, versions_end_conflict = "stop"),
+      epix_merge(x_no_conflict, y_no_conflict, sync = "forbid"),
       xy_no_conflict_expected
     )
   })
-  test_that('epix_merge versions_end_conflict="na" on no-conflict works', {
+  test_that('epix_merge sync="na" on no-conflict works', {
     # This test is the main reason for these no-conflict tests. We want to make
     # sure that we don't add an unnecessary NA-ing-out version beyond a common
     # versions_end.
     expect_equal(
-      epix_merge(x_no_conflict, y_no_conflict, versions_end_conflict = "na"),
+      epix_merge(x_no_conflict, y_no_conflict, sync = "na"),
       xy_no_conflict_expected
     )
   })
-  test_that('epix_merge versions_end_conflict="locf" on no-conflict works', {
+  test_that('epix_merge sync="locf" on no-conflict works', {
     expect_equal(
-      epix_merge(x_no_conflict, y_no_conflict, versions_end_conflict = "locf"),
+      epix_merge(x_no_conflict, y_no_conflict, sync = "locf"),
       xy_no_conflict_expected
     )
   })
 })
 
 
-test_that('epix_merge versions_end_conflict="na" balks if do not know next_after', {
+test_that('epix_merge sync="na" balks if do not know next_after', {
   expect_error(
     epix_merge(
       as_epi_archive(tibble::tibble(geo_value=1L, time_value=1L, version=as.POSIXct(as.Date("2020-01-01")), x_value=10L)),
       as_epi_archive(tibble::tibble(geo_value=1L, time_value=1L, version=as.POSIXct(as.Date("2020-01-02")), y_value=20L)),
-      versions_end_conflict = "na"
+      sync = "na"
     ),
     regexp = "no applicable method.*next_after"
   )

man/epix_merge.Rd

@@ -244,9 +244,10 @@ When merging archives, unless the archives have identical data release patterns,
   been released)
 - to represent the "value" of an observation that has no recorded versions at
   all (in the same sort of situation)
-- if requested via `versions_end_conflict="na"`, to represent potential
-  update data that we do not yet have access to (e.g., due to one of the
-  archives being out of sync).
+- if requested via `sync="na"`, to represent potential update data that we do
+  not yet have access to (e.g., due to encountering issues while attempting to
+  download the currently available version data for one of the archives, but not
+  the other).
 
 ```{r, message = FALSE, warning = FALSE,eval=FALSE}
 y <- covidcast(