Merge pull request #434 from cmu-delphi/ndefries/epi_slide-share-docs

Move some documentation to templates for easier updating

Author: nmdefries

R/epi_df.R

@@ -91,25 +91,7 @@ NULL
 #' 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 will be included as
-#'   well. If your tibble has additional keys, be sure to specify them as a
-#'   character vector in the `other_keys` component of `additional_metadata`.
-#' @param ... Additional arguments passed to methods.
-#' @return An `epi_df` object.
+#' @template epi_df-params
 #'
 #' @export
 new_epi_df <- function(x = tibble::tibble(), geo_type, time_type, as_of,
@@ -182,25 +164,7 @@ new_epi_df <- function(x = tibble::tibble(), geo_type, time_type, as_of,
 #' guide](https://cmu-delphi.github.io/epiprocess/articles/epiprocess.html) for
 #' examples.
 #'
-#' @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 will be included as
-#'   well. If your tibble has additional keys, be sure to specify them as a
-#'   character vector in the `other_keys` component of `additional_metadata`.
-#' @param ... Additional arguments passed to methods.
-#' @return An `epi_df` object.
+#' @template epi_df-params
 #'
 #' @export
 #' @examples

R/methods-epi_df.R

@@ -3,8 +3,8 @@
 #' Converts an `epi_df` object into a tibble, dropping metadata and any
 #' grouping.
 #'
-#' @param x an `epi_df`
-#' @param ... arguments to forward to `NextMethod()`
+#' @template x
+#' @param ... additional arguments to forward to `NextMethod()`
 #'
 #' @importFrom tibble as_tibble
 #' @export
@@ -22,7 +22,7 @@ as_tibble.epi_df <- function(x, ...) {
 #' others in the `other_keys` field of the metadata, or else explicitly set.
 #'
 #' @method as_tsibble epi_df
-#' @param x The `epi_df` object.
+#' @template x
 #' @param key Optional. Any additional keys (other than `geo_value`) to add to
 #'   the `tsibble`.
 #' @param ... additional arguments passed on to `tsibble::as_tsibble()`
@@ -39,8 +39,8 @@ as_tsibble.epi_df <- function(x, key, ...) {
 #'
 #' Print and summary functions for an `epi_df` object.
 #'
-#' @param x The `epi_df` object.
-#' @param ... Additional arguments passed to methods.
+#' @template x
+#' @param ... additional arguments to forward to `NextMethod()`
 #'
 #' @method print epi_df
 #' @export
@@ -61,7 +61,7 @@ print.epi_df <- function(x, ...) {
 #' Prints a variety of summary statistics about the `epi_df` object, such as
 #' the time range included and geographic coverage.
 #'
-#' @param object The `epi_df` object.
+#' @param object an `epi_df`
 #' @param ... Additional arguments, for compatibility with `summary()`.
 #'   Currently unused.
 #'
@@ -204,6 +204,7 @@ dplyr_row_slice.epi_df <- function(data, i, ...) {
 }
 
 #' @method group_by epi_df
+#' @param .data an `epi_df`
 #' @rdname print.epi_df
 #' @export
 group_by.epi_df <- function(.data, ...) {
@@ -223,7 +224,7 @@ ungroup.epi_df <- function(x, ...) {
 
 #' @method group_modify epi_df
 #' @rdname print.epi_df
-#' @param .data The `epi_df` object.
+#' @param .data an `epi_df`
 #' @param .f function or formula; see [`dplyr::group_modify`]
 #' @param .keep Boolean; see [`dplyr::group_modify`]
 #' @export
@@ -233,7 +234,7 @@ group_modify.epi_df <- function(.data, .f, ..., .keep = FALSE) {
 
 #' @method unnest epi_df
 #' @rdname print.epi_df
-#' @param data The `epi_df` object.
+#' @param data an `epi_df`
 #' @export
 unnest.epi_df <- function(data, ...) {
   dplyr::dplyr_reconstruct(NextMethod(), data)

R/outliers.R

@@ -6,10 +6,7 @@
 #' vignette](https://cmu-delphi.github.io/epiprocess/articles/outliers.html) for
 #' examples.
 #'
-#' @param x Design points corresponding to the signal values `y`. Default is
-#'   `seq_along(y)` (that is, equally-spaced points from 1 to the length of
-#'   `y`).
-#' @param y Signal values.
+#' @template x-y
 #' @param methods A tibble specifying the method(s) to use for outlier
 #'   detection, with one row per method, and the following columns:
 #'   * `method`: Either "rm" or "stl", or a custom function for outlier
@@ -25,9 +22,7 @@
 #'   summarized results are calculated. Note that if the number of `methods`
 #'   (number of rows) is odd, then "median" is equivalent to a majority vote for
 #'   purposes of determining whether a given observation is an outlier.
-#' @return An tibble with number of rows equal to `length(y)` and columns giving
-#'   the outlier detection thresholds and replacement values from each detection
-#'   method.
+#' @template detect-outlr-return
 #'
 #' @details Each outlier detection method, one per row of the passed `methods`
 #'   tibble, is a function that must take as its first two arguments `x` and
@@ -147,32 +142,14 @@ detect_outlr <- function(x = seq_along(y), y,
 #' Detects outliers based on a distance from the rolling median specified in
 #' terms of multiples of the rolling interquartile range (IQR).
 #'
-#' @param x Design points corresponding to the signal values `y`. Default is
-#'   `seq_along(y)` (that is, equally-spaced points from 1 to the length of
-#'   `y`).
-#' @param y Signal values.
+#' @template x-y
 #' @param n Number of time steps to use in the rolling window. Default is 21.
 #'   This value is centrally aligned. When `n` is an odd number, the rolling
 #'   window extends from `(n-1)/2` time steps before each design point to `(n-1)/2`
 #'   time steps after. When `n` is even, then the rolling range extends from
 #'   `n/2-1` time steps before to `n/2` time steps after.
-#' @param log_transform Should a log transform be applied before running outlier
-#'   detection? Default is `FALSE`. If `TRUE`, and zeros are present, then the
-#'   log transform will be padded by 1.
-#' @param detect_negatives Should negative values automatically count as
-#'   outliers? Default is `FALSE`.
-#' @param detection_multiplier Value determining how far the outlier detection
-#'   thresholds are from the rolling median, which are calculated as (rolling
-#'   median) +/- (detection multiplier) * (rolling IQR). Default is 2.
-#' @param min_radius Minimum distance between rolling median and threshold, on
-#'   transformed scale. Default is 0.
-#' @param replacement_multiplier Value determining how far the replacement
-#'   values are from the rolling median. The replacement is the original value
-#'   if it is within the detection thresholds, or otherwise it is rounded to the
-#'   nearest (rolling median) +/- (replacement multiplier) * (rolling IQR).
-#'   Default is 0.
-#' @return A tibble with number of rows equal to `length(y)`, and columns
-#'   `lower`, `upper`, and `replacement`.
+#' @template outlier-detection-options
+#' @template detect-outlr-return
 #'
 #' @export
 #' @examples
@@ -235,10 +212,7 @@ detect_outlr_rm <- function(x = seq_along(y), y, n = 21,
 #'
 #' Detects outliers based on a seasonal-trend decomposition using LOESS (STL).
 #'
-#' @param x Design points corresponding to the signal values `y`. Default is
-#'   `seq_along(y)` (that is, equally-spaced points from 1 to the length of
-#'   `y`).
-#' @param y Signal values.
+#' @template x-y
 #' @param n_trend Number of time steps to use in the rolling window for trend.
 #'   Default is 21.
 #' @param n_seasonal Number of time steps to use in the rolling window for
@@ -248,23 +222,8 @@ detect_outlr_rm <- function(x = seq_along(y), y, n = 21,
 #' @param seasonal_period Integer specifying period of seasonality. For example,
 #'   for daily data, a period 7 means weekly seasonality. The default is `NULL`,
 #'   meaning that no seasonal term will be included in the STL decomposition.
-#' @param log_transform Should a log transform be applied before running outlier
-#'   detection? Default is `FALSE`. If `TRUE`, and zeros are present, then the
-#'   log transform will be padded by 1.
-#' @param detect_negatives Should negative values automatically count as
-#'   outliers? Default is `FALSE`.
-#' @param detection_multiplier Value determining how far the outlier detection
-#'   thresholds are from the rolling median, which are calculated as (rolling
-#'   median) +/- (detection multiplier) * (rolling IQR). Default is 2.
-#' @param min_radius Minimum distance between rolling median and threshold, on
-#'   transformed scale. Default is 0.
-#' @param replacement_multiplier Value determining how far the replacement
-#'   values are from the rolling median. The replacement is the original value
-#'   if it is within the detection thresholds, or otherwise it is rounded to the
-#'   nearest (rolling median) +/- (replacement multiplier) * (rolling IQR).
-#'   Default is 0.
-#' @return A tibble with number of rows equal to `length(y)`, and columns
-#'   `lower`, `upper`, and `replacement`.
+#' @template outlier-detection-options
+#' @template detect-outlr-return
 #'
 #' @details The STL decomposition is computed using the `feasts` package. Once
 #'   computed, the outlier detection method is analogous to the rolling median