Rework epi_slide_{opt,mean,sum} examples as they are 1 help topic

Author: brookslogan

R/slide.R

@@ -632,22 +632,53 @@ get_before_after_from_window <- function(window_size, align, time_type) {
 #' @export
 #' @seealso [`epi_slide`] for the more general slide function
 #' @examples
-#' # Compute a 7-day trailing average on cases.
+#' # Add a column (`cases_7dsum`) containing a 7-day trailing sum on `cases`:
 #' cases_deaths_subset %>%
+#'   select(geo_value, time_value, cases) %>%
+#'   epi_slide_sum(cases, .window_size = 7)
+#'
+#' # Add a column (`cases_rate_7dav`) containing a 7-day trailing average on `case_rate`:
+#' covid_case_death_rates_extended %>%
+#'   epi_slide_mean(case_rate, .window_size = 7)
+#'
+#' # Use a less common specialized slide function:
+#' cases_deaths_subset %>%
+#'   epi_slide_opt(cases, slider::slide_min, .window_size = 7)
+#'
+#' # Specify output column names and/or a naming scheme:
+#' cases_deaths_subset %>%
+#'   select(geo_value, time_value, cases) %>%
 #'   group_by(geo_value) %>%
-#'   epi_slide_opt(cases, .f = data.table::frollmean, .window_size = 7) %>%
+#'   epi_slide_sum(cases, .window_size = 7, .new_col_names = "case_sum") %>%
 #'   ungroup()
-#'
-#' # Same as above, but adjust `frollmean` settings for speed, accuracy, and
-#' # to allow partially-missing windows.
 #' cases_deaths_subset %>%
+#'   select(geo_value, time_value, cases) %>%
 #'   group_by(geo_value) %>%
-#'   epi_slide_opt(
-#'     cases,
-#'     .f = data.table::frollmean, .window_size = 7,
-#'     algo = "exact", hasNA = TRUE, na.rm = TRUE
-#'   ) %>%
+#'   epi_slide_sum(cases, .window_size = 7, .prefix = "sum_") %>%
 #'   ungroup()
+#'
+#' # Additional settings can be sent to the {data.table} and {slider} functions
+#' # via `...`. This example passes some arguments to `frollmean` settings for
+#' # speed, accuracy, and to allow partially-missing windows:
+#' covid_case_death_rates_extended %>%
+#'   epi_slide_mean(
+#'     case_rate,
+#'     .window_size = 7,
+#'     na.rm = TRUE, algo = "exact", hasNA = TRUE
+#'   )
+#'
+#' # If the more specialized possibilities for `.f` don't cover your needs, you
+#' # can use `epi_slide_opt` with `.f = data.table::frollapply` to apply a
+#' # custom function at the cost of more computation time. See also `epi_slide`
+#' # if you need something even more general.
+#' cases_deaths_subset %>%
+#'   select(geo_value, time_value, case_rate_7d_av, death_rate_7d_av) %>%
+#'   epi_slide_opt(c(case_rate_7d_av, death_rate_7d_av),
+#'     data.table::frollapply,
+#'     FUN = median, .window_size = 28,
+#'     .suffix = "_{.n}{.time_unit_abbr}_median"
+#'   ) %>%
+#'   print(n = 40)
 epi_slide_opt <- function(
     .x, .col_names, .f, ...,
     .window_size = NULL, .align = c("right", "center", "left"),
@@ -951,40 +982,6 @@ epi_slide_opt <- function(
 #' datatable::frollmean`.
 #'
 #' @export
-#' @examples
-#' # Compute a 7-day trailing average of case rates.
-#' covid_case_death_rates_extended %>%
-#'   group_by(geo_value) %>%
-#'   epi_slide_mean(case_rate, .window_size = 7) %>%
-#'   ungroup()
-#'
-#' # Same as above, but adjust `frollmean` settings for speed, accuracy, and
-#' # to allow partially-missing windows.
-#' covid_case_death_rates_extended %>%
-#'   group_by(geo_value) %>%
-#'   epi_slide_mean(
-#'     case_rate,
-#'     .window_size = 7,
-#'     na.rm = TRUE, algo = "exact", hasNA = TRUE
-#'   ) %>%
-#'   ungroup()
-#'
-#' # Compute a 7-day trailing average of case rates and death rates, with custom
-#' # output column names:
-#' covid_case_death_rates_extended %>%
-#'   group_by(geo_value) %>%
-#'   epi_slide_mean(c(case_rate, death_rate),
-#'     .window_size = 7,
-#'     .new_col_names = c("smoothed_case_rate", "smoothed_death_rate")
-#'   ) %>%
-#'   ungroup()
-#' covid_case_death_rates_extended %>%
-#'   group_by(geo_value) %>%
-#'   epi_slide_mean(c(case_rate, death_rate),
-#'     .window_size = 7,
-#'     .suffix = "_{.n}{.time_unit_abbr}_avg"
-#'   ) %>%
-#'   ungroup()
 epi_slide_mean <- function(
     .x, .col_names, ...,
     .window_size = NULL, .align = c("right", "center", "left"),
@@ -1044,25 +1041,6 @@ epi_slide_mean <- function(
 #' datatable::frollsum`.
 #'
 #' @export
-#' @examples
-#' # Compute a 7-day trailing sum on cases.
-#' cases_deaths_subset %>%
-#'   select(geo_value, time_value, cases) %>%
-#'   group_by(geo_value) %>%
-#'   epi_slide_sum(cases, .window_size = 7) %>%
-#'   ungroup()
-#'
-#' # Specify output column names and/or naming scheme:
-#' cases_deaths_subset %>%
-#'   select(geo_value, time_value, cases) %>%
-#'   group_by(geo_value) %>%
-#'   epi_slide_sum(cases, .window_size = 7, .new_col_names = "case_sum") %>%
-#'   ungroup()
-#' cases_deaths_subset %>%
-#'   select(geo_value, time_value, cases) %>%
-#'   group_by(geo_value) %>%
-#'   epi_slide_sum(cases, .window_size = 7, .prefix = "sum_") %>%
-#'   ungroup()
 epi_slide_sum <- function(
     .x, .col_names, ...,
     .window_size = NULL, .align = c("right", "center", "left"),