Type:	Package
Title:	Coherent Forecast Combination for Linearly Constrained Multiple Time Series
Version:	0.1.2
Description:	Methods and tools designed to improve the forecast accuracy for a linearly constrained multiple time series, while fulfilling the linear/aggregation relationships linking the components (Girolimetto and Di Fonzo, 2024 <doi:10.48550/arXiv.2412.03429>). 'FoCo2' offers multi-task forecast combination and reconciliation approaches leveraging input from multiple forecasting models or experts and ensuring that the resulting forecasts satisfy specified linear constraints. In addition, linear inequality constraints (e.g., non-negativity of the forecasts) can be imposed, if needed.
License:	GPL (≥ 3)
Encoding:	UTF-8
Depends:	R (≥ 3.4), Matrix, FoReco
Imports:	stats, cli, methods, quadprog, osqp
RoxygenNote:	7.3.2
URL:	https://github.com/danigiro/FoCo2/, https://danigiro.github.io/FoCo2/
BugReports:	https://github.com/danigiro/FoCo2/issues/
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2025-06-12 14:50:41 UTC; daniele
Author:	Daniele Girolimetto [aut, cre, fnd, cph], Tommaso Di Fonzo [aut, fnd]
Maintainer:	Daniele Girolimetto <daniele.girolimetto@unipd.it>
Repository:	CRAN
Date/Publication:	2025-06-14 08:50:02 UTC

FoCo2: Coherent Forecast Combination for Linearly Constrained Multiple Time Series

Description

Methods and tools designed to improve the forecast accuracy for a linearly constrained multiple time series, while fulfilling the linear/aggregation relationships linking the components (Girolimetto and Di Fonzo, 2024 doi:10.48550/arXiv.2412.03429). FoCo2 offers multi-task forecast combination and reconciliation approaches leveraging input from multiple forecasting models or experts and ensuring that the resulting forecasts satisfy specified linear constraints. In addition, linear inequality constraints (e.g., non-negativity of the forecasts) can be imposed, if needed.

Author(s)

Maintainer: Daniele Girolimetto daniele.girolimetto@unipd.it (ORCID) [funder, copyright holder]

Authors:

• Tommaso Di Fonzo (ORCID) [funder]

See Also

Useful links:

• https://github.com/danigiro/FoCo2/

• https://danigiro.github.io/FoCo2/

• Report bugs at https://github.com/danigiro/FoCo2/issues/

Cross-sectional covariance matrix approximation

Description

Extended version of the FoReco::cscov function, introducing two new approximations for the covariance matrix (both shrunk and sample versions). Specifically, shrbe/sambe assume no correlation between experts, while shrbv/sambv assume no correlation between variables.

Usage

## S3 method for class 'shrbe'
cscov(comb = "shrbe", ..., n = NULL, p = NULL, matNA = NULL,
      res = NULL, mse = TRUE, shrink_fun = NULL)

## S3 method for class 'sambe'
cscov(comb = "sambe", ..., n = NULL, p = NULL, matNA = NULL,
      res = NULL, mse = TRUE)

## S3 method for class 'shrbv'
cscov(comb = "shrbv", ..., n = NULL, p = NULL, matNA = NULL,
      res = NULL, mse = TRUE, shrink_fun = NULL)

## S3 method for class 'sambv'
cscov(comb = "sambv", ..., n = NULL, p = NULL, matNA = NULL,
      res = NULL, mse = TRUE)

Arguments

Value

A (m \times m) symmetric positive (semi-)definite matrix, with m = \sum_{j = 1}^p n_j, n_j \leq n.

See Also

Other Optimal combination: csmtc(), csocc(), occmat()

Cross-sectional optimal multi-task forecast combination

Description

This function computes the optimal multi-task linear forecast combination, as described in Girolimetto and Di Fonzo (2024)

Usage

csmtc(base, comb = "ols", res = NULL, approach = "proj",
      nn = NULL, settings = NULL, bounds = NULL, agg_mat = NULL, ...)

Arguments

Value

A (h \times n) numeric matrix of cross-sectional multi-task combined forecasts.

References

Girolimetto, D. and Di Fonzo, T. (2024), Coherent forecast combination for linearly constrained multiple time series, doi:10.48550/arXiv.2412.03429.

