rename sharpness to dispersion

R/eval_forecasts.R

@@ -15,7 +15,7 @@
 #'   \item {aem} Absolute error of the median prediction
 #'   \item {Bias} 0 is good, 1 and -1 are bad.
 #'   See [bias()] for more information.
-#'   \item {Sharpness} Smaller is better. See [sharpness()] for more
+#'   \item {Sharpness/dispersion} Smaller is better. See [sharpness()] for more
 #'   information.
 #'   \item {Calibration} represented through the p-value of the
 #'   Anderson-Darling test for the uniformity of the Probability Integral
@@ -131,8 +131,8 @@
 #'
 #' @return A data.table with appropriate scores. For binary predictions,
 #' the Brier Score will be returned, for quantile predictions the interval
-#' score, as well as adapted metrics for calibration, sharpness and bias.
-#' For integer forecasts, Sharpness, Bias, DSS, CRPS, LogS, and
+#' score, as well as adapted metrics for calibration, sharpness/dispersion and
+#' bias. For integer forecasts, Sharpness, Bias, DSS, CRPS, LogS, and
 #' pit_p_val (as an indicator of calibration) are returned. For integer
 #' forecasts, pit_sd is returned (to account for the randomised PIT),
 #' but no Log Score is returned (the internal estimation relies on a

R/eval_forecasts_quantile.R

