Merge branch 'scoringutils-review' into intermediate-clean-up

NEWS.md

@@ -2,7 +2,7 @@
 
 This major update and addresses a variety of comments made by reviewers from the Journal of Statistical Software (see preprint of the manuscript [here](https://arxiv.org/abs/2205.07090)).
 
-The update introduces a lot of breaking changes. If you want to keep using the older version, you can download it using `remotes::install_github("epiforecasts/[email protected].0")`. 
+The update introduces breaking changes. If you want to keep using the older version, you can download it using `remotes::install_github("epiforecasts/[email protected]")`. 
 
 ## Package updates
 - In `score()`, required columns "true_value" and "prediction" were renamed and replaced by required columns "observed" and "predicted". Scoring functions now also use the function arguments "observed" and "predicted" everywhere consistently. 
@@ -30,6 +30,7 @@ The update introduces a lot of breaking changes. If you want to keep using the o
   - `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.
 - 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()`.
+- added documentation for the return value of `summarise_scores()`. 
 
 # scoringutils 1.2.1
 

R/correlations.R

@@ -7,6 +7,8 @@
 #' @param metrics A character vector with the metrics to show. If set to
 #' `NULL` (default), all metrics present in `scores` will
 #' be shown
+#' @param digits A number indicating how many decimal places the result should
+#' be rounded to. By default (`digits = NULL`) no rounding takes place.
 #' @inheritParams pairwise_comparison
 #' @return A data.table with correlations for the different metrics
 #' @importFrom data.table setDT
@@ -15,9 +17,11 @@
 #' @keywords scoring
 #' @examples
 #' scores <- score(example_quantile)
-#' correlation(scores)
+#' correlation(scores, digits = 2)
 correlation <- function(scores,
-                        metrics = NULL) {
+                        metrics = NULL,
+                        digits = NULL) {
+  metrics <- check_metrics(metrics)
 
   metrics <- get_metrics(scores)
 
@@ -41,7 +45,11 @@ correlation <- function(scores,
   df <- df[, .SD, .SDcols = names(df) %in% metrics]
 
   # define correlation matrix
-  cor_mat <- round(cor(as.matrix(df)), 2)
+  cor_mat <- cor(as.matrix(df))
+
+  if (!is.null(digits)) {
+    cor_mat <- round(cor_mat, digits)
+  }
 
   correlations <- setDT(as.data.frame((cor_mat)),
     keep.rownames = TRUE

R/plot.R

@@ -1065,7 +1065,8 @@ plot_avail_forecasts <- function(available_forecasts,
 #' @examples
 #' scores <- score(example_quantile)
 #' correlations <- correlation(
-#'  summarise_scores(scores)
+#'  summarise_scores(scores),
+#'  digits = 2
 #' )
 #' plot_correlation(correlations)
 

R/summarise_scores.R

@@ -24,6 +24,9 @@
 #' @param ... additional parameters that can be passed to the summary function
 #' provided to `fun`. For more information see the documentation of the
 #' respective function.
+#' @return a data.table with summarised scores. Scores are summarised according
+#' to the names of the columns of the original data specified in `by` or
+#' `across` using the `fun` passed to `summarise_scores()`.
 #' @examples
 #' data.table::setDTthreads(1) # only needed to avoid issues on CRAN
 #' library(magrittr) # pipe operator

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

@@ -654,7 +654,7 @@ p1 / p2 +
 correlations <- example_quantile |>
   score() |>
   summarise_scores() |>
-  correlation()
+  correlation(digits = 2)
 
 correlations |>
   glimpse()

inst/manuscript/manuscript.Rmd

@@ -637,7 +637,7 @@ It may sometimes be interesting to see how different scores correlate with each
 correlations <- example_quantile |>
   score() |>
   summarise_scores() |>
-  correlation() 
+  correlation(digits = 2) 
 
 correlations |>
   glimpse()

tests/testthat/test-plot_correlation.R

@@ -1,5 +1,5 @@
 test_that("plot_correlation() works as expected", {
-  correlations <- correlation(summarise_scores(scores_quantile))
+  correlations <- correlation(summarise_scores(scores), digits = 2)
   p <- plot_correlation(correlations)
   expect_s3_class(p, "ggplot")
   skip_on_cran()

vignettes/scoringutils.Rmd

@@ -373,7 +373,7 @@ Visualising correlations:
 example_quantile %>%
   score() %>%
   summarise_scores() %>%
-  correlation() %>%
+  correlation(digits = 2) %>%
   plot_correlation()
 ```