Plot s3 methods

NAMESPACE

@@ -1,6 +1,8 @@
 # Generated by roxygen2: do not edit by hand
 
 S3method(plot,scoringutils_available_forecasts)
+S3method(plot,scoringutils_correlation)
+S3method(plot,scoringutils_pairwise)
 S3method(print,scoringutils_check)
 export(abs_error)
 export(add_coverage)

NEWS.md

@@ -3,11 +3,18 @@
 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
-- changes to `avail_forecasts()` and `plot_avail_forecasts()`:
-  - 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, but will be removed in the future. 
-  - 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. 
+
+### changes to `avail_forecasts()` and `plot_avail_forecasts()`:
+- 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, but will be removed in the future. 
+- 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. 
+
+### New S3 plotting methods
+- `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. 
+- `plot_correlation()` has been deprecated in favour of an S3 method for `plot()`. An alias is still available, but will be removed in the future. 
+- `plot_pairwise_comparison()` has been deprecated in favour of an S3 method for `plot()`. An alias is still available, but will be removed in the future. 
+
+### other
 - the deprecated `..density..` was replaced with `after_stat(density)` in ggplot calls.
 - files ending in ".Rda" were renamed to ".rds" where appropriate when used together with `saveRDS()` or readRDS()`. 
 

R/avail_forecasts.R

@@ -20,11 +20,14 @@
 #' that a single forecast only gets counted once.
 #'
 #' @return A data.table with columns as specified in `by` and an additional
-#' column "count" with the number of forecasts.
+#' column "count" with the number of forecasts. In addition the output has class
+#' `scoringutils_available_forecasts` and can e.g. be visualised
+#' using [plot()] (which dispatches [plot.scoringutils_available_forecasts()].
 #'
 #' @inheritParams score
 #' @importFrom data.table .I .N nafill
 #' @export
+#' @seealso [plot.scoringutils_available_forecasts()]
 #' @keywords check-forecasts
 #' @examples
 #' data.table::setDTthreads(1) # only needed to avoid issues on CRAN

R/correlations.R

@@ -2,20 +2,25 @@
 #'
 #' @description
 #' Calculate the correlation between different metrics for a data.frame of
-#' scores as produced by [score()].
+#' scores as produced by [score()]. You can visualise results
 #'
 #' @param metrics A character vector with the metrics to show. If set to
 #' `NULL` (default), all metrics present in `scores` will
 #' be shown
 #' @inheritParams pairwise_comparison
-#' @return A data.table with correlations for the different metrics
+#' @return A data.table with correlations for the different metrics. In addition,
+#' the output is of class `scoringutils_correlation` and can e.g. be visualised
+#' using [plot()] (which dispatches [plot.scoringutils_correlation()].
+#'
 #' @importFrom data.table setDT
 #' @importFrom stats cor na.omit
 #' @export
 #' @keywords scoring
+#' @seealso [plot.scoringutils_correlation()]
 #' @examples
 #' scores <- score(example_quantile)
-#' correlation(scores)
+#' corrs <- correlation(scores)
+#' plot(corrs)
 correlation <- function(scores,
                         metrics = NULL) {
   metrics <- check_metrics(metrics)
@@ -49,6 +54,8 @@ correlation <- function(scores,
     keep.rownames = TRUE
   )[, metric := rn][, rn := NULL]
 
+  class(correlations) <- c("scoringutils_correlation", class(correlations))
+
   return(correlations[])
 }
 

R/pairwise-comparisons.R

@@ -43,22 +43,25 @@
 #' model against which to compare other models.
 #' @param ... additional arguments for the comparison between two models. See
 #' [compare_two_models()] for more information.
-#' @return A ggplot2 object with a coloured table of summarised scores
+#' @return A data.table with pairwise comparisons. In addition, the output is
+#' of class `scoringutils_pairwise` and can be visualised using [plot()] (which
+#' dispatches [plot.scoringutils_pairwise()].
 #' @importFrom data.table as.data.table data.table setnames copy
 #' @importFrom stats sd rbinom wilcox.test p.adjust
 #' @importFrom utils combn
 #' @export
 #' @author Nikos Bosse \email{nikosbosse@@gmail.com}
 #' @author Johannes Bracher, \email{johannes.bracher@@kit.edu}
 #' @keywords scoring
+#' @seealso [plot.scoringutils_pairwise()]
 #' @examples
 #' data.table::setDTthreads(1) # only needed to avoid issues on CRAN
 #'
 #' scores <- score(example_quantile)
 #' pairwise <- pairwise_comparison(scores, by = "target_type")
 #'
 #' library(ggplot2)
-#' plot_pairwise_comparison(pairwise, type = "mean_scores_ratio") +
+#' plot(pairwise, type = "mean_scores_ratio") +
 #'   facet_wrap(~target_type)
 
 pairwise_comparison <- function(scores,
@@ -139,6 +142,8 @@ pairwise_comparison <- function(scores,
 
   out <- data.table::rbindlist(results)
 
+  class(out) <- c("scoringutils_pairwise", class(out))
+
   return(out[])
 }
 

R/plot.R

@@ -19,6 +19,7 @@
 #' @importFrom ggplot2 ggplot aes element_blank element_text labs coord_cartesian coord_flip
 #' @importFrom data.table setDT melt
 #' @importFrom stats sd
+#' @family plotting functions
 #' @export
 #'
 #' @examples
@@ -148,6 +149,7 @@ plot_score_table <- function(scores,
 #' scale_fill_discrete
 #' theme theme_light unit guides guide_legend .data
 #' @export
+#' @family plotting functions
 #' @examples
 #' library(ggplot2)
 #' scores <- score(example_quantile)
@@ -233,6 +235,7 @@ plot_wis <- function(scores,
 #' @importFrom ggplot2 ggplot aes aes geom_point geom_line
 #' expand_limits theme theme_light element_text scale_color_continuous labs
 #' @export
+#' @family plotting functions
 #' @examples
 #' library(ggplot2)
 #' scores <- score(example_quantile)
@@ -296,6 +299,7 @@ plot_ranges <- function(scores,
 #' @importFrom ggplot2 ggplot  aes geom_tile geom_text .data
 #' scale_fill_gradient2 labs element_text coord_cartesian
 #' @export
+#' @family plotting functions
 #' @examples
 #' scores <- score(example_quantile)
 #' scores <- summarise_scores(scores, by = c("model", "target_type", "range"))
@@ -352,6 +356,7 @@ plot_heatmap <- function(scores,
 #' @importFrom data.table dcast
 #' @importFrom ggdist geom_lineribbon
 #' @export
+#' @family plotting functions
 #' @examples
 #' library(ggplot2)
 #' library(magrittr)
@@ -581,6 +586,7 @@ make_na <- make_NA
 #' facet_wrap facet_grid geom_polygon
 #' @importFrom data.table dcast
 #' @export
+#' @family plotting functions
 #' @examples
 #' data.table::setDTthreads(1) # only needed to avoid issues on CRAN
 #' scores <- score(example_quantile)
@@ -637,6 +643,7 @@ plot_interval_coverage <- function(scores,
 #' scale_y_continuous
 #' @importFrom data.table dcast
 #' @export
+#' @family plotting functions
 #' @examples
 #' scores <- score(example_quantile)
 #' scores <- summarise_scores(scores, by = c("model", "quantile"))
@@ -687,35 +694,41 @@ plot_quantile_coverage <- function(scores,
   return(p2)
 }
 
+
 #' @title Plot Heatmap of Pairwise Comparisons
 #'
 #' @description
 #' Creates a heatmap of the ratios or pvalues from a pairwise comparison
 #' between models
 #'
-#' @param comparison_result A data.frame as produced by
+#' @param x An S3 object as produced by
 #' [pairwise_comparison()]
 #' @param type character vector of length one that is either
 #'  "mean_scores_ratio" or "pval". This denotes whether to
 #' visualise the ratio or the p-value of the pairwise comparison.
 #' Default is "mean_scores_ratio".
+#' @inheritParams print.scoringutils_check
+#' @return A data.table with pairwise comparisons. In addition, the output is
+#' of class `scoringutils_pairwise` and can be visualised using [plot()].
 #' @importFrom ggplot2 ggplot aes geom_tile geom_text labs coord_cartesian
 #' scale_fill_gradient2 theme_light element_text
 #' @importFrom data.table as.data.table setnames rbindlist
 #' @importFrom stats reorder
 #' @importFrom ggplot2 labs coord_cartesian facet_wrap facet_grid theme
 #' element_text element_blank
 #' @export
+#' @family plotting functions
 #' @examples
 #' library(ggplot2)
 #' scores <- score(example_quantile)
 #' pairwise <- pairwise_comparison(scores, by = "target_type")
-#' plot_pairwise_comparison(pairwise, type = "mean_scores_ratio") +
+#' plot(pairwise, type = "mean_scores_ratio") +
 #'   facet_wrap(~target_type)
 
-plot_pairwise_comparison <- function(comparison_result,
-                                     type = c("mean_scores_ratio", "pval")) {
-  comparison_result <- data.table::as.data.table(comparison_result)
+plot.scoringutils_pairwise <- function(x,
+                                       type = c("mean_scores_ratio", "pval"),
+                                       ...) {
+  comparison_result <- data.table::as.data.table(x)
 
   comparison_result[, model := reorder(model, -relative_skill)]
   levels <- levels(comparison_result$model)
@@ -810,6 +823,28 @@ plot_pairwise_comparison <- function(comparison_result,
 }
 
 
+#' @title `r lifecycle::badge("deprecated")` Plot Heatmap of Pairwise Comparisons
+#'
+#' @description
+#' Deprecated version of [plot.scoringutils_pairwise()]
+#'
+#' @param comparison_result A data.frame as produced by
+#' [pairwise_comparison()]
+#' @inherit plot.scoringutils_pairwise
+#' @export
+plot_pairwise_comparison <- function(comparison_result,
+                                     type = c("mean_scores_ratio", "pval")) {
+
+  lifecycle::deprecate_warn(
+    "1.2.2", "plot_pairwise_comparison()",
+    "plot()"
+  )
+
+  plot.scoringutils_pairwise(x = comparison_result,
+                             type = type)
+}
+
+
 #' @title PIT Histogram
 #'
 #' @description
@@ -833,6 +868,7 @@ plot_pairwise_comparison <- function(comparison_result,
 #' @importFrom stats as.formula
 #' @importFrom ggplot2 geom_col
 #' @importFrom stats density
+#' @family plotting functions
 #' @return vector with the scoring values
 #' @examples
 #' data.table::setDTthreads(1) # only needed to avoid issues on CRAN
@@ -937,6 +973,7 @@ plot_pit <- function(pit,
   return(hist)
 }
 
+
 #' @title Visualise Where Forecasts Are Available
 #'
 #' @description
@@ -958,6 +995,7 @@ plot_pit <- function(pit,
 #' geom_tile scale_fill_gradient .data
 #' @importFrom data.table dcast .I .N
 #' @export
+#' @family plotting functions
 #' @examples
 #' library(ggplot2)
 #' available_forecasts <- available_forecasts(
@@ -1047,33 +1085,32 @@ plot_avail_forecasts <- function(available_forecasts,
 }
 
 
-
-
 #' @title Plot Correlation Between Metrics
-#'
 #' @description
 #' Plots a heatmap of correlations between different metrics
 #'
-#' @param correlations A data.table of correlations between scores as produced
-#' by [correlation()].
+#' @param x An S3 object with correlations between scores as produced by
+#' [correlation()].
+#' @inheritParams print.scoringutils_check
 #' @return A ggplot2 object showing a coloured matrix of correlations
 #' between metrics
 #' @importFrom ggplot2 ggplot geom_tile geom_text aes scale_fill_gradient2
 #' element_text labs coord_cartesian theme element_blank
 #' @importFrom data.table setDT melt
 #' @export
+#' @family plotting functions
 #' @examples
 #' scores <- score(example_quantile)
 #' correlations <- correlation(
 #'  summarise_scores(scores)
 #' )
-#' plot_correlation(correlations)
+#' plot(correlations)
 
-plot_correlation <- function(correlations) {
+plot.scoringutils_correlation <- function(x, ...) {
 
-  metrics <- names(correlations)[names(correlations) %in% available_metrics()]
+  metrics <- names(x)[names(x) %in% available_metrics()]
 
-  lower_triangle <- get_lower_tri(correlations[, .SD, .SDcols = metrics])
+  lower_triangle <- get_lower_tri(x[, .SD, .SDcols = metrics])
   rownames(lower_triangle) <- colnames(lower_triangle)
 
   # get plot data.frame
@@ -1111,6 +1148,23 @@ plot_correlation <- function(correlations) {
   return(plot)
 }
 
+
+#' @title `r lifecycle::badge("deprecated")` Plot Correlation Between Metrics
+#'
+#' @description
+#' Deprecated version of [plot.scoringutils_correlation()] for compatibility.
+#' @param correlations A data.table with correalations as produced by
+#' [correlation()]
+#' @export
+plot_correlation <- function(correlations) {
+  lifecycle::deprecate_warn(
+    "1.2.2", "plot_correlation()",
+    "plot()"
+  )
+  plot.scoringutils_correlation(x = correlations)
+}
+
+
 #' @title Scoringutils ggplot2 theme
 #'
 #' @description

inst/manuscript/R/00-standalone-Figure-replication.R

@@ -660,4 +660,4 @@ correlations |>
   glimpse()
 
 correlations |>
-  plot_correlation()
+  plot()

inst/manuscript/manuscript.Rmd

@@ -527,7 +527,7 @@ Using the function \fct{plot\_pairwise\_comparison} we can visualise the mean sc
 score(example_quantile) |>
   pairwise_comparison(by = c("model", "target_type"), 
                       baseline = "EuroCOVIDhub-baseline") |>
-  plot_pairwise_comparison() + 
+  plot() + 
   facet_wrap(~ target_type)
 ```
 
@@ -642,8 +642,7 @@ correlations <- example_quantile |>
 correlations |>
   glimpse()
 
-correlations |>
-  plot_correlation()
+plot(correlations)
 ```
 
 ## Summary and discussion