Package 'fable.bayesRecon'

BUIS for probabilistic reconciliation of forecasts via conditioning

Description

Specifies Bottom-Up Importance Sampling (BUIS) reconciliation for use within reconcile(). The method uses the Bottom-Up Importance Sampling algorithm to draw samples from the reconciled forecast distribution, obtained via conditioning. Reconciliation is performed when forecast() is called on the resulting model. Marginal reconciled forecasts follow a sample distribution.

Usage

bayesRecon_BUIS(models, n_samples = 1000)

Arguments

models	A list of fitted models to reconcile.
n_samples	Number of samples to draw from the reconciled distribution.

Value

A model specification of class "bayesRecon_BUIS" (inheriting from "mdl_lst") to be passed to reconcile. The reconciliation is performed when forecast is called on the resulting mable (a model table). The forecast output is a fable object containing reconciled probabilistic forecasts represented as sample distributions (dist_sample).

References

Zambon, L., Azzimonti, D. & Corani, G. (2024). Efficient probabilistic reconciliation of forecasts for real-valued and count time series. Statistics and Computing 34 (1), 21. doi:10.1007/s11222-023-10343-y.

See Also

fabletools::reconcile(), fabletools::aggregate_key(), bayesRecon_MixCond(), bayesRecon::reconc_BUIS()

Examples

library(fable)
library(fabletools)
library(tsibble)
library(fable.bayesRecon)

# Small hierarchical example using tourism data
tourism_small <- tsibble::tourism |>
dplyr::filter(Region == "Melbourne") |> 
fabletools::aggregate_key(Purpose, Trips = sum(Trips))

fit <- tourism_small |> 
model(base = ETS(Trips ~ trend("A") + season("A"))) |>
reconcile(recon = bayesRecon_BUIS(base, n_samples = 300))

fc <- forecast(fit, h = "2 years")
fc

---

Probabilistic reconciliation of mixed hierarchies

Description

bayesRecon_MixCond specifies Mixed-Conditioning (Mix-Cond) reconciliation for use within reconcile(). The method uses importance sampling to draw samples from the reconciled forecast distribution, obtained via conditioning, in the case of a mixed hierarchy.

bayesRecon_TDcond specifies Top-Down Conditioning reconciliation for use within reconcile(). The method uses a top-down conditioning algorithm: first, upper base forecasts are reconciled via conditioning using only the hierarchical constraints between the upper; then, the bottom distributions are updated via a probabilistic top-down procedure.

Reconciliation is performed when forecast() is called on the resulting model. Marginal reconciled forecasts follow a sample distribution.

Usage

bayesRecon_MixCond(models, n_samples = 1000, suppress_warnings = TRUE)

bayesRecon_TDcond(models, n_samples = 1000, suppress_warnings = TRUE)

Arguments

models	A list of fitted models to reconcile.
n_samples	Number of samples to draw from the reconciled distribution.
suppress_warnings	If TRUE, suppress warnings from reconciliation.

Value

A model specification of class "bayesRecon_MixCond" or "bayesRecon_TDcond" (inheriting from "mdl_lst") to be passed to reconcile. The reconciliation is performed when forecast is called on the resulting mable (a model table). The forecast output is a fable object containing reconciled probabilistic forecasts represented as sample distributions (dist_sample).

References

Zambon, L., Azzimonti, D., Rubattu, N., Corani, G. (2024). Probabilistic reconciliation of mixed-type hierarchical time series. Proceedings of the Fortieth Conference on Uncertainty in Artificial Intelligence, PMLR 244:4078-4095. https://proceedings.mlr.press/v244/zambon24a.html.

See Also

fabletools::reconcile(), fabletools::aggregate_key(), bayesRecon_BUIS(), bayesRecon::reconc_MixCond(), bayesRecon::reconc_TDcond()

Examples

library(tsibble)
library(dplyr)
library(tibble)
library(fable)
library(fabletools)


# Mixed hierarchy with integer-valued bottom series and one upper aggregate.
# Two low-rate Poisson count series at the bottom; their sum forms the
# continuous-looking upper aggregate. 
set.seed(42)
n <- 60
idx <- tsibble::yearmonth("2019 Jan") + 0:(n - 1)

counts <- dplyr::bind_rows(
   tibble::tibble(Month = idx, Item = "A", Sales = rpois(n, lambda = 3)),
   tibble::tibble(Month = idx, Item = "B", Sales = rpois(n, lambda = 5))) |>
   tsibble::as_tsibble(index = Month, key = Item) |>
   fabletools::aggregate_key(Item, Sales = sum(Sales))
   
# Fit a base model on every level, then reconcile via MixCond:
# the upper (aggregated) forecast is treated as Gaussian, while the
# bottom-level forecast samples are treated as discrete via importance
# sampling.
fit <- counts |>
model(base = ETS(Sales)) |>
reconcile(mc = bayesRecon_MixCond(base))


# Alternative reconciliation via TDcond
fit_TDcond <- counts |>
model(base = ETS(Sales)) |>
reconcile(mc = bayesRecon_TDcond(base))


fc <- forecast(fit, h = 2)
fc

---

t-Rec: reconciliation via conditioning with uncertain covariance via multivariate t-distribution

Description

Specifies t-Rec reconciliation for use within reconcile().

Reconciles base forecasts by conditioning on the hierarchical constraints. The base forecasts are assumed to be jointly Gaussian, conditionally on the covariance matrix of the forecast errors. A Bayesian approach is adopted to account for the uncertainty of the covariance matrix. An Inverse-Wishart prior is specified on the covariance matrix, leading to a multivariate t-distribution for the base forecasts. The reconciliation via conditioning is in closed-form, yielding a multivariate t reconciled distribution.

Reconciliation is performed when forecast() is called on the resulting model. Marginal reconciled forecasts follow a Student-t distribution.

Usage

bayesRecon_t(models, ...)

Arguments

models

A list of fitted models to reconcile.

...

Additional arguments passed to other methods, including: prior: Optional list with entries nu and Psi specifying the parameters of the Inverse-Wishart prior distribution for the covariance matrix. If not provided, the prior is estimated from the data. freq: Optional frequency of the time series, used for estimating the naive covariance matrix via seasonal naive residuals. If not provided, the frequency is inferred from the data. criterion: Criterion for estimating the naive covariance matrix (default: "RSS"). l_shr: Optional shrinkage parameter (between 0 and 1) for the covariance matrix of the residuals.

Value

A model specification of class "bayesRecon_t" (inheriting from "mdl_lst") to be passed to reconcile. The reconciliation is performed when forecast is called on the resulting mable (a model table). The forecast output is a fable object containing reconciled probabilistic forecasts represented as sample distributions (dist_student_t).

References

Carrara, C., Corani, G., Azzimonti, D., & Zambon, L. (2025). Modeling the uncertainty on the covariance matrix for probabilistic forecast reconciliation. arXiv preprint arXiv:2506.19554. https://arxiv.org/abs/2506.19554

See Also

fabletools::reconcile(), fabletools::aggregate_key(), fabletools::min_trace(), bayesRecon::reconc_t()

Examples

library(fable)
library(fabletools)
library(tsibble)
library(fable.bayesRecon)

# Small hierarchical example using tourism data
tourism_small <- tsibble::tourism |>
dplyr::filter(Region == "Melbourne") |> 
fabletools::aggregate_key(Purpose, Trips = sum(Trips))

fit <- tourism_small |> 
model(base = ETS(Trips ~ trend("A") + season("A"))) |>
reconcile(recon = bayesRecon_t(base))

fc <- forecast(fit, h = "2 years")
fc

---