diff --git a/R/reconciliation.R b/R/reconciliation.R index 71e8ba36..1a025c9f 100644 --- a/R/reconciliation.R +++ b/R/reconciliation.R @@ -1,7 +1,16 @@ #' Forecast reconciliation #' -#' This function allows you to specify the method used to reconcile forecasts -#' in accordance with its key structure. +#' This function allows you to specify the method for reconciling forecasts for +#' hierarchical or grouped time series. `aggregate_key()` specifies the +#' relationships between the series. After an aggregated `tsibble` is modeled, +#' `reconcile()` defines the reconciliation algorithm, which is applied to the +#' individual and aggregated forecasts for each forecast horizon. +#' +#' Forecast reconciliation ensures that the relationships between time series +#' (e.g. that a national forecast equals the sum of regional forecasts within +#' that nation) are maintained in the forecasts. Specific reconciliation methods +#' may have different constraints. For example, some only work with aggregations +#' that are summations. #' #' @param .data A mable. #' @param ... Reconciliation methods applied to model columns within `.data`. @@ -31,8 +40,11 @@ reconcile.mdl_df <- function(.data, ...){ #' Minimum trace forecast reconciliation #' -#' Reconciles a hierarchy using the minimum trace combination method. The -#' response variable of the hierarchy must be aggregated using sums. The +#' Reconciles a hierarchy using the minimum trace combination method. This +#' approach minimizes the mean squared error of the coherent forecasts across +#' the entire collection of time series under the assumption of unbiasedness. +#' +#' The response variable of the hierarchy must be aggregated using sums. The #' forecasted time points must match for all series in the hierarchy (caution: #' this is not yet tested for beyond the series length). #' @@ -43,7 +55,8 @@ reconcile.mdl_df <- function(.data, ...){ #' package is installed. #' #' @seealso -#' [`reconcile()`], [`aggregate_key()`] +#' [`reconcile()`], [`aggregate_key()`], +#' \url{https://otexts.com/fpp2/reconciliation.html} #' #' @references #' Wickramasuriya, S. L., Athanasopoulos, G., & Hyndman, R. J. (2019). Optimal forecast reconciliation for hierarchical and grouped time series through trace minimization. Journal of the American Statistical Association, 1-45. https://doi.org/10.1080/01621459.2018.1448825 @@ -166,14 +179,19 @@ forecast.lst_mint_mdl <- function(object, key_data, #' #' \lifecycle{experimental} #' -#' Reconciles a hierarchy using the bottom up reconciliation method. The -#' response variable of the hierarchy must be aggregated using sums. The +#' Reconciles a hierarchy using the bottom up reconciliation method. This +#' method generates forecasts for all time series at the lowest level, then +#' sums them according to the aggregation to create forecasts for each level +#' of aggregation. +#' +#' The response variable of the hierarchy must be aggregated using sums. The #' forecasted time points must match for all series in the hierarchy. #' #' @param models A column of models in a mable. #' #' @seealso -#' [`reconcile()`], [`aggregate_key()`] +#' [`reconcile()`], [`aggregate_key()`], +#' \url{https://otexts.com/fpp2/bottom-up.html} #' @export bottom_up <- function(models){ structure(models, class = c("lst_btmup_mdl", "lst_mdl", "list")) @@ -213,15 +231,20 @@ forecast.lst_btmup_mdl <- function(object, key_data, #' #' \lifecycle{experimental} #' -#' Reconciles a hierarchy using the top down reconciliation method. The -#' response variable of the hierarchy must be aggregated using sums. The +#' Reconciles a hierarchy using the top down reconciliation method. This method +#' generates forecasts for the highest level, then disaggregates these +#' forecasts to lower levels using the disaggregation specified in the `method` +#' argument. +#' +#' The response variable of the hierarchy must be aggregated using sums. The #' forecasted time points must match for all series in the hierarchy. #' #' @param models A column of models in a mable. #' @param method The reconciliation method to use. #' #' @seealso -#' [`reconcile()`], [`aggregate_key()`] +#' [`reconcile()`], [`aggregate_key()`], +#' \url{https://otexts.com/fpp2/top-down.html} #' #' @export top_down <- function(models, method = c("forecast_proportions", "average_proportions", "proportion_averages")){ diff --git a/man/bottom_up.Rd b/man/bottom_up.Rd index 286da787..be060c39 100644 --- a/man/bottom_up.Rd +++ b/man/bottom_up.Rd @@ -13,10 +13,15 @@ bottom_up(models) \lifecycle{experimental} } \details{ -Reconciles a hierarchy using the bottom up reconciliation method. The -response variable of the hierarchy must be aggregated using sums. The +Reconciles a hierarchy using the bottom up reconciliation method. This +method generates forecasts for all time series at the lowest level, then +sums them according to the aggregation to create forecasts for each level +of aggregation. + +The response variable of the hierarchy must be aggregated using sums. The forecasted time points must match for all series in the hierarchy. } \seealso{ -\code{\link[=reconcile]{reconcile()}}, \code{\link[=aggregate_key]{aggregate_key()}} +\code{\link[=reconcile]{reconcile()}}, \code{\link[=aggregate_key]{aggregate_key()}}, +\url{https://otexts.com/fpp2/bottom-up.html} } diff --git a/man/min_trace.Rd b/man/min_trace.Rd index 4106c528..fd72de2d 100644 --- a/man/min_trace.Rd +++ b/man/min_trace.Rd @@ -20,8 +20,12 @@ matrix algebra? By default, sparse matrices will be used if the MatrixM package is installed.} } \description{ -Reconciles a hierarchy using the minimum trace combination method. The -response variable of the hierarchy must be aggregated using sums. The +Reconciles a hierarchy using the minimum trace combination method. This +approach minimizes the mean squared error of the coherent forecasts across +the entire collection of time series under the assumption of unbiasedness. +} +\details{ +The response variable of the hierarchy must be aggregated using sums. The forecasted time points must match for all series in the hierarchy (caution: this is not yet tested for beyond the series length). } @@ -29,5 +33,6 @@ this is not yet tested for beyond the series length). Wickramasuriya, S. L., Athanasopoulos, G., & Hyndman, R. J. (2019). Optimal forecast reconciliation for hierarchical and grouped time series through trace minimization. Journal of the American Statistical Association, 1-45. https://doi.org/10.1080/01621459.2018.1448825 } \seealso{ -\code{\link[=reconcile]{reconcile()}}, \code{\link[=aggregate_key]{aggregate_key()}} +\code{\link[=reconcile]{reconcile()}}, \code{\link[=aggregate_key]{aggregate_key()}}, +\url{https://otexts.com/fpp2/reconciliation.html} } diff --git a/man/reconcile.Rd b/man/reconcile.Rd index 9abbb5d4..673bdcc3 100644 --- a/man/reconcile.Rd +++ b/man/reconcile.Rd @@ -15,8 +15,18 @@ reconcile(.data, ...) \item{...}{Reconciliation methods applied to model columns within \code{.data}.} } \description{ -This function allows you to specify the method used to reconcile forecasts -in accordance with its key structure. +This function allows you to specify the method for reconciling forecasts for +hierarchical or grouped time series. \code{aggregate_key()} specifies the +relationships between the series. After an aggregated \code{tsibble} is modeled, +\code{reconcile()} defines the reconciliation algorithm, which is applied to the +individual and aggregated forecasts for each forecast horizon. +} +\details{ +Forecast reconciliation ensures that the relationships between time series +(e.g. that a national forecast equals the sum of regional forecasts within +that nation) are maintained in the forecasts. Specific reconciliation methods +may have different constraints. For example, some only work with aggregations +that are summations. } \examples{ if (requireNamespace("fable", quietly = TRUE)) { diff --git a/man/top_down.Rd b/man/top_down.Rd index 4c589dd6..2683fcac 100644 --- a/man/top_down.Rd +++ b/man/top_down.Rd @@ -18,10 +18,15 @@ top_down( \lifecycle{experimental} } \details{ -Reconciles a hierarchy using the top down reconciliation method. The -response variable of the hierarchy must be aggregated using sums. The +Reconciles a hierarchy using the top down reconciliation method. This method +generates forecasts for the highest level, then disaggregates these +forecasts to lower levels using the disaggregation specified in the \code{method} +argument. + +The response variable of the hierarchy must be aggregated using sums. The forecasted time points must match for all series in the hierarchy. } \seealso{ -\code{\link[=reconcile]{reconcile()}}, \code{\link[=aggregate_key]{aggregate_key()}} +\code{\link[=reconcile]{reconcile()}}, \code{\link[=aggregate_key]{aggregate_key()}}, +\url{https://otexts.com/fpp2/top-down.html} }