Skip to content

Commit d6a28f3

Browse files
committed
redocument
1 parent f18e88f commit d6a28f3

24 files changed

+340
-74
lines changed

NAMESPACE

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ S3method(residuals,flatline)
7979
S3method(run_mold,default_epi_recipe_blueprint)
8080
S3method(slather,layer_add_forecast_date)
8181
S3method(slather,layer_add_target_date)
82+
S3method(slather,layer_cdc_flatline_quantiles)
8283
S3method(slather,layer_naomit)
8384
S3method(slather,layer_point_from_distn)
8485
S3method(slather,layer_population_scaling)
@@ -131,6 +132,7 @@ export(is_layer)
131132
export(layer)
132133
export(layer_add_forecast_date)
133134
export(layer_add_target_date)
135+
export(layer_cdc_flatline_quantiles)
134136
export(layer_naomit)
135137
export(layer_point_from_distn)
136138
export(layer_population_scaling)

R/layer_cdc_flatline_quantiles.R

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,97 @@
1+
#' CDC Flatline Forecast Quantiles
2+
#'
3+
#' This layer creates quantile forecasts by taking a sample from the
4+
#' interpolated CDF of the flatline residuals, and shuffling them.
5+
#' These are then added on to the point prediction.
6+
#'
7+
#' @details
8+
#' This layer is intended to be used in concert with [flatline()]. But it can
9+
#' also be used with anything else. As long as residuals are available in the
10+
#' the fitted model, this layer could be useful. Like
11+
#' [layer_residual_quantiles()] it only uses the residuals for the fitted model
12+
#' object. However, it propagates these forward for *all* aheads, by
13+
#' iteratively shuffling them (randomly), and then adding them to the previous
14+
#' set. This is in contrast to what happens with the [flatline_forecaster()].
15+
#' When using [flatline()] as the underlying engine (here), both will result in the
16+
#' same predictions (the most recent observed value), but that model calculates
17+
#' separate residuals for each `ahead` by comparing to observations further into
18+
#' the future. This version continues to use the same set of residuals, and
19+
#' adds them on to produce wider intervals as `ahead` increases.
20+
#'
21+
#'
22+
#' @inheritParams layer_residual_quantiles
23+
#' @param aheads Numeric vector of desired forecast horizons. These should be
24+
#' given in the "units of the training data". So, for example, for data
25+
#' typically observed daily (possibly with missing values), but
26+
#' with weekly forecast targets, you would use `c(7, 14, 21, 28)`. But with
27+
#' weekly data, you would use `1:4`.
28+
#' @param quantiles Numeric vector of probabilities with values in (0,1)
29+
#' referring to the desired predictive intervals. The default is the standard
30+
#' set for the COVID Forecast Hub.
31+
#' @param nsims Positive integer. The number of draws from the empirical CDF.
32+
#' These samples are spaced evenly on the (0, 1) scale, F_X(x) resulting
33+
#' in linear interpolation on the X scale. This is achieved with
34+
#' [stats::quantile()] Type 7 (the default for that function).
35+
#' @param nonneg Logical. Force all predictive intervals be non-negative.
36+
#' Because non-negativity is forced _before_ propagating forward, this
37+
#' has slightly different behaviour than would occur if using
38+
#' [layer_threshold_preds()].
39+
#'
40+
#' @return an updated `frosting` postprocessor. Calling [predict()] will result
41+
#' in an additional `<list-col>` named `.pred_distn_all` containing 2-column
42+
#' [tibble::tibble()]'s. For each
43+
#' desired combination of `key`'s, the tibble will contain one row per ahead
44+
#' with the associated [dist_quantiles()].
45+
#' @export
46+
#'
47+
#' @examples
48+
#' r <- epi_recipe(case_death_rate_subset) %>%
49+
#' # data is "daily", so we fit this to 1 ahead, the result will contain
50+
#' # 1 day ahead residuals
51+
#' step_epi_ahead(death_rate, ahead = 1L, skip = TRUE) %>%
52+
#' recipes::update_role(death_rate, new_role = "predictor") %>%
53+
#' recipes::add_role(time_value, geo_value, new_role = "predictor")
54+
#'
55+
#' forecast_date <- max(case_death_rate_subset$time_value)
56+
#'
57+
#' latest <- get_test_data(
58+
#' epi_recipe(case_death_rate_subset), case_death_rate_subset
59+
#' )
60+
#'
61+
#' f <- frosting() %>%
62+
#' layer_predict() %>%
63+
#' layer_cdc_flatline_quantiles(aheads = c(7, 14, 21, 28), symmetrize = TRUE)
64+
#'
65+
#' eng <- parsnip::linear_reg() %>% parsnip::set_engine("flatline")
66+
#'
67+
#' wf <- epi_workflow(r, eng, f) %>% fit(case_death_rate_subset)
68+
#' preds <- suppressWarnings(predict(wf, new_data = latest)) %>%
69+
#' dplyr::select(-time_value) %>%
70+
#' dplyr::mutate(forecast_date = forecast_date)
71+
#' preds
72+
#'
73+
#' preds <- preds %>%
74+
#' unnest(.pred_distn_all) %>%
75+
#' pivot_quantiles(.pred_distn) %>%
76+
#' mutate(target_date = forecast_date + ahead)
77+
#'
78+
#' library(ggplot2)
79+
#' four_states <- c("ca", "pa", "wa", "ny")
80+
#' preds %>%
81+
#' filter(geo_value %in% four_states) %>%
82+
#' ggplot(aes(target_date)) +
83+
#' geom_ribbon(aes(ymin = `0.1`, ymax = `0.9`), fill = blues9[3]) +
84+
#' geom_ribbon(aes(ymin = `0.25`, ymax = `0.75`), fill = blues9[6]) +
85+
#' geom_line(aes(y = .pred), color = "orange") +
86+
#' geom_line(data = case_death_rate_subset %>% filter(geo_value %in% four_states),
87+
#' aes(x = time_value, y = death_rate)) +
88+
#' scale_x_date(limits = c(forecast_date - 90, forecast_date + 30)) +
89+
#' labs(x = "Date", y = "Death rate") +
90+
#' facet_wrap(~geo_value, scales = "free_y") +
91+
#' theme_bw() +
92+
#' geom_vline(xintercept = forecast_date)
93+
#'
94+
#'
195
layer_cdc_flatline_quantiles <- function(
296
frosting,
397
...,

man/add_frosting.Rd

Lines changed: 3 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/arx_fcast_epi_workflow.Rd

Lines changed: 8 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/arx_forecaster.Rd

Lines changed: 8 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/create_layer.Rd

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/dist_quantiles.Rd

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/extrapolate_quantiles.Rd

Lines changed: 5 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/fit-epi_workflow.Rd

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/flatline.Rd

Lines changed: 4 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/flatline_args_list.Rd

Lines changed: 6 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/frosting.Rd

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/layer_add_forecast_date.Rd

Lines changed: 7 additions & 5 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/layer_add_target_date.Rd

Lines changed: 4 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)