​
module hierarchicalforecast.probabilistic_methods

​
class Normality

Normality Probabilistic Reconciliation Class. The Normality method leverages the Gaussian Distribution linearity, to generate hierarchically coherent prediction distributions. This class is meant to be used as the sampler input as other HierarchicalForecast reconciliation classes. Given base forecasts under a normal distribution: y^h∼N(μ^,W^h)\hat{y}_{h} \sim \mathrm{N}(\hat{\boldsymbol{\mu}}, \hat{\mathbf{W}}_{h}) The reconciled forecasts are also normally distributed: y~h∼N(SPμ^,SPW^hP⊺S⊺)\tilde{y}_{h} \sim \mathrm{N}(\mathbf{S}\mathbf{P}\hat{\boldsymbol{\mu}}, \mathbf{S}\mathbf{P}\hat{\mathbf{W}}_{h} \mathbf{P}^{\intercal} \mathbf{S}^{\intercal}) Args:
  • S (Union[np.ndarray, sp.spmatrix]): np.array, summing matrix of size (base, bottom).
  • P (Union[np.ndarray, sp.spmatrix]): np.array, reconciliation matrix of size (bottom, base).
  • y_hat (np.ndarray): Point forecasts values of size (base, horizon).
  • W (Union[np.ndarray, sp.spmatrix]): np.array, hierarchical covariance matrix of size (base, base).
  • sigmah (np.ndarray): np.array, forecast standard dev. of size (base, horizon).
  • seed (int, optional): int, random seed for numpy generator’s replicability. Default is 0.
References:

​
method __init__

__init__(
    S: Union[ndarray, spmatrix],
    P: Union[ndarray, spmatrix],
    y_hat: ndarray,
    sigmah: ndarray,
    W: Union[ndarray, spmatrix],
    seed: int = 0
)

​
method get_prediction_levels

get_prediction_levels(res, level)
Adds reconciled forecast levels to results dictionary Args:
  • res (dict): Results dictionary to update.
  • level (list): Confidence levels.
Returns:
  • dict: Updated results dictionary.

​
method get_prediction_quantiles

get_prediction_quantiles(res, quantiles)
Adds reconciled forecast quantiles to results dictionary Args:
  • res (dict): Results dictionary to update.
  • quantiles (np.ndarray): Quantiles to compute.
Returns:
  • dict: Updated results dictionary.

​
method get_samples

get_samples(num_samples: int)
Normality Coherent Samples. Obtains coherent samples under the Normality assumptions. Args:
  • num_samples (int): number of samples generated from coherent distribution.
Returns:
  • np.ndarray: samples: Coherent samples of size (base, horizon, num_samples).

​
class Bootstrap

Bootstrap Probabilistic Reconciliation Class. This method goes beyond the normality assumption for the base forecasts, the technique simulates future sample paths and uses them to generate base sample paths that are latered reconciled. This clever idea and its simplicity allows to generate coherent bootstraped prediction intervals for any reconciliation strategy. This class is meant to be used as the sampler input as other HierarchicalForecast reconciliation classes. Given a boostraped set of simulated sample paths: (y^τ[1],…,y^τ[B])(\hat{\mathbf{y}}^{[1]}_{\tau}, \dots ,\hat{\mathbf{y}}^{[B]}_{\tau}) The reconciled sample paths allow for reconciled distributional forecasts: (SPy^τ[1],…,SPy^τ[B])(\mathbf{S}\mathbf{P}\hat{\mathbf{y}}^{[1]}_{\tau}, \dots ,\mathbf{S}\mathbf{P}\hat{\mathbf{y}}^{[B]}_{\tau}) Args:
  • S: np.array, summing matrix of size (base, bottom).
  • P: np.array, reconciliation matrix of size (bottom, base).
  • y_hat: Point forecasts values of size (base, horizon).
  • y_insample: Insample values of size (base, insample_size).
  • y_hat_insample: Insample point forecasts of size (base, insample_size).
  • num_samples: int, number of bootstraped samples generated.
  • seed: int, random seed for numpy generator’s replicability.
