Merge branch 'cmu-delphi/main' into km/growth_rate

Author: kenmawer

.github/CODEOWNERS

@@ -1 +1 @@
-@dajmcdon @brookslogan
+* @dajmcdon @brookslogan

DESCRIPTION

@@ -6,15 +6,19 @@ Authors@R: c(
     person("Jacob", "Bien", role = "ctb"),
     person("Logan", "Brooks", role = "aut"),
     person("Rafael", "Catoia", role = "ctb"),
-    person("Daniel", "McDonald", role = "ctb"),
+    person("Daniel", "McDonald", role = "aut"),
+    person("Rachel", "Lobay", role = "ctb"),
+    person("Ken", "Mawer", role = "ctb"),
+    person("Chloe", "You", role = "ctb"),
     person("Quang", "Nguyen", role = "ctb"),
     person("Evan", "Ray", role = "aut"),
     person("Dmitry", "Shemetov", role = "ctb"),
     person("Ryan", "Tibshirani", , "[email protected]", role = c("aut", "cre"))
   )
-Description: This package introduces a common data structure for
-    epidemiological data sets measured over space and time, and offers
-    associated utilities to perform basic signal processing tasks.
+Description: This package introduces a common data structure for epidemiological
+    data reported by location and time, provides another data structure to
+    work with revisions to these data sets over time, and offers associated
+    utilities to perform basic signal processing tasks.
 License: MIT + file LICENSE
 Imports: 
     data.table,

NAMESPACE

@@ -40,6 +40,7 @@ export(growth_rate)
 export(is_epi_archive)
 export(is_epi_df)
 export(mutate)
+export(new_epi_df)
 export(relocate)
 export(rename)
 export(slice)

R/data.R

@@ -1,37 +1,53 @@
-#' Subset of JHU daily cases and deaths from California, Florida, Texas, New York, Georgia, and Pennsylvania
+#' Subset of JHU daily state cases and deaths 
 #'
-#' This data source of confirmed COVID-19 cases and deaths 
-#' is based on reports made available by the Center for 
-#' Systems Science and Engineering at Johns Hopkins University. 
-#' This example data ranges from Mar 1, 2020 to Dec 31, 2021, and is limited to California, Florida, Texas, New York, Georgia, and Pennsylvania.
+#' This data source of confirmed COVID-19 cases and deaths
+#' is based on reports made available by the Center for
+#' Systems Science and Engineering at Johns Hopkins University.
+#' This example data ranges from Mar 1, 2020 to Dec 31, 2021, and is limited to 
+#' California, Florida, Texas, New York, Georgia, and Pennsylvania.
 #'
 #' @format A tibble with 4026 rows and 6 variables:
 #' \describe{
-#'   \item{geo_value}{the geographic value associated with each row of measurements.}
+#'   \item{geo_value}{the geographic value associated with each row 
+#'       of measurements.}
 #'   \item{time_value}{the time value associated with each row of measurements.}
-#'   \item{case_rate_7d_av}{7-day average signal of number of new confirmed COVID-19 cases per 100,000 population, daily}
-#'   \item{death_rate_7d_av}{7-day average signal of number of new confirmed deaths due to COVID-19 per 100,000 population, daily}
+#'   \item{case_rate_7d_av}{7-day average signal of number of new 
+#'       confirmed COVID-19 cases per 100,000 population, daily}
+#'   \item{death_rate_7d_av}{7-day average signal of number of new confirmed 
+#'       deaths due to COVID-19 per 100,000 population, daily}
 #'   \item{cases}{Number of new confirmed COVID-19 cases, daily}
-#'   \item{cases_7d_av}{7-day average signal of number of new confirmed COVID-19 cases, daily}
+#'   \item{cases_7d_av}{7-day average signal of number of new confirmed 
+#'       COVID-19 cases, daily}
 #' }
-#' @source This object contains a modified part of the \href{https://github.com/CSSEGISandData/COVID-19}{COVID-19 Data Repository by the Center for Systems Science and Engineering (CSSE) at Johns Hopkins University} as \href{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html}{republished in the COVIDcast Epidata API}. This data set is licensed under the terms of the
-#' \href{https://creativecommons.org/licenses/by/4.0/}{Creative Commons Attribution 4.0 International license}
-#' by the Johns Hopkins University on behalf of its Center for Systems Science in Engineering.
-#' Copyright Johns Hopkins University 2020.
-#' 
+#' @source This object contains a modified part of the 
+#'   \href{https://github.com/CSSEGISandData/COVID-19}{COVID-19 Data Repository by the Center for Systems Science and Engineering (CSSE) at Johns Hopkins University}
+#'   as \href{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html}{republished in the COVIDcast Epidata API}. 
+#'   This data set is licensed under the terms of the
+#'   \href{https://creativecommons.org/licenses/by/4.0/}{Creative Commons Attribution 4.0 International license}
+#'   by the Johns Hopkins University on behalf of its Center for Systems Science
+#'   in Engineering. Copyright Johns Hopkins University 2020.
+#'
 #' Modifications:
-#' * \href{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html}{From the COVIDcast Epidata API}: These signals are taken directly from the JHU CSSE \href{https://github.com/CSSEGISandData/COVID-19}{COVID-19 GitHub repository} without changes. The 7-day average signals are computed by Delphi by calculating moving averages of the preceding 7 days, so the signal for June 7 is the average of the underlying data for June 1 through 7, inclusive.
-#' * Furthermore, the data has been limited to a very small number of rows, the signal names slightly altered, and formatted into a tibble.
+#' * \href{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html}{From the COVIDcast Epidata API}: 
+#'   These signals are taken directly from the JHU CSSE 
+#'   \href{https://github.com/CSSEGISandData/COVID-19}{COVID-19 GitHub repository} 
+#'   without changes. The 7-day average signals are computed by Delphi by 
+#'   calculating moving averages of the preceding 7 days, so the signal for 
+#'   June 7 is the average of the underlying data for June 1 through 7, 
+#'   inclusive.
+#' * Furthermore, the data has been limited to a very small number of rows, 
+#'   the signal names slightly altered, and formatted into a tibble.
 "jhu_csse_daily_subset"
 
 
-#' Subset of daily doctor visits and cases from California, Florida, Texas, and New York in archive format
+#' Subset of daily doctor visits and cases in archive format
 #'
-#' This data source is based on information about outpatient visits, 
-#' provided to us by health system partners, and also contains confirmed 
-#' COVID-19 cases based on reports made available by the Center for 
-#' Systems Science and Engineering at Johns Hopkins University. 
-#' This example data ranges from June 1, 2020 to Dec 1, 2021, and is also limited to California, Florida, Texas, and New York.
+#' This data source is based on information about outpatient visits,
+#' provided to us by health system partners, and also contains confirmed
+#' COVID-19 cases based on reports made available by the Center for
+#' Systems Science and Engineering at Johns Hopkins University.
+#' This example data ranges from June 1, 2020 to Dec 1, 2021, and 
+#' is also limited to California, Florida, Texas, and New York.
 #'
 #' @format An `epi_archive` data format. The data table DT has 129,638 rows and 5 columns:
 #' \describe{
@@ -41,26 +57,28 @@
 #'   \item{percent_cli}{percentage of doctor’s visits with CLI (COVID-like illness) computed from medical insurance claims}
 #'   \item{case_rate_7d_av}{7-day average signal of number of new confirmed deaths due to COVID-19 per 100,000 population, daily}
 #' }
-#' @source 
+#' @source
 #' This object contains a modified part of the \href{https://github.com/CSSEGISandData/COVID-19}{COVID-19 Data Repository by the Center for Systems Science and Engineering (CSSE) at Johns Hopkins University} as \href{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html}{republished in the COVIDcast Epidata API}. This data set is licensed under the terms of the
 #' \href{https://creativecommons.org/licenses/by/4.0/}{Creative Commons Attribution 4.0 International license}
 #' by Johns Hopkins University on behalf of its Center for Systems Science in Engineering.
 #' Copyright Johns Hopkins University 2020.
-#' 
+#'
 #' Modifications:
-#' * \href{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/doctor-visits.html}{From the COVIDcast Epidata Doctor Visits API}: These signals are taken directly from the JHU CSSE \href{https://github.com/CSSEGISandData/COVID-19}{COVID-19 GitHub repository} without changes. The 7-day average signals are computed by Delphi by calculating moving averages of the preceding 7 days, so the signal for June 7 is the average of the underlying data for June 1 through 7, inclusive.
-#' * Furthermore, the data has been limited to a very small number of rows, the signal names slightly altered, and formatted into a tibble.
+#' * \href{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/doctor-visits.html}{From the COVIDcast Doctor Visits API}: The signal `percent_cli` is taken directly from the API without changes.
+#' * \href{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html}{From the COVIDcast Epidata API}: `case_rate_7d_av` is taken directly from the JHU CSSE \href{https://github.com/CSSEGISandData/COVID-19}{COVID-19 GitHub repository} without changes. The 7-day average signals are computed by Delphi by calculating moving averages of the preceding 7 days, so the signal for June 7 is the average of the underlying data for June 1 through 7, inclusive.
+#' * Furthermore, the data is a subset of the full dataset, the signal names slightly altered, and formatted into a tibble.
 "archive_cases_dv_subset"
 
 
 #' Subset of JHU daily cases from California and Florida
-#' 
-#' This data source of confirmed COVID-19 cases 
-#' is based on reports made available by the Center for 
-#' Systems Science and Engineering at Johns Hopkins University. 
-#' This example data is a snapshot as of Oct 28, 2021 and captures the cases from June 1, 2020 to May 31, 2021 
+#'
+#' This data source of confirmed COVID-19 cases
+#' is based on reports made available by the Center for
+#' Systems Science and Engineering at Johns Hopkins University.
+#' This example data is a snapshot as of Oct 28, 2021 and captures the cases 
+#' from June 1, 2020 to May 31, 2021
 #' and is limited to California and Florida.
-#' 
+#'
 #' @format A tibble with 730 rows and 3 variables:
 #' \describe{
 #'   \item{geo_value}{the geographic value associated with each row of measurements.}
@@ -71,19 +89,20 @@
 #' \href{https://creativecommons.org/licenses/by/4.0/}{Creative Commons Attribution 4.0 International license}
 #' by the Johns Hopkins University on behalf of its Center for Systems Science in Engineering.
 #' Copyright Johns Hopkins University 2020.
-#' 
+#'
 #' Modifications:
-#' * \href{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html}{From the COVIDcast Epidata API}: 
-#' These signals are taken directly from the JHU CSSE \href{https://github.com/CSSEGISandData/COVID-19}{COVID-19 GitHub repository} without changes. 
+#' * \href{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html}{From the COVIDcast Epidata API}:
+#' These signals are taken directly from the JHU CSSE \href{https://github.com/CSSEGISandData/COVID-19}{COVID-19 GitHub repository} without changes.
 #' * Furthermore, the data has been limited to a very small number of rows, the signal names slightly altered, and formatted into a tibble.
 "incidence_num_outlier_example"
 
 #' Subset of JHU daily cases from counties in Massachusetts and Vermont
 #'
-#' This data source of confirmed COVID-19 cases and deaths 
-#' is based on reports made available by the Center for 
-#' Systems Science and Engineering at Johns Hopkins University. 
-#' This example data ranges from Mar 1, 2020 to Dec 31, 2021, and is limited to Massachusetts and Vermont.
+#' This data source of confirmed COVID-19 cases and deaths
+#' is based on reports made available by the Center for
+#' Systems Science and Engineering at Johns Hopkins University.
+#' This example data ranges from Mar 1, 2020 to Dec 31, 2021, 
+#' and is limited to Massachusetts and Vermont.
 #'
 #' @format A tibble with 16,212 rows and 5 variables:
 #' \describe{
@@ -97,9 +116,8 @@
 #' \href{https://creativecommons.org/licenses/by/4.0/}{Creative Commons Attribution 4.0 International license}
 #' by the Johns Hopkins University on behalf of its Center for Systems Science in Engineering.
 #' Copyright Johns Hopkins University 2020.
-#' 
+#'
 #' Modifications:
 #' * \href{https://cmu-delphi.github.io/delphi-epidata/api/covidcast-signals/jhu-csse.html}{From the COVIDcast Epidata API}: These signals are taken directly from the JHU CSSE \href{https://github.com/CSSEGISandData/COVID-19}{COVID-19 GitHub repository} without changes. The 7-day average signals are computed by Delphi by calculating moving averages of the preceding 7 days, so the signal for June 7 is the average of the underlying data for June 1 through 7, inclusive.
 #' * Furthermore, the data has been limited to a very small number of rows, the signal names slightly altered, and formatted into a tibble.
-
 "jhu_csse_county_level_subset"

R/epi_df.R

@@ -84,6 +84,85 @@
 #' @name epi_df
 NULL
 
+
+#' Creates an `epi_df` object
+#'
+#' Creates a new `epi_df` object. By default, builds an empty tibble with the 
+#' correct metadata for an `epi_df` object (ie. `geo_type`, `time_type`, and `as_of`).
+#' Refer to the below info. about the arguments for more details.
+#'
+#' @param x A data.frame, [tibble::tibble], or [tsibble::tsibble] to be converted
+#' @param geo_type Type for the geo values. If missing, then the function will
+#'   attempt to infer it from the geo values present; if this fails, then it
+#'   will be set to "custom".
+#' @param time_type Type for the time values. If missing, then the function will
+#'   attempt to infer it from the time values present; if this fails, then it
+#'   will be set to "custom".
+#' @param as_of Time value representing the time at which the given data were
+#'   available. For example, if `as_of` is January 31, 2022, then the `epi_df`
+#'   object that is created would represent the most up-to-date version of the
+#'   data available as of January 31, 2022. If the `as_of` argument is missing,
+#'   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.
+#' @param ... Additional arguments passed to methods.
+#' @return An `epi_df` object.
+#' 
+#' @export
+new_epi_df = function(x = tibble::tibble(), geo_type, time_type, as_of,
+                      additional_metadata = list(), ...) {
+  # Check that we have a data frame
+  if (!is.data.frame(x)) {
+    Abort("`x` must be a data frame.")
+  }
+  
+  # If geo type is missing, then try to guess it
+  if (missing(geo_type)) {
+    geo_type = guess_geo_type(x$geo_value)
+  }
+  
+  # If time type is missing, then try to guess it
+  if (missing(time_type)) {
+    time_type = guess_time_type(x$time_value)
+  }
+  
+  # If as_of is missing, then try to guess it
+  if (missing(as_of)) {
+    # First check the metadata for an as_of field
+    if ("metadata" %in% names(attributes(x)) &&
+        "as_of" %in% names(attributes(x)$metadata)) {
+      as_of = attributes(x)$metadata$as_of
+    }
+    
+    # Next check for as_of, issue, or version columns
+    else if ("as_of" %in% names(x)) as_of = max(x$as_of)
+    else if ("issue" %in% names(x)) as_of = max(x$issue)
+    else if ("version" %in% names(x)) as_of = max(x$version)
+    
+    # If we got here then we failed
+    else as_of = Sys.time() # Use the current day-time
+  }
+  
+  # Define metadata fields
+  metadata = list()
+  metadata$geo_type = geo_type
+  metadata$time_type = time_type
+  metadata$as_of = as_of
+  metadata = c(metadata, additional_metadata)
+  
+  # Reorder columns (geo_value, time_value, ...)
+  if(sum(dim(x)) != 0){
+    x = dplyr::relocate(x, .data$geo_value, .data$time_value)
+  }
+  
+  # Apply epi_df class, attach metadata, and return
+  class(x) = c("epi_df", class(x))
+  attributes(x)$metadata = metadata
+  return(x)
+}
+
 #' Convert to `epi_df` format
 #'
 #' Converts a data frame or tibble into an `epi_df` object. See the [getting
@@ -142,47 +221,8 @@ as_epi_df.tbl_df = function(x, geo_type, time_type, as_of,
     Abort("`x` must contain a `time_value` column.")
   }
 
-  # If geo type is missing, then try to guess it
-  if (missing(geo_type)) {
-    geo_type = guess_geo_type(x$geo_value)
-  }
-
-  # If time type is missing, then try to guess it
-  if (missing(time_type)) {
-    time_type = guess_time_type(x$time_value)
-  }
-
-  # If as_of is missing, then try to guess it
-  if (missing(as_of)) {
-    # First check the metadata for an as_of field
-    if ("metadata" %in% names(attributes(x)) &&
-        "as_of" %in% names(attributes(x)$metadata)) {
-      as_of = attributes(x)$metadata$as_of
-    }
-
-    # Next check for as_of, issue, or version columns
-    else if ("as_of" %in% names(x)) as_of = max(x$as_of)
-    else if ("issue" %in% names(x)) as_of = max(x$issue)
-    else if ("version" %in% names(x)) as_of = max(x$version)
-
-    # If we got here then we failed
-    else as_of = Sys.time() # Use the current day-time
-  }
-
-  # Define metadata fields
-  metadata = list()
-  metadata$geo_type = geo_type
-  metadata$time_type = time_type
-  metadata$as_of = as_of
-  metadata = c(metadata, additional_metadata)
-
-  # Reorder columns (geo_value, time_value, ...)
-  x = dplyr::relocate(x, .data$geo_value, .data$time_value)
-
-  # Apply epi_df class, attach metadata, and return
-  class(x) = c("epi_df", class(x))
-  attributes(x)$metadata = metadata
-  return(x)
+  new_epi_df(x, geo_type, time_type, as_of,
+             additional_metadata = list(), ...)
 }
 
 #' @method as_epi_df data.frame

_pkgdown.yml

@@ -63,6 +63,6 @@ reference:
   - incidence_num_outlier_example
   - contains("jhu_csse")
 - title: internal
-- contents:
+  contents:
   - epiprocess