Merge branch 'main' into fix-printing-issue

R/class-forecast-binary.R

@@ -1,12 +1,35 @@
 #' @title Create a `forecast` object for binary forecasts
-#' @description
-#' Create a `forecast` object for binary forecasts. See more information on
-#' forecast types and expected input formats by calling `?`[as_forecast()].
-#' @export
-#' @inheritParams as_forecast
+#' @inherit as_forecast_doc_template params description
+#' @details
+#' # Required input
+#'
+#' The input needs to be a data.frame or similar with the following columns:
+#' - `observed`: `factor` with exactly two levels representing the observed
+#'   values. The highest factor level is assumed to be the reference level.
+#'   This means that corresponding value in `predicted` represent the
+#'   probability that the observed value is equal to the highest factor level.
+#' - `predicted`: `numeric` with predicted probabilities, representing
+#'   the probability that the corresponding value in `observed` is equal to
+#'   the highest available factor level.
+#'
+#' For convenience, we recommend an additional column `model` holding the name
+#' of the forecaster or model that produced a prediction, but this is not
+#' strictly necessary.
+#'
+#' See the [example_binary] data set for an example.
+#' @inheritSection forecast_types Forecast unit
+#' @returns A `forecast` object of class `forecast_binary`
 #' @family functions to create forecast objects
 #' @importFrom cli cli_warn
 #' @keywords as_forecast
