From 764b0aa42fec2984984641b0e675c0dd49257808 Mon Sep 17 00:00:00 2001 From: David Holt Date: Tue, 8 Jun 2021 16:06:01 -0400 Subject: [PATCH 1/4] add additional documentation for reconcile() --- R/reconciliation.R | 13 +++++++++++-- man/reconcile.Rd | 14 ++++++++++++-- 2 files changed, 23 insertions(+), 4 deletions(-) diff --git a/R/reconciliation.R b/R/reconciliation.R index 71e8ba36..5efbbb8b 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 +#' heirarchical 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`. diff --git a/man/reconcile.Rd b/man/reconcile.Rd index 9abbb5d4..6b22d367 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 +heirarchical 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)) { From 260fcdfc39ef717dd8a674b862a388954e47180e Mon Sep 17 00:00:00 2001 From: David Holt Date: Tue, 8 Jun 2021 16:20:23 -0400 Subject: [PATCH 2/4] add documentation to min_trace --- R/reconciliation.R | 9 ++++++--- man/min_trace.Rd | 8 ++++++-- man/reconcile.Rd | 2 +- 3 files changed, 13 insertions(+), 6 deletions(-) diff --git a/R/reconciliation.R b/R/reconciliation.R index 5efbbb8b..d82ead48 100644 --- a/R/reconciliation.R +++ b/R/reconciliation.R @@ -1,7 +1,7 @@ #' Forecast reconciliation #' #' This function allows you to specify the method for reconciling forecasts for -#' heirarchical or grouped time series. `aggregate_key()` specifies the +#' 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. @@ -40,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). #' diff --git a/man/min_trace.Rd b/man/min_trace.Rd index 4106c528..dc9f459c 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). } diff --git a/man/reconcile.Rd b/man/reconcile.Rd index 6b22d367..673bdcc3 100644 --- a/man/reconcile.Rd +++ b/man/reconcile.Rd @@ -16,7 +16,7 @@ reconcile(.data, ...) } \description{ This function allows you to specify the method for reconciling forecasts for -heirarchical or grouped time series. \code{aggregate_key()} specifies the +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. From 874910fcdd2f2541c4196551ccd46ff85f0814ad Mon Sep 17 00:00:00 2001 From: David Holt Date: Tue, 8 Jun 2021 16:33:25 -0400 Subject: [PATCH 3/4] add topdown and bottomup documentation --- R/reconciliation.R | 16 ++++++++++++---- man/bottom_up.Rd | 8 ++++++-- man/top_down.Rd | 8 ++++++-- 3 files changed, 24 insertions(+), 8 deletions(-) diff --git a/R/reconciliation.R b/R/reconciliation.R index d82ead48..f0609df7 100644 --- a/R/reconciliation.R +++ b/R/reconciliation.R @@ -178,8 +178,12 @@ 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. @@ -225,8 +229,12 @@ 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. diff --git a/man/bottom_up.Rd b/man/bottom_up.Rd index 286da787..620c0738 100644 --- a/man/bottom_up.Rd +++ b/man/bottom_up.Rd @@ -13,8 +13,12 @@ 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{ diff --git a/man/top_down.Rd b/man/top_down.Rd index 4c589dd6..70ccae83 100644 --- a/man/top_down.Rd +++ b/man/top_down.Rd @@ -18,8 +18,12 @@ 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{ From a335eb1c7fe5a7b91f0560f7c35b7bb999e7141d Mon Sep 17 00:00:00 2001 From: David Holt Date: Tue, 8 Jun 2021 16:42:17 -0400 Subject: [PATCH 4/4] add fpp2 urls for reconciliation methods --- R/reconciliation.R | 9 ++++++--- man/bottom_up.Rd | 3 ++- man/min_trace.Rd | 3 ++- man/top_down.Rd | 3 ++- 4 files changed, 12 insertions(+), 6 deletions(-) diff --git a/R/reconciliation.R b/R/reconciliation.R index f0609df7..1a025c9f 100644 --- a/R/reconciliation.R +++ b/R/reconciliation.R @@ -55,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 @@ -189,7 +190,8 @@ forecast.lst_mint_mdl <- function(object, key_data, #' @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")) @@ -241,7 +243,8 @@ forecast.lst_btmup_mdl <- function(object, key_data, #' @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 620c0738..be060c39 100644 --- a/man/bottom_up.Rd +++ b/man/bottom_up.Rd @@ -22,5 +22,6 @@ 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 dc9f459c..fd72de2d 100644 --- a/man/min_trace.Rd +++ b/man/min_trace.Rd @@ -33,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/top_down.Rd b/man/top_down.Rd index 70ccae83..2683fcac 100644 --- a/man/top_down.Rd +++ b/man/top_down.Rd @@ -27,5 +27,6 @@ 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} }