Linear Reconciliation#

This page documents the available functions for reconciliation. Canonical modules are under bayesreconpy.linear; legacy module paths remain available for backward compatibility.

bayesreconpy.linear.conditioning#

bayesreconpy.linear.gaussian#

Gaussian linear reconciliation.

bayesreconpy.linear.gaussian.reconc_gaussian(A, base_forecasts_mu, base_forecasts_Sigma)#

Analytical reconciliation of Gaussian base forecasts. Reconciles forecasts using a closed-form computation for Gaussian base forecasts.

Parameters:

A (ndarray) – Aggregation matrix with shape (n_upper, n_bottom). Each column represents a bottom-level forecast, and each row represents an upper-level forecast. A value of 1 in A[i, j] indicates that the bottom-level forecast j contributes to the upper-level forecast i.
base_forecasts_mu (List[float]) –
A 1D list containing the means of the base forecasts. The order is:
- First, the upper-level means (in the order of rows in A).
- Then, the bottom-level means (in the order of columns in A).
base_forecasts_Sigma (ndarray) – A 2D covariance matrix representing the uncertainties in the base forecasts. The order of rows and columns must match the order of base_forecasts_mu. Shape: (n, n), where n = n_upper + n_bottom.

Returns:

A dictionary containing:

’bottom_reconciled_mean’numpy.ndarray
A 1D array of the reconciled means for the bottom-level forecasts. Shape: (n_bottom,).
’bottom_reconciled_covariance’numpy.ndarray
A 2D covariance matrix of the reconciled bottom-level forecasts. Shape: (n_bottom, n_bottom).

Return type:

Dict[str, ndarray]

Notes

The function assumes that base forecasts follow a multivariate Gaussian distribution.
The covariance matrix base_forecasts_Sigma should be symmetric and positive semi-definite.
The order of elements in base_forecasts_mu and rows/columns in base_forecasts_Sigma is critical: first the upper-level forecasts (in the order of rows in A), followed by the bottom-level forecasts (in the order of columns in A).
The function returns only the reconciled parameters for the bottom-level forecasts. Reconciled parameters for upper-level forecasts and the entire hierarchy can be derived using the reconciliation matrix A.

Examples

Example 1: Minimal hierarchy with Gaussian base forecasts

>>> A = np.array([
...     [1, 0, 0],
...     [0, 1, 1]
... ])
>>> base_forecasts_mu = [9.0, 2.0, 4.0]
>>> base_forecasts_Sigma = np.diag([9.0, 4.0, 4.0])
>>> result = reconc_gaussian(A, base_forecasts_mu, base_forecasts_Sigma)
>>> print(result['bottom_reconciled_mean'])
[2.5, 4.0]
>>> print(result['bottom_reconciled_covariance'])
[[2.25, 1.5 ],
 [1.5 , 2.0 ]]

References

Corani, G., Azzimonti, D., Augusto, J.P.S.C., Zaffalon, M. (2021). Probabilistic Reconciliation of Hierarchical Forecast via Bayes’ Rule. ECML PKDD 2020. Lecture Notes in Computer Science, vol 12459. https://doi.org/10.1007/978-3-030-67664-3_13
Zambon, L., Agosto, A., Giudici, P., Corani, G. (2024). Properties of the reconciled distributions for Gaussian and count forecasts. International Journal of Forecasting (in press). https://doi.org/10.1016/j.ijforecast.2023.12.004

bayesreconpy.linear.projection#

Projection-based linear reconciliation methods.

bayesreconpy.linear.projection.reconc_mint(A, base_forecasts, res=None, W=None, samples=False)#

Reconciles base forecasts using the MinT (Minimum Trace) approach with a shrinkage-based covariance estimator.

The MinT method adjusts base forecasts to ensure coherence with a given aggregation structure, minimizing the total variance of the reconciliation errors using the residual covariance matrix.

Parameters:#

Anp.ndarray: The aggregation constraint matrix (typically of shape [n_agg_levels, n_total_series]), defining how the bottom-level time series aggregate into upper levels.
base_forecastsnp.ndarray: The base forecasts to be reconciled: - of shape [n_total_series, n_time, n_samples] if samples=True, or - of shape [n_total_series, n_time] if samples=False.
resnp.ndarray: Residuals (forecast errors) from a previous model, used to estimate the covariance matrix. Should be of shape [n_total_series, n_time].
Wnp.ndarray, optional: Pre-computed covariance/weight matrix (W_h). If provided, ‘res’ is ignored.
samplesbool, optional (default=False): Indicates whether the base forecasts include multiple samples. If True, reconciliation is applied sample-by-sample along the third axis.

Returns:#

y_tilde_meannp.ndarray: The reconciled forecast means, with the same shape as base_forecasts.
y_tilde_varnp.ndarray or list of np.ndarray: The reconciled forecast variances: - A single matrix of shape [n_total_series, n_total_series] if samples=False. - A list of such matrices, one per sample, if samples=True.

bayesreconpy.linear.projection.reconc_ols(A, base_forecasts, samples=False)#

Reconciles base forecasts using Ordinary Least Squares (OLS) based on a summing matrix.

This function applies forecast reconciliation using the OLS method, ensuring that the reconciled forecasts are coherent with the aggregation structure defined by the matrix A.

Parameters:#

Anp.ndarray: The aggregation constraint matrix (usually of shape [n_agg_levels, n_total_series]). It defines how bottom-level time series are aggregated into upper levels.
base_forecastsnp.ndarray: The base forecasts before reconciliation. Should be: - of shape [n_total_series, n_time, n_samples] if samples=True, or - of shape [n_total_series, n_time] if samples=False.
samplesbool, optional (default=False): Indicates whether the base forecasts contain multiple samples (i.e., are probabilistic). If True, reconciliation is applied to each sample individually along the third axis.

Returns:#

y_tilde_meannp.ndarray: The reconciled forecasts: - of shape [n_total_series, n_time, n_samples] if samples=True, or - of shape [n_total_series, n_time] if samples=False.