Move issue from column to metadata

- As per the discussion on #8, from now on, an `epi_signal` object
  represents a single snapshot of a data set
- Modify `as.epi_signal()` to reflect this change
- Update documentation and vignettes accordingly

Author: ryantibs

R/change.R

@@ -1,8 +1,7 @@
 #' Compute percentage change of values in `epi_signal` data frame
 #' 
 #' Computes the percentage change of the values in a `epi_signal` data frame,
-#' per geographic location. (When multiple issue dates are present, only the
-#' latest issue is considered.)  See the [percentage change
+#' per geographic location. See the [percentage change
 #' vignette](https://cmu-delphi.github.io/epitools/articles/pct-change.html) for 
 #' examples.   
 #'

R/cor.R

@@ -1,9 +1,7 @@
 #' Compute correlations between two `epi_signal` data frames
 #'
 #' Computes correlations between two `epi_signal` data frames, allowing for
-#' slicing by geo location, or by time. (When multiple issue dates are present,
-#' only the latest issue from each data frame is used for correlations.) See the
-#' [correlations
+#' slicing by geo location, or by time. See the [correlations
 #' vignette](https://cmu-delphi.github.io/epitools/articles/correlations.html)
 #' for examples.
 #'
@@ -41,10 +39,6 @@ sliced_cor = function(x, y, dt_x = 0, dt_y = 0,
     abort("`y` be of class `epi_signal`.")
   }
 
-  # Get the latest issue per value
-  x = latest_issue(x)
-  y = latest_issue(y)
-
   # Which way to slice? Which method?
   by = match.arg(by)
   method = match.arg(method)

R/deriv.R

@@ -1,8 +1,7 @@
 #' Estimate derivatives of values in an `epi_signal` data frame
 #' 
 #' Estimates derivatives of the values in an `epi_signal` data frame, using a
-#' local (in time) linear regression or a smoothing spline. (When multiple issue
-#' dates are present, only the latest issue is considered.) See the [estimating
+#' local (in time) linear regression or a smoothing spline. See the [estimating 
 #' derivatives
 #' vignette](https://cmu-delphi.github.io/epitools/articles/derivatives.html) 
 #' for examples.  

R/epi_signal.R

@@ -6,16 +6,18 @@
 #'
 #' @details An `epi_signal` object is simply a tibble, with (at least) the
 #'   following columns (with data types written in tibble notation):    
-#' * `value` <dbl>: the value of the signal
+#' * `value` <dbl> or <list>: the value of the signal
 #' * `geo_value` <int> or <str>: the associated geographic value  
 #' * `time_value` <date>: the associated time value 
-#' * `issue` <date>: the time value at which the given signal value was issued 
 #'
 #' An `epi_signal` object also has a tibble `metadata` stored in its attributes,  
 #' with (at least) the following columns:
 #' * `name` <str>: the name of the signal
 #' * `geo_type` <str>: the geographic resolution
 #' * `time_type` <str>: the temporal resolution
+#' * `issue` <date>: the time value at which the given data set was issued (this
+#'   represents the maximum of issue dates of individual signal values in the
+#'   data set) 
 #' * `signal_type` <str>: the type of the signal value (optional)
 #' * `signal_unit` <str>: the units associated with the signal value (optional) 
 #'
@@ -51,13 +53,12 @@
 #' @param geo_type The geographic resolution. If missing, then it will be
 #'   guessed from the geo values present.  
 #' @param time_type The temporal resolution. If missing, then it will be guessed
-#'   from the time values present. 
+#'   from the time values present.
+#' @param issue Issue date to use for this data. If missing, then today's date
+#'   will be used. 
 #' @param signal_type The type of the signal value. 
 #' @param signal_unit The units of the signal value. 
-#' @param issue Issue date to use for this data, if not present in `x`. If no
-#'   issue date is present in `x` and `issue` is missing, then today's date will
-#'   be used. 
-#' @param metadata List or tibble of additional metadata to attach to the
+#' @param metadata List or tibble of *additional* metadata to attach to the
 #'   `epi_signal` object. All objects will have `geo_type`, `time_type`,
 #'   `signal_type` (optional), and `signal_unit` (optional) entries included in
 #'   their metadata, derived from the above arguments; any entries in the passed
