Merge pull request #203 from reichlab/issue-68

rename plot_forecast() to plot_forecasts()

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: covidHubUtils
 Title: Utility functions for the COVID-19 forecast hub
-Version: 0.1.2
+Version: 0.1.5
 Authors@R: c(
     person(given = "Serena",
            family = "Wang",
@@ -53,7 +53,8 @@ Imports:
     readr,
     httr,
     stringr,
-    yaml
+    yaml,
+    lifecycle
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -17,6 +17,7 @@ export(load_latest_forecasts_repo)
 export(load_truth)
 export(pivot_forecasts_wider)
 export(plot_forecast)
+export(plot_forecasts)
 export(preprocess_hospitalization)
 export(preprocess_jhu)
 export(preprocess_nytimes)

NEWS.md

@@ -1,3 +1,11 @@
+## covidHubUtils 0.1.5
+
+This is a release for renaming `plot_forecast()` to `plot_forecasts()`. `plot_forecast()` is still available to use but will return deprecation warnings to the user.
+
+### Package updates
+- There is backwards compatibility.
+
+
 ## covidHubUtils 0.1.4
 
 This is a release focusing on updates that provide better interface with Zoltar and European COVID-19 Forecast Hub. The release also contains new feature updates and bug fixes in other util functions.

R/plot_forecast.R → R/plot_forecasts.R

@@ -53,28 +53,28 @@
 #' @return invisible ggplot object
 #' 
 #' @export
-plot_forecast <- function(forecast_data,
-                          truth_data = NULL, 
-                          models,
-                          target_variable,
-                          locations,
-                          facet = NULL,
-                          facet_scales = "fixed",
-                          facet_nrow = NULL,
-                          facet_ncol = NULL,
-                          forecast_dates,
-                          intervals,
-                          horizon,
-                          truth_source,
-                          use_median_as_point = FALSE,
-                          plot_truth = TRUE,
-                          plot = TRUE,
-                          fill_by_model = FALSE,
-                          fill_transparency = 1.0,
-                          truth_as_of = NULL, 
-                          title = "default", 
-                          subtitle = "default",
-                          show_caption = TRUE){
+plot_forecasts <- function(forecast_data,
+                           truth_data = NULL, 
+                           models,
+                           target_variable,
+                           locations,
+                           facet = NULL,
+                           facet_scales = "fixed",
+                           facet_nrow = NULL,
+                           facet_ncol = NULL,
+                           forecast_dates,
+                           intervals,
+                           horizon,
+                           truth_source,
+                           use_median_as_point = FALSE,
+                           plot_truth = TRUE,
+                           plot = TRUE,
+                           fill_by_model = FALSE,
+                           fill_transparency = 1.0,
+                           truth_as_of = NULL, 
+                           title = "default", 
+                           subtitle = "default",
+                           show_caption = TRUE){
 
   # title format
   if(is.na(title))
@@ -474,3 +474,63 @@ plot_forecast <- function(forecast_data,
 
   return (invisible(graph))
 }
+
+#' Plot forecasts and optional truth for only one selected target variable.
+#' Faceted plots for multiple models, locations and forecast dates are 
+#' supported with specified facet formula. 
+#' 
+#' \Sexpr[results=rd, stage=render]{lifecycle::badge("deprecated")}
+#' Please use [plot_forecasts()] instead.
+#' 
+#' @inheritParams plot_forecasts
+#' @importFrom grDevices dev.size
+#' @return invisible ggplot object
+#' 
+#' @export
+#'
+plot_forecast <- function(forecast_data,
+                           truth_data = NULL, 
+                           models,
+                           target_variable,
+                           locations,
+                           facet = NULL,
+                           facet_scales = "fixed",
+                           facet_nrow = NULL,
+                           facet_ncol = NULL,
+                           forecast_dates,
+                           intervals,
+                           horizon,
+                           truth_source,
+                           use_median_as_point = FALSE,
+                           plot_truth = TRUE,
+                           plot = TRUE,
+                           fill_by_model = FALSE,
+                           fill_transparency = 1.0,
+                           truth_as_of = NULL, 
+                           title = "default", 
+                           subtitle = "default",
+                           show_caption = TRUE){
+  lifecycle::deprecate_warn("0.1.5", "plot_forecast()", "plot_forecasts()")
+  plot_forecasts(forecast_data = forecast_data,
+                 truth_data = truth_data, 
+                 models = models,
+                 target_variable = target_variable,
+                 locations = locations,
+                 facet = facet,
+                 facet_scales = facet_scales,
+                 facet_nrow = facet_nrow,
+                 facet_ncol = facet_ncol,
+                 forecast_dates = forecast_dates,
+                 intervals = intervals,
+                 horizon = horizon,
+                 truth_source = truth_source,
+                 use_median_as_point = use_median_as_point,
+                 plot_truth = plot_truth,
+                 plot = plot,
+                 fill_by_model = fill_by_model,
+                 fill_transparency = fill_transparency,
+                 truth_as_of = truth_as_of, 
+                 title = title, 
+                 subtitle = subtitle,
+                 show_caption = show_caption)  
+}

README.md

@@ -29,7 +29,7 @@ For those starting out we recommend you begin with the [Getting Started vignette
 * `load_truth(truth_source, target_variable, truth_end_date, temporal_resolution, locations, data_location, local_repo_path, hub)`: Load truth data for specified target variable and locations from covid19-forecast-hub repository. **Note:** Only support national level and state level truth data for `"inc hosp"` from `"HealthData"` source.
 
 **Plotting Forecasts**
- * `plot_forecast(forecast_data, truth_data, models, target_variable, locations, facet, facet_scales, forecast_dates, intervals, horizon, truth_source, use_median_as_point, plot_truth, plot, fill_by_model, truth_as_of, title, subtitle, show_caption)`: Plot forecasts with optional truth data for multiple models, locations and forecast dates. To see more example plots, please to go [vignettes/demo](https://htmlpreview.github.io/?https://github.com/reichlab/covidHubUtils/blob/master/vignettes/demo.html).
+ * `plot_forecasts(forecast_data, truth_data, models, target_variable, locations, facet, facet_scales, forecast_dates, intervals, horizon, truth_source, use_median_as_point, plot_truth, plot, fill_by_model, truth_as_of, title, subtitle, show_caption)`: Plot forecasts with optional truth data for multiple models, locations and forecast dates. To see more example plots, please to go [vignettes/demo](https://htmlpreview.github.io/?https://github.com/reichlab/covidHubUtils/blob/master/vignettes/demo.html).
 
 **Scoring Forecasts**
  * `score_forecasts(forecasts, truth, desired_score_types = c(...), return_format = c("long", "wide"))` Calculate specified scores for each combination of `model`, `forecast_date`, `location`, `horizon`, `temporal_resolution`, `target_variable`, and `target_end_date` in the `forecasts` data frame. Please see [this reference](https://epiforecasts.io/scoringutils/reference/eval_forecasts.html#details) for valid scores in the `desired_score_types` vector.

vignettes/covidHubUtils-overview.Rmd

@@ -98,9 +98,9 @@ datatable(forecasts,
 ))
 ```
 
-This data can then be plotted directly with a call to `plot_forecast()`.
+This data can then be plotted directly with a call to `plot_forecasts()`.
 ```{r}
-p <- plot_forecast(forecast_data = forecasts, 
+p <- plot_forecasts(forecast_data = forecasts, 
   truth_source = "JHU",
   target_variable = "inc case",  
   intervals = c(.5, .8, .95))
@@ -115,7 +115,7 @@ p + scale_x_date(name=NULL, date_breaks = "1 month", date_labels = "%b") +
 ```
 
 
-Additionally, `plot_forecast()` can handle plotting multiple models or locations or forecast dates at the same time as the following examples show.
+Additionally, `plot_forecasts()` can handle plotting multiple models or locations or forecast dates at the same time as the following examples show.
 
 
 ## Plot multiple models
@@ -131,7 +131,7 @@ fdat <- load_latest_forecasts(models = c("Karlen-pypm", "UMass-MechBayes", "CU-s
   types = c("quantile", "point"), 
   targets = paste(1:4, "wk ahead inc death"))
 
-p <- plot_forecast(fdat, 
+p <- plot_forecasts(fdat, 
   target_variable = "inc death", 
   truth_source = "JHU",
   intervals = c(.5, .95), 
@@ -159,7 +159,7 @@ fdat <- load_latest_forecasts(models = c("Karlen-pypm", "UMass-MechBayes", "CU-s
   types = c("quantile", "point"), 
   targets = paste(1:4, "wk ahead inc death"))
 
-p <- plot_forecast(fdat, 
+p <- plot_forecasts(fdat, 
   target_variable = "inc death", 
   intervals = c(.5, .95), 
   truth_source = "JHU",
@@ -186,7 +186,7 @@ fdat <- load_forecasts(models = c("Karlen-pypm", "UMass-MechBayes"),
   types = c("quantile", "point"), 
   targets = paste(1:4, "wk ahead inc death"))
 
-p <- plot_forecast(fdat, 
+p <- plot_forecasts(fdat, 
   target_variable = "inc death", 
   truth_source = "JHU",
   intervals = c(.5, .95), 
@@ -201,18 +201,19 @@ p + scale_x_date(name=NULL, date_breaks = "1 months", date_labels = "%b") +
 
 # Working with truth data
 
-By default `plot_forecast()` uses JHU CSSE data as the "Observed Data" in the above plots. However, users can specify custom "ground truth" data that either they provide themselves or that is loaded in from the package. 
+By default `plot_forecasts()` uses JHU CSSE data as the "Observed Data" in the above plots. However, users can specify custom "ground truth" data that either they provide themselves or that is loaded in from the package. 
 
-Here is an example of a call to `plot_forecast()` that simply specifies an alternate truth source, which must be one of "JHU", "USAFacts", or "NYTimes".
+Here is an example of a call to `plot_forecasts()` that simply specifies an alternate truth source, which must be one of "JHU", "USAFacts", or "NYTimes".
 
 ```{r}
-plot_forecast (forecast_data = forecasts, 
+plot_forecasts(forecast_data = forecasts, 
   target_variable = "inc case",  
+  locations = "US",
   truth_source = "USAFacts",
   intervals = c(.5, .8, .95))
 ```
 
-Alternatively, truth data can be loaded in from one of those sources independently and stored in your active R session and passed to the `plot_forecast()` function.
+Alternatively, truth data can be loaded in from one of those sources independently and stored in your active R session and passed to the `plot_forecasts()` function.
 ```{r}
 truth_data <- load_truth(truth_source = "USAFacts",
   target_variable = "inc case",
@@ -231,9 +232,9 @@ datatable(truth_data,
 ))
 ```
 
-And can be used in conjunction with a call to plot_forecast
+And can be used in conjunction with a call to plot_forecasts
 ```{r}
-plot_forecast(forecast_data = forecasts, 
+plot_forecasts(forecast_data = forecasts, 
   target_variable = "inc case",  
   truth_data = truth_data,
   truth_source = "USAFacts",