Lint and typos

DESCRIPTION

@@ -67,4 +67,4 @@ Config/testthat/edition: 3
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.2
+RoxygenNote: 7.2.3

R/arx_forecaster.R

@@ -38,6 +38,9 @@ arx_forecaster <- function(epi_data,
 
   # --- validation
   validate_forecaster_inputs(epi_data, outcome, predictors)
+  if (!inherits(args_list, "arx_alist")) {
+    cli_stop("args_list was not created using `arx_args_list().")
+  }
   if (!is.list(trainer) || trainer$mode != "regression")
     cli_stop("{trainer} must be a `parsnip` method of mode 'regression'.")
   lags <- arx_lags_validator(predictors, args_list$lags)
@@ -121,7 +124,7 @@ arx_lags_validator <- function(predictors, lags) {
 #'   [layer_residual_quantiles()] for more information. The default,
 #'   `character(0)` performs no grouping.
 #'
-#' @return A list containing updated parameter choices.
+#' @return A list containing updated parameter choices with class `arx_alist`.
 #' @export
 #'
 #' @examples
@@ -151,14 +154,15 @@ arx_args_list <- function(lags = c(0L, 7L, 14L),
   arg_is_probabilities(levels, allow_null = TRUE)
 
   max_lags <- max(lags)
-  enlist(lags = .lags,
-         ahead,
-         min_train_window,
-         levels,
-         forecast_date,
-         target_date,
-         symmetrize,
-         nonneg,
-         max_lags,
-         quantile_by_key)
+  structure(enlist(lags = .lags,
+                   ahead,
+                   min_train_window,
+                   levels,
+                   forecast_date,
+                   target_date,
+                   symmetrize,
+                   nonneg,
+                   max_lags,
+                   quantile_by_key),
+            class = "arx_alist")
 }

R/flatline_forecaster.R

@@ -32,6 +32,9 @@ flatline_forecaster <- function(epi_data,
                                 args_list = flatline_args_list()) {
 
   validate_forecaster_inputs(epi_data, outcome, "time_value")
+  if (!inherits(args_list, "flatline_alist")) {
+    cli_stop("args_list was not created using `flatline_args_list().")
+  }
   keys <- epi_keys(epi_data)
   ek <- keys[-1]
   outcome <- rlang::sym(outcome)
@@ -75,7 +78,7 @@ flatline_forecaster <- function(epi_data,
 #'
 #' @inheritParams arx_args_list
 #'
-#' @return A list containing updated parameter choices.
+#' @return A list containing updated parameter choices with class `flatline_alist`.
 #' @export
 #'
 #' @examples
@@ -99,14 +102,15 @@ flatline_args_list <- function(ahead = 7L,
   arg_is_lgl(symmetrize, nonneg)
   arg_is_probabilities(levels, allow_null = TRUE)
 
-  enlist(ahead,
-         min_train_window,
-         forecast_date,
-         target_date,
-         levels,
-         symmetrize,
-         nonneg,
-         quantile_by_key)
+  structure(enlist(ahead,
+                   min_train_window,
+                   forecast_date,
+                   target_date,
+                   levels,
+                   symmetrize,
+                   nonneg,
+                   quantile_by_key),
+            class = "flatline_alist")
 }
 
 validate_forecaster_inputs <- function(epi_data, outcome, predictors) {

README.Rmd

@@ -19,15 +19,15 @@ knitr::opts_chunk$set(
 [![R-CMD-check](https://github.com/cmu-delphi/epipredict/workflows/R-CMD-check/badge.svg)](https://github.com/cmu-delphi/epipredict/actions)
 <!-- badges: end -->
 
-**Note:** This package is currently in development and likely will not work as expected.
+**Note:** This package is currently in development and may not work as expected. Please file bug reports as issues in this repo, and we will do our best to address them quickly.
 
 ## Installation
 
 You can install the development version of epipredict from [GitHub](https://github.com/) with:
 
 ``` r
-# install.packages("devtools")
-devtools::install_github("cmu-delphi/epipredict")
+# install.packages("remotes")
+remotes::install_github("cmu-delphi/epipredict")
 ```
 
 ## Documentation
@@ -39,7 +39,7 @@ You can view documentation for the `main` branch at <https://cmu-delphi.github.i
 
 **We hope to provide:**
 
-1. A set of basic, easy-to-use forecasters that work out of the box. You should be able to do a reasonably limited amount of customization on them. (Any serious customization happens with point number 2.) For the basic forecasters, we should provide, at least: 
+1. A set of basic, easy-to-use forecasters that work out of the box. You should be able to do a reasonably limited amount of customization on them. For the basic forecasters, we currently provide: 
     * Baseline flat-line forecaster 
     * Autoregressive forecaster
     * Autoregressive classifier
@@ -49,15 +49,58 @@ You can view documentation for the `main` branch at <https://cmu-delphi.github.i
     * Predictor: make predictions, using a fitted model object
     * Postprocessor: do things to the predictions before returning
 
-**Target audience:**
+**Target audiences:**
 
 * Basic. Has data, calls forecaster with default arguments.
 * Intermediate. Wants to examine changes to the arguments, take advantage of built in flexibility.
 * Advanced. Wants to write their own forecasters. Maybe willing to build up from some components that we write. 
 
-The Advanced user should find their task to be relatively easy (and we'll show them how). 
+The Advanced user should find their task to be relatively easy. Examples of these tasks are illustrated in the [vignettes and articles](https://cmu-delphi.github.io/epipredict).
+
+## Intermediate example
+
+The package comes with some built-in historical data for illustration, but
+up-to-date versions of this could be downloaded with the [`{covidcast}` package](https://cmu-delphi.github.io/covidcast/covidcastR/index.html) and processed using [`{epiprocess}`](https://cmu-delphi.github.io/epiprocess/).[^1]
+
+[^1]: Other epidemiological signals for non-Covid related illnesses are available with [`{epidatr}`](https://github.com/cmu-delphi/epidatr) which interfaces directly to Delphi's [Epidata API](https://cmu-delphi.github.io/delphi-epidata/)
+
+```{r epidf, message=FALSE}
+library(tidyverse)
+library(epipredict)
+jhu <- case_death_rate_subset
+jhu
+```
+
+To create and train a simple auto-regressive forecaster to predict the death rate two weeks into the future using past (lagged) deaths and cases, we could use the following function.
+
+```{r make-forecasts, warning=FALSE}
+two_week_ahead <- arx_forecaster(
+  jhu, 
+  outcome = "death_rate", 
+  predictors = c("case_rate", "death_rate"),
+  args_list = arx_args_list(
+    lags = list(c(0,1,2,3,7,14), c(0,7,14)),
+    ahead = 14
+  )
+) 
+```
+
+In this case, we have used a number of different lags for the case rate, while only using 3 weekly lags for the death rate (as predictors). The result is both a fitted model object which could be used any time in the future to create different forecasts, as well as a set of predicted values (and prediction intervals) for each location 14 days after the last available time value in the data.
+
+```{r print-model}
+two_week_ahead$epi_workflow
+```
+
+The fitted model here involved preprocessing the data to appropriately generate lagged predictors, estimating a linear model with `stats::lm()` and then postprocessing the results to be meaningful for epidemiological tasks. We can also examine the predictions.
+
+```{r show-preds}
+two_week_ahead$predictions
+```
+
+The results above show a distributional forecast produced using data through the end of 2021 for the 14th of January 2022. A prediction for the death rate per 100K inhabitants is available for every state (`geo_value`) along with a 90% predictive interval.
+
+<!--
 
-**Example:**  
 During a quiet period, a user decides they want to first predict whether a surge is about to occur, say using variant information from GISAID. Then for surging locations, they want to train an AR model using past surges in the same location. Everywhere else, they predict a flat line. We should be able to do this in a few lines of code.
 
 Delphi's own forecasts have been produced/evaluated in this way for a while now, but the code base is scattered and evolving. We want to consolidate, generalize, and simplify to allow others to benefit as well.
@@ -84,25 +127,11 @@ my_fcaster(lead(cases, 7) ~ ., epi_df, key_vars, time_vars)
 
 The hypothetical example of first classifying, then fitting different models would also fit into this framework. And this isn't far from our current production models.
 
-### Why doesn't this exist
 
-Closest neighbor is [`{fable}`](https://fable.tidyverts.org/). It does some of what we want but has a few major downsides:
 
-1. Small set of standard Time Series models.
-    * Small modifications are hard (e.g. can't "just use" `glmnet` instead of `lm`) in an AR model.
-1. Multi-period forecasting is model-based only.
-    * This is "iterative" forecasting, and is very bad in epidemiology.
-    * Much better with simple models to use "direct" forecasting.
-1. Confidence bands are model-based only.
-    * In epi tasks, these dramatically under-cover.
-1. Layering is not possible/natural
-1. Can't use methods that aren't already implemented.
-
-The forecasts we did above can't be produced with `{fable}`.
-
-
-**However:** The developers behind `{fable}` wrote a package called `{fabletools}` that powers model creation (based on `R6`). We can almost certainly borrow some of that technology to lever up.
 
 ### What this isn't
 
 This is not a framework for SIR models. We intend to create some simple versions, but advanced models---those that use variants, hospitalizations, different types of immunity, age stratification, etc.---cannot be compartmentalized in the same way (though see [pypm](https://pypm.github.io/home/)). These types of models also are better at scenario modeling than short term forecasts unless they are quite complicated.
+
+-->