Merge pull request #886 from epiforecasts/update-pkgdown

Issue #481: Update pkgdown structure
epiforecasts · Aug 10, 2024 · a62899f · a62899f
2 parents 5cf89cc + f353a1f
commit a62899f
Show file tree

Hide file tree

Showing 38 changed files with 140 additions and 110 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -39,15 +39,15 @@ Authors@R: c(
            email = "[email protected]",
            comment = c(ORCID = "0000-0003-0787-087X")))
 Description: 
-    `scoringutils` facilitates the evaluation of forecasts in a convenient 
-    framework based on `data.table`. It allows user to to check their forecasts 
+    scoringutils facilitates the evaluation of forecasts in a convenient 
+    framework based on data.table. It allows user to to check their forecasts 
     and diagnose issues, to visualise forecasts and missing data, to transform 
     data before scoring, to handle missing forecasts, to aggregate scores, and 
     to visualise the results of the evaluation. The package mostly focuses on 
     the evaluation of probabilistic forecasts and allows evaluating several 
     different forecast types and input formats. Find more information about the 
-    package in the Vignettes as well as in the accompanying paper 
-    (<doi:10.48550/arXiv.2205.07090>).
+    package in the Vignettes as well as in the accompanying paper, 
+    <doi:10.48550/arXiv.2205.07090>.
 License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true

diff --git a/R/convenience-functions.R b/R/convenience-functions.R
@@ -62,7 +62,7 @@
 #' medRxiv 2023.01.23.23284722
 #' \doi{https://doi.org/10.1101/2023.01.23.23284722}
 #' <https://www.medrxiv.org/content/10.1101/2023.01.23.23284722v1>
-#' @keywords check-forecasts
+#' @keywords transform
 #' @examples
 #' library(magrittr) # pipe operator
 #'
