diff --git a/NAMESPACE b/NAMESPACE index 0ba840341..c4e3a3ad2 100644 --- a/NAMESPACE +++ b/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) diff --git a/NEWS.md b/NEWS.md index 727c865ba..bfa62d240 100644 --- a/NEWS.md +++ b/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 diff --git a/R/avail_forecasts.R b/R/avail_forecasts.R index 046ca9b35..cef7f8605 100644 --- a/R/avail_forecasts.R +++ b/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[]) } diff --git a/R/plot.R b/R/plot.R index a9124f66c..52813d0f8 100644 --- a/R/plot.R +++ b/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 diff --git a/man/plot.scoringutils_available_forecasts.Rd b/man/plot.scoringutils_available_forecasts.Rd new file mode 100644 index 000000000..f11e0dc5d --- /dev/null +++ b/man/plot.scoringutils_available_forecasts.Rd @@ -0,0 +1,50 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/plot.R +\name{plot.scoringutils_available_forecasts} +\alias{plot.scoringutils_available_forecasts} +\title{Visualise Where Forecasts Are Available} +\usage{ +\method{plot}{scoringutils_available_forecasts}( + x, + yvar = "model", + xvar = "forecast_date", + make_xvar_factor = TRUE, + show_numbers = TRUE, + ... +) +} +\arguments{ +\item{x}{an S3 object of class "scoringutils_available_forecasts" +as produced by \code{\link[=available_forecasts]{available_forecasts()}}} + +\item{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".} + +\item{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".} + +\item{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.} + +\item{show_numbers}{logical (default is \code{TRUE}) that indicates whether +or not to show the actual count numbers on the plot} + +\item{...}{additional arguments (not used here)} +} +\value{ +ggplot object with a plot of interval coverage +} +\description{ +Visualise Where Forecasts Are Available +} +\examples{ +library(ggplot2) +available_forecasts <- available_forecasts( + example_quantile, by = c("model", "target_type", "target_end_date") +) +plot( + available_forecasts, xvar = "target_end_date", show_numbers = FALSE +) + + facet_wrap("target_type") +} diff --git a/man/plot_available_forecasts.Rd b/man/plot_avail_forecasts.Rd similarity index 57% rename from man/plot_available_forecasts.Rd rename to man/plot_avail_forecasts.Rd index 58a089a07..ce9580d1e 100644 --- a/man/plot_available_forecasts.Rd +++ b/man/plot_avail_forecasts.Rd @@ -1,18 +1,9 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/plot.R -\name{plot_available_forecasts} -\alias{plot_available_forecasts} +\name{plot_avail_forecasts} \alias{plot_avail_forecasts} -\title{Visualise Where Forecasts Are Available} +\title{Visualise Where Forecasts Are Available (deprecated)} \usage{ -plot_available_forecasts( - available_forecasts, - y = "model", - x = "forecast_date", - make_x_factor = TRUE, - show_numbers = TRUE -) - plot_avail_forecasts( available_forecasts, y = "model", @@ -22,7 +13,7 @@ plot_avail_forecasts( ) } \arguments{ -\item{available_forecasts}{data.frame with a column called \code{count} +\item{available_forecasts}{an S3 object of class "scoringutils_available_forecasts" as produced by \code{\link[=available_forecasts]{available_forecasts()}}} \item{y}{character vector of length one that denotes the name of the column @@ -38,19 +29,6 @@ are shown on the x-axis.} \item{show_numbers}{logical (default is \code{TRUE}) that indicates whether or not to show the actual count numbers on the plot} } -\value{ -ggplot object with a plot of interval coverage -} \description{ -Visualise Where Forecasts Are Available -} -\examples{ -library(ggplot2) -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 -) + - facet_wrap("target_type") +Old version of \code{\link[=plot.scoringutils_available_forecasts]{plot.scoringutils_available_forecasts()}} for compatibility. } diff --git a/tests/testthat/test-plot_avail_forecasts.R b/tests/testthat/test-plot_avail_forecasts.R index f326bd554..9f2efea6b 100644 --- a/tests/testthat/test-plot_avail_forecasts.R +++ b/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") diff --git a/vignettes/scoringutils.Rmd b/vignettes/scoringutils.Rmd index 1c7cd8b26..b4dd0bf16 100644 --- a/vignettes/scoringutils.Rmd +++ b/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) ```