recommended edits

Author: dsweber2

NAMESPACE

@@ -190,6 +190,7 @@ export(nested_quantiles)
 export(new_default_epi_recipe_blueprint)
 export(new_epi_recipe_blueprint)
 export(pivot_longer)
+export(pivot_quantiles)
 export(pivot_quantiles_longer)
 export(pivot_quantiles_wider)
 export(pivot_wider)

R/arx_classifier.R

@@ -34,17 +34,17 @@
 #' ```
 #'
 #' The key takeaway from the predictions is that there are two prediction
-#'   classes: `(-Inf, 0.25]` and `(0.25, Inf)`. This is because for our goal of
-#'   classification the classes must be discrete. The discretization of the
-#'   real-valued outcome is controlled by the `breaks` argument, which defaults
-#'   to `0.25`. Such breaks will be automatically extended to cover the entire
-#'   real line. For example, the default break of `0.25` is silently extended to
-#'   `breaks = c(-Inf, .25, Inf)` and, therefore, results in two classes:
-#'   `[-Inf, 0.25]` and `(0.25, Inf)`. These two classes are used to discretize
-#'   the outcome. The conversion of the outcome to such classes is handled
-#'   internally. So if discrete classes already exist for the outcome in the
-#'   `epi_df`, then we recommend to code a classifier from scratch using the
-#'   `epi_workflow` framework for more control.
+#'   classes: `(-Inf, 0.25]` and `(0.25, Inf)`: the classes to predict must be
+#'   discrete. The discretization of the real-valued outcome is controlled by
+#'   the `breaks` argument, which defaults to `0.25`. Such breaks will be
+#'   automatically extended to cover the entire real line. For example, the
+#'   default break of `0.25` is silently extended to `breaks = c(-Inf, .25,
+#'   Inf)` and, therefore, results in two classes: `[-Inf, 0.25]` and `(0.25,
+#'   Inf)`. These two classes are used to discretize the outcome. The conversion
+#'   of the outcome to such classes is handled internally. So if discrete
+#'   classes already exist for the outcome in the `epi_df`, then we recommend to
+#'   code a classifier from scratch using the `epi_workflow` framework for more
+#'   control.
 #'
 #' The `trainer` is a `parsnip` model describing the type of estimation such
 #'   that `mode = "classification"` is enforced. The two typical trainers that

R/arx_forecaster.R

@@ -3,7 +3,7 @@
 #' This is an autoregressive forecasting model for
 #' [epiprocess::epi_df][epiprocess::as_epi_df] data. It does "direct"
 #' forecasting, meaning that it estimates a model for a particular target
-#' horizon of `outcome` based on the lags of the `predictors`. See the [Get
+#' horizon of the `outcome` based on the lags of the `predictors`. See the [Get
 #' started vignette](../articles/epipredict.html) for some worked examples and
 #' [Custom epi_workflows vignette](../articles/custom_epiworkflows.html) for a
 #' recreation using a custom `epi_workflow()`.
@@ -13,16 +13,15 @@
 #' @param outcome A character (scalar) specifying the outcome (in the `epi_df`).
 #' @param predictors A character vector giving column(s) of predictor variables.
 #'   This defaults to the `outcome`. However, if manually specified, only those
-#'   variables specifically mentioned will be used. (The `outcome` will not be
-#'   added.)  By default, equals the outcome. If manually specified, does not
-#'   add the outcome variable, so make sure to specify it.
+#'   variables specifically mentioned will be used, and the `outcome` will not be
+#'   added.
 #' @param trainer A `{parsnip}` model describing the type of estimation.  For
 #'   now, we enforce `mode = "regression"`.
 #' @param args_list A list of customization arguments to determine the type of
 #'   forecasting model. See [arx_args_list()].
 #'
 #' @return An `arx_fcast`, with the fields `predictions` and `epi_workflow`.
-#'   `predictions` is an `epi_df` of predicted values while `epi_workflow()` is
+#'   `predictions` is a `tibble` of predicted values while `epi_workflow()` is
 #'   the fit workflow used to make those predictions
 #' @export
 #' @seealso [arx_fcast_epi_workflow()], [arx_args_list()]