+#' @export
+#' @examples
+#' as_forecast_binary(
+#'   example_binary,
+#'   predicted = "predicted",
+#'   forecast_unit = c("model", "target_type", "target_end_date",
+#'                     "horizon", "location")
+#' )
 as_forecast_binary <- function(data,
                                forecast_unit = NULL,
                                observed = NULL,
@@ -90,7 +113,7 @@ score.forecast_binary <- function(forecast, metrics = get_metrics(forecast), ...
 #' - "log_score" = [logs_binary()]
 #' @inheritSection illustration-input-metric-binary-point Input format
 #' @param x A forecast object (a validated data.table with predicted and
-#'   observed values, see [as_forecast()]).
+#'   observed values, see [as_forecast_binary()]).
 #' @param select A character vector of scoring rules to select from the list. If
 #'   `select` is `NULL` (the default), all possible scoring rules are returned.
 #' @param exclude A character vector of scoring rules to exclude from the list.
@@ -128,8 +151,8 @@ get_metrics.forecast_binary <- function(x, select = NULL, exclude = NULL, ...) {
 #' The data was created using the script create-example-data.R in the inst/
 #' folder (or the top level folder in a compiled package).
 #'
-#' @format An object of class `forecast_binary` (see [as_forecast()]) with the
-#' following columns:
+#' @format An object of class `forecast_binary` (see [as_forecast_binary()])
+#' with the following columns:
 #' \describe{
 #'   \item{location}{the country for which a prediction was made}
 #'   \item{location_name}{name of the country for which a prediction was made}

R/class-forecast-nominal.R

@@ -1,16 +1,45 @@
 #' @title Create a `forecast` object for nominal forecasts
-#' @description
-#' Nominal forecasts are a form of categorical forecasts where the possible
-#' outcomes that the observed values can assume are not ordered. In that sense,
-#' Nominal forecasts represent a generalisation of binary forecasts.
-#' @inheritParams as_forecast
+#' @inherit as_forecast_doc_template params description
+#' @details
+#' Nominal forecasts are a form of categorical forecasts and represent a
+#' generalisation of binary forecasts to multiple outcomes. The possible
+#' outcomes that the observed values can assume are not ordered.
+#'
+#' # Required input
+#'
+#' The input needs to be a data.frame or similar with the following columns:
+#' - `observed`: Column with observed values of type `factor` with N levels,
+#'    where N is the number of possible outcomes.
+#'    The levels of the factor represent the possible outcomes that
+#'    the observed values can assume.
+#' - `predicted`: `numeric` column with predicted probabilities. The values
+#'    represent the probability that the observed value is equal to the factor
+#'    level denoted in `predicted_label`. Note that forecasts must be complete,
+#'    i.e. there must be a probability assigned to every possible outcome and
+#'    those probabilities must sum to one.
+#' - `predicted_label`: `factor` with N levels, denoting the outcome that the
+#'    probabilities in `predicted` correspond to.
+#'
+#' For convenience, we recommend an additional column `model` holding the name
+#' of the forecaster or model that produced a prediction, but this is not
+#' strictly necessary.
+#'
+#' See the [example_nominal] data set for an example.
+#' @inheritSection forecast_types Forecast unit
 #' @param predicted_label (optional) Name of the column in `data` that denotes
 #'   the outcome to which a predicted probability corresponds to.
-#'   This column will be renamed to "predicted_label". Only applicable to
-#'   nominal forecasts.
+#'   This column will be renamed to "predicted_label".
+#' @returns A `forecast` object of class `forecast_nominal`
 #' @family functions to create forecast objects
 #' @keywords as_forecast
 #' @export
+#' @examples
+#' as_forecast_nominal(
+#'   na.omit(example_nominal),
+#'   predicted = "predicted",
+#'   forecast_unit = c("model", "target_type", "target_end_date",
+#'                     "horizon", "location")
+#' )
 as_forecast_nominal <- function(data,
                                 forecast_unit = NULL,
                                 observed = NULL,
@@ -135,8 +164,8 @@ get_metrics.forecast_nominal <- function(x, select = NULL, exclude = NULL, ...)
 #' The data was created using the script create-example-data.R in the inst/
 #' folder (or the top level folder in a compiled package).
 #'
-#' @format An object of class `forecast_nominal` (see [as_forecast()]) with the
-#' following columns:
+#' @format An object of class `forecast_nominal`
+#' (see [as_forecast_nominal()]) with the following columns:
 #' \describe{
 #'   \item{location}{the country for which a prediction was made}
 #'   \item{target_end_date}{the date for which a prediction was made}

R/class-forecast-point.R

@@ -1,9 +1,19 @@
 #' @title Create a `forecast` object for point forecasts
-#' @description
-#' Create a `forecast` object for point forecasts. See more information on
-#' forecast types and expected input formats by calling `?`[as_forecast()].
-#' @inherit as_forecast params
+#' @inherit as_forecast_doc_template params description
+#' @details
+#' # Required input
+#'
+#' The input needs to be a data.frame or similar with the following columns:
+#' - `observed`: Column of type `numeric` with observed values.
+#' - `predicted`: Column of type `numeric` with predicted values.
+#'
+#' For convenience, we recommend an additional column `model` holding the name
+#' of the forecaster or model that produced a prediction, but this is not
+#' strictly necessary.
+#'
+#' See the [example_point] data set for an example.
 #' @param ... Unused
+#' @returns A `forecast` object of class `forecast_point`
 #' @family functions to create forecast objects
 #' @export
 #' @keywords as_forecast transform
@@ -146,8 +156,8 @@ get_metrics.forecast_point <- function(x, select = NULL, exclude = NULL, ...) {
 #' The data was created using the script create-example-data.R in the inst/
 #' folder (or the top level folder in a compiled package).
 #'
-#' @format An object of class `forecast_point` (see [as_forecast()]) with the
-#' following columns:
+#' @format An object of class `forecast_point` (see [as_forecast_point()])
+#' with the following columns:
 #' \describe{
 #'   \item{location}{the country for which a prediction was made}
 #'   \item{target_end_date}{the date for which a prediction was made}

R/class-forecast-quantile.R

@@ -1,12 +1,34 @@
 #' @title Create a `forecast` object for quantile-based forecasts
-#' @description
-#' Create a `forecast` object for quantile-based forecasts. See more information
-#' on forecast types and expected input formats by calling `?`[as_forecast()].
+#' @inherit as_forecast_doc_template params description
+#' @details
+#' # Required input
+#'
+#' The input needs to be a data.frame or similar with the following columns:
+#' - `observed`: Column of type `numeric` with observed values.
+#' - `predicted`: Column of type `numeric` with predicted values. Predicted
+#'    values represent quantiles of the predictive distribution.
+#' - `quantile_level`: Column of type `numeric`, denoting the quantile level of
+#'    the corresponding predicted value.
+#'    Quantile levels must be between 0 and 1.
+#'
+#' For convenience, we recommend an additional column `model` holding the name
+#' of the forecaster or model that produced a prediction, but this is not
+#' strictly necessary.
+#'
+#' See the [example_quantile] data set for an example.
+#' @inheritSection forecast_types Forecast unit
 #' @param ... Unused
 #' @family functions to create forecast objects
-#' @inheritParams as_forecast
+#' @returns A `forecast` object of class `forecast_quantile`
 #' @export
 #' @keywords as_forecast transform
+#' @examples
+#' as_forecast_quantile(
+#'   example_quantile,
+#'   predicted = "predicted",
+#'   forecast_unit = c("model", "target_type", "target_end_date",
+#'                     "horizon", "location")
+#' )
 as_forecast_quantile <- function(data, ...) {
   UseMethod("as_forecast_quantile")
 }
@@ -237,8 +259,8 @@ get_pit_histogram.forecast_quantile <- function(forecast, num_bins = NULL,
 #' The data was created using the script create-example-data.R in the inst/
 #' folder (or the top level folder in a compiled package).
 #'
-#' @format An object of class `forecast_quantile` (see [as_forecast()]) with the
-#' following columns:
+#' @format An object of class `forecast_quantile`
+#' (see [as_forecast_quantile()]) with the following columns:
 #' \describe{
 #'   \item{location}{the country for which a prediction was made}
 #'   \item{target_end_date}{the date for which a prediction was made}

R/class-forecast-sample.R

@@ -1,9 +1,26 @@
 #' @title Create a `forecast` object for sample-based forecasts
+#' @inherit as_forecast_doc_template params description
+#' @details
+#' # Required input
+#'
+#' The input needs to be a data.frame or similar with the following columns:
+#' - `observed`: Column of type `numeric` with observed values.
+#' - `predicted`: Column of type `numeric` with predicted values. Predicted
+#'    values represent random samples from the predictive distribution.
+#' - `sample_id`: Column of any type with unique identifiers
+#'    (unique within a single forecast) for each sample.
+#'
+#' For convenience, we recommend an additional column `model` holding the name
+#' of the forecaster or model that produced a prediction, but this is not
+#' strictly necessary.
+#'
+#' See the [example_sample_continuous] and [example_sample_discrete] data set
+#' for an example
+#' @inheritSection forecast_types Forecast unit
 #' @param sample_id (optional) Name of the column in `data` that contains the
-#'   sample id. This column will be renamed to "sample_id". Only applicable to
-#'   sample-based forecasts.
-#' @inheritParams as_forecast
+#'   sample id. This column will be renamed to "sample_id".
 #' @export
+#' @returns A `forecast` object of class `forecast_sample`
 #' @family functions to create forecast objects
 #' @importFrom cli cli_warn
 #' @keywords as_forecast
@@ -45,7 +62,7 @@ is_forecast_sample <- function(x) {
 
 
 #' @rdname as_forecast_quantile
-#' @description
+#' @details # Converting from `forecast_sample` to `forecast_quantile`
 #' When creating a `forecast_quantile` object from a `forecast_sample` object,
 #' the quantiles are estimated by computing empircal quantiles from the samples
 #' via [quantile()]. Note that empirical quantiles are a biased estimator for
@@ -223,8 +240,8 @@ get_pit_histogram.forecast_sample <- function(forecast, num_bins = 10,
 #' The data was created using the script create-example-data.R in the inst/
 #' folder (or the top level folder in a compiled package).
 #'
-#' @format An object of class `forecast_sample` (see [as_forecast()]) with the
-#' following columns:
+#' @format An object of class `forecast_sample` (see [as_forecast_sample()])
+#' with the following columns:
 #' \describe{
 #'   \item{location}{the country for which a prediction was made}
 #'   \item{target_end_date}{the date for which a prediction was made}
@@ -251,8 +268,8 @@ get_pit_histogram.forecast_sample <- function(forecast, num_bins = 10,
 #' The data was created using the script create-example-data.R in the inst/
 #' folder (or the top level folder in a compiled package).
 #'
-#' @format An object of class `forecast_sample` (see [as_forecast()]) with the
-#' following columns:
+#' @format An object of class `forecast_sample` (see [as_forecast_sample()])
+#' with the following columns:
 #' \describe{
 #'   \item{location}{the country for which a prediction was made}
 #'   \item{target_end_date}{the date for which a prediction was made}