@@ -78,13 +79,13 @@ as.epi_signal.epi_signal = function(x, ...) {
 
 #' @method as.epi_signal tibble
 #' @describeIn as.epi_signal The input tibble `x` must contain the columns
-#'   `value`, `geo_value`, and `time_value`. If an `issue` column is present in
-#'   `x`, it will be used as the issue date for each observation; if not, the
-#'   `issue` argument will be used. Other columns will be preserved as-is.
+#'   `value`, `geo_value`, and `time_value`. All other columns will be preserved
+#'   as-is. 
 #' @importFrom rlang .data abort
 #' @export
-as.epi_signal.tibble = function(x, name, geo_type, time_type, signal_type,
-                                signal_unit, issue, metadata = list(), ...) { 
+as.epi_signal.tibble = function(x, name, geo_type, time_type, issue,
+                                signal_type, signal_unit, metadata = list(),
+                                ...) {  
   if (!("value" %in% names(x))) {
     abort(paste(
       "`x` must contain a `value` column",
@@ -111,7 +112,11 @@ as.epi_signal.tibble = function(x, name, geo_type, time_type, signal_type,
       "`name` must be specified.",
       class = "epi_coerce_name")
   }
-  
+
+  # If issue is missing, thne use today's date
+  if (missing(issue)) issue = Sys.Date()
+
+  # If geo type is missing ,then try to guess it
   if (missing(geo_type)) {
     if (is.character(x$geo_value)) {
       # Convert geo values to lowercase
@@ -143,6 +148,7 @@ as.epi_signal.tibble = function(x, name, geo_type, time_type, signal_type,
     else geo_type = "unknown" # TODO should we use NA? Or some other flag?
   }
 
+  # If time type is missing, then try to guess it
   if (missing(time_type)) {
     # Convert time values to Date format
     x$time_value = as.Date(x$time_value)
@@ -156,6 +162,7 @@ as.epi_signal.tibble = function(x, name, geo_type, time_type, signal_type,
 
   # Define metadata fields
   metadata$name = name
+  metadata$issue = issue
   metadata$geo_type = geo_type
   metadata$time_type = time_type
   if (!missing(signal_type)) metadata$signal_type = signal_type
@@ -167,34 +174,19 @@ as.epi_signal.tibble = function(x, name, geo_type, time_type, signal_type,
   class(x) = c("epi_signal", class(x))
   attributes(x)$metadata = metadata
 
-  # Reorder columns: value, geo_value, time_value,
+  # Reorder columns: value, geo_value, time_value
   x = dplyr::relocate(x,
                       .data$value,
                       .data$geo_value,
                       .data$time_value)
 
-  # If no rows, then quit
-  if (nrow(x) == 0) return(x)
-
-  # Add issue column if we need to
-  if (!("issue" %in% names(x))) {
-    if (missing(issue)) x$issue = Sys.Date()
-    else x$issue = issue
-  }
-
-  # Reorder columns: issue after time_value
-  x = dplyr::relocate(x, 
-                      .data$issue,
-                      .after = .data$time_value)
-
   return(x)
 }
 
 #' @method as.epi_signal data.frame
 #' @describeIn as.epi_signal The input data frame `x` must contain the columns
-#'   `value`, `geo_value`, and `time_value`. If an `issue` column is present in
-#'   `x`, it will be used as the issue date for each observation; if not, the
-#'   `issue` argument will be used. Other columns will be preserved as-is.
+#'   `value`, `geo_value`, and `time_value`. All other columns will be preserved 
+#'   as-is. 
 #' @export
 as.epi_signal.data.frame = as.epi_signal.tibble
 

R/slide.R

@@ -2,8 +2,7 @@
 #' location    
 #'
 #' Slides a given function over the values in an `epi_signal` data frame,
-#' grouped by geo location. (When multiple issue dates are present, only the
-#' latest issue is considered.) See the [slide
+#' grouped by geo location. See the [slide
 #' vignette](https://cmu-delphi.github.io/epitools/articles/slide.html)   
 #' for examples.    
 #'
@@ -41,9 +40,6 @@ slide_by_geo = function(x, slide_fun, n = 14, col_name = "slide_value",
     abort("`x` be of class `epi_signal`.")
   }
 
-  # Get the latest issue per value
-  x = latest_issue(x) 
-
   # Which slide_index function?
   col_type = match.arg(col_type)
   slide_index_zzz = switch(col_type,

R/utils.R

@@ -38,22 +38,24 @@ quiet = function(x) {
 
 ##########
 
-#' Fetch the latest or earliest issue for each observation
+# TODO: fix. this function is no longer in sync with the epi_signal format.
+# Currently not being exported
+
+#' Fetch the latest or for each observation
 #'
 #' The data returned from `covidcast_signal()` or `covidcast_signals()` can, if
 #' called with the `issues` argument, contain multiple issues for a single
 #' observation in a single location. These functions filter the data frame to
-#' contain only the earliest issue or only the latest issue.
+#' contain only the latest issue.
 #'
 #' @param df A `covidcast_signal` or `covidcast_signal_long` data frame, such as
 #'   returned from `covidcast_signal()` or the "long" format of
 #'   `aggregate_signals()`.
-#' @return A data frame in the same form, but with only the earliest or latest
-#'   issue of every observation. Note that these functions sort the data frame
-#'   as part of their filtering, so the output data frame rows may be in a
-#'   different order.
+#' @return A data frame in the same form, but with only the latest issue of
+#'   every observation. Note that these functions sort the data frame as part of
+#'   their filtering, so the output data frame rows may be in a different
+#'   order. 
 #' 
-#' @export
 latest_issue = function(x) {
   if (!inherits(x, "epi_signal")) {
     abort("`x` of class `epi_signal`.")