@@ -270,8 +269,7 @@ arx_fcast_epi_workflow <- function(
 #'   training residuals. A `NULL` value will result in point forecasts only.
 #' @param symmetrize Logical. The default `TRUE` calculates symmetric prediction
 #'   intervals. This argument only applies when residual quantiles are used. It
-#'   is not applicable with `trainer = quantile_reg()`, for example. This is
-#'   achieved by including both the residuals and their negation. Typically, one
+#'   is not applicable with `trainer = quantile_reg()`, for example. Typically, one
 #'   would only want non-symmetric quantiles when increasing trajectories are
 #'   quite different from decreasing ones, such as a strictly postive variable
 #'   near zero.

R/climatological_forecaster.R

@@ -134,12 +134,12 @@ climatological_forecaster <- function(epi_data,
   # get the distinct .idx for the target date(s)
   distinct_target_idx <- predictions$.idx %>% unique()
   # get all of the idx's within the window of the target .idxs
-  entries <- map(distinct_target_idx, \(idx) within_window(idx, window_size, modulus)) %>%
+  entries <- map(distinct_target_idx, function(idx) within_window(idx, window_size, modulus)) %>%
     do.call(c, .) %>%
     unique()
   # for the center, we need those within twice the window, since for each point
   # we're subtracting out the center to generate the quantiles
-  entries_double_window <- map(entries, \(idx) within_window(idx, window_size, modulus)) %>%
+  entries_double_window <- map(entries, function(idx) within_window(idx, window_size, modulus)) %>%
     do.call(c, .) %>%
     unique()
 

R/epi_recipe.R

@@ -232,8 +232,7 @@ is_epi_recipe <- function(x) {
 
 
 
-#' Given an `epi_recipe`, add it to, remove it from, or update it in an
-#' `epi_workflow`
+#' Add/remove/update the `epi_recipe` of an `epi_workflow`
 #'
 #' @description
 #' - `add_recipe()` specifies the terms of the model and any preprocessing that

R/epi_workflow.R

@@ -113,14 +113,19 @@ fit.epi_workflow <- function(object, data, ..., control = workflows::control_wor
 #'
 #' @description
 #' This is the `predict()` method for a fit epi_workflow object. The 3 steps that this implements are:
+#' - Preprocess `new_data` using the preprocessing method specified when the
+#'   workflow was created and fit. This is accomplished using
+#'   [hardhat::forge()], which will apply any formula preprocessing or call
+#'   [recipes::bake()] if a recipe was supplied.
 #'
 #' - Preprocessing `new_data` using the preprocessing method specified when the
 #'   epi_workflow was created and fit. This is accomplished using
-#'   `recipes::bake()` if a recipe was supplied. Note that this is a slightly
-#'   different `bake` operation than the one occuring during the fit. Any `step`
-#'   that has `skip = TRUE` isn't applied during prediction; for example in
-#'   `step_epi_naomit()`, `all_outcomes()` isn't `NA` omitted, since doing so
-#'   would drop the exact `time_values` we are trying to predict.
+#'   `hardhat::bake()` if a recipe was supplied (passing through
+#'   [hardhat::forge()], which is used for non-recipe preprocessors). Note that
+#'   this is a slightly different `bake` operation than the one occuring during
+#'   the fit. Any `step` that has `skip = TRUE` isn't applied during prediction;
+#'   for example in `step_epi_naomit()`, `all_outcomes()` isn't `NA` omitted,
+#'   since doing so would drop the exact `time_values` we are trying to predict.
 #'
 #' - Calling `parsnip::predict.model_fit()` for you using the underlying fit
 #'   parsnip model.
@@ -137,7 +142,7 @@ fit.epi_workflow <- function(object, data, ..., control = workflows::control_wor
 #'
 #' @return
 #' A data frame of model predictions, with as many rows as `new_data` has.
-#' If `new_data` is an `epi_df()` or a data frame with `time_value` or
+#' If `new_data` is an `epiprocess::epi_df` or a data frame with `time_value` or
 #' `geo_value` columns, then the result will have those as well.
 #'
 #' @name predict-epi_workflow
@@ -234,7 +239,7 @@ print.epi_workflow <- function(x, ...) {
 }
 
 
-#' Produce a forecast from just an epi workflow
+#' Produce a forecast from an epi workflow and it's training data
 #'
 #' `forecast.epi_workflow` predicts by restricting the training data to the
 #' latest available data, and predicting on that. It binds together

R/extrapolate_quantiles.R

@@ -3,14 +3,15 @@
 #' This both interpolates between quantile levels already defined in `x` and
 #' extrapolates quantiles outside their bounds. The interpolation method is
 #' determined by the `quantile` argument `middle`, which can be either `"cubic"`
-#' for a (hyman) cubic spline interpolation, or `"linear"` for simple linear
+#' for a (Hyman) cubic spline interpolation, or `"linear"` for simple linear
 #' interpolation.
 #'
 #' There is only one extrapolation method for values greater than the largest
-#' known quantile level or smaller than the smallest known quantile level. It
-#' assumes a roughly exponential tail, whose decay rate and offset is derived
-#' from the slope of the two most extreme quantile levels on a logistic scale.
-#' See the internal function `tail_extrapolate()` for the exact implementation.
+#' available quantile level or smaller than the smallest available quantile
+#' level. It assumes a roughly exponential tail, whose decay rate and offset is
+#' derived from the slope of the two most extreme quantile levels on a logistic
+#' scale.  See the internal function `tail_extrapolate()` for the exact
+#' implementation.
 #'
 #' This function takes a `quantile_pred` vector and returns the same
 #' type of object, expanded to include

R/frosting.R

@@ -1,5 +1,4 @@
-#' Given a `frosting()`, add it to, remove it from, or update it in an
-#' `epi_workflow`
+#' Add/remove/update the `frosting` of an `epi_workflow`
 #'
 #' @param x A workflow
 #' @param frosting A frosting object created using `frosting()`.

R/get_test_data.R

@@ -1,9 +1,12 @@
 #' Get test data for prediction based on longest lag period
 #'
-#' If `predict()` is given the full training dataset, it will produce a forecast
-#' for every day which has enough data. For most cases, this is far more
-#' forecasts than is necessary. `get_test_data()` is designed to restrict the given dataset to the minimum amount needed to produce a forecast on the `forecast_date`.
-#' Primarily this is based on the longest lag period in the recipe.
+#' If `predict()` is given the full training dataset, it will produce a
+#' prediction for every `time_value` which has enough data. For most cases, this
+#' generates predictions for `time_values` where the `outcome` has already been
+#' observed.  `get_test_data()` is designed to restrict the given dataset to the
+#' minimum amount needed to produce a forecast on the `forecast_date` for future
+#' data, rather than a prediction on past `time_value`s.  Primarily this is
+#' based on the longest lag period in the recipe.
 #'
 #' The minimum required (recent) data to produce a forecast is equal to
 #' the maximum lag requested (on any predictor) plus the longest horizon

R/layer_population_scaling.R

@@ -1,10 +1,10 @@
 #' Convert per-capita predictions to raw scale
 #'
 #' `layer_population_scaling` creates a specification of a frosting layer that
-#' will "undo" per-capita scaling done in `step_population_scaling()`. Typical
-#' usage would set `df` to be a dataset that contains state-level population,
-#' and use it to convert predictions made from a raw scale model to rate-scale
-#' by dividing by the population.
+#' will "undo" per-capita scaling done in `step_population_scaling()`.
+#' Typical usage would set `df` to be a dataset that contains a list of
+#' population for the `geo_value`s, and use it to convert predictions made from
+#' a raw scale model to rate-scale by dividing by the population.
 #' Although, it is worth noting that there is nothing special about
 #' "population", and  the function can be used to scale by any variable.
 #' Population is the standard use case in the epidemiology forecasting scenario.