See Also

Other Optimal combination: cscov(), csocc(), occmat()

Examples

set.seed(123)
# (2 x 3) base forecasts matrix (simulated), expert 1
base1 <- matrix(rnorm(6, mean = c(20, 10, 10)), 2, byrow = TRUE)
# (10 x 3) in-sample residuals matrix (simulated), expert 1
res1 <- t(matrix(rnorm(n = 30), nrow = 3))

# (2 x 3) base forecasts matrix (simulated), expert 2
base2 <- matrix(rnorm(6, mean = c(20, 10, 10)), 2, byrow = TRUE)
# (10 x 3) in-sample residuals matrix (simulated), expert 2
res2 <- t(matrix(rnorm(n = 30), nrow = 3))

## BALANCED PANEL OF FORECASTS
# Base forecasts' and residuals' lists
brc <- list(base1, base2)
erc <- list(res1, res2)

# Aggregation matrix for Z = X + Y
A <- t(c(1,1))
rrc <- csocc(base = brc, agg_mat = A, comb = "shr", res = erc)

yc <- csmtc(base = brc, agg_mat = A, comb = "shr", res = erc)
M <- occmat(base = brc, agg_mat = A, comb = "shr", p = 2, res = erc)$M
M%*%t(yc)-t(rrc)

## UNBALANCED PANEL OF FORECASTS
base2[, 2] <- res2[, 2] <-  NA

# Base forecasts' and residuals' lists
bgc <- list(base1, base2)
egc <- list(res1, res2)
matNA <- matrix(1, 3, 2)
matNA[2,2] <- 0

# Aggregation matrix for Z = X + Y
A <- t(c(1,1))
rgc <- csocc(base = bgc, agg_mat = A, comb = "shr", res = egc)

yc <- csmtc(base = bgc, agg_mat = A, comb = "shr", res = egc)
M <- occmat(base = bgc, agg_mat = A, comb = "shr", p = 2, res = egc, matNA = matNA)$M
M%*%t(yc)-t(rgc)

Cross-sectional optimal coherent forecast combination

Description

This function implements the optimal linear coherent forecast combination for a linearly constrained (e.g., hierarchical/grouped) multiple time series combining forecasts from multiple sources (experts). The method minimizes forecast errors while ensuring that the resulting forecasts are coherent, meaning they satisfy the constraints across the time series. Using a linear constrained optimization approach, csocc combines forecasts from multiple experts, accounting for the relations between variables and constraints. In addition, linear inequality constraints (e.g. non-negative forecasts) can be imposed, if needed.

Usage

csocc(base, agg_mat, cons_mat, comb = "ols", res = NULL,
      approach = "proj", nn = NULL, settings = NULL, bounds = NULL, ...)

Arguments

Details

If an expert does not provide a forecast for a given variable, the missing value can be represented as NA. For instance, consider a case where the number of experts is p = 4, with n = 3 variables and h = 2. If the second and third experts do not provide forecasts for, respectively, the second and first variable, the corresponding matrix in the base list will be as follows:

\texttt{base[[1]]} = \begin{bmatrix} \hat{y}_{1,1}^{1} & \hat{y}_{2,1}^{1} & \hat{y}_{3,1}^{1} \\ \hat{y}_{1,2}^{1} & \hat{y}_{2,2}^{1} & \hat{y}_{3,2}^{1} \end{bmatrix}, \quad \texttt{base[[2]]} = \begin{bmatrix} \hat{y}_{1,1}^{2} & \texttt{NA} & \hat{y}_{3,1}^{2} \\ \hat{y}_{1,2}^{2} & \texttt{NA} & \hat{y}_{3,2}^{2} \end{bmatrix},

\texttt{base[[3]]} = \begin{bmatrix} \texttt{NA} & \hat{y}_{2,1}^{3} & \hat{y}_{3,1}^{3} \\ \texttt{NA} & \hat{y}_{2,2}^{3} & \hat{y}_{3,2}^{3} \end{bmatrix}, \quad \texttt{base[[4]]} = \begin{bmatrix} \hat{y}_{1,1}^{4} & \hat{y}_{2,1}^{4} & \hat{y}_{3,1}^{4} \\ \hat{y}_{1,2}^{4} & \hat{y}_{2,2}^{4} & \hat{y}_{3,2}^{4} \end{bmatrix}.

