Merge branch 'main' into cran-release

R/check-input-helpers.R

@@ -4,7 +4,7 @@
 #' If the object is not a data table, it is converted to one. If the object
 #' is a data table, a copy of the object is returned.
 #' @param data An object to ensure is a data table.
-#' @return A data.table/a copy of an existing data.table.
+#' @returns A data.table/a copy of an existing data.table.
 #' @keywords internal
 #' @importFrom data.table copy is.data.table as.data.table
 ensure_data.table <- function(data) {
@@ -101,7 +101,7 @@ check_columns_present <- function(data, columns) {
 #' one or more columns are missing, the function returns FALSE. If all columns
 #' are present, the function returns TRUE.
 #' @inheritParams document_check_functions
-#' @return Returns TRUE if all columns are present and FALSE otherwise
+#' @returns Returns TRUE if all columns are present and FALSE otherwise
 #' @keywords internal_input_check
 test_columns_present <- function(data, columns) {
   check <- check_columns_present(data, columns)
@@ -113,7 +113,7 @@ test_columns_present <- function(data, columns) {
 #' If none of the columns are present, the function returns TRUE. If one or
 #' more columns are present, the function returns FALSE.
 #' @inheritParams document_check_functions
-#' @return Returns TRUE if none of the columns are present and FALSE otherwise
+#' @returns Returns TRUE if none of the columns are present and FALSE otherwise
 #' @importFrom checkmate test_names
 #' @keywords internal_input_check
 test_columns_not_present <- function(data, columns) {

R/class-forecast-binary.R

@@ -96,7 +96,7 @@ score.forecast_binary <- function(forecast, metrics = get_metrics(forecast), ...
 #' @param exclude A character vector of scoring rules to exclude from the list.
 #'   If `select` is not `NULL`, this argument is ignored.
 #' @param ... unused
-#' @return A list of scoring functions.
+#' @returns A list of scoring functions.
 #' @export
 #' @family get_metrics functions
 #' @keywords handle-metrics

R/class-forecast.R

@@ -155,7 +155,7 @@ assert_forecast.default <- function(
 #' @param data A data.table with forecasts and observed values that should
 #' be validated.
 #' @inheritParams assert_forecast
-#' @return returns the input
+#' @returns returns the input
 #' @importFrom data.table ':=' is.data.table
 #' @importFrom checkmate assert_data_table
 #' @importFrom cli cli_abort cli_inform cli_warn
@@ -279,7 +279,7 @@ clean_forecast <- function(forecast, copy = FALSE, na.omit = FALSE) {
 #'
 #' @inheritParams as_forecast
 #' @param classname name of the class to be created
-#' @return An object of the class indicated by `classname`
+#' @returns An object of the class indicated by `classname`
 #' @export
 #' @keywords internal
 new_forecast <- function(data, classname) {
@@ -447,7 +447,7 @@ tail.forecast <- function(x, ...) {
 #' @param x A forecast object (a validated data.table with predicted and
 #'   observed values, see [as_forecast()]).
 #' @param ... Additional arguments for [print()].
-#' @return Returns `x` invisibly.
+#' @returns Returns `x` invisibly.
 #' @importFrom cli cli_inform cli_warn col_blue cli_text
 #' @export
 #' @keywords gain-insights

R/class-scores.R

@@ -8,7 +8,7 @@
 #' @param ... Additional arguments to [data.table::as.data.table()]
 #' @keywords internal
 #' @importFrom data.table as.data.table setattr
-#' @return An object of class `scores`
+#' @returns An object of class `scores`
 #' @examples
 #' \dontrun{
 #' df <- data.frame(

R/documentation-templates.R

@@ -88,7 +88,7 @@ NULL
 #' @param observed Input to be checked. Should be a numeric vector with the
 #'   observed values of size n.
 #' @param columns A character vector of column names to check
-#' @return Returns TRUE if the check was successful and a string with an
+#' @returns Returns TRUE if the check was successful and a string with an
 #'   error message otherwise.
 #' @name document_check_functions
 #' @keywords internal

R/forecast-unit.R

@@ -19,7 +19,7 @@
 #' @param forecast_unit Character vector with the names of the columns that
 #'   uniquely identify a single forecast.
 #' @importFrom cli cli_warn
-#' @return A data.table with only those columns kept that are relevant to
+#' @returns A data.table with only those columns kept that are relevant to
 #'   scoring or denote the unit of a single forecast as specified by the user.
 #' @importFrom data.table ':=' is.data.table copy
 #' @importFrom checkmate assert_character assert_subset

R/get-correlations.R

@@ -63,7 +63,7 @@ get_correlations <- function(scores,
 #' @importFrom data.table setDT melt
 #' @importFrom checkmate assert_data_frame
 #' @export
-#' @return A ggplot object with a visualisation of correlations between metrics
+#' @returns A ggplot object with a visualisation of correlations between metrics
 #' @examples
 #' library(magrittr) # pipe operator
 #' scores <- example_quantile %>%

R/get-coverage.R

@@ -110,7 +110,7 @@ get_coverage <- function(forecast, by = "model") {
 #' [get_coverage()].
 #' @param colour According to which variable shall the graphs be coloured?
 #' Default is "model".
-#' @return ggplot object with a plot of interval coverage
+#' @returns ggplot object with a plot of interval coverage
 #' @importFrom ggplot2 ggplot scale_colour_manual scale_fill_manual .data
 #' facet_wrap facet_grid geom_polygon geom_line xlab ylab
 #' @importFrom checkmate assert_subset
@@ -178,7 +178,7 @@ plot_interval_coverage <- function(coverage,
 #' @inheritParams plot_interval_coverage
 #' @param colour String, according to which variable shall the graphs be
 #' coloured? Default is "model".
-#' @return A ggplot object with a plot of interval coverage
+#' @returns A ggplot object with a plot of interval coverage
 #' @importFrom ggplot2 ggplot scale_colour_manual scale_fill_manual .data aes
 #'   scale_y_continuous geom_line
 #' @importFrom checkmate assert_subset assert_data_frame

R/get-duplicate-forecasts.R

@@ -8,7 +8,7 @@
 #' @inheritParams as_forecast
 #' @param counts Should the output show the number of duplicates per forecast
 #'   unit instead of the individual duplicated rows? Default is `FALSE`.
-#' @return A data.frame with all rows for which a duplicate forecast was found
+#' @returns A data.frame with all rows for which a duplicate forecast was found
 #' @export
 #' @importFrom checkmate assert_data_frame assert_subset
 #' @importFrom data.table setorderv

R/get-forecast-counts.R

@@ -23,7 +23,7 @@
 #'   `collapse = c()` would mean that all quantiles / samples would be counted
 #'   as individual forecasts.
 #'
-#' @return A data.table with columns as specified in `by` and an additional
+#' @returns A data.table with columns as specified in `by` and an additional
 #' column "count" with the number of forecasts.
 #'
 #' @inheritParams score
@@ -90,7 +90,7 @@ get_forecast_counts <- function(forecast,
 #'   are shown on the x-axis.
 #' @param show_counts Logical (default is `TRUE`) that indicates whether
 #'   or not to show the actual count numbers on the plot.
-#' @return A ggplot object with a plot of forecast counts
+#' @returns A ggplot object with a plot of forecast counts
 #' @importFrom ggplot2 ggplot scale_colour_manual scale_fill_manual
 #'   geom_tile scale_fill_gradient .data
 #' @importFrom data.table dcast .I .N

R/get-pit-histogram.R

@@ -24,7 +24,7 @@
 #'   'location' in the input data and want to have a PIT histogram for
 #' every model and location, specify `by = c("model", "location")`.
 #' @inheritParams pit_histogram_sample
-#' @return A data.table with density values for each bin in the PIT histogram.
+#' @returns A data.table with density values for each bin in the PIT histogram.
 #' @examples
 #' library("ggplot2")
 #'

R/helper-quantile-interval-range.R

@@ -25,7 +25,7 @@
 #' and upper bounds of the 50% and 90% prediction intervals (corresponding to
 #' the 0.25 and 0.75 as well as the 0.05 and 0.095 quantiles).
 #' @param ... Arguments
-#' @return A data.table with forecasts in an interval format.
+#' @returns A data.table with forecasts in an interval format.
 #' @keywords internal
 quantile_to_interval <- function(...) {
   dots <- list(...)
@@ -142,7 +142,7 @@ quantile_to_interval_numeric <- function(observed,
 #'
 #' @inheritParams as_forecast_quantile
 #' @param keep_quantile_col keep quantile_level column, default is TRUE
-#' @return A data.table in a long interval interval range format
+#' @returns A data.table in a long interval interval range format
 #' @importFrom data.table as.data.table
 #' @importFrom stats quantile
 #' @keywords internal
@@ -179,7 +179,7 @@ sample_to_interval_long <- function(data,
 #' rounded to 10 decimal places. This is not a problem for the vast majority of
 #' use cases, but it is something to be aware of.
 #' @param quantile_level A numeric vector of quantile levels of size N.
-#' @return a numeric vector of interval ranges of size N
+#' @returns a numeric vector of interval ranges of size N
 #' @keywords internal
 get_range_from_quantile <- function(quantile_level) {
   boundary <- ifelse(quantile_level <= 0.5, "lower", "upper")

R/metrics-binary.R

@@ -89,7 +89,7 @@ NULL
 #' } where \eqn{\textrm{outcome} \in \{0, 1\}}{outcome in {0, 1}}, and
 #' \eqn{\textrm{prediction} \in [0, 1]}{prediction in [0, 1]} represents
 #' the probability that the outcome is equal to 1.
-#' @return A numeric vector of size n with the Brier scores
+#' @returns A numeric vector of size n with the Brier scores
 #' @keywords metric
 #' @export
 #' @rdname scoring-functions-binary
@@ -111,7 +111,7 @@ brier_score <- function(observed, predicted) {
 #' assigned to the observed value. It is a proper scoring rule. Small values
 #' are better (best is zero, worst is infinity).
 #'
-#' @return A numeric vector of size n with log scores
+#' @returns A numeric vector of size n with log scores
 #' @importFrom methods hasArg
 #' @export
 #' @keywords metric

R/metrics-nominal.R

@@ -78,7 +78,7 @@ assert_input_nominal <- function(observed, predicted, predicted_label) {
 #'   possible outcomes.
 #' @param predicted_label A factor of length N, denoting the outcome that the
 #'   probabilities in `predicted` correspond to.
-#' @return A numeric vector of size n with log scores
+#' @returns A numeric vector of size n with log scores
 #' @importFrom methods hasArg
 #' @export
 #' @keywords metric

R/metrics-quantile.R

@@ -421,7 +421,7 @@ interval_coverage <- function(observed, predicted,
 #' @importFrom cli cli_inform
 #' @inheritParams wis
 #' @inheritSection illustration-input-metric-quantile Input format
-#' @return scalar with the quantile bias for a single quantile prediction
+#' @returns scalar with the quantile bias for a single quantile prediction
 #' @export
 #' @keywords metric
 #' @examples
@@ -469,7 +469,7 @@ bias_quantile <- function(observed, predicted, quantile_level, na.rm = TRUE) {
 #'   quantiles) that holds predictions.
 #' @inheritParams bias_quantile
 #' @importFrom cli cli_abort
-#' @return scalar with the quantile bias for a single quantile prediction
+#' @returns scalar with the quantile bias for a single quantile prediction
 #' @keywords internal
 bias_quantile_single_vector <- function(observed, predicted,
                                         quantile_level, na.rm) {
@@ -534,7 +534,7 @@ bias_quantile_single_vector <- function(observed, predicted,
 #' This is done using linear interpolation between the two innermost quantiles.
 #' @inheritParams bias_quantile_single_vector
 #' @inheritSection illustration-input-metric-quantile Input format
-#' @return scalar with the imputed median prediction
+#' @returns scalar with the imputed median prediction
 #' @keywords internal
 interpolate_median <- function(predicted, quantile_level) {
   if (0.5 %in% quantile_level) {
@@ -567,7 +567,7 @@ interpolate_median <- function(predicted, quantile_level) {
 #'
 #' @inheritParams wis
 #' @inheritSection illustration-input-metric-quantile Input format
-#' @return Numeric vector of length N with the absolute error of the median.
+#' @returns Numeric vector of length N with the absolute error of the median.
 #' @seealso [ae_median_sample()]
 #' @importFrom stats median
 #' @importFrom cli cli_warn
@@ -632,7 +632,7 @@ ae_median_quantile <- function(observed, predicted, quantile_level) {
 #' `quantile_score()` returns the average quantile score across the quantile
 #' levels provided. For a set of quantile levels that form pairwise central
 #' prediction intervals, the quantile score is equivalent to the interval score.
-#' @return Numeric vector of length n with the quantile score. The scores are
+#' @returns Numeric vector of length n with the quantile score. The scores are
 #' averaged across quantile levels if multiple quantile levels are provided
 #' (the result of calling `rowMeans()` on the matrix of quantile scores that
 #' is computed based on the observed and predicted values).

R/metrics-sample.R

@@ -130,7 +130,7 @@ bias_sample <- function(observed, predicted) {
 #'   the number of data points and N (number of columns) the number of Monte
 #'   Carlo samples. Alternatively, `predicted` can just be a vector of size n.
 #' @inheritSection illustration-input-metric-sample Input format
-#' @return Numeric vector of length n with the absolute errors of the median.
+#' @returns Numeric vector of length n with the absolute errors of the median.
 #' @seealso [ae_median_quantile()]
 #' @importFrom stats median
 #' @keywords metric
@@ -199,7 +199,7 @@ se_mean_sample <- function(observed, predicted) {
 #' @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.
+#' @returns Vector with scores.
 #' @importFrom scoringRules logs_sample
 #' @family log score functions
 #' @examples
@@ -231,7 +231,7 @@ logs_sample <- function(observed, predicted, ...) {
 #' @param ... Additional arguments passed to
 #' [dss_sample()][scoringRules::dss_sample()] from the scoringRules package.
 #' @inheritSection illustration-input-metric-sample Input format
-#' @return Vector with scores.
+#' @returns Vector with scores.
 #' @importFrom scoringRules dss_sample
 #' @examples
 #' observed <- rpois(30, lambda = 1:30)
@@ -282,7 +282,7 @@ dss_sample <- function(observed, predicted, ...) {
 #' @param ... Additional arguments passed to
 #' [crps_sample()][scoringRules::crps_sample()] from the scoringRules package.
 #' @inheritSection illustration-input-metric-sample Input format
-#' @return Vector with scores.
+#' @returns Vector with scores.
 #' @importFrom scoringRules crps_sample
 #' @examples
 #' observed <- rpois(30, lambda = 1:30)
@@ -395,7 +395,7 @@ underprediction_sample <- function(observed, predicted, ...) {
 #' @param ... Additional arguments passed to [mad()][stats::mad()].
 #' @importFrom stats mad
 #' @inheritSection illustration-input-metric-sample Input format
-#' @return Vector with dispersion values.
+#' @returns Vector with dispersion values.
 #'
 #' @references
 #' Funk S, Camacho A, Kucharski AJ, Lowe R, Eggo RM, Edmunds WJ (2019)
@@ -494,7 +494,7 @@ mad_sample <- function(observed = NULL, predicted, ...) {
 #'   not set to `random`.
 #' @inheritParams ae_median_sample
 #' @inheritParams get_pit_histogram
-#' @return A vector with PIT histogram densities for the bins corresponding
+#' @returns A vector with PIT histogram densities for the bins corresponding
 #'   to the given quantiles.
 #' @seealso [get_pit_histogram()]
 #' @importFrom stats runif

R/metrics.R

@@ -9,7 +9,7 @@
 #'   `select` is `NULL` (the default), all possible scoring rules are returned.
 #' @param exclude A character vector of scoring rules to exclude from the list.
 #'   If `select` is not `NULL`, this argument is ignored.
-#' @return A list of scoring functions.
+#' @returns A list of scoring functions.
 #' @keywords handle-metrics
 #' @importFrom checkmate assert_subset assert_list
 #' @export

R/pairwise-comparisons.R

@@ -78,7 +78,7 @@
 #' @param ... Additional arguments for the comparison between two models. See
 #'   [compare_forecasts()] for more information.
 #' @inheritParams summarise_scores
-#' @return A data.table with the results of pairwise comparisons
+#' @returns A data.table with the results of pairwise comparisons
 #' containing the mean score ratios (`mean_scores_ratio`),
 #' unadjusted (`pval`) and adjusted (`adj_pval`) p-values, and relative skill
 #' values of each model (`..._relative_skill`). If a baseline model is given
@@ -415,7 +415,7 @@ pairwise_comparison_one_group <- function(scores,
 #'   determine p-values.
 #' @param n_permutations Numeric, the number of permutations for a
 #'   permutation test. Default is 999.
-#' @return A list with mean score ratios and p-values for the comparison
+#' @returns A list with mean score ratios and p-values for the comparison
 #' between two comparators
 #' @importFrom cli cli_abort
 #' @author Johannes Bracher, \email{johannes.bracher@@kit.edu}
@@ -492,7 +492,7 @@ compare_forecasts <- function(scores,
 #' Used in [get_pairwise_comparisons()].
 #'
 #' @param x Numeric vector of values for which to calculate the geometric mean.
-#' @return The geometric mean of the values in `x`. `NA` values are ignored.
+#' @returns The geometric mean of the values in `x`. `NA` values are ignored.
 #'
 #' @keywords internal
 geometric_mean <- function(x) {
@@ -524,7 +524,7 @@ geometric_mean <- function(x) {
 #' @param comparison_mode How to compute the test statistic for the comparison
 #'   of the two scores. Should be either "difference" or "ratio".
 #'
-#' @return p-value of the permutation test
+#' @returns p-value of the permutation test
 #' @keywords internal
 permutation_test <- function(scores1,
                              scores2,

R/plot-heatmap.R

@@ -13,7 +13,7 @@
 #'   could be something like "horizon", or "location"
 #' @param metric String, the metric that determines the value and colour shown
 #'   in the tiles of the heatmap.
-#' @return A ggplot object showing a heatmap of the desired metric
+#' @returns A ggplot object showing a heatmap of the desired metric
 #' @importFrom data.table setDT `:=`
 #' @importFrom ggplot2 ggplot  aes geom_tile geom_text .data
 #' scale_fill_gradient2 labs element_text coord_cartesian

R/plot-wis.R

@@ -13,14 +13,14 @@
 #'   of absolute contributions? Default is `FALSE` and this functionality is not
 #'   available yet.
 #' @param flip Boolean (default is `FALSE`), whether or not to flip the axes.
-#' @return A ggplot object showing a contributions from the three components of
+#' @returns A ggplot object showing a contributions from the three components of
 #'   the weighted interval score.
 #' @importFrom ggplot2 ggplot aes geom_linerange facet_wrap labs
 #' scale_fill_discrete coord_flip geom_col
 #' theme theme_light unit guides guide_legend .data
 #' @importFrom data.table melt
 #' @importFrom checkmate assert_subset assert_logical
-#' @return A ggplot object with a visualisation of the WIS decomposition
+#' @returns A ggplot object with a visualisation of the WIS decomposition
 #' @export
 #' @examples
 #' library(ggplot2)

R/score.R

@@ -119,7 +119,7 @@ score.default <- function(forecast, metrics, ...) {
 #'   avoid passing arguments via `...` and instead expect that the metrics
 #'   directly be modified using [purrr::partial()].
 #' @inheritParams score
-#' @return A data table with the forecasts and the calculated metrics.
+#' @returns A data table with the forecasts and the calculated metrics.
 #' @keywords internal
 apply_metrics <- function(forecast, metrics, ...) {
   lapply(names(metrics), function(metric_name) {
@@ -154,7 +154,7 @@ apply_metrics <- function(forecast, metrics, ...) {
 #'   provide a more informative warning message in case `fun` errors.
 #' @importFrom cli cli_warn
 #' @importFrom checkmate assert_function
-#' @return The result of `fun` or `NULL` if `fun` errors
+#' @returns The result of `fun` or `NULL` if `fun` errors
 #' @keywords internal
 #' @examples
 #' f <- function(x) {x}