minor changes pre submission

Author: dazzimonti

R/bayesRecon-package.R

@@ -2,11 +2,15 @@
 #'
 #' The package implements reconciliation via conditioning for probabilistic forecasts of hierarchical time series. The main functions are
 #'
-#' * [reconc_gaussian]: implements analytic formulae for the reconciliation of Gaussian base forecasts.
+#' * [reconc_gaussian]: implements analytic formulae for the reconciliation of Gaussian base forecasts;
 #' * [reconc_BUIS]: a generic tool for the reconciliation of any probabilistic time series forecast via importance sampling;
-#'    this is the recommended option for non-Gaussian base forecasts.
+#'    this is the recommended option for non-Gaussian base forecasts;
 #' * [reconc_MCMC]: a generic tool for the reconciliation of probabilistic count time series forecasts via Markov Chain Monte Carlo.
 #'
+#' @section Utility functions:
+#'
+#' * [temporal_aggregation]: creates a list of aggregated time series from a time series of class \link[stats]{ts};
+#' * [get_reconc_matrices]: creates the aggregation and summing matrices for a temporal hierarchy of time series from user-selected list of aggregation levels.
 #'
 #' @references
 #' Corani, G., Azzimonti, D., Augusto, J.P.S.C., Zaffalon, M. (2021). *Probabilistic Reconciliation of Hierarchical Forecast via Bayes’ Rule*. In: Hutter, F., Kersting, K., Lijffijt, J., Valera, I. (eds) Machine Learning and Knowledge Discovery in Databases. ECML PKDD 2020. Lecture Notes in Computer Science(), vol 12459. Springer, Cham. \doi{10.1007/978-3-030-67664-3_13}.

R/hierarchy.R

@@ -182,36 +182,36 @@
 #' @description
 #' Creates a list of aggregated time series from a time series of class \link[stats]{ts}.
 #'
-#' @param y Univariate time series of class \link[stats]{ts}.
-#' @param aggf User-selected list of aggregation levels.
+#' @param y univariate time series of class \link[stats]{ts}.
+#' @param agg_levels user-selected list of aggregation levels.
 #'
 #' @details
-#' If `aggf=NULL` then `aggf` is automatically generated by taking all the factors of the time series frequency.
+#' If `agg_levels=NULL` then `agg_levels` is automatically generated by taking all the factors of the time series frequency.
 #'
-#' @return A list of \link[stats]{ts} objects each containing the aggregates time series in the order defined by `aggf`.
+#' @return A list of \link[stats]{ts} objects each containing the aggregates time series in the order defined by `agg_levels`.
 #'
-#' @seealso [get_reconc_matrices()]
+#' @seealso [get_reconc_matrices]
 #' @export
