Change "LVCF" back to "LOCF", but with consistent intro text

Always introduce version-wise LOCF as "last observation of each observation
carried forward (LOCF)" or something quite similar.

Clarify time-wise LOCF in one place.

Author: lcbrooks

R/archive.R

@@ -128,7 +128,7 @@ next_after.Date = function(x) x + 1L
 #'   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, the last version of each observation is carried forward (LVCF) to
+#' In general, the last version of each observation is carried forward (LOCF) to
 #'   fill in data between recorded versions, and between the last recorded
 #'   update and the `observed_versions_end`. One consequence is that the `DT`
 #'   doesn't have to contain a full snapshot of every version (although this
@@ -230,8 +230,8 @@ epi_archive =
 #' @param compactify Optional; Boolean or `NULL`: should we remove rows that are
 #'   considered redundant for the purposes of `epi_archive`'s built-in methods
 #'   such as `as_of`? As these methods use the last version of each observation
-#'   carried forward (LVCF) to interpolate between the version data provided,
-#'   rows that don't change these LVCF results can potentially be omitted to
+#'   carried forward (LOCF) to interpolate between the version data provided,
+#'   rows that don't change these LOCF results can potentially be omitted to
 #'   save space while maintaining the same behavior (with the help of the
 #'   `clobberable_versions_start` and `observed_versions_end` fields in some
 #'   edge cases). `TRUE` will remove these rows, `FALSE` will not, and missing
@@ -337,30 +337,30 @@ epi_archive =
             DT = as.data.table(x, key = key_vars)
             if (!identical(key_vars, key(DT))) setkeyv(DT, cols = key_vars)
 