Value

A (h \times n) numeric matrix of cross-sectional combined and reconciled forecasts.

References

Di Fonzo, T. and Girolimetto, D. (2023), Spatio-temporal reconciliation of solar forecasts, Solar Energy, 251, 13–29. doi:10.1016/j.solener.2023.01.003

Girolimetto, D. and Di Fonzo, T. (2024), Coherent forecast combination for linearly constrained multiple time series, doi:10.48550/arXiv.2412.03429.

Stellato, B., Banjac, G., Goulart, P., Bemporad, A. and Boyd, S. (2020), OSQP: An Operator Splitting solver for Quadratic Programs, Mathematical Programming Computation, 12, 4, 637-672. doi:10.1007/s12532-020-00179-2

See Also

Other Optimal combination: cscov(), csmtc(), occmat()

Examples

set.seed(123)
# (2 x 3) base forecasts matrix (simulated), expert 1
base1 <- matrix(rnorm(6, mean = c(20, 10, 10)), 2, byrow = TRUE)
# (10 x 3) in-sample residuals matrix (simulated), expert 1
res1 <- t(matrix(rnorm(n = 30), nrow = 3))

# (2 x 3) base forecasts matrix (simulated), expert 2
base2 <- matrix(rnorm(6, mean = c(20, 10, 10)), 2, byrow = TRUE)
# (10 x 3) in-sample residuals matrix (simulated), expert 2
res2 <- t(matrix(rnorm(n = 30), nrow = 3))

## BALANCED PANEL OF FORECASTS
# Base forecasts' and residuals' lists
brc <- list(base1, base2)
erc <- list(res1, res2)

# Aggregation matrix for Z = X + Y
A <- t(c(1,1))
rrc <- csocc(base = brc, agg_mat = A, comb = "wls", res = erc)

# Zero constraints matrix for Z - X - Y = 0
C <- t(c(1, -1, -1))
rrc <- csocc(base = brc, cons_mat = C, comb = "wls", res = erc) # same results

## UNBALANCED PANEL OF FORECASTS
base2[, 2] <- res2[, 2] <-  NA

# Base forecasts' and residuals' lists
bgc <- list(base1, base2)
egc <- list(res1, res2)

# Aggregation matrix for Z = X + Y
A <- t(c(1,1))
rgc <- csocc(base = bgc, agg_mat = A, comb = "shrbe", res = egc)

Cross-sectional sequential combination-reconciliation

Description

This function performs a two-step process designed to first combine forecasts from multiple models or experts and then apply reconciliation techniques to ensure coherence.

Usage

csscr(base, fc = "sa", comb = "ols", res = NULL, mse = TRUE, shrink = TRUE,
      nnw = FALSE, factorized = FALSE, ...)

Arguments

Value

A (h \times n) numeric matrix of cross-sectional combined and reconciled forecasts.

References

Bates, J. and Granger, C. W. (1969), The combination of forecasts, Operations Research Quarterly, 20, 451–468. doi:10.1057/jors.1969.103.

Conflitti, C., De Mol, C., and Giannone, D. (2015), Optimal combination of survey forecasts. International Journal of Forecasting, 31(4), 1096–1103. doi:10.1016/j.ijforecast.2015.03.009.

Girolimetto, D. and Di Fonzo, T. (2024), Coherent forecast combination for linearly constrained multiple time series. doi:10.48550/arXiv.2412.03429.

Newbold, P. and Granger, C. W. (1974), Experience with forecasting univariate time series and the combination of forecasts, Journal of the Royal Statistical Society, A, 137, 131–146. doi:10.2307/2344546

See Also

Sequential coherent combination: cssrc()

Examples

set.seed(123)
# (2 x 3) base forecasts matrix (simulated), expert 1
base1 <- matrix(rnorm(6, mean = c(20, 10, 10)), 2, byrow = TRUE)
# (10 x 3) in-sample residuals matrix (simulated), expert 1
res1 <- t(matrix(rnorm(n = 30), nrow = 3))

# (2 x 3) base forecasts matrix (simulated), expert 2
base2 <- matrix(rnorm(6, mean = c(20, 10, 10)), 2, byrow = TRUE)
# (10 x 3) in-sample residuals matrix (simulated), expert 2
res2 <- t(matrix(rnorm(n = 30), nrow = 3))

# Base forecasts' and residuals' lists
base <- list(base1, base2)
res <- list(res1, res2)

# Aggregation matrix for Z = X + Y
A <- t(c(1,1))
reco <- csscr(base = base, agg_mat = A, comb = "wls", res = res, fc = "sa")

# Zero constraints matrix for Z - X - Y = 0
C <- t(c(1, -1, -1))
reco <- csscr(base = base, cons_mat = C, comb = "wls", res = res, fc = "sa") # same results

# Incoherent combined forecasts
fc_comb <- csscr(base = base, comb = "none", fc = "sa")
round(C %*% t(fc_comb), 3) # Incoherent forecasts

Cross-sectional sequential reconciliation-combination

Description

This function applies a sequential method that first reconciles the base forecasts from each expert to satisfy the linear constraints, and then combines the reconciled forecasts obtained so far. cssrc may be applied only in 'balanced' cases (e.g., n_j = n \forall j, see Girolimetto and Di Fonzo, 2024)

Usage

cssrc(base, fc = "sa", comb = "ols", res = NULL, mse = TRUE, shrink = TRUE,
      nnw = FALSE, factorized = FALSE, ...)

Arguments

Value

A (h \times n) numeric matrix of cross-sectional combined and reconciled forecasts.

References

Bates, J. and Granger, C. W. (1969), The combination of forecasts, Operations Research Quarterly, 20, 451–468. doi:10.1057/jors.1969.103.

Conflitti, C., De Mol, C., and Giannone, D. (2015), Optimal combination of survey forecasts. International Journal of Forecasting, 31(4), 1096–1103. doi:10.1016/j.ijforecast.2015.03.009.

Girolimetto, D. and Di Fonzo, T. (2024), Coherent forecast combination for linearly constrained multiple time series. doi:10.48550/arXiv.2412.03429.

Newbold, P. and Granger, C. W. (1974), Experience with forecasting univariate time series and the combination of forecasts, Journal of the Royal Statistical Society, A, 137, 131–146. doi:10.2307/2344546

See Also

Sequential coherent combination: csscr()

Examples

set.seed(123)
# (2 x 3) base forecasts matrix (simulated), expert 1
base1 <- matrix(rnorm(6, mean = c(20, 10, 10)), 2, byrow = TRUE)
# (10 x 3) in-sample residuals matrix (simulated), expert 1
res1 <- t(matrix(rnorm(n = 30), nrow = 3))

# (2 x 3) base forecasts matrix (simulated), expert 2
base2 <- matrix(rnorm(6, mean = c(20, 10, 10)), 2, byrow = TRUE)
# (10 x 3) in-sample residuals matrix (simulated), expert 2
res2 <- t(matrix(rnorm(n = 30), nrow = 3))

# Base forecasts' and residuals' lists
base <- list(base1, base2)
res <- list(res1, res2)

# Aggregation matrix for Z = X + Y
A <- t(c(1,1))
reco <- cssrc(base = base, agg_mat = A, comb = "wls", res = res, fc = "sa")

# Zero constraints matrix for Z - X - Y = 0
C <- t(c(1, -1, -1))
reco <- cssrc(base = base, cons_mat = C, comb = "wls", res = res, fc = "sa") # same results

# WARNING!
reco_v <- cssrc(base = base, agg_mat = A, comb = "wls", res = res, fc = "var")
round(C %*% t(reco_v), 3) # Incoherent forecasts

Matrices for the optimal coherent forecast combination

Description

This function computes the matrices required for the optimal coherent forecast combination csocc, as described in Girolimetto and Di Fonzo (2024). These matrices serve as the foundation for building forecasts that effectively combines the individual information from multiple experts while ensuring coherence across the variables.

Usage

occmat(agg_mat, cons_mat, p = NULL, matNA = NULL,
       comb = "ols", res = NULL, approach = "proj", ...)

Arguments

Value

A list of matrices:

References

Girolimetto, D. and Di Fonzo, T. (2024), Coherent forecast combination for linearly constrained multiple time series, doi:10.48550/arXiv.2412.03429.

See Also

Other Optimal combination: cscov(), csmtc(), csocc()