@@ -51,7 +51,7 @@ eval_forecasts_quantile <- function(data,
     # compute separate results if desired
     if (interval_score_arguments$separate_results) {
       res <- res[, c("interval_score",
-                     "sharpness",
+                     "dispersion",
                      "underprediction",
                      "overprediction") := do.call(scoringutils::interval_score,
                                                   c(list(true_value,
@@ -155,7 +155,7 @@ eval_forecasts_quantile <- function(data,
       res <- add_quantiles(res,
                            c("interval_score", "coverage",
                              "overprediction", "underprediction",
-                             "coverage_deviation", "bias", "sharpness", "aem",
+                             "coverage_deviation", "bias", "dispersion", "aem",
                              "ae_point"),
                            quantiles,
                            by = c(summarise_by))
@@ -165,7 +165,7 @@ eval_forecasts_quantile <- function(data,
       res <- add_sd(res,
                     varnames = c("interval_score", "bias", "coverage",
                                  "overprediction", "underprediction",
-                                 "coverage_deviation", "sharpness", "aem",
+                                 "coverage_deviation", "dispersion", "aem",
                                  "ae_point"),
                     by = c(summarise_by))
     }
@@ -174,7 +174,7 @@ eval_forecasts_quantile <- function(data,
     res <- res[, lapply(.SD, mean, na.rm = TRUE),
                by = c(summarise_by),
                .SDcols = colnames(res) %like%
-                 "coverage|bias|sharpness|coverage_deviation|interval_score|overprediction|underprediction|aem|ae_point|relative_skill|scaled_rel_skill"]
+                 "coverage|bias|dispersion|coverage_deviation|interval_score|overprediction|underprediction|aem|ae_point|relative_skill|scaled_rel_skill"]
   }
 
   # if neither quantile nor range are in summarise_by, remove coverage and quantile_coverage

R/interval_score.R

@@ -36,7 +36,7 @@
 #' into an interval score that, in the limit, corresponds to CRPS. Default:
 #' `FALSE`.
 #' @param separate_results if `TRUE` (default is `FALSE`), then the separate
-#' parts of the interval score (sharpness, penalties for over- and
+#' parts of the interval score (dispersion penalty, penalties for over- and
 #' under-prediction get returned as separate elements of a list). If you want a
 #' `data.frame` instead, simply call [as.data.frame()] on the output.
 #' @return vector with the scoring values, or a list with separate entries if
@@ -91,21 +91,21 @@ interval_score <- function(true_values,
   alpha <- (100 - interval_range) / 100
 
   # calculate three components of WIS
-  sharpness <- (upper - lower)
+  dispersion <- (upper - lower)
   overprediction <- 2/alpha * (lower - true_values) * (true_values < lower)
   underprediction <- 2/alpha * (true_values - upper) * (true_values > upper)
 
   if (weigh) {
-    sharpness <- sharpness * alpha / 2
+    dispersion <- dispersion * alpha / 2
     underprediction <- underprediction * alpha / 2
     overprediction <- overprediction * alpha / 2
   }
 
-  score <- sharpness + underprediction + overprediction
+  score <- dispersion + underprediction + overprediction
 
   if (separate_results) {
     return(list(interval_score = score,
-                sharpness = sharpness,
+                dispersion = dispersion,
                 underprediction = underprediction,
                 overprediction = overprediction))
   } else {

R/plot.R

@@ -265,7 +265,7 @@ correlation_plot <- function(scores,
 #'
 #' @description
 #' Visualise the components of the weighted interval score: penalties for
-#' over-prediction, under-prediction and for a lack of sharpness
+#' over-prediction, under-prediction and for high dispersion (lack of sharpness)
 #'
 #' @param scores A data.frame of scores based on quantile forecasts as
 #' produced by [eval_forecasts()]
@@ -323,7 +323,7 @@ wis_components <- function(scores,
   scores <- data.table::melt(scores,
                              measure.vars = c("overprediction",
                                               "underprediction",
-                                              "sharpness"),
+                                              "dispersion"),
                              variable.name = "wis_component_name",
                              value.name = "component_value")
 
@@ -363,14 +363,14 @@ wis_components <- function(scores,
 #'
 #' @description
 #' Visualise the metrics by range, e.g. if you are interested how different
-#' interval ranges contribute to the overall interval score, or how sharpness
-#' changes by range.
+#' interval ranges contribute to the overall interval score, or how
+#' sharpness / dispersion changes by range.
 #'
 #' @param scores A data.frame of scores based on quantile forecasts as
 #' produced by [eval_forecasts()]. Note that "range" must be included
 #' in the `summarise_by` argument when running `eval_forecasts`
 #' @param y The variable from the scores you want to show on the y-Axis.
-#' This could be something like "interval_score" (the default) or "sharpness"
+#' This could be something like "interval_score" (the default) or "dispersion"
 #' @param x The variable from the scores you want to show on the x-Axis.
 #' Usually this will be "model"
 #' @param colour Character vector of length one used to determine a variable
@@ -399,15 +399,15 @@ wis_components <- function(scores,
 #'
 #' scoringutils::range_plot(scores, x = "model", facet_formula = ~ value_desc)
 #'
-#' # visualise sharpness instead of interval score
-#' scoringutils::range_plot(scores, y = "sharpness", x = "model",
+#' # visualise dispersion instead of interval score
+#' scoringutils::range_plot(scores, y = "dispersion", x = "model",
 #'                           facet_formula =  ~value_desc)
 #'
-#' # we saw above that sharpness values crossed. Let's look at the unweighted WIS
+#' # we saw above that dispersion values crossed. Let's look at the unweighted WIS
 #' scores <- scoringutils::eval_forecasts(scoringutils::quantile_example_data,
 #'                                         interval_score_arguments = list(weigh = FALSE),
 #'                                         summarise_by = c("model", "value_desc", "range"))
-#' scoringutils::range_plot(scores, y = "sharpness", x = "model",
+#' scoringutils::range_plot(scores, y = "dispersion", x = "model",
 #'                           facet_formula =  ~value_desc)
 
 

vignettes/scoringutils.Rmd

@@ -98,7 +98,7 @@ Let us look at the individual components of the weighted interval score:
 
 ```{r}
 scores <- scoringutils::eval_forecasts(data, 
-                             summarise_by = c("model", "value_desc"))
+                                       summarise_by = c("model", "value_desc"))
 scoringutils::wis_components(scores, facet_formula = ~ value_desc)
 ```
 
@@ -203,7 +203,7 @@ Sharpness is the ability of the model to generate predictions within a
 narrow range. It is a data-independent measure, and is purely a feature
 of the forecasts themselves.
 
-Shaprness of predictive samples corresponding to one single true value is
+Shaprness / dispersion of predictive samples corresponding to one single true value is
 measured as the normalised median of the absolute deviation from
 the median of the predictive samples. For details, see `?stats::mad`