htsrec: Cross-sectional (contemporaneous) forecast reconciliation

Description Usage Arguments Details Value References See Also Examples

View source: R/htsrec.R


Cross-sectional (contemporaneous) forecast reconciliation of a linearly constrained (e.g., hierarchical/grouped) multiple time series. The reconciled forecasts are calculated either through a projection approach (Byron, 1978, see also van Erven and Cugliari, 2015, and Wickramasuriya et al., 2019), or the equivalent structural approach by Hyndman et al. (2011). Moreover, the classic bottom-up approach is available.


htsrec(basef, comb, C, res, Ut, nb, mse = TRUE, corpcor = FALSE,
       type = "M", sol = "direct", keep = "list", nn = FALSE,
       nn_type = "osqp", settings = list(), bounds = NULL, W = NULL)



(\mjseqnh \times n) matrix of base forecasts to be reconciled; \mjseqnh is the forecast horizon and \mjseqnn is the total number of time series.


Type of the reconciliation. Except for Bottom-up, each option corresponds to a specific (\mjseqnn \times n) covariance matrix:

  • bu (Bottom-up);

  • ols (Identity);

  • struc (Structural variances);

  • wls (Series variances) - uses res;

  • shr (Shrunk covariance matrix - MinT-shr) - uses res;

  • sam (Sample covariance matrix - MinT-sam) - uses res;

  • w use your personal matrix W in param W.


(\mjseqnn_a \times n_b) cross-sectional (contemporaneous) matrix mapping the bottom level series into the higher level ones.


(\mjseqnN \times n) in-sample residuals matrix needed when comb = {"wls", "shr", "sam"}. The columns must be in the same order as basef.


Zero constraints cross-sectional (contemporaneous) kernel matrix \mjseqn(\mathbfU'\mathbfy = \mathbf0) spanning the null space valid for the reconciled forecasts. It can be used instead of parameter C, but nb (\mjseqnn = n_a + n_b) is needed if \mjseqn\mathbfU' \neq [\mathbfI \ -\mathbfC]. If the hierarchy admits a structural representation, \mjseqn\mathbfU' has dimension (\mjseqnn_a \times n).


Number of bottom time series; if C is present, nb and Ut are not used.


Logical value: TRUE (default) calculates the covariance matrix of the in-sample residuals (when necessary) according to the original hts and thief formulation: no mean correction, T as denominator.


Logical value: TRUE if corpcor (Schäfer et al., 2017) must be used to shrink the sample covariance matrix according to Schäfer and Strimmer (2005), otherwise the function uses the same implementation as package hts.


Approach used to compute the reconciled forecasts: "M" for the projection approach with matrix M (default), or "S" for the structural approach with summing matrix S.


Solution technique for the reconciliation problem: either "direct" (default) for the closed-form matrix solution, or "osqp" for the numerical solution (solving a linearly constrained quadratic program using solve_osqp).


Return a list object of the reconciled forecasts at all levels (if keep = "list") or only the reconciled forecasts matrix (if keep = "recf").


Logical value: TRUE if non-negative reconciled forecasts are wished.


"osqp" (default), "KAnn" (only type == "M") or "sntz".


Settings for osqp (object osqpSettings). The default options are: verbose = FALSE, eps_abs = 1e-5, eps_rel = 1e-5, polish_refine_iter = 100 and polish = TRUE. For details, see the osqp documentation (Stellato et al., 2019).


(\mjseqnn \times 2) matrix containing the cross-sectional bounds: the first column is the lower bound, and the second column is the upper bound.


This option permits to directly enter the covariance matrix:

  1. W must be a p.d. (\mjseqnn \times n) matrix or a list of \mjseqnh matrix (one for each forecast horizon);

  2. if comb is different from "w", W is not used.



Let \mjseqn\mathbfy be a (\mjseqnn \times 1) vector of target point forecasts which are wished to satisfy the system of linearly independent constraints \mjsdeqn\mathbfU'\mathbfy = \mathbf0_(r \times 1), where \mjseqn\mathbfU' is a (\mjseqnr \times n) matrix, with rank\mjseqn(\mathbfU') = r \leq n, and \mjseqn\mathbf0_(r \times 1) is a (\mjseqnr \times 1) null vector. Let \mjseqn\widehat\mathbfy be a (\mjseqnn \times 1) vector of unbiased point forecasts, not fulfilling the linear constraints (i.e., \mjseqn\mathbfU'\widehat\mathbfy \ne \mathbf0).

We consider a regression-based reconciliation method assuming that \mjseqn\widehat\mathbfy is related to \mjseqn\mathbfy by \mjsdeqn\widehat\mathbfy = \mathbfy + \mathbf\varepsilon, where \mjseqn\mathbf\varepsilon is a (\mjseqnn \times 1) vector of zero mean disturbances, with known p.d. covariance matrix \mjseqn\mathbfW. The reconciled forecasts \mjseqn\widetilde\mathbfy are found by minimizing the generalized least squares (GLS) objective function \mjseqn\left(\widehat\mathbfy - \mathbfy\right)'\mathbfW^-1 \left(\widehat\mathbfy - \mathbfy\right) constrained by \mjseqn\mathbfU'\mathbfy = \mathbf0_(r \times 1):


y = \mboxargmin_\mathbfy \left(\mathbfy - \widehat\mathbfy \right)' \mathbfW^-1 \left(\mathbfy - \widehat\mathbfy \right), \quad \mboxs.t. \mathbfU'\mathbfy = \mathbf0.

The solution is given by \mjsdeqn\widetilde\mathbfy= \widehat\mathbfy - \mathbfW\mathbfU \left(\mathbfU’\mathbfWU\right)^-1\mathbfU'\widehat\mathbfy= \mathbfM\widehat\mathbfy, where \mjseqn\mathbfM = \mathbfI_n - \mathbfW\mathbfU\left( \mathbfU’\mathbfWU\right)^-1\mathbfU’ is a (\mjseqnn \times n) projection matrix. This solution is used by htsrec when type = "M".

Denoting with \mjseqn\mathbfd_\widehat\mathbfy = \mathbf0 - \mathbfU'\widehat\mathbfy the (\mjseqnr \times 1) vector containing the coherency errors of the base forecasts, we can re-state the solution as \mjsdeqn\widetilde\mathbfy= \widehat\mathbfy + \mathbfWU \left( \mathbfU'\mathbfWU\right)^-1\mathbfd_\widehaty, which makes it clear that the reconciliation formula simply adjusts the vector \mjseqn\widehat\mathbfy with a linear combination – according to the smoothing matrix \mjseqn\mathbfL = \mathbfWU \left(\mathbfU’\mathbfWU\right)^-1 – of the coherency errors of the base forecasts.