@@ -203,7 +203,7 @@ transform_forecasts <- function(forecast,
 #'   medRxiv 2023.01.23.23284722
 #'   \doi{https://doi.org/10.1101/2023.01.23.23284722}
 #'   <https://www.medrxiv.org/content/10.1101/2023.01.23.23284722v1> # nolint
-#' @keywords check-forecasts
+#' @keywords transform
 #' @importFrom checkmate assert_numeric assert_number
 #' @examples
 #' library(magrittr) # pipe operator
@@ -267,7 +267,7 @@ log_shift <- function(x, offset = 0, base = exp(1)) {
 #' @importFrom data.table ':=' is.data.table copy
 #' @importFrom checkmate assert_character assert_subset
 #' @export
-#' @keywords data-handling
+#' @keywords as_forecast
 #' @examples
 #' library(magrittr) # pipe operator
 #' example_quantile %>%

diff --git a/R/default-scoring-rules.R b/R/default-scoring-rules.R
@@ -10,7 +10,7 @@
 #' @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.
-#' @keywords metric
+#' @keywords handle-metrics
 #' @importFrom checkmate assert_subset assert_list
 #' @export
 #' @examples
@@ -53,7 +53,7 @@ select_metrics <- function(metrics, select = NULL, exclude = NULL) {
 #' @inheritSection illustration-input-metric-binary-point Input format
 #' @inherit select_metrics params return
 #' @export
-#' @keywords metric
+#' @keywords handle-metrics
 #' @examples
 #' metrics_binary()
 #' metrics_binary(select = "brier_score")
@@ -81,7 +81,7 @@ metrics_binary <- function(select = NULL, exclude = NULL) {
 #' @inheritSection illustration-input-metric-binary-point Input format
 #' @inherit select_metrics params return
 #' @export
-#' @keywords metric
+#' @keywords handle-metrics
 #' @examples
 #' metrics_point()
 #' metrics_point(select = "ape")
@@ -116,7 +116,7 @@ metrics_point <- function(select = NULL, exclude = NULL) {
 #' @inheritSection illustration-input-metric-sample Input format
 #' @inherit select_metrics params return
 #' @export
-#' @keywords metric
+#' @keywords handle-metrics
 #' @examples
 #' metrics_sample()
 #' metrics_sample(select = "mad")
@@ -168,7 +168,7 @@ metrics_sample <- function(select = NULL, exclude = NULL) {
 #' @inherit select_metrics params return
 #' @export
 #' @importFrom purrr partial
-#' @keywords metric
+#' @keywords handle-metrics
 #' @examples
 #' metrics_quantile()
 #' metrics_quantile(select = "wis")

diff --git a/R/forecast.R b/R/forecast.R
@@ -1,8 +1,9 @@
-#' @title Create a `forecast` object
+#' @title General information on creating a `forecast` object
 #'
 #' @description
-#' Process and validate a data.frame (or similar) or similar with forecasts
-#' and observations. If the input passes all input checks, it will be converted
+#' There are several ``as_forecast_<type>()` functions to process and validate
+#' a data.frame (or similar) or similar with forecasts and observations. If
+#' the input passes all input checks, those functions will be converted
 #' to a `forecast` object. A forecast object is a `data.table` with a
 #' class `forecast` and an additional class that depends on the forecast type.
 #' Every forecast type has its own `as_forecast_<type>()` function.
@@ -48,9 +49,8 @@
 #' - `forecast_point` for point forecasts
 #' - `forecast_sample` for sample-based forecasts
 #' - `forecast_quantile` for quantile-based forecasts
-#' @keywords check-forecasts
-#' @seealso [as_forecast_point()], [as_forecast_binary()],
-#'   [as_forecast_sample()], [as_forecast_quantile()]
+#' @keywords as_forecast
+#' @family functions to create forecast objects
 #' @examples
 #' as_forecast_binary(example_binary)
 #' as_forecast_quantile(
@@ -68,7 +68,7 @@ NULL
 #' It renames the required columns, where appropriate, and sets the forecast
 #' unit.
 #' @inheritParams as_forecast
-#' @keywords check-forecasts
+#' @keywords as_forecast
 as_forecast_generic <- function(data,
                                 forecast_unit = NULL,
                                 observed = NULL,
@@ -113,10 +113,9 @@ as_forecast_generic <- function(data,
 #' forecast types and expected input formats by calling `?`[as_forecast()].
 #' @export
 #' @inheritParams as_forecast
-#' @seealso [as_forecast()], [as_forecast_point()], [as_forecast_binary()],
-#'   [as_forecast_sample()], [as_forecast_quantile()]
+#' @family functions to create forecast objects
 #' @importFrom cli cli_warn
-#' @keywords check-forecasts
+#' @keywords as_forecast
 as_forecast_binary <- function(data,
                                forecast_unit = NULL,
                                observed = NULL,
@@ -135,10 +134,9 @@ as_forecast_binary <- function(data,
 #' forecast types and expected input formats by calling `?`[as_forecast()].
 #' @inherit as_forecast params
 #' @param ... Unused
-#' @seealso [as_forecast()], [as_forecast_point()], [as_forecast_binary()],
-#'   [as_forecast_sample()], [as_forecast_quantile()]
+#' @family functions to create forecast objects
 #' @export
-#' @keywords check-forecasts
+#' @keywords as_forecast transform
 as_forecast_point <- function(data, ...) {
   UseMethod("as_forecast_point")
 }
@@ -165,7 +163,7 @@ as_forecast_point.default <- function(data,
 #' When converting a `forecast_quantile` object into a `forecast_point` object,
 #' the 0.5 quantile is extracted and returned as the point forecast.
 #' @export
-#' @keywords check-forecasts
+#' @keywords as_forecast
 as_forecast_point.forecast_quantile <- function(data, ...) {
   assert_forecast(data, verbose = FALSE)
   assert_subset(0.5, unique(data$quantile_level))
@@ -183,11 +181,10 @@ as_forecast_point.forecast_quantile <- function(data, ...) {
 #' Create a `forecast` object for quantile-based forecasts. See more information
 #' on forecast types and expected input formats by calling `?`[as_forecast()].
 #' @param ... Unused
-#' @seealso [as_forecast()], [as_forecast_point()], [as_forecast_binary()],
-#'   [as_forecast_sample()], [as_forecast_quantile()]
+#' @family functions to create forecast objects
 #' @inheritParams as_forecast
 #' @export
-#' @keywords check-forecasts
+#' @keywords as_forecast transform
 as_forecast_quantile <- function(data, ...) {
   UseMethod("as_forecast_quantile")
 }
@@ -270,10 +267,9 @@ as_forecast_quantile.forecast_sample <- function(
 #'   sample-based forecasts.
 #' @inheritParams as_forecast
 #' @export
-#' @seealso [as_forecast()], [as_forecast_point()], [as_forecast_binary()],
-#'   [as_forecast_sample()], [as_forecast_quantile()]
+#' @family functions to create forecast objects
 #' @importFrom cli cli_warn
-#' @keywords check-forecasts
+#' @keywords as_forecast
 as_forecast_sample <- function(data,
                                forecast_unit = NULL,
                                observed = NULL,
@@ -312,7 +308,7 @@ as_forecast_sample <- function(data,
 #' @importFrom data.table ':=' is.data.table
 #' @importFrom checkmate assert_data_frame
 #' @export
-#' @keywords check-forecasts
+#' @keywords validate-forecast-object
 #' @examples
 #' forecast <- as_forecast_binary(example_binary)
 #' assert_forecast(forecast)
@@ -326,7 +322,7 @@ assert_forecast <- function(
 #' @importFrom cli cli_abort
 #' @rdname assert_forecast
 #' @export
-#' @keywords check-forecasts
+#' @keywords validate-forecast-object
 assert_forecast.default <- function(
   forecast, forecast_type = NULL, verbose = TRUE, ...
 ) {
@@ -342,7 +338,7 @@ assert_forecast.default <- function(
 #' @export
 #' @rdname assert_forecast
 #' @importFrom cli cli_abort
-#' @keywords check-forecasts
+#' @keywords validate-forecast-object
 assert_forecast.forecast_binary <- function(
   forecast, forecast_type = NULL, verbose = TRUE, ...
 ) {
@@ -379,7 +375,7 @@ assert_forecast.forecast_binary <- function(
 #' @export
 #' @rdname assert_forecast
 #' @importFrom cli cli_abort
-#' @keywords check-forecasts
+#' @keywords validate-forecast-object
 assert_forecast.forecast_point <- function(
   forecast, forecast_type = NULL, verbose = TRUE, ...
 ) {
@@ -402,7 +398,7 @@ assert_forecast.forecast_point <- function(
 
 #' @export
 #' @rdname assert_forecast
-#' @keywords check-forecasts
+#' @keywords validate-forecast-object
 assert_forecast.forecast_quantile <- function(
   forecast, forecast_type = NULL, verbose = TRUE, ...
 ) {
@@ -415,7 +411,7 @@ assert_forecast.forecast_quantile <- function(
 
 #' @export
 #' @rdname assert_forecast
-#' @keywords check-forecasts
+#' @keywords validate-forecast-object
 assert_forecast.forecast_sample <- function(
   forecast, forecast_type = NULL, verbose = TRUE, ...
 ) {
@@ -433,7 +429,7 @@ assert_forecast.forecast_sample <- function(
 #' `NULL`. See [as_forecast()] for details on the expected input formats.
 #' @inherit assert_forecast params return examples
 #' @export
-#' @keywords check-forecasts
+#' @keywords validate-forecast-object
 validate_forecast <- function(forecast, forecast_type = NULL, verbose = TRUE) {
   assert_forecast(forecast, forecast_type, verbose)
   return(forecast)
@@ -573,7 +569,7 @@ new_forecast <- function(data, classname) {
 #' *`is_forecast_<type>*`*: `TRUE` if the object is of class `forecast_*` in addition
 #' to class `forecast`, `FALSE` otherwise.
 #' @export
-#' @keywords check-forecasts
+#' @keywords validate-forecast-object
 #' @examples
 #' forecast_binary <- as_forecast_binary(example_binary)
 #' is_forecast(forecast_binary)
@@ -583,28 +579,28 @@ is_forecast <- function(x) {
 
 #' @export
 #' @rdname is_forecast
-#' @keywords check-forecasts
+#' @keywords validate-forecast-object
 is_forecast_sample <- function(x) {
   inherits(x, "forecast_sample") && inherits(x, "forecast")
 }
 
 #' @export
 #' @rdname is_forecast
-#' @keywords check-forecasts
+#' @keywords validate-forecast-object
 is_forecast_binary <- function(x) {
   inherits(x, "forecast_binary") && inherits(x, "forecast")
 }
 
 #' @export
 #' @rdname is_forecast
-#' @keywords check-forecasts
+#' @keywords validate-forecast-object
 is_forecast_point <- function(x) {
   inherits(x, "forecast_point") && inherits(x, "forecast")
 }
 
 #' @export
 #' @rdname is_forecast
-#' @keywords check-forecasts
+#' @keywords validate-forecast-object
 is_forecast_quantile <- function(x) {
   inherits(x, "forecast_quantile") && inherits(x, "forecast")
 }
diff --git a/R/get_-functions.R b/R/get_-functions.R
@@ -12,7 +12,7 @@
 #' Character vector of length one with either "binary", "quantile",
 #' "sample" or "point".
 #' @export
-#' @keywords check-forecasts
+#' @keywords diagnose-inputs
 get_forecast_type <- function(data) {
   assert_data_frame(data)
   assert(check_columns_present(data, c("observed", "predicted")))
@@ -186,7 +186,7 @@ get_type <- function(x) {
 #' @return
 #' Character vector with the names of the scoring rules that were used
 #' for scoring or `NULL` if no scores were computed previously.
-#' @keywords check-forecasts
+#' @keywords handle-metrics
 #' @export
 get_metrics <- function(scores, error = FALSE) {
   assert_data_frame(scores)
@@ -235,7 +235,7 @@ get_metrics <- function(scores, error = FALSE) {
 #' a single forecast
 #' @importFrom checkmate assert_data_frame
 #' @export
-#' @keywords check-forecasts
+#' @keywords diagnose-inputs
 get_forecast_unit <- function(data) {
   assert_data_frame(data)
   protected_columns <- get_protected_columns(data)
@@ -298,7 +298,7 @@ get_protected_columns <- function(data = NULL) {
 #' @export
 #' @importFrom checkmate assert_data_frame assert_subset
 #' @importFrom data.table setorderv
-#' @keywords check-forecasts
+#' @keywords diagnose-inputs
 #' @examples
 #' example <- rbind(example_quantile, example_quantile[1000:1010])
 #' get_duplicate_forecasts(example)
@@ -464,7 +464,7 @@ get_coverage <- function(forecast, by = "model") {
 #' @inheritParams score
 #' @importFrom data.table .I .N nafill
 #' @export
-#' @keywords check-forecasts
+#' @keywords gain-insights
 #' @examples
 #' \dontshow{
 #'   data.table::setDTthreads(2) # restricts number of cores used on CRAN

diff --git a/R/print.R b/R/print.R
@@ -10,7 +10,7 @@
 #' @return Returns `x` invisibly.
 #' @importFrom cli cli_inform cli_warn col_blue cli_text
 #' @export
-#' @keywords check-forecasts
+#' @keywords gain-insights
 #' @examples
 #' dat <- as_forecast_quantile(example_quantile)
 #' print(dat)

diff --git a/R/score.R b/R/score.R
@@ -55,6 +55,7 @@
 #' scores.
 #' @importFrom data.table ':=' as.data.table
 #' @importFrom stats na.omit
+#' @keywords scoring
 #' @examples
 #' library(magrittr) # pipe operator
 #' \dontshow{

diff --git a/R/utils.R b/R/utils.R
@@ -18,7 +18,7 @@
 #' @importFrom cli cli_warn
 #' @importFrom checkmate assert_function
 #' @return The result of `fun` or `NULL` if `fun` errors
-#' @keywords scoring
+#' @keywords internal
 #' @examples
 #' f <- function(x) {x}
 #' scoringutils:::run_safely(2, fun = f, metric_name = "f")

diff --git a/README.Rmd b/README.Rmd
@@ -10,8 +10,7 @@ output:
 [![codecov](https://codecov.io/github/epiforecasts/scoringutils/branch/main/graph/badge.svg)](https://app.codecov.io/gh/epiforecasts/scoringutils) 
 [![CRAN\_Release\_Badge](https://www.r-pkg.org/badges/version-ago/scoringutils)](https://CRAN.R-project.org/package=scoringutils)
 ![GitHub R package version](https://img.shields.io/github/r-package/v/epiforecasts/scoringutils)
-[![metacran
-downloads](http://cranlogs.r-pkg.org/badges/grand-total/scoringutils)](https://cran.r-project.org/package=scoringutils)
+[![metacran downloads](http://cranlogs.r-pkg.org/badges/grand-total/scoringutils)](https://cran.r-project.org/package=scoringutils)
 <!-- badges: end -->
 
 
@@ -204,4 +203,4 @@ All contributions to this project are gratefully acknowledged using the [`allcon
 
 <!-- markdownlint-enable -->
 <!-- prettier-ignore-end -->
-<!-- ALL-CONTRIBUTORS-LIST:END -->
+<!-- ALL-CONTRIBUTORS-LIST:END -->
diff --git a/README.md b/README.md
@@ -262,7 +262,9 @@ Health.
 ## Contributors
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+
 <!-- prettier-ignore-start -->
+
 <!-- markdownlint-disable -->
 
 All contributions to this project are gratefully acknowledged using the
@@ -300,5 +302,7 @@ Contributions of any kind are welcome!
 <a href="https://github.com/epiforecasts/scoringutils/issues?q=is%3Aissue+commenter%3Akathsherratt">kathsherratt</a>
 
 <!-- markdownlint-enable -->
+
 <!-- prettier-ignore-end -->
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->