-temporal_aggregation <- function(y, aggf=NULL) {
+temporal_aggregation <- function(y, agg_levels=NULL) {
   f = stats::frequency(y)
   L = length(y)
   s = stats::time(y)[1]
-  if (is.null(aggf)) {
-    aggf = c()
+  if (is.null(agg_levels)) {
+    agg_levels = c()
     for (i in 1:f) {
       if (f %% i == 0 && L >= i) {
-        aggf = c(aggf, i)
+        agg_levels = c(agg_levels, i)
       }
     }
   } else {
-    aggf = sort(aggf[aggf <= L])
-    if (!(1 %in% aggf)) {
-      aggf = c(1, aggf)
+    agg_levels = sort(agg_levels[agg_levels <= L])
+    if (!(1 %in% agg_levels)) {
+      agg_levels = c(1, agg_levels)
     }
   }
   out = list()
-  for (i in 1:length(aggf)) {
-    k = aggf[i]
+  for (i in 1:length(agg_levels)) {
+    k = agg_levels[i]
     num_aggs = floor(L / k)
     y_trunc = y[(L - num_aggs*k + 1):L]
     y_matrix = matrix(y_trunc, nrow = k, ncol = num_aggs)
@@ -220,7 +220,7 @@ temporal_aggregation <- function(y, aggf=NULL) {
     y_agg = stats::ts(data = apply(y_matrix, 2, sum), frequency = y_f, start = y_start)
     out[[i]] = y_agg
   }
-  names(out) <- paste0("f=", f / aggf)
+  names(out) <- paste0("f=", f / agg_levels)
   out = rev(out)
   return(out)
 }
@@ -231,10 +231,10 @@ temporal_aggregation <- function(y, aggf=NULL) {
 #' Creates the aggregation and summing matrices for a temporal hierarchy of time series
 #' from user-selected list of aggregation levels.
 #'
-#' @param aggf User-selected list of aggregation levels.
-#' @param h Number of steps ahead for the bottom level forecasts.
+#' @param agg_levels user-selected list of aggregation levels.
+#' @param h number of steps ahead for the bottom level forecasts.
 #'
-#' @return A list containing the named elements
+#' @return A list containing the named elements:
 #'
 #' * `A` the aggregation matrix;
 #' * `S` the summing matrix.
@@ -244,19 +244,19 @@ temporal_aggregation <- function(y, aggf=NULL) {
 #'library(bayesRecon)
 #'
 #'#Create monthly hierarchy
-#'aggf <- c(1,2,3,4,6,12)
+#'agg_levels <- c(1,2,3,4,6,12)
 #'h <- 12
-#'rec_mat <- get_reconc_matrices(aggf, h)
+#'rec_mat <- get_reconc_matrices(agg_levels, h)
 #'S <- rec_mat$S
 #'A <- rec_mat$A
 #'
-#' @seealso [temporal_aggregation()]
+#' @seealso [temporal_aggregation]
 #'
 #' @export
-get_reconc_matrices <- function(aggf, h) {
+get_reconc_matrices <- function(agg_levels, h) {
   A = list()
-  for (i in 1:length(aggf)) {
-    k = aggf[i]
+  for (i in 1:length(agg_levels)) {
+    k = agg_levels[i]
     if (k==1) {
       next
     }

R/reconc.R

@@ -112,7 +112,7 @@
 #'library(bayesRecon)
 #'
 #'# Create a minimal hierarchy with 2 bottom and 1 upper variable
-#'rec_mat <- get_reconc_matrices(aggf=c(1,2), h=2)
+#'rec_mat <- get_reconc_matrices(agg_levels=c(1,2), h=2)
 #'S <- rec_mat$S
 #'
 #'
@@ -178,7 +178,7 @@
 #'
 #'
 #' @seealso
-#' [reconc_gaussian()]
+#' [reconc_gaussian]
 #'
 #' @export
 reconc_BUIS <- function(S,
@@ -313,7 +313,7 @@ reconc_BUIS <- function(S,
 #'library(bayesRecon)
 #'
 #'# Create a minimal hierarchy with 2 bottom and 1 upper variable
-#'rec_mat <- get_reconc_matrices(aggf=c(1,2), h=2)
+#'rec_mat <- get_reconc_matrices(agg_levels=c(1,2), h=2)
 #'S <- rec_mat$S
 #'
 #'#Set the parameters of the Gaussian base forecast distributions
@@ -342,7 +342,7 @@ reconc_BUIS <- function(S,
 #' Zambon, L., Agosto, A., Giudici, P., Corani, G. (2023). *Properties of the reconciled distributions for Gaussian and count forecasts*. \doi{10.48550/arXiv.2303.15135}.
 #'
 #'
-#' @seealso [reconc_BUIS()]
+#' @seealso [reconc_BUIS]
 #'
 #' @export
 reconc_gaussian <- function(S, base_forecasts.mu,

R/reconc_MH.R

@@ -7,7 +7,7 @@
 #' forecast distribution, which is obtained via conditioning.
 #' It only works with Poisson or Negative Binomial base forecasts.
 #'
-#' We strongly recommend to use the function [reconc_BUIS()], which implements
+#' We strongly recommend to use the function [reconc_BUIS], which implements
 #' the Bottom-Up Importance Sampling algorithm instead of MCMC.
 #' If you use this function, we suggest the usage of tools to check the convergence.
 #'
@@ -43,7 +43,7 @@
 #'library(bayesRecon)
 #'
 #'# Create a minimal hierarchy with 2 bottom and 1 upper variable
-#'rec_mat <- get_reconc_matrices(aggf=c(1,2), h=2)
+#'rec_mat <- get_reconc_matrices(agg_levels=c(1,2), h=2)
 #'S <- rec_mat$S
 #'
 #'#Set the parameters of the Poisson base forecast distributions
@@ -75,7 +75,7 @@
 #'
 #'
 #' @seealso
-#' [reconc_BUIS()]
+#' [reconc_BUIS]
 #'
 #' @export
 reconc_MCMC <- function(S,

README.Rmd

@@ -44,7 +44,7 @@ which can be obtained using the function `get_reconc_matrices`.
 ```{r}
 library(bayesRecon)
 
-rec_mat <- get_reconc_matrices(aggf=c(1,2), h=2)
+rec_mat <- get_reconc_matrices(agg_levels=c(1,2), h=2)
 S <- rec_mat$S
 print(S)
 ```

README.md

@@ -34,7 +34,7 @@ obtained using the function `get_reconc_matrices`.
 ``` r
 library(bayesRecon)
 
-rec_mat <- get_reconc_matrices(aggf=c(1,2), h=2)
+rec_mat <- get_reconc_matrices(agg_levels=c(1,2), h=2)
 S <- rec_mat$S
 print(S)
 #>      [,1] [,2]

examples/hydepark.R

@@ -31,8 +31,8 @@ train = window(HydePark.ts, end = c(1973, 12))
 test = window(HydePark.ts, start = c(1974))
 
 ### Build hierarchy
-aggf = c(1,2,3,4,6,12)
-train.aggregate = bayesRecon::temporal_aggregation(train, aggf)
+agg_levels = c(1,2,3,4,6,12)
+train.aggregate = bayesRecon::temporal_aggregation(train, agg_levels)
 levels <- attributes(train.aggregate)$names
 
 ### Hierarchical forecasting
@@ -58,7 +58,7 @@ for (l in seq_along(train.aggregate)) {
 }
 
 ### Reconciliation
-tmp = bayesRecon::get_reconc_matrices(aggf, bottom.f = frequency(train), bottom.H = 12)
+tmp = bayesRecon::get_reconc_matrices(agg_levels, bottom.f = frequency(train), bottom.H = 12)
 S = tmp$S
 A = tmp$A
 reconc.res = bayesRecon::reconc_IS(S, base_forecasts = fc.samples, in_type = "samples", distr = "discrete")