Improve variogram docs, deduplicate point implementation, and update vignette

R/metrics-multivariate-point.R

@@ -1,21 +1,16 @@
 #' @title Variogram score for multivariate point forecasts
 #' @description
-#' Compute the variogram score
-#' (see [scoringRules::vs_sample()])
-#' for each group defined by `mv_group_id`, treating each point
-#' forecast as a single-sample ensemble.
-#' @param observed Numeric vector of observed values.
+#' Compute the variogram score for multivariate point forecasts,
+#' treating each point forecast as a single-sample ensemble.
+#' This is a thin wrapper around
+#' [variogram_score_multivariate()] with `w = NULL`.
+#'
+#' See [variogram_score_multivariate()] for details on the
+#' variogram score and its parameters.
+#' @inheritParams variogram_score_multivariate
+#' @inherit variogram_score_multivariate return references
 #' @param predicted Numeric matrix with one column, where each row
 #'   corresponds to a target within a multivariate group.
-#' @param mv_group_id Numeric vector of length equal to
-#'   `length(observed)` with group identifiers.
-#' @param w_vs Numeric matrix of weights for the variogram score.
-#'   See [scoringRules::vs_sample()] for details.
-#' @param p Numeric, order of the variogram score.
-#'   Defaults to 0.5. See [scoringRules::vs_sample()] for details.
-#' @return A named numeric vector of scores, one per multivariate
-#'   group. Lower values are better.
-#' @importFrom scoringRules vs_sample
 #' @importFrom checkmate assert_numeric
 #' @export
 #' @keywords metric
@@ -27,19 +22,13 @@ variogram_score_multivariate_point <- function(
   assert_numeric(observed, min.len = 1)
   assert_numeric(as.vector(predicted), min.len = 1)
   assert_numeric(mv_group_id, len = length(observed))
-  unique_groups <- unique(mv_group_id)
-
-  vs <- vapply(unique_groups, function(group) {
-    idx <- which(mv_group_id == group)
-    scoringRules::vs_sample(
-      y = observed[idx],
-      dat = predicted[idx, , drop = FALSE],
-      w_vs = w_vs,
-      p = p
-    )
-  }, numeric(1))
-
-  names(vs) <- unique_groups
-  return(vs)
+  variogram_score_multivariate(
+    observed = observed,
+    predicted = predicted,
+    mv_group_id = mv_group_id,
+    w = NULL,
+    w_vs = w_vs,
+    p = p
+  )
 }
 # nolint end

R/metrics-multivariate-sample.R

@@ -29,13 +29,27 @@ assert_input_multivariate_sample <- function(observed, predicted, mv_group_id) {
 
 #' @title Energy score for multivariate forecasts
 #' @description
-#' Compute the multivariate energy score
-#' (see \link[scoringRules:es_sample]{scoringRules::es_sample})
-#' for each group defined by `mv_group_id`.
+#' Compute the energy score (Gneiting and Raftery, 2007) for
+#' multivariate forecasts. The energy score is a multivariate
+#' generalisation of the CRPS that measures both calibration and
+#' sharpness of the forecast distribution.
+#'
+#' The score is computed using
+#' [scoringRules::es_sample()].
 #' @inheritParams ae_median_sample
 #' @inheritParams assert_input_multivariate_sample
-#' @inherit scoringRules::es_sample params
-#' @keywords internal_input_check
+#' @param w Optional numeric vector of weights for forecast samples
+#'   (length equal to the number of columns of `predicted`).
+#'   If `NULL` (the default), equal weights are used.
+#' @return A named numeric vector of scores, one per multivariate
+#'   group. Lower values are better.
+#' @references
+#' Gneiting, T., Stanberry, L.I., Grimit, E.P., Held, L. and
+#' Johnson, N.A. (2008). Assessing probabilistic forecasts of
+#' multivariate quantities, with an application to ensemble
+#' predictions of surface winds.
+#' *TEST*, 17, 211-235.
+#' @keywords metric
 #' @export
 energy_score_multivariate <- function(observed, predicted, mv_group_id, w = NULL) {
   assert_input_multivariate_sample(observed, predicted, mv_group_id)
@@ -64,9 +78,12 @@ energy_score_multivariate <- function(observed, predicted, mv_group_id, w = NULL
 #' [scoringRules::vs_sample()].
 #'
 #' @inheritParams energy_score_multivariate
-#' @param w_vs Optional non-negative weight matrix. If not `NULL`,
-#'   must be a square matrix with dimensions equal to the number
-#'   of targets within each multivariate group.
+#' @param w_vs Optional non-negative weight matrix for the
+#'   pairwise comparisons between dimensions. Entry `w_vs[i, j]`
+#'   controls the importance of the pair (i, j) in the score.
+#'   Must be a symmetric square matrix with dimensions equal to
+#'   the number of targets within each multivariate group.
+#'   If `NULL` (the default), all pairs are weighted equally.
 #' @param p Numeric, order of the variogram score.
 #'   Typical choices are 0.5 (default, more robust) and 1.
 #' @return A named numeric vector of scores, one per multivariate