Merge pull request #322 from epiforecasts/s3_plot_avail_forecasts

Create an S3 method for plot_avail_forecasts

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(plot,scoringutils_available_forecasts)
 S3method(print,scoringutils_check)
 export(abs_error)
 export(add_coverage)
@@ -29,7 +30,6 @@ export(pairwise_comparison)
 export(pit)
 export(pit_sample)
 export(plot_avail_forecasts)
-export(plot_available_forecasts)
 export(plot_correlation)
 export(plot_heatmap)
 export(plot_interval_coverage)

NEWS.md

@@ -3,9 +3,10 @@
 This minor update addresses comments made by review from the Journal of Statistical Software (see preprint of the manuscript [here](https://arxiv.org/abs/2205.07090)).
 
 ## Package updates
-- the function `avail_forecasts()` was renamed to `available_forecasts()` for consistency with `available_metrics()`. Similarly, `plot_avail_forecasts()` was renamed to `plot_available_forecasts()`. The old functions, `avail_forecasts()` and `plot_avail_forecasts()` are still available as aliases.
+- the function `avail_forecasts()` was renamed to `available_forecasts()` for consistency with `available_metrics()`. The old function, `avail_forecasts()` is still available as an alias.
 - For clarity, the output column in `avail_forecasts()` was renamed from "Number forecasts" to "count". 
 - `available_forecasts()` now also displays combinations where there are 0 forecasts, instead of silently dropping corresponding rows. 
+- `plot_avail_forecasts()` has been deprecated in favour of an S3 method for `plot()`. An alias is still available, but will be removed in the future. 
 
 # scoringutils 1.2.1
 

R/avail_forecasts.R

@@ -70,6 +70,8 @@ available_forecasts <- function(data,
   out <- merge(out, out_empty, by = by, all.y = TRUE)
   out[, count := nafill(count, fill = 0)]
 
+  class(out) <- c("scoringutils_available_forecasts", class(out))
+
   return(out[])
 }
 

R/plot.R

@@ -941,14 +941,14 @@ plot_pit <- function(pit,
 #'
 #' @description
 #' Visualise Where Forecasts Are Available
-#'
-#' @param available_forecasts data.frame with a column called `count`
+#' @inheritParams print.scoringutils_check
+#' @param x an S3 object of class "scoringutils_available_forecasts"
 #' as produced by [available_forecasts()]
-#' @param y character vector of length one that denotes the name of the column
+#' @param yvar character vector of length one that denotes the name of the column
 #' to appear on the y-axis of the plot. Default is "model".
-#' @param x character vector of length one that denotes the name of the column
+#' @param xvar character vector of length one that denotes the name of the column
 #' to appear on the x-axis of the plot. Default is "forecast_date".
-#' @param make_x_factor logical (default is TRUE). Whether or not to convert
+#' @param make_xvar_factor logical (default is TRUE). Whether or not to convert
 #' the variable on the x-axis to a factor. This has an effect e.g. if dates
 #' are shown on the x-axis.
 #' @param show_numbers logical (default is `TRUE`) that indicates whether
@@ -963,27 +963,28 @@ plot_pit <- function(pit,
 #' available_forecasts <- available_forecasts(
 #'   example_quantile, by = c("model", "target_type", "target_end_date")
 #' )
-#' plot_available_forecasts(
-#'  available_forecasts, x = "target_end_date", show_numbers = FALSE
+#' plot(
+#'  available_forecasts, xvar = "target_end_date", show_numbers = FALSE
 #' ) +
 #'  facet_wrap("target_type")
 
-plot_available_forecasts <- function(available_forecasts,
-                                 y = "model",
-                                 x = "forecast_date",
-                                 make_x_factor = TRUE,
-                                 show_numbers = TRUE) {
-  available_forecasts <- as.data.table(available_forecasts)
+plot.scoringutils_available_forecasts <- function(x,
+                                                  yvar = "model",
+                                                  xvar = "forecast_date",
+                                                  make_xvar_factor = TRUE,
+                                                  show_numbers = TRUE,
+                                                  ...) {
+  x <- as.data.table(x)
 
-  if (make_x_factor) {
-    available_forecasts[, eval(x) := as.factor(get(x))]
+  if (make_xvar_factor) {
+    x[, eval(xvar) := as.factor(get(xvar))]
   }
 
-  setnames(available_forecasts, old = "count", new = "Count")
+  setnames(x, old = "count", new = "Count")
 
   plot <- ggplot(
-    available_forecasts,
-    aes(y = .data[[y]], x = .data[[x]])
+    x,
+    aes(y = .data[[yvar]], x = .data[[xvar]])
   ) +
     geom_tile(aes(fill = `Count`),
       width = 0.97, height = 0.97
@@ -1010,9 +1011,42 @@ plot_available_forecasts <- function(available_forecasts,
 }
 
 
-#' @rdname plot_available_forecasts
+#' @title Visualise Where Forecasts Are Available (deprecated)
+#'
+#' @description
+#' Old version of [plot.scoringutils_available_forecasts()] for compatibility.
+#' @inheritParams plot.scoringutils_available_forecasts
+#' @param available_forecasts an S3 object of class "scoringutils_available_forecasts"
+#' as produced by [available_forecasts()]
+#' @param y character vector of length one that denotes the name of the column
+#' to appear on the y-axis of the plot. Default is "model".
+#' @param x character vector of length one that denotes the name of the column
+#' to appear on the x-axis of the plot. Default is "forecast_date".
+#' @param make_x_factor logical (default is TRUE). Whether or not to convert
+#' the variable on the x-axis to a factor. This has an effect e.g. if dates
+#' are shown on the x-axis.
 #' @export
-plot_avail_forecasts <- plot_available_forecasts
+plot_avail_forecasts <- function(available_forecasts,
+                                 y = "model",
+                                 x = "forecast_date",
+                                 make_x_factor = TRUE,
+                                 show_numbers = TRUE) {
+
+  lifecycle::deprecate_warn(
+    "1.2.2", "plot_avail_forecasts()",
+    "plot()"
+  )
+
+  plot.scoringutils_available_forecasts(
+    x = available_forecasts,
+    yvar = y,
+    xvar = x,
+    make_xvar_factor = make_x_factor,
+    show_numbers = show_numbers
+  )
+}
+
+
 
 
 #' @title Plot Correlation Between Metrics

tests/testthat/test-plot_avail_forecasts.R

@@ -4,8 +4,8 @@ test_that("plot_available_forecasts() works as expected", {
       by = c("model", "target_type", "target_end_date")
     )
   )
-  p <- plot_available_forecasts(available_forecasts,
-    x = "target_end_date", show_numbers = FALSE
+  p <- plot(available_forecasts,
+    xvar = "target_end_date", show_numbers = FALSE
   ) +
     facet_wrap("target_type")
   expect_s3_class(p, "ggplot")

vignettes/scoringutils.Rmd

@@ -87,12 +87,12 @@ available_forecasts(example_quantile, by = c("model", "target_type"))
 
 We see that 'epiforecasts-EpiNow2' has some missing forecasts for the deaths forecast target and that UMass-MechBayes has no case forecasts. 
 
-This information can also be visualised using the `plot_available_forecasts()` function: 
+This information can also be visualised using `plot()`: 
 
 ```{r, fig.width=11, fig.height=6}
 example_quantile %>%
   available_forecasts(by = c("model", "forecast_date", "target_type")) %>%
-  plot_available_forecasts() +
+  plot() +
   facet_wrap(~ target_type)
 ```