-            # Checks to see if a value in a vector is LVCF
-            is_lvcf <- function(vec) {
+            # Checks to see if a value in a vector is LOCF
+            is_locf <- function(vec) {
               dplyr::if_else(!is.na(vec) & !is.na(dplyr::lag(vec)),
                      vec == dplyr::lag(vec),
                      is.na(vec) & is.na(dplyr::lag(vec)))
             }
 
-            # LVCF is defined by a row where all values except for the version
+            # LOCF is defined by a row where all values except for the version
             # differ from their respective lag values
 
-            # Checks for LVCF's in a data frame
-            rm_lvcf <- function(df) {
-             dplyr::filter(df,if_any(c(everything(),-version),~ !is_lvcf(.))) 
+            # Checks for LOCF's in a data frame
+            rm_locf <- function(df) {
+             dplyr::filter(df,if_any(c(everything(),-version),~ !is_locf(.))) 
             }
 
-            # Keeps LVCF values, such as to be printed
-            keep_lvcf <- function(df) {
-              dplyr::filter(df,if_all(c(everything(),-version),~ is_lvcf(.))) 
+            # Keeps LOCF values, such as to be printed
+            keep_locf <- function(df) {
+              dplyr::filter(df,if_all(c(everything(),-version),~ is_locf(.))) 
             }
 
             # Runs compactify on data frame
             if (is.null(compactify) || compactify == TRUE) {
-              elim = keep_lvcf(DT)
-              DT = rm_lvcf(DT)
+              elim = keep_locf(DT)
+              DT = rm_locf(DT)
             } else {
               # Create empty data frame for nrow(elim) to be 0
               elim = tibble::tibble()
@@ -370,7 +370,7 @@ epi_archive =
             if (is.null(compactify) && nrow(elim) > 0) {
               warning_intro <- break_str(paste(
                 'Found rows that appear redundant based on',
-                'last (version of an) observation carried forward;',
+                'last (version of each) observation carried forward;',
                 'these rows have been removed to "compactify" and save space:'
               ))
 
@@ -494,7 +494,7 @@ epi_archive =
 #' @importFrom data.table key setkeyv := address copy
 #' @importFrom rlang arg_match
           fill_through_version = function(fill_versions_end,
-                                          how=c("na", "lvcf")) {
+                                          how=c("na", "locf")) {
             validate_version_bound(fill_versions_end, self$DT, na_ok=FALSE)
             how <- arg_match(how)
             if (self$observed_versions_end < fill_versions_end) {
@@ -532,8 +532,8 @@ epi_archive =
                   # full result DT:
                   setkeyv(rbind(self$DT, next_version_DT), key(self$DT))[]
                 },
-                "lvcf" = {
-                  # just the old DT; LVCF is built into other methods:
+                "locf" = {
+                  # just the old DT; LOCF is built into other methods:
                   self$DT
                 }
               )
@@ -557,7 +557,7 @@ epi_archive =
 #' @param y as in [`epix_merge`]
 #' @param observed_versions_end_conflict as in [`epix_merge`]
 #' @param compactify as in [`epix_merge`]
-          merge = function(y, observed_versions_end_conflict = c("stop","na","lvcf","truncate"), compactify=TRUE) {
+          merge = function(y, observed_versions_end_conflict = c("stop","na","locf","truncate"), compactify=TRUE) {
             result = epix_merge(self, y,
                                 observed_versions_end_conflict = observed_versions_end_conflict,
                                 compactify = compactify)
@@ -751,8 +751,8 @@ epi_archive =
 #' @param compactify Optional; Boolean or `NULL`: should we remove rows that are
 #'   considered redundant for the purposes of `epi_archive`'s built-in methods
 #'   such as `as_of`? As these methods use the last version of each observation
-#'   carried forward (LVCF) to interpolate between the version data provided,
-#'   rows that don't change these LVCF results can potentially be omitted to
+#'   carried forward (LOCF) to interpolate between the version data provided,
+#'   rows that don't change these LOCF results can potentially be omitted to
 #'   save space. `TRUE` will remove these rows, `FALSE` will not, and missing or
 #'   `NULL` will remove these rows and issue a warning. Generally, this can be
 #'   set to `TRUE`, but if you directly inspect or edit the fields of the

R/methods-epi_archive.R

@@ -41,13 +41,13 @@
 #'            max_version = as.Date("2020-06-12"))
 #'
 #' # When fetching a snapshot as of the latest version with update data in the
-#' # archive, a warning is issued as this update data might not yet be finalized
-#' # (for example, if data versions are labeled with dates, these versions might be
-#' # overwritten throughout the day if the data can be updated multiple times per
-#' # day; when we build an archive based on special update-data queries all made at
-#' # the same time, the latest available update might still be subject to change,
-#' # but previous versions should be finalized). We can muffle such warnings with
-#' # the following pattern:
+#' # archive, a warning is issued by default, as this update data might not yet
+#' # be finalized (for example, if data versions are labeled with dates, these
+#' # versions might be overwritten throughout the corresponding days with
+#' # additional data or "hotfixes" of erroroneous data; when we build an archive
+#' # based on database queries, the latest available update might still be
+#' # subject to change, but previous versions should be finalized). We can
+#' # muffle such warnings with the following pattern:
 #' withCallingHandlers({
 #'   epix_as_of(x = archive_cases_dv_subset,
 #'              max_version = max(archive_cases_dv_subset$DT$version))
@@ -80,17 +80,17 @@ epix_as_of = function(x, max_version, min_time_value = -Inf) {
 #'   version through which to fill in missing version history; this will be the
 #'   result's `$observed_versions_end` unless it already had a later
 #'   `$observed_versions_end`.
-#' @param how Optional; `"na"` or `"lvcf"`: `"na"` will fill in any missing
+#' @param how Optional; `"na"` or `"locf"`: `"na"` will fill in any missing
 #'   required version history with `NA`s, by inserting (if necessary) an update
 #'   immediately after the current `$observed_versions_end` that revises all
 #'   existing measurements to be `NA` (this is only supported for `version`
-#'   classes with a `next_after` implementation); `"lvcf"` will fill in missing
+#'   classes with a `next_after` implementation); `"locf"` will fill in missing
 #'   version history with the last version of each observation carried forward
-#'   (LVCF), by leaving the update `$DT` alone (other `epi_archive` methods are
-#'   based on LVCF).  Default is `"na"`.
+#'   (LOCF), by leaving the update `$DT` alone (other `epi_archive` methods are
+#'   based on LOCF).  Default is `"na"`.
 #' @return An `epi_archive`
 epix_fill_through_version = function(x, fill_versions_end,
-                                     how=c("na", "lvcf")) {
+                                     how=c("na", "locf")) {
   if (!inherits(x, "epi_archive")) Abort("`x` must be of class `epi_archive`.")
   # Enclosing parentheses drop the invisibility flag. See description above of
   # potential mutation and aliasing behavior.
@@ -115,17 +115,17 @@ 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 observed_versions_end_conflict Optional; `"stop"`, `"na"`, `"lvcf"`,
+#' @param observed_versions_end_conflict Optional; `"stop"`, `"na"`, `"locf"`,
 #'   or `"truncate"`; in the case that `x$observed_versions_end` doesn't match
 #'   `y$observed_versions_end`, what do we do?: `"stop"`: emit an error; "na":
 #'   use `max(x$observed_versions_end, y$observed_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`;
-#'   `"lvcf"`: use `max(x$observed_versions_end, y$observed_versions_end)`, and
-#'   last-version-carried-forward extrapolation to invent update data for the
-#'   less up-to-date input archive; or `"truncate"`: use
-#'   `min(x$observed_versions_end, y$observed_versions_end)` and discard any
-#'   rows containing update rows for later versions.
+#'   `"locf"`: use `max(x$observed_versions_end, y$observed_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$observed_versions_end, y$observed_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.
 #'   Default here is `TRUE`.
@@ -151,7 +151,7 @@ epix_fill_through_version = function(x, fill_versions_end,
 #' @importFrom data.table key set
 #' @export
 epix_merge = function(x, y,
-                      observed_versions_end_conflict = c("stop","na","lvcf","truncate"),
+                      observed_versions_end_conflict = c("stop","na","locf","truncate"),
                       compactify = TRUE) {
   if (!inherits(x, "epi_archive")) {
     Abort("`x` must be of class `epi_archive`.")
@@ -205,7 +205,7 @@ epix_merge = function(x, y,
       x_DT = x$DT
       y_DT = y$DT
     }
-  } else if (observed_versions_end_conflict %in% c("na", "lvcf")) {
+  } else if (observed_versions_end_conflict %in% c("na", "locf")) {
     new_observed_versions_end = max(x$observed_versions_end, y$observed_versions_end)
     x_DT = epix_fill_through_version(x, new_observed_versions_end, observed_versions_end_conflict)$DT
     y_DT = epix_fill_through_version(y, new_observed_versions_end, observed_versions_end_conflict)$DT

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,
-                                     observed_versions_end_conflict="lvcf",
+                                     observed_versions_end_conflict="locf",
                                      compactify=FALSE)
 
 # If we directly store an epi_archive R6 object as data, it will store its class