In addition, if the error term \mjseqn\mathbf\varepsilon is gaussian, the reconciliation error \mjseqn\widetilde\varepsilon = \widetilde\mathbfy - \mathbfy is a zero-mean gaussian vector with covariance matrix \mjsdeqnE\left( \widetilde\mathbfy - \mathbfy\right) \left( \widetilde\mathbfy - \mathbfy\right)' = \mathbfW - \mathbfWU \left(\mathbfU'\mathbfWU\right)^-1\mathbfU' = \mathbfMW.

Hyndman et al. (2011, see also Wickramasuriya et al., 2019) propose an equivalent, alternative formulation as for the reconciled estimates, obtained by GLS estimation of the model \mjsdeqn\widehat\mathbfy = \mathbfS\mathbf\beta + \mathbf\varepsilon, where \mjseqn\mathbfS is the structural summation matrix describing the aggregation relationships operating on \mjseqn\mathbfy, and \mjseqn\mathbf\beta is a subset of \mjseqn\mathbfy containing the target forecasts of the bottom level series, such that \mjseqn\mathbfy = \mathbfS\mathbf\beta. Since the hypotheses on \mjseqn\mathbf\varepsilon remain unchanged, \mjsdeqn\widetilde\mathbf\beta = \left(\mathbfS'\mathbfW^-1\mathbfS \right)^-1\mathbfS'\mathbfW^-1\widehat\mathbfy is the best linear unbiased estimate of \mjseqn\mathbf\beta, and the whole reconciled forecasts vector is given by \mjsdeqn\widetilde\mathbfy = \mathbfS\widetilde\mathbf\beta = \mathbfSG \widehat\mathbfy, where \mjseqn\mathbfG = \left(\mathbfS'\mathbfW^-1 \mathbfS\right)^-1\mathbfS'\mathbfW^-1, and \mjseqn\mathbfM=\mathbfSG. This solution is used by htsrec when type = "S".

Bounds on the reconciled forecasts

The user may impose bounds on the reconciled forecasts. The parameter bounds permits to consider lower (\mjseqn\mathbfa) and upper (\mjseqn\mathbfb) bounds like \mjseqn\mathbfa \leq \widetilde\mathbfy \leq \mathbfb such that: \mjsdeqn \beginarrayc a_1 \leq \widetildey_1 \leq b_1
a_n \leq \widetildey_n \leq b_n
\endarray \Rightarrow \mboxbounds = [\mathbfa \; \mathbfb] = \left[\beginarraycc a_1 & b_1
\vdots & \vdots
a_n & b_n
\endarray\right], where \mjseqna_i \in [- \infty, + \infty] and \mjseqnb_i \in [- \infty, + \infty]. If \mjseqny_i is unbounded, the i-th row of bounds would be equal to c(-Inf, +Inf). Notice that if the bounds parameter is used, sol = "osqp" must be used. This is not true in the case of non-negativity constraints:

In this case it is not necessary to build a matrix containing the bounds, and it is sufficient to set nn = "TRUE".

Non-negative reconciled forecasts may be obtained by setting nn_type alternatively as:


If the parameter keep is equal to "recf", then the function returns only the (\mjseqnh \times n) reconciled forecasts matrix, otherwise (keep="all") it returns a list that mainly depends on what type of representation (type) and solution technique (sol) have been used:


(\mjseqnh \times n) reconciled forecasts matrix, \mjseqn\widetilde\mathbfY.


Covariance matrix used for forecast reconciliation, \mjseqn\mathbfW.


Number of negative values (if zero, there are no values below zero).


Logical value: has the hierarchy been respected?

varf (type="direct")

(\mjseqnn \times 1) reconciled forecasts variance vector for \mjseqnh=1, \mjseqn\mboxdiag(\mathbfMW).

M (type="direct")

Projection matrix, \mjseqn\mathbfM (projection approach).

G (type="S" and type="direct")

Projection matrix, \mjseqn\mathbfG (structural approach, \mjseqn\mathbfM=\mathbfS\mathbfG).

S (type="S" and type="direct")

Cross-sectional summing matrix, \mjseqn\mathbfS.

info (type="osqp")

matrix with information in columns for each forecast horizon \mjseqnh (rows): run time (run_time), number of iteration (iter), norm of primal residual (pri_res), status of osqp's solution (status) and polish's status (status_polish). It will also be returned with nn = TRUE if a solver (see nn_type) will be used.

Only if comb = "bu", the function returns recf, S and M.


Byron, R.P. (1978), The estimation of large social accounts matrices, Journal of the Royal Statistical Society A, 141, 3, 359-367.

Di Fonzo, T., Girolimetto, D. (2020), Cross-Temporal Forecast Reconciliation: Optimal Combination Method and Heuristic Alternatives, Department of Statistical Sciences, University of Padua, arXiv:2006.08570.

Di Fonzo, T., Marini, M. (2011), Simultaneous and two-step reconciliation of systems of time series: methodological and practical issues, Journal of the Royal Statistical Society. Series C (Applied Statistics), 60, 2, 143-164

Hyndman, R.J., Ahmed, R.A., Athanasopoulos, G., Shang, H.L.(2011), Optimal combination forecasts for hierarchical time series, Computational Statistics & Data Analysis, 55, 9, 2579-2589.

Kourentzes, N., Athanasopoulos, G. (2021), Elucidate structure in intermittent demand series, European Journal of Operational Research, 288, 1, pp. 141–152.

Schäfer, J.L., Opgen-Rhein, R., Zuber, V., Ahdesmaki, M., Duarte Silva, A.P., Strimmer, K. (2017), Package ‘corpcor’, R package version 1.6.9 (April 1, 2017), corpcor.

Schäfer, J.L., Strimmer, K. (2005), A Shrinkage Approach to Large-Scale Covariance Matrix Estimation and Implications for Functional Genomics, Statistical Applications in Genetics and Molecular Biology, 4, 1.

Stellato, B., Banjac, G., Goulart, P., Bemporad, A., Boyd, S. (2020). OSQP: An Operator Splitting Solver for Quadratic Programs, Mathematical Programming Computation, 12, 4, 637-672.

Stellato, B., Banjac, G., Goulart, P., Boyd, S., Anderson, E. (2019), OSQP: Quadratic Programming Solver using the ‘OSQP’ Library, R package version (October 10, 2019),

van Erven, T., Cugliari, J. (2015), Game-theoretically Optimal Reconciliation of Contemporaneous Hierarchical Time Series Forecasts, in Antoniadis, A., Poggi, J.M., Brossat, X. (eds.), Modeling and Stochastic Learning for Forecasting in High Dimensions, Berlin, Springer, 297-317.

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, 114, 526, 804-819.

See Also

Other reconciliation procedures: cstrec(), ctbu(), iterec(), lccrec(), octrec(), tcsrec(), tdrec(), thfrec()


# monthly base forecasts
id <- which(simplify2array(strsplit(colnames(FoReco_data$base),split = "_"))[1, ] == "k1")
mbase <- t(FoReco_data$base[, id])
# monthly residuals
id <- which(simplify2array(strsplit(colnames(FoReco_data$res),split = "_"))[1, ] == "k1")
mres <- t(FoReco_data$res[, id])
obj <- htsrec(mbase, C = FoReco_data$C, comb = "shr", res = mres)

# FoReco is able to work also with covariance matrix that are not equal
# across all the forecast horizon. For example, we can consider the
# normalized squared differences (see Di Fonzo and Marini, 2011) where
# Wh = diag(|yh|):
Wh <- lapply(split(mbase, row(mbase)), function(x) diag(abs(x)))

# Now we can introduce the list of the covariance matrix in htsrec throught
# the parameter "W" and setting comb = "w".
objh <- htsrec(mbase, C = FoReco_data$C, W = Wh, comb = "w")

FoReco documentation built on July 23, 2021, 5:06 p.m.