Merge pull request #725 from epiforecasts/rename-correlation

Issue #638 - Rename `correlation()` to `get_correlations()`

NAMESPACE

@@ -30,10 +30,10 @@ export(as_forecast)
 export(bias_quantile)
 export(bias_sample)
 export(brier_score)
-export(correlation)
 export(crps_sample)
 export(dispersion)
 export(dss_sample)
+export(get_correlations)
 export(get_coverage)
 export(get_duplicate_forecasts)
 export(get_forecast_counts)
@@ -57,7 +57,7 @@ export(new_forecast)
 export(overprediction)
 export(pairwise_comparison)
 export(pit_sample)
-export(plot_correlation)
+export(plot_correlations)
 export(plot_forecast_counts)
 export(plot_heatmap)
 export(plot_interval_coverage)

NEWS.md

@@ -54,6 +54,7 @@ The update introduces breaking changes. If you want to keep using the older vers
 - Removed the function `plot_predictions()`, as well as its helper function `make_NA()`, in favour of a dedicated Vignette that shows different ways of visualising predictions. For future reference, the function code can be found [here](https://github.com/epiforecasts/scoringutils/issues/659) (Issue #659).
 - Added a first versino of a dedicated Vignette that displays some possible ways of visualising forecasts. 
 - Replaced warnings with errors in `pairwise_comparison` to avoid returning `NULL`
+- Renamed `correlation()` to `get_correlations()` and `plot_correlation()` to `plot_correlations()`
 - `pit()` was renamed to `get_pit()`
 
 # scoringutils 1.2.2

R/correlations.R

@@ -20,10 +20,10 @@
 #' @keywords scoring
 #' @examples
 #' scores <- score(as_forecast(example_quantile))
-#' correlation(scores, digits = 2)
-correlation <- function(scores,
-                        metrics = NULL,
-                        digits = NULL) {
+#' get_correlations(scores, digits = 2)
+get_correlations <- function(scores,
+                             metrics = NULL,
+                             digits = NULL) {
   metrics <- get_metrics(scores, error = TRUE)
 
   # remove all non metrics and non-numeric columns

R/plot.R

@@ -734,7 +734,7 @@ plot_forecast_counts <- function(forecast_counts,
 #' Plots a heatmap of correlations between different metrics
 #'
 #' @param correlations A data.table of correlations between scores as produced
-#' by [correlation()].
+#' by [get_correlations()].
 #' @return A ggplot object showing a coloured matrix of correlations
 #' between metrics
 #' @importFrom ggplot2 ggplot geom_tile geom_text aes scale_fill_gradient2
@@ -744,13 +744,13 @@ plot_forecast_counts <- function(forecast_counts,
 #' @return A ggplot object with a visualisation of correlations between metrics
 #' @examples
 #' scores <- score(as_forecast(example_quantile))
-#' correlations <- correlation(
+#' correlations <- get_correlations(
 #'  summarise_scores(scores),
 #'  digits = 2
 #' )
-#' plot_correlation(correlations)
+#' plot_correlations(correlations)
 
-plot_correlation <- function(correlations) {
+plot_correlations <- function(correlations) {
 
   metrics <- get_metrics(correlations, error = TRUE)
 

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

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

tests/testthat/test-plot_correlation.R

@@ -1,12 +1,12 @@
-test_that("plot_correlation() works as expected", {
-  correlations <- correlation(
+test_that("plot_correlations() works as expected", {
+  correlations <- get_correlations(
     summarise_scores(
       scores_quantile,
       by = get_forecast_unit(scores_quantile)
     ),
     digits = 2
   )
-  p <- plot_correlation(correlations)
+  p <- plot_correlations(correlations)
   expect_s3_class(p, "ggplot")
   skip_on_cran()
   vdiffr::expect_doppelganger("plot__correlation", p)

vignettes/scoringutils.Rmd

@@ -313,13 +313,13 @@ forecast_quantile %>%
 
 ### Correlation between scores
 
-It may sometimes be interesting to see how different scores correlate with each other. We can examine this using the function `correlation()`. When dealing with quantile-based forecasts, it is important to call `summarise_scorees()` before `correlation()` to summarise over quantiles before computing correlations.
+It may sometimes be interesting to see how different scores correlate with each other. We can examine this using the function `correlation()`. When dealing with quantile-based forecasts, it is important to call `summarise_scorees()` before `get_correlations()` to summarise over quantiles before computing correlations.
 
 ```{r}
 forecast_quantile %>%
   score() %>%
   summarise_scores() %>%
-  correlation()
+  get_correlations()
 ```
 
 Visualising correlations: 
@@ -328,8 +328,8 @@ Visualising correlations:
 forecast_quantile %>%
   score() %>%
   summarise_scores() %>%
-  correlation(digits = 2) %>%
-  plot_correlation()
+  get_correlations(digits = 2) %>%
+  plot_correlations()
 ```