References:
  • [Puwasala Gamakumara Ph. D. dissertation. Monash University, Econometrics and Business Statistics (2020).
  • "Probabilistic Forecast Reconciliation"](https: //bridges.monash.edu/articles/thesis/Probabilistic_Forecast_Reconciliation_Theory_and_Applications/11869533)
    • [Panagiotelis A., Gamakumara P. Athanasopoulos G., and Hyndman R. J. (2022).
  • "Probabilistic forecast reconciliation: Properties, evaluation and score optimisation”. European Journal of Operational Research.](https://www.sciencedirect.com/science/article/pii/S0377221722006087)

​
method __init__

__init__(
    S: Union[ndarray, spmatrix],
    P: Union[ndarray, spmatrix],
    y_hat: ndarray,
    y_insample: ndarray,
    y_hat_insample: ndarray,
    num_samples: int = 100,
    seed: int = 0,
    W: Union[ndarray, spmatrix] = None
)

​
method get_prediction_levels

get_prediction_levels(res, level)
Adds reconciled forecast levels to results dictionary

​
method get_prediction_quantiles

get_prediction_quantiles(res, quantiles)
Adds reconciled forecast quantiles to results dictionary

​
method get_samples

get_samples(num_samples: int)
Bootstrap Sample Reconciliation Method. Applies Bootstrap sample reconciliation method as defined by Gamakumara 2020. Generating independent sample paths and reconciling them with Bootstrap. Args:
  • num_samples: int, number of samples generated from coherent distribution.
Returns:
  • samples: Coherent samples of size (base, horizon, num_samples).

​
class PERMBU

PERMBU Probabilistic Reconciliation Class. The PERMBU method leverages empirical bottom-level marginal distributions with empirical copula functions (describing bottom-level dependencies) to generate the distribution of aggregate-level distributions using BottomUp reconciliation. The sample reordering technique in the PERMBU method reinjects multivariate dependencies into independent bottom-level samples. Algorithm: 1. For all series compute conditional marginals distributions. 2. Compute residuals ϵ^i,t\hat{\epsilon}_{i,t} and obtain rank permutations. 2. Obtain K-sample from the bottom-level series predictions. 3. Apply recursively through the hierarchical structure:
3.1. For a given aggregate series ii and its children series:
3.2. Obtain children’s empirical joint using sample reordering copula.
3.2. From the children’s joint obtain the aggregate series’s samples. Args:
  • S: np.array, summing matrix of size (base, bottom).
  • tags: Each key is a level and each value its S indices.
  • y_insample: Insample values of size (base, insample_size).
  • y_hat_insample: Insample point forecasts of size (base, insample_size).
  • sigmah: np.array, forecast standard dev. of size (base, horizon).
  • num_samples: int, number of normal prediction samples generated.
  • seed: int, random seed for numpy generator’s replicability.
References:
  • [Taieb, Souhaib Ben and Taylor, James W and Hyndman, Rob J. (2017). Coherent probabilistic forecasts for hierarchical time series.
  • International conference on machine learning ICML.](https: //proceedings.mlr.press/v70/taieb17a.html)

​
method __init__

__init__(
    S: Union[ndarray, spmatrix],
    tags: dict[str, ndarray],
    y_hat: ndarray,
    y_insample: ndarray,
    y_hat_insample: ndarray,
    sigmah: ndarray,
    num_samples: Optional[int] = None,
    seed: int = 0,
    P: Union[ndarray, spmatrix] = None
)

​
method get_prediction_levels

get_prediction_levels(res, level)
Adds reconciled forecast levels to results dictionary

​
method get_prediction_quantiles

get_prediction_quantiles(res, quantiles)
Adds reconciled forecast quantiles to results dictionary

​
method get_samples

get_samples(num_samples: Optional[int] = None)
PERMBU Sample Reconciliation Method. Applies PERMBU reconciliation method as defined by Taieb et. al 2017. Generating independent base prediction samples, restoring its multivariate dependence using estimated copula with reordering and applying the BottomUp aggregation to the new samples. Args:
  • num_samples: int, number of samples generated from coherent distribution.
Returns:
  • samples: Coherent samples of size (base, horizon, num_samples).