From 851c4cc3f6222638bc054e4c9f312e3a2a934a51 Mon Sep 17 00:00:00 2001
From: Nikos Bosse <37978797+nikosbosse@users.noreply.github.com>
Date: Tue, 24 Sep 2024 19:24:47 +0200
Subject: [PATCH] #896 Update documentation of log score (#918)

* use neg_log_score

* update docs, revert previous change

* update docs
---
 R/metrics-binary.R               |  1 +
 R/metrics-nominal.R              |  1 +
 R/metrics-sample.R               | 14 +++++++++-----
 man/logs_sample.Rd               | 19 ++++++++++++++-----
 man/scoring-functions-binary.Rd  |  6 ++++++
 man/scoring-functions-nominal.Rd |  6 ++++++
 6 files changed, 37 insertions(+), 10 deletions(-)

diff --git a/R/metrics-binary.R b/R/metrics-binary.R
index 7a6b92b3b..49cc800c9 100644
--- a/R/metrics-binary.R
+++ b/R/metrics-binary.R
@@ -80,6 +80,7 @@ brier_score <- function(observed, predicted) {
 #' @importFrom methods hasArg
 #' @export
 #' @keywords metric
+#' @family log score functions
 #' @rdname scoring-functions-binary
 logs_binary <- function(observed, predicted) {
   assert_input_binary(observed, predicted)
diff --git a/R/metrics-nominal.R b/R/metrics-nominal.R
index 103ef9d4a..63afc6c75 100644
--- a/R/metrics-nominal.R
+++ b/R/metrics-nominal.R
@@ -18,6 +18,7 @@
 #' @export
 #' @keywords metric
 #' @rdname scoring-functions-nominal
+#' @family log score functions
 #' @examples
 #' factor_levels <- c("one", "two", "three")
 #' predicted_label <- factor(c("one", "two", "three"), levels = factor_levels)
diff --git a/R/metrics-sample.R b/R/metrics-sample.R
index 38c3f0b21..74479d1c1 100644
--- a/R/metrics-sample.R
+++ b/R/metrics-sample.R
@@ -149,19 +149,23 @@ se_mean_sample <- function(observed, predicted) {
 #' [`logs_sample()`][scoringRules::scores_sample_univ] function from the
 #' \pkg{scoringRules} package.
 #'
+#' The log score is the negative logarithm of the predictive density evaluated
+#' at the observed value.
+#'
 #' The function should be used to score continuous predictions only.
 #' While the Log Score is in theory also applicable
-#' to discrete forecasts, the problem lies in the implementation: The Log score
-#' needs a kernel density estimation, which is not well defined with
-#' integer-valued Monte Carlo Samples. The Log score can be used for specific
-#' discrete probability distributions. See the scoringRules package for
-#' more details.
+#' to discrete forecasts, the problem lies in the implementation: The function
+#' uses a kernel density estimation, which is not well defined with
+#' integer-valued Monte Carlo Samples.
+#' See the scoringRules package for more details and alternatives, e.g.
+#' calculating scores for specific discrete probability distributions.
 #' @inheritParams ae_median_sample
 #' @param ... Additional arguments passed to
 #' [logs_sample()][scoringRules::logs_sample()] from the scoringRules package.
 #' @inheritSection illustration-input-metric-sample Input format
 #' @return Vector with scores.
 #' @importFrom scoringRules logs_sample
+#' @family log score functions
 #' @examples
 #' observed <- rpois(30, lambda = 1:30)
 #' predicted <- replicate(200, rpois(n = 30, lambda = 1:30))
diff --git a/man/logs_sample.Rd b/man/logs_sample.Rd
index 00812c507..f5d71e66d 100644
--- a/man/logs_sample.Rd
+++ b/man/logs_sample.Rd
@@ -24,13 +24,16 @@ This function is a wrapper around the
 \code{\link[scoringRules:scores_sample_univ]{logs_sample()}} function from the
 \pkg{scoringRules} package.
 
+The log score is the negative logarithm of the predictive density evaluated
+at the observed value.
+
 The function should be used to score continuous predictions only.
 While the Log Score is in theory also applicable
-to discrete forecasts, the problem lies in the implementation: The Log score
-needs a kernel density estimation, which is not well defined with
-integer-valued Monte Carlo Samples. The Log score can be used for specific
-discrete probability distributions. See the scoringRules package for
-more details.
+to discrete forecasts, the problem lies in the implementation: The function
+uses a kernel density estimation, which is not well defined with
+integer-valued Monte Carlo Samples.
+See the scoringRules package for more details and alternatives, e.g.
+calculating scores for specific discrete probability distributions.
 }
 \section{Input format}{
 \if{html}{
@@ -52,4 +55,10 @@ logs_sample(observed, predicted)
 Alexander Jordan, Fabian Krüger, Sebastian Lerch, Evaluating Probabilistic
 Forecasts with scoringRules, \url{https://www.jstatsoft.org/article/view/v090i12}
 }
+\seealso{
+Other log score functions: 
+\code{\link{logs_nominal}()},
+\code{\link{scoring-functions-binary}}
+}
+\concept{log score functions}
 \keyword{metric}
diff --git a/man/scoring-functions-binary.Rd b/man/scoring-functions-binary.Rd
index 4956d400f..371f7eab5 100644
--- a/man/scoring-functions-binary.Rd
+++ b/man/scoring-functions-binary.Rd
@@ -85,4 +85,10 @@ predicted <- runif(n = 30, min = 0, max = 1)
 brier_score(observed, predicted)
 logs_binary(observed, predicted)
 }
+\seealso{
+Other log score functions: 
+\code{\link{logs_nominal}()},
+\code{\link{logs_sample}()}
+}
+\concept{log score functions}
 \keyword{metric}
diff --git a/man/scoring-functions-nominal.Rd b/man/scoring-functions-nominal.Rd
index dfc400556..a7b6d81ed 100644
--- a/man/scoring-functions-nominal.Rd
+++ b/man/scoring-functions-nominal.Rd
@@ -37,4 +37,10 @@ predicted <- matrix(c(0.8, 0.1, 0.4,
                     nrow = 3)
 logs_nominal(observed, predicted, predicted_label)
 }
+\seealso{
+Other log score functions: 
+\code{\link{logs_sample}()},
+\code{\link{scoring-functions-binary}}
+}
+\concept{log score functions}
 \keyword{metric}