Covariance matrix approximation

This module provides functions for approximating forecast error covariance matrices, with support for both cross-sectional and temporal frameworks. These covariance approximations are a key component of optimal combination forecast reconciliation methods, since the choice of covariance structure determines the weighting in least-squares adjustments.

Two main toolsets are included:

  • cscov(): For hierarchically, grouped, or otherwise linearly constrained series observed at the same frequency.

  • tecov(): For temporal hierarchies, where the same time series can be aggregated or linearly combined at multiple frequencies (e.g., monthly, quarterly, yearly).

class cscov(params: cstools = None, res: Array = None, cov_mat=None)[source]

Cross-sectional covariances

Approximate the cross-sectional base forecast error covariance matrix under several reconciliation assumptions (Wickramasuriya et al., 2019; Di Fonzo & Girolimetto, 2023).

Parameters

params: cstools

A cstools object.

res: ndarray

An \((N \times n)\) optional numeric matrix containing the residuals. This matrix is used to compute some covariance matrices.

cov_mat: jnp.ndarray

If given, this \((n \times n)\) matrix is returned by fit() regardless of comb. Use this to plug in a fully custom covariance.

Attributes

params: cstools

Cached params.

n: int

Number of series.

res: jnp.ndarray

Cached residual matrix.

cov_mat: jnp.ndarray

Custom covariance to return as-is.

References

  • Di Fonzo, T. and Girolimetto, D. (2023), Cross-temporal forecast reconciliation: Optimal combination method and heuristic alternatives, International Journal of Forecasting, 39, 1, 39-57. DOI:10.1016/j.ijforecast.2021.08.004

  • Wickramasuriya, S.L., Athanasopoulos, G. and 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. DOI:10.1080/01621459.2018.1448825

See Also

shrink_estim cstools csrec

fit(comb='ols', return_vector=False, shr_fun=<function shrink_estim>, mse=True)[source]

Estimate a cross-sectional covariance approximation.

Parameters

comb: str, default ‘ols’

The approximation/reconciliation assumption to use:

  • ols: identity error covariance matrix.

  • str: structural variances.

  • wls: series-wise variances from residuals res.

  • shr: shrunk covariance of res (Wickramasuriya et al., 2019).

  • sam : sample covariance of res.

return_vector: bool, default False

If True, return the diagonal of the matrix, only for {‘ols’,’str’, ‘wls’}. Otherwise return an \((n \times n)\) matrix.

shr_fun: callable, default shrink_estim()

Shrinkage estimator used when comb=’shr’. It must accept residuals res and mse and return a mapping with at least the key ‘cov’ containing the shrunk covariance \((n \times n)\).

mse: bool, default True

When True, residual moments are not mean-corrected (i.e., MSE rather than unbiased variance). When False, apply mean correction.

Returns

A \((n \times n)\) symmetric positive (semi-)definite matrix.

class tecov(params: tetools = None, res: Array = None, cov_mat=None)[source]

Temporal covariances

Approximate the temporal base forecast error covariance matrix under several reconciliation assumptions (Di Fonzo & Girolimetto, 2023).

Parameters

params: tetools

A tetools object.

res: ndarray

A \([N(k^\ast+m) \times 1]\) optional numeric vector containing the residuals ordered from the lowest frequency to the highest frequency. This vector is used to compute some covariance matrices.

cov_mat: jnp.ndarray

If given, this \([(k^\ast+m) \times (k^\ast+m)]\) matrix is returned by fit() regardless of comb. Use this to plug in a fully custom covariance.

Attributes

params: cstools

Cached params.

kt: int

Total sum of factors.

res: jnp.ndarray

Cached residual matrix.

cov_mat: jnp.ndarray

Custom covariance to return as-is.

References

  • Di Fonzo, T. and Girolimetto, D. (2023), Cross-temporal forecast reconciliation: Optimal combination method and heuristic alternatives, International Journal of Forecasting, 39, 1, 39-57. DOI:10.1016/j.ijforecast.2021.08.004

See Also

shrink_estim tetools terec

fit(comb='ols', return_vector=False, shr_fun=<function shrink_estim>, mse=True)[source]

Estimate a cross-sectional covariance approximation.

Parameters

comb: str, default ‘ols’

The approximation/reconciliation assumption to use:

  • ols: identity error covariance matrix.

  • str: structural variances.

  • wlsv: series-wise variances from residuals res.

  • shr: shrunk covariance of res.

  • sam : sample covariance of res.

return_vector: bool, default False

If True, return the diagonal of the matrix, only for {‘ols’,’str’,’wlsv’}. Otherwise return an \([(k^\ast+m) \times (k^\ast+m)]\) matrix.

shr_fun: callable, default shrink_estim()

Shrinkage estimator used when comb=’shr’. It must accept residuals res and mse and return a mapping with at least the key ‘cov’ containing the shrunk covariance \([(k^\ast+m) \times (k^\ast+m)]\).

mse: bool, default True

When True, residual moments are not mean-corrected (i.e., MSE rather than unbiased variance). When False, apply mean correction.

Returns

A \([(k^\ast+m) \times (k^\ast+m)]\) symmetric positive (semi-)definite matrix.