Add documentation and make rounding for correlation() explicit

NEWS.md

@@ -8,8 +8,10 @@ This minor update addresses comments made by review from the Journal of Statisti
   - 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. 
+- remove hard-coded rounding value for `correlation()`. Previously, the function always rounded correlations to two digits. Instead, a new argument, `digits` was introduced and the default set to 0, meaning that no rounding takes place. 
 - 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()`. 
+- add 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,10 @@
 #' @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)
 
   # check metrics are present
@@ -43,7 +46,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

@@ -41,6 +41,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))
+  correlations <- correlation(summarise_scores(scores), digits = 2)
   p <- plot_correlation(correlations)
   expect_s3_class(p, "ggplot")
   skip_on_cran()

vignettes/scoringutils.Rmd

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