127127# ' dplyr::rename(geo_value = state, time_value = reported_date) %>%
128128# ' as_epi_df(
129129# ' as_of = "2020-06-03",
130- # ' additional_metadata = list( other_keys = "pol")
130+ # ' other_keys = "pol"
131131# ' )
132132# '
133133# ' attr(ex2, "metadata")
146146# ' state = rep("MA", 6),
147147# ' pol = rep(c("blue", "swing", "swing"), each = 2)
148148# ' ) %>%
149- # ' # the 2 extra keys we added have to be specified in the other_keys
150- # ' # component of additional_metadata.
151- # ' as_epi_df(additional_metadata = list(other_keys = c("state", "pol")))
149+ # ' as_epi_df(other_keys = c("state", "pol"))
152150# '
153151# ' attr(ex3, "metadata")
154152NULL
155153
156- # ' Create an `epi_df` object
157- # '
158- # ' @rdname epi_df
159- # ' @param geo_type DEPRECATED Has no effect. Geo value type is inferred from the
160- # ' location column and set to "custom" if not recognized.
161- # ' @param time_type DEPRECATED Has no effect. Time value type inferred from the time
162- # ' column and set to "custom" if not recognized. Unpredictable behavior may result
163- # ' if the time type is not recognized.
154+ # ' @describeIn epi_df Lower-level constructor for `epi_df` object
155+ # ' @order 2
156+ # ' @param geo_type `r lifecycle::badge("deprecated")` in `as_epi_df()`, has no
157+ # ' effect; the geo value type is inferred from the location column and set to
158+ # ' "custom" if not recognized. In `new_epi_df()`, should be set to the same
159+ # ' value that would be inferred.
160+ # ' @param time_type `r lifecycle::badge("deprecated")` in `as_epi_df()`, has no
161+ # ' effect: the time value type inferred from the time column and set to
162+ # ' "custom" if not recognized. Unpredictable behavior may result if the time
163+ # ' type is not recognized. In `new_epi_df()`, should be set to the same value
164+ # ' that would be inferred.
164165# ' @param as_of Time value representing the time at which the given data were
165166# ' available. For example, if `as_of` is January 31, 2022, then the `epi_df`
166167# ' object that is created would represent the most up-to-date version of the
167168# ' data available as of January 31, 2022. If the `as_of` argument is missing,
168169# ' then the current day-time will be used.
169- # ' @param additional_metadata List of additional metadata to attach to the
170- # ' `epi_df` object. The metadata will have `geo_type`, `time_type`, and
171- # ' `as_of` fields; named entries from the passed list will be included as
172- # ' well. If your tibble has additional keys, be sure to specify them as a
173- # ' character vector in the `other_keys` component of `additional_metadata`.
170+ # ' @param other_keys If your tibble has additional keys, be sure to specify them
171+ # ' as a character vector here (typical examples are "age" or sub-geographies).
174172# ' @param ... Additional arguments passed to methods.
175173# ' @return An `epi_df` object.
176174# '
177175# ' @export
178- new_epi_df <- function (x = tibble :: tibble(), geo_type , time_type , as_of ,
179- additional_metadata = list ()) {
176+ new_epi_df <- function (x = tibble :: tibble(geo_value = character (), time_value = as.Date(integer())),
177+ geo_type , time_type , as_of ,
178+ other_keys = character (), ... ) {
180179 # Define metadata fields
181180 metadata <- list ()
182181 metadata $ geo_type <- geo_type
183182 metadata $ time_type <- time_type
184183 metadata $ as_of <- as_of
185- metadata <- c( metadata , additional_metadata )
184+ metadata $ other_keys <- other_keys
186185
187186 # Reorder columns (geo_value, time_value, ...)
188187 if (sum(dim(x )) != 0 ) {
189- cols_to_put_first <- c(" geo_value" " time_value"
188+ cols_to_put_first <- c(" geo_value" " time_value" , other_keys )
190189 x <- x [, c(
191190 cols_to_put_first ,
192191 # All other columns
@@ -200,7 +199,8 @@ new_epi_df <- function(x = tibble::tibble(), geo_type, time_type, as_of,
200199 return (x )
201200}
202201
203- # ' @rdname epi_df
202+ # ' @describeIn epi_df The preferred way of constructing `epi_df`s
203+ # ' @order 1
204204# ' @param x An `epi_df`, `data.frame`, [tibble::tibble], or [tsibble::tsibble]
205205# ' to be converted
206206# ' @param ... used for specifying column names, as in [`dplyr::rename`]. For
@@ -211,24 +211,26 @@ as_epi_df <- function(x, ...) {
211211}
212212
213213# ' @rdname epi_df
214+ # ' @order 1
214215# ' @method as_epi_df epi_df
215216# ' @export
216217as_epi_df.epi_df <- function (x , ... ) {
217218 return (x )
218219}
219220
220221# ' @rdname epi_df
221- # ' @method as_epi_df tbl_df
222+ # ' @order 1
222223# ' @importFrom rlang .data
223224# ' @importFrom tidyselect any_of
224225# ' @importFrom cli cli_inform
226+ # ' @method as_epi_df tbl_df
225227# ' @export
226228as_epi_df.tbl_df <- function (
227229 x ,
228230 geo_type = deprecated(),
229231 time_type = deprecated(),
230232 as_of ,
231- additional_metadata = list (),
233+ other_keys = character (),
232234 ... ) {
233235 # possible standard substitutions for time_value
234236 x <- rename(x , ... )
@@ -274,29 +276,28 @@ as_epi_df.tbl_df <- function(
274276 } # Use the current day-time
275277 }
276278
277- assert_list(additional_metadata )
278- additional_metadata [[" other_keys" <- additional_metadata [[" other_keys" || % character (0L )
279- new_epi_df(x , geo_type , time_type , as_of , additional_metadata )
279+ assert_character(other_keys )
280+ new_epi_df(x , geo_type , time_type , as_of , other_keys )
280281}
281282
282- # ' @method as_epi_df data.frame
283283# ' @rdname epi_df
284+ # ' @order 1
285+ # ' @method as_epi_df data.frame
284286# ' @export
285- as_epi_df.data.frame <- function (x , as_of , additional_metadata = list (), ... ) {
286- as_epi_df.tbl_df(x = tibble :: as_tibble(x ), as_of = as_of , additional_metadata = additional_metadata , ... )
287+ as_epi_df.data.frame <- function (x , as_of , other_keys = character (), ... ) {
288+ as_epi_df.tbl_df(x = tibble :: as_tibble(x ), as_of = as_of , other_keys = other_keys , ... )
287289}
288290
289- # ' @method as_epi_df tbl_ts
290291# ' @rdname epi_df
292+ # ' @order 1
293+ # ' @method as_epi_df tbl_ts
291294# ' @export
292- as_epi_df.tbl_ts <- function (x , as_of , additional_metadata = list (), ... ) {
295+ as_epi_df.tbl_ts <- function (x , as_of , other_keys = character (), ... ) {
293296 tsibble_other_keys <- setdiff(tsibble :: key_vars(x ), " geo_value"
294- if (length(tsibble_other_keys ) != 0 ) {
295- additional_metadata $ other_keys <- unique(
296- c(additional_metadata $ other_keys , tsibble_other_keys )
297- )
297+ if (length(tsibble_other_keys ) > 0 ) {
298+ other_keys <- unique(c(other_keys , tsibble_other_keys ))
298299 }
299- as_epi_df.tbl_df(x = tibble :: as_tibble(x ), as_of = as_of , additional_metadata = additional_metadata , ... )
300+ as_epi_df.tbl_df(x = tibble :: as_tibble(x ), as_of = as_of , other_keys = other_keys , ... )
300301}
301302
302303# ' Test for `epi_df` format
0 commit comments