FoReco Reconciliation Class — foreco-class • FoReco

The foreco class represents reconciled forecasts produced by the FoReco package. It extends the base matrix class with additional attributes that store metadata about the reconciliation procedure (framework, function used, forecast type, and other reconciliation-specific information). The class provides dedicated methods for printing, summarising, extracting components and visualising reconciled forecasts.

Usage

new_foreco_class(x, framework, rfun, rtype, rinfo = NULL, nninfo = NULL)

# S3 method for class 'foreco'
summary(object, keep_forecasts = TRUE, ...)

# S3 method for class 'summary.foreco'
print(x, n_row = NULL, n_col = NULL, ...)

# S3 method for class 'foreco'
print(x, n_row = NULL, n_col = NULL, ...)

# S3 method for class 'foreco'
plot(x, cs = NULL, te = 1, alpha = 0.95, ...)

# S3 method for class 'foreco'
components(
  object,
  cs = NULL,
  te = NULL,
  keep_names = FALSE,
  temporal_names = NULL,
  ...
)

Arguments

x: For new_foreco_class(), a numeric matrix of reconciled forecasts (when rtype = "point") or a distributional object (when rtype = "probabilistic"). For print.foreco() and plot.foreco(), an object of class foreco. For print.summary.foreco(), an object of class summary.foreco.
framework: A character string identifying the reconciliation framework. Must be one of "cross-sectional", "temporal", or "cross-temporal".
rfun: A character scalar with the name of the FoReco function that produced the reconciled forecasts (e.g. "csrec", "terec", "ctrec").
rtype: A character string indicating the type of reconciled forecasts. Must be one of "point" or "probabilistic".
rinfo: An optional named list with additional reconciliation information (e.g. covariance approximation comb, machine-learning approach ml, non-negativity flag nn, cross-sectional size cs_n, temporal aggregation set te_set, forecast horizon forecast_horizon, level-conditional reconciled forecasts lcc).
nninfo: An optional matrix with information about the non-negativity procedure applied during reconciliation. Stored as the info field of the "FoReco" attribute.
object: An object of class foreco, passed to summary.foreco() and components.foreco().
keep_forecasts: Logical; if TRUE (the default), the reconciled forecasts are stored in the rf element of the returned summary.foreco object (and therefore printed at the end of the summary). Set to FALSE to obtain a lighter summary object that omits them.
...: Additional arguments passed to the underlying methods (e.g. print()).
n_row, n_col: Integers giving the maximum number of rows and columns to display when printing. If NULL (the default) all rows/columns are shown. When the matrix is truncated, a summary line reports how many rows and columns have been omitted.
cs: Optional integer vector selecting the cross-sectional series to keep. If NULL (the default) all series are returned.
te: Optional vector (numeric or character) selecting the temporal aggregation orders to keep, matched against the elements of te_set. If NULL (the default) all orders are returned.
alpha: Nominal coverage of the prediction interval drawn by plot.foreco() for probabilistic forecasts. Defaults to 0.95.
keep_names: Logical; if TRUE, the row/column names of the reconciled forecasts are preserved in the output of components.foreco(). Defaults to FALSE.
temporal_names: Optional character vector of labels for the temporal aggregation orders returned by components.foreco(). Its length must match the number of returned orders, otherwise a warning is emitted and the default "k-..." labels are used.

Value

new_foreco_class() returns x with class "foreco" (prepended to its existing class) and a "FoReco" attribute containing at least:

framework: The reconciliation framework: "cross-sectional", "temporal" or "cross-temporal".
rfun: The name of the reconciliation function that produced the object.
rtype: The forecast type: "point" or "probabilistic".
info: A matrix with convergence information of the non-negative reconciliation algorithm, when one has been applied; NULL otherwise. Corresponds to the nninfo argument of new_foreco_class().

plus all the additional fields supplied through rinfo, which typically include:

cs_n: The cross-sectional number of variables.
te_set: The set of temporal aggregation orders.
forecast_horizon: The forecast horizon. In the temporal and cross-temporal frameworks it refers to the most temporally aggregated series.
lcc: A list of level-conditional reconciled forecasts (plus bottom-up) returned by cslcc(), telcc() and ctlcc().
nn: Logical; if TRUE, all reconciled forecasts are non-negative.
comb: The covariance approximation used in the reconciliation.
ml: The machine-learning approach used to produce the base forecasts, when applicable.

components.foreco() returns a named list of reconciled forecasts split by temporal aggregation order. For the cross-sectional framework the list has a single element "k-1".

Details

new_foreco_class() is the low-level constructor. It is exported so that companion packages can produce objects that integrate with FoReco's print(), summary(), plot() and components() methods.

plot.foreco() draws the reconciled forecasts as line/point plots. For probabilistic forecasts (rtype = "probabilistic") it also overlays a shaded central alpha * 100% prediction interval, built from the (1 - alpha)/2 and 1 - (1 - alpha)/2 quantiles of the distributional object; the median is shown as a dashed line and the interval limits as dotted lines.

Examples

set.seed(123)
# Aggregation matrix for Z = X + Y
A   <- t(c(1, 1))
bts <- matrix(rnorm(6, mean = 10), 3, 2)
reco <- csbu(base = bts, agg_mat = A)

# Inspect the reconciled-forecast object
print(reco)
#>          s-1       s-2      s-3
#> h-1 19.51003  9.439524 10.07051
#> h-2 19.89911  9.769823 10.12929
#> h-3 23.27377 11.558708 11.71506
print(reco, n_row = 2, n_col = 2)
#>          s-1      s-2
#> h-1 19.51003 9.439524
#> h-2 19.89911 9.769823
#> ... (1 more row, 1 more column)
summary(reco)
#> ✔ Cross-sectional point forecast reconciliation
#> 
#> ── Method 
#> • Function used: `csbu`
#> • Output: (3 x 3) matrix
#> 
#> ── Structure 
#> • Number of cross-sectional series: 3
#> • Forecast horizons (h): 3
#> • Non-negative forecasts (check): `TRUE`
#> 
#> ── Reconciled forecasts 
#>          s-1       s-2      s-3
#> h-1 19.51003  9.439524 10.07051
#> h-2 19.89911  9.769823 10.12929
#> h-3 23.27377 11.558708 11.71506
summary(reco, keep_forecasts = FALSE)
#> ✔ Cross-sectional point forecast reconciliation
#> 
#> ── Method 
#> • Function used: `csbu`
#> • Output: (3 x 3) matrix
#> 
#> ── Structure 
#> • Number of cross-sectional series: 3
#> • Forecast horizons (h): 3
#> • Non-negative forecasts (check): `TRUE`
#> 
#> ── Reconciled forecasts 
#> [1] "csbu"