% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reconc_MixCond.R, R/reconc_TDcond.R
\name{Mixed_reconciliation}
\alias{Mixed_reconciliation}
\alias{reconc_MixCond}
\alias{reconc_TDcond}
\title{Probabilistic forecast reconciliation of mixed hierarchies}
\usage{
reconc_MixCond(
  A,
  base_fc_bottom,
  base_fc_upper,
  bottom_in_type = "pmf",
  distr = NULL,
  num_samples = 20000,
  return_type = "pmf",
  return_upper = TRUE,
  suppress_warnings = FALSE,
  seed = NULL
)

reconc_TDcond(
  A,
  base_fc_bottom,
  base_fc_upper,
  bottom_in_type = "pmf",
  distr = NULL,
  num_samples = 20000,
  return_type = "pmf",
  return_upper = TRUE,
  suppress_warnings = TRUE,
  seed = NULL
)
}
\arguments{
\item{A}{Aggregation matrix (n_upper x n_bottom).}

\item{base_fc_bottom}{A list containing the bottom base forecasts, see details.}

\item{base_fc_upper}{A list containing the upper base forecasts, see details.}

\item{bottom_in_type}{A string with three possible values:
\itemize{
\item 'pmf' if the bottom base forecasts are in the form of pmf, see details;
\item 'samples' if the bottom base forecasts are in the form of samples;
\item 'params'  if the bottom base forecasts are in the form of estimated parameters.
}}

\item{distr}{A string describing the type of bottom base forecasts ('poisson' or 'nbinom').

This is only used if \code{bottom_in_type='params'}.}

\item{num_samples}{Number of samples drawn from the reconciled distribution.
This is ignored if \code{bottom_in_type='samples'}; in this case, the number of
reconciled samples is equal to the number of samples of the base forecasts.}

\item{return_type}{The return type of the reconciled distributions.
A string with three possible values:
\itemize{
\item 'pmf' returns a list containing the reconciled marginal pmf objects;
\item 'samples' returns a list containing the reconciled multivariate samples;
\item 'all' returns a list with both pmf objects and samples.
}}

\item{return_upper}{Logical, whether to return the reconciled parameters for the upper variables (default is TRUE).}

\item{suppress_warnings}{Logical. If \code{TRUE}, no warnings about samples are triggered;
if \code{FALSE}, warnings are generated. Default is \code{FALSE} for \code{reconc_MixCond}
and \code{TRUE} for \code{reconc_TDcond}. See the respective sections above.}

\item{seed}{Seed for reproducibility.}
}
\value{
A list containing the reconciled forecasts. The list has the following named elements:
\itemize{
\item \code{bottom_rec_pmf}: a list of PMF objects for each bottom series
(only if \code{return_type} is \code{'pmf'} or \code{'all'});
\item \code{bottom_rec_samples}: a matrix (n_bottom x \code{num_samples}) of reconciled bottom samples
(only if \code{return_type} is \code{'samples'} or \code{'all'});
\item \code{upper_rec_pmf}: a list of PMF objects for each upper series
(only if \code{return_type} is \code{'pmf'} or \code{'all'}, and \code{return_upper = TRUE});
\item \code{upper_rec_samples}: a matrix (n_upper x \code{num_samples}) of reconciled upper samples
(only if \code{return_type} is \code{'samples'} or \code{'all'}, and \code{return_upper = TRUE}).
}
}
\description{
\code{reconc_MixCond()} uses importance sampling to draw samples from the reconciled
forecast distribution, obtained via conditioning, in the case of a mixed hierarchy.

\code{reconc_TDcond()} 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.
}
\details{
The base bottom forecasts \code{base_fc_bottom} must be a list of length n_bottom, where each element is either
\itemize{
\item a PMF object (see details below), if \code{bottom_in_type='pmf'};
\item a vector of samples, if \code{bottom_in_type='samples'};
\item a list of parameters, if \code{bottom_in_type='params'}:
\itemize{
\item lambda for the Poisson base forecast if \code{distr}='poisson', see \link[stats]{Poisson};
\item size and prob (or mu) for the negative binomial base forecast if \code{distr}='nbinom',
see \link[stats]{NegBinomial}.
}
}

The base upper forecasts \code{base_fc_upper} must be a list containing the parameters of
the multivariate Gaussian distribution of the upper forecasts.
The list must contain only the named elements \code{mean} (vector of length n_upper)
and \code{cov} (n_upper x n_upper matrix).

The order of the upper and bottom base forecasts must match the order of (respectively) the rows and the columns of A.

A PMF object is a numerical vector containing the probability mass function of a discrete distribution.
Each element corresponds to the probability of the integers from 0 to the last value of the support.
See also \link{PMF} for functions that handle PMF objects.

\strong{Warnings and errors.}

In \code{reconc_MixCond}, warnings are triggered from the importance sampling step if:
\itemize{
\item weights are all zeros, then the upper forecast is ignored during reconciliation;
\item the effective sample size is < 200;
\item the effective sample size is < 1\% of the sample size.
}

These warnings are an indication that the base forecasts might have issues.
Please check the base forecasts in case of warnings.

In \code{reconc_TDcond}, if some of the reconciled upper samples lie outside the support of the bottom-up
distribution, those samples are discarded; the remaining ones are resampled with
replacement, so that the number of output samples is equal to \code{num_samples}.
In this case, a warning is issued if \code{suppress_warnings=FALSE} (default is \code{TRUE}).
If the fraction of discarded samples is above 50\%, the function returns an error.
}
\examples{

library(bayesRecon)

# Consider a simple hierarchy with two bottom and one upper
A <- matrix(c(1, 1), nrow = 1)
# The bottom forecasts are Poisson with lambda=15
lambda <- 15
n_tot <- 60
base_fc_bottom <- list()
base_fc_bottom[[1]] <- apply(matrix(seq(0, n_tot)), MARGIN = 1,
                             FUN = \(x) dpois(x, lambda = lambda))
base_fc_bottom[[2]] <- apply(matrix(seq(0, n_tot)), MARGIN = 1,
                             FUN = \(x) dpois(x, lambda = lambda))

# The upper forecast is a Normal with mean 40 and std 5
base_fc_upper <- list(mean = 40, cov = matrix(5^2))

# Reconcile with reconc_MixCond
res.mixCond <- reconc_MixCond(A, base_fc_bottom, base_fc_upper)

# Note that the bottom distributions are slightly shifted to the right
PMF_summary(res.mixCond$bottom_rec_pmf[[1]])
PMF_summary(base_fc_bottom[[1]])

PMF_summary(res.mixCond$bottom_rec_pmf[[2]])
PMF_summary(base_fc_bottom[[2]])

# The upper distribution is slightly shifted to the left
PMF_summary(res.mixCond$upper_rec_pmf[[1]])
PMF_get_var(res.mixCond$upper_rec_pmf[[1]])


library(bayesRecon)

# Consider a simple hierarchy with two bottom and one upper
A <- matrix(c(1, 1), nrow = 1)
# The bottom forecasts are Poisson with lambda=15
lambda <- 15
n_tot <- 60
base_fc_bottom <- list()
base_fc_bottom[[1]] <- apply(matrix(seq(0, n_tot)), MARGIN = 1,
                             FUN = \(x) dpois(x, lambda = lambda))
base_fc_bottom[[2]] <- apply(matrix(seq(0, n_tot)), MARGIN = 1,
                             FUN = \(x) dpois(x, lambda = lambda))

# The upper forecast is a Normal with mean 40 and std 5
base_fc_upper <- list(mean = 40, cov = matrix(c(5^2)))

# Reconcile with reconc_TDcond
res.TDcond <- reconc_TDcond(A, base_fc_bottom, base_fc_upper)

# Note that the bottom distributions are shifted to the right
PMF_summary(res.TDcond$bottom_rec_pmf[[1]])
PMF_summary(base_fc_bottom[[1]])

PMF_summary(res.TDcond$bottom_rec_pmf[[2]])
PMF_summary(base_fc_bottom[[2]])

# The upper distribution remains similar
PMF_summary(res.TDcond$upper_rec_pmf[[1]])
PMF_get_var(res.TDcond$upper_rec_pmf[[1]])

## Example 2: reconciliation with unbalanced hierarchy
# We consider the example in Fig. 9 of Zambon et al. (2024).

# The hierarchy has 5 bottoms and 3 uppers
A <- matrix(c(
  1, 1, 1, 1, 1,
  1, 1, 0, 0, 0,
  0, 0, 1, 1, 0
), nrow = 3, byrow = TRUE)
# Note that the 5th bottom only appears in the highest level, this is an unbalanced hierarchy.
n_upper <- nrow(A)
n_bottom <- ncol(A)

# The bottom forecasts are Poisson with lambda=15
lambda <- 15
n_tot <- 60
base_fc_bottom <- list()
for (i in seq(n_bottom)) {
  base_fc_bottom[[i]] <- apply(matrix(seq(0, n_tot)), MARGIN = 1,
                               FUN = \(x) dpois(x, lambda = lambda))
}

# The upper forecasts are a multivariate Gaussian
mean <- c(75, 30, 30)
cov <- matrix(c(
  5^2, 5, 5,
  5, 10, 0,
  5, 0, 10
), nrow = 3, byrow = TRUE)

base_fc_upper <- list(mean = mean, cov = cov)
\dontrun{
# If we reconcile with reconc_TDcond it won't work (unbalanced hierarchy)
res.TDcond <- reconc_TDcond(A, base_fc_bottom, base_fc_upper)
}

# We can balance the hierarchy by duplicating the node b5:
# i) consider the time series observations for b5 as the upper u4,
# ii) fit the multivariate ts model for u1, u2, u3, u4.

# In this example we simply assume that the forecast for u1-u4 is
# Gaussian with the mean and variance of u4 given by the parameters in b5.
mean_b5 <- lambda
var_b5 <- lambda
mean <- c(75, 30, 30, mean_b5)
cov <- matrix(c(
  5^2, 5, 5, 5,
  5, 10, 0, 0,
  5, 0, 10, 0,
  5, 0, 0, var_b5
), nrow = 4, byrow = TRUE)
base_fc_upper <- list(mean = mean, cov = cov)

# We also need to update the aggregation matrix
A <- matrix(c(
  1, 1, 1, 1, 1,
  1, 1, 0, 0, 0,
  0, 0, 1, 1, 0,
  0, 0, 0, 0, 1
), nrow = 4, byrow = TRUE)

# We can now reconcile with TDcond
res.TDcond <- reconc_TDcond(A, base_fc_bottom, base_fc_upper)

# Note that the reconciled distribution of b5 and u4 are identical,
# keep this in mind when using the results of your reconciliation!
max(abs(res.TDcond$bottom_rec_pmf[[5]] - res.TDcond$upper_rec_pmf[[4]]))

}
\references{
Zambon, L., Azzimonti, D., Rubattu, N., Corani, G. (2024).
\emph{Probabilistic reconciliation of mixed-type hierarchical time series}.
Proceedings of the Fortieth Conference on Uncertainty in Artificial Intelligence,
PMLR 244:4078-4095. \url{https://proceedings.mlr.press/v244/zambon24a.html}.
}
\seealso{
\code{\link[=reconc_BUIS]{reconc_BUIS()}}, \code{\link[=reconc_gaussian]{reconc_gaussian()}}, \link{PMF}
}
