Issue #530 - Clarify workflow in examples (#877)

R/convenience-functions.R

@@ -206,14 +206,13 @@ transform_forecasts <- function(forecast,
 #' @keywords check-forecasts
 #' @importFrom checkmate assert_numeric assert_number
 #' @examples
+#' library(magrittr) # pipe operator
 #' log_shift(1:10)
 #' log_shift(0:9, offset = 1)
 #'
-#' transform_forecasts(
-#'   as_forecast_quantile(example_quantile)[observed > 0, ],
-#'   fun = log_shift,
-#'   offset = 1
-#'  )
+#' example_quantile[observed > 0, ] %>%
+#'   as_forecast_quantile() %>%
+#'   transform_forecasts(fun = log_shift, offset = 1)
 
 log_shift <- function(x, offset = 0, base = exp(1)) {
 
@@ -270,10 +269,11 @@ log_shift <- function(x, offset = 0, base = exp(1)) {
 #' @export
 #' @keywords data-handling
 #' @examples
-#' set_forecast_unit(
-#'   example_quantile,
-#'   c("location", "target_end_date", "target_type", "horizon", "model")
-#' )
+#' library(magrittr) # pipe operator
+#' example_quantile %>%
+#'   set_forecast_unit(
+#'     c("location", "target_end_date", "target_type", "horizon", "model")
+#'   )
 set_forecast_unit <- function(data, forecast_unit) {
   data <- ensure_data.table(data)
   assert_subset(forecast_unit, names(data), empty.ok = FALSE)

R/correlations.R

@@ -19,7 +19,12 @@
 #' @export
 #' @keywords scoring
 #' @examples
-#' scores <- score(as_forecast_quantile(example_quantile))
+#' library(magrittr) # pipe operator
+#'
+#' scores <- example_quantile %>%
+#'  as_forecast_quantile() %>%
+#'  score()
+#'
 #' get_correlations(scores)
 get_correlations <- function(scores,
                              metrics = get_metrics(scores),
@@ -40,9 +45,3 @@ get_correlations <- function(scores,
 
   return(correlations[])
 }
-
-# helper function to obtain lower triangle of matrix
-get_lower_tri <- function(cormat) {
-  cormat[lower.tri(cormat)] <- NA
-  return(cormat)
-}

R/default-scoring-rules.R

@@ -78,12 +78,12 @@ select_metrics <- function(metrics, select = NULL, exclude = NULL) {
 #'   metrics_quantile(),
 #'   "interval_coverage_70" = interval_coverage_70
 #' )
-#' score(
-#'   as_forecast_quantile(example_quantile),
-#'   metrics = updated_metrics
-#' )
 #'
+#' library(magrittr) # pipe operator
 #'
+#' example_quantile %>%
+#'   as_forecast_quantile() %>%
+#'   score(metrics = updated_metrics)
 customise_metric <- function(metric, ...) {
   assert_function(metric)
   dots <- list(...)

R/get_-functions.R

@@ -470,10 +470,10 @@ get_coverage <- function(forecast, by = "model") {
 #'   data.table::setDTthreads(2) # restricts number of cores used on CRAN
 #' }
 #'
-#' get_forecast_counts(
-#'   as_forecast_quantile(example_quantile),
-#'   by = c("model", "target_type")
-#' )
+#' library(magrittr) # pipe operator
+#' example_quantile %>%
+#'   as_forecast_quantile() %>%
+#'   get_forecast_counts(by = c("model", "target_type"))
 get_forecast_counts <- function(forecast,
                                 by = get_forecast_unit(forecast),
                                 collapse = c("quantile_level", "sample_id")) {

R/pairwise-comparisons.R

@@ -96,7 +96,12 @@
 #'   data.table::setDTthreads(2) # restricts number of cores used on CRAN
 #' }
 #'
-#' scores <- score(as_forecast_quantile(example_quantile))
+#' library(magrittr) # pipe operator
+#'
+#' scores <- example_quantile %>%
+#'  as_forecast_quantile() %>%
+#'  score()
+#'
 #' pairwise <- get_pairwise_comparisons(scores, by = "target_type")
 #' pairwise2 <- get_pairwise_comparisons(
 #'   scores, by = "target_type", baseline = "EuroCOVIDhub-baseline"

R/plot.R

@@ -24,7 +24,10 @@
 #' @export
 #' @examples
 #' library(ggplot2)
-#' scores <- score(as_forecast_quantile(example_quantile))
+#' library(magrittr) # pipe operator
+#' scores <- example_quantile %>%
+#'   as_forecast_quantile %>%
+#'   score()
 #' scores <- summarise_scores(scores, by = c("model", "target_type"))
 #'
 #' plot_wis(scores,
@@ -111,7 +114,10 @@ plot_wis <- function(scores,
 #' @importFrom checkmate assert_subset
 #' @export
 #' @examples
-#' scores <- score(as_forecast_quantile(example_quantile))
+#' library(magrittr) # pipe operator
+#' scores <- example_quantile %>%
+#'   as_forecast_quantile %>%
+#'   score()
 #' scores <- summarise_scores(scores, by = c("model", "target_type"))
 #' scores <- summarise_scores(
 #'   scores, by = c("model", "target_type"),
@@ -309,7 +315,10 @@ plot_quantile_coverage <- function(coverage,
 #' @export
 #' @examples
 #' library(ggplot2)
-#' scores <- score(as_forecast_quantile(example_quantile))
+#' library(magrittr) # pipe operator
+#' scores <- example_quantile %>%
+#'   as_forecast_quantile %>%
+#'   score()
 #' pairwise <- get_pairwise_comparisons(scores, by = "target_type")
 #' plot_pairwise_comparisons(pairwise, type = "mean_scores_ratio") +
 #'   facet_wrap(~target_type)
@@ -444,6 +453,7 @@ plot_pairwise_comparisons <- function(comparison_result,
 #' \dontshow{
 #'   data.table::setDTthreads(2) # restricts number of cores used on CRAN
 #' }
+#' library(magrittr) # pipe operator
 #'
 #' # PIT histogram in vector based format
 #' observed <- rnorm(30, mean = 1:30)
@@ -452,11 +462,15 @@ plot_pairwise_comparisons <- function(comparison_result,
 #' plot_pit(pit)
 #'
 #' # quantile-based pit
-#' pit <- get_pit(as_forecast_quantile(example_quantile), by = "model")
+#' pit <- example_quantile %>%
+#'   as_forecast_quantile() %>%
+#'   get_pit(by = "model")
 #' plot_pit(pit, breaks = seq(0.1, 1, 0.1))
 #'
 #' # sample-based pit
-#' pit <- get_pit(as_forecast_sample(example_sample_discrete), by = "model")
+#' pit <- example_sample_discrete %>%
+#'   as_forecast_sample %>%
+#'   get_pit(by = "model")
 #' plot_pit(pit)
 #' @importFrom ggplot2 ggplot aes xlab ylab geom_histogram stat theme_light after_stat
 #' @importFrom checkmate assert check_set_equal check_number
@@ -576,10 +590,10 @@ plot_pit <- function(pit,
 #' @export
 #' @examples
 #' library(ggplot2)
-#' forecast_counts <- get_forecast_counts(
-#'   as_forecast_quantile(example_quantile),
-#'   by = c("model", "target_type", "target_end_date")
-#' )
+#' library(magrittr) # pipe operator
+#' forecast_counts <- example_quantile %>%
+#'   as_forecast_quantile %>%
+#'   get_forecast_counts(by = c("model", "target_type", "target_end_date"))
 #' plot_forecast_counts(
 #'  forecast_counts, x = "target_end_date", show_counts = FALSE
 #' ) +
@@ -647,10 +661,13 @@ plot_forecast_counts <- function(forecast_counts,
 #' @export
 #' @return A ggplot object with a visualisation of correlations between metrics
 #' @examples
-#' scores <- score(as_forecast_quantile(example_quantile))
-#' correlations <- get_correlations(
-#'  summarise_scores(scores)
-#' )
+#' library(magrittr) # pipe operator
+#' scores <- example_quantile %>%
+#'   as_forecast_quantile %>%
+#'   score()
+#' correlations <- scores %>%
+#'   summarise_scores() %>%
+#'   get_correlations()
 #' plot_correlations(correlations, digits = 2)
 
 plot_correlations <- function(correlations, digits = NULL) {
@@ -715,6 +732,14 @@ plot_correlations <- function(correlations, digits = NULL) {
   return(plot)
 }
 
+
+# helper function to obtain lower triangle of matrix
+get_lower_tri <- function(cormat) {
+  cormat[lower.tri(cormat)] <- NA
+  return(cormat)
+}
+
+
 #' @title Scoringutils ggplot2 theme
 #'
 #' @description

R/summarise_scores.R

@@ -28,7 +28,9 @@
 #'   data.table::setDTthreads(2) # restricts number of cores used on CRAN
 #' }
 #' library(magrittr) # pipe operator
-#' scores <- score(as_forecast_sample(example_sample_continuous))
+#' scores <- example_sample_continuous %>%
+#'  as_forecast_sample() %>%
+#'  score()
 #'
 #' # get scores by model
 #' summarise_scores(scores, by = "model")

R/utils_data_handling.R

@@ -19,7 +19,10 @@
 #' @keywords data-handling
 #' @export
 #' @examples
-#' sample_to_quantile(as_forecast_sample(example_sample_discrete))
+#' library(magrittr) # pipe operator
+#' example_sample_discrete %>%
+#'   as_forecast_sample() %>%
+#'   sample_to_quantile()
 sample_to_quantile <- function(forecast,
                                quantile_level = c(0.05, 0.25, 0.5, 0.75, 0.95),
                                type = 7) {