> ## Documentation Index
> Fetch the complete documentation index at: https://nixtla-old-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Probabilistic Methods

Here we provide a collection of methods designed to provide
hierarchically coherent probabilistic distributions, which means that
they generate samples of multivariate time series with hierarchical
linear constraints.

We designed these methods to extend the `core.HierarchicalForecast`
capabilities class. Check their [usage example
here](https://nixtlaverse.nixtla.io/hierarchicalforecast/examples/introduction.html).

# 1. Normality

***

<a href="https://github.com/Nixtla/hierarchicalforecast/blob/main/hierarchicalforecast/probabilistic_methods.py#L18" target="_blank" style={{ float: "right", fontSize: "smaller" }}>source</a>

### Normality

> ```text theme={null}
>  Normality (S:Union[numpy.ndarray,scipy.sparse._matrix.spmatrix],
>             P:Union[numpy.ndarray,scipy.sparse._matrix.spmatrix],
>             y_hat:numpy.ndarray, sigmah:numpy.ndarray,
>             W:Union[numpy.ndarray,scipy.sparse._matrix.spmatrix],
>             seed:int=0)
> ```

\*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](https://nixtla.github.io/hierarchicalforecast/src/methods.html).

Given base forecasts under a normal distribution:
$\hat{y}_{h} \sim \mathrm{N}(\hat{\boldsymbol{\mu}}, \hat{\mathbf{W}}_{h})$

The reconciled forecasts are also normally distributed:

$$

\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})

$$

**Parameters:**<br /> `S`: np.array, summing matrix of size (`base`,
`bottom`).<br /> `P`: np.array, reconciliation matrix of size (`bottom`,
`base`).<br /> `y_hat`: Point forecasts values of size (`base`,
`horizon`).<br /> `W`: np.array, hierarchical covariance matrix of size
(`base`, `base`).<br /> `sigmah`: np.array, forecast standard dev. of size
(`base`, `horizon`).<br /> `num_samples`: int, number of bootstraped
samples generated.<br /> `seed`: int, random seed for numpy generator’s
replicability.<br />

**References:**<br /> - [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)\*

***

<a href="https://github.com/Nixtla/hierarchicalforecast/blob/main/hierarchicalforecast/probabilistic_methods.py#L94" target="_blank" style={{ float: "right", fontSize: "smaller" }}>source</a>

### Normality.get\_samples

> ```text theme={null}
>  Normality.get_samples (num_samples:int)
> ```

\*Normality Coherent Samples.

Obtains coherent samples under the Normality assumptions.

**Parameters:**<br /> `num_samples`: int, number of samples generated from
coherent distribution.<br />

**Returns:**<br /> `samples`: Coherent samples of size (`base`, `horizon`,
`num_samples`).\*

# 2. Bootstrap

***

<a href="https://github.com/Nixtla/hierarchicalforecast/blob/main/hierarchicalforecast/probabilistic_methods.py#L144" target="_blank" style={{ float: "right", fontSize: "smaller" }}>source</a>

### Bootstrap

> ```text theme={null}
>  Bootstrap (S:Union[numpy.ndarray,scipy.sparse._matrix.spmatrix],
>             P:Union[numpy.ndarray,scipy.sparse._matrix.spmatrix],
>             y_hat:numpy.ndarray, y_insample:numpy.ndarray,
>             y_hat_insample:numpy.ndarray, num_samples:int=100, seed:int=0,
>             W:Union[numpy.ndarray,scipy.sparse._matrix.spmatrix]=None)
> ```

\*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](https://nixtla.github.io/hierarchicalforecast/src/methods.html).

Given a boostraped set of simulated sample paths:
$(\hat{\mathbf{y}}^{[1]}_{\tau}, \dots ,\hat{\mathbf{y}}^{[B]}_{\tau})$

The reconciled sample paths allow for reconciled distributional
forecasts:
$(\mathbf{S}\mathbf{P}\hat{\mathbf{y}}^{[1]}_{\tau}, \dots ,\mathbf{S}\mathbf{P}\hat{\mathbf{y}}^{[B]}_{\tau})$

**Parameters:**<br /> `S`: np.array, summing matrix of size (`base`,
`bottom`).<br /> `P`: np.array, reconciliation matrix of size (`bottom`,
`base`).<br /> `y_hat`: Point forecasts values of size (`base`,
`horizon`).<br /> `y_insample`: Insample values of size (`base`,
`insample_size`).<br /> `y_hat_insample`: Insample point forecasts of size
(`base`, `insample_size`).<br /> `num_samples`: int, number of bootstraped
samples generated.<br /> `seed`: int, random seed for numpy generator’s
replicability.<br />

**References:**<br /> - [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)\*

***

<a href="https://github.com/Nixtla/hierarchicalforecast/blob/main/hierarchicalforecast/probabilistic_methods.py#L196" target="_blank" style={{ float: "right", fontSize: "smaller" }}>source</a>

### Bootstrap.get\_samples

> ```text theme={null}
>  Bootstrap.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.

**Parameters:**<br /> `num_samples`: int, number of samples generated from
coherent distribution.<br />

**Returns:**<br /> `samples`: Coherent samples of size (`base`, `horizon`,
`num_samples`).\*

# 3. PERMBU

***

<a href="https://github.com/Nixtla/hierarchicalforecast/blob/main/hierarchicalforecast/probabilistic_methods.py#L245" target="_blank" style={{ float: "right", fontSize: "smaller" }}>source</a>

### PERMBU

> ```text theme={null}
>  PERMBU (S:Union[numpy.ndarray,scipy.sparse._matrix.spmatrix],
>          tags:dict[str,numpy.ndarray], y_hat:numpy.ndarray,
>          y_insample:numpy.ndarray, y_hat_insample:numpy.ndarray,
>          sigmah:numpy.ndarray, num_samples:Optional[int]=None, seed:int=0,
>          P:Union[numpy.ndarray,scipy.sparse._matrix.spmatrix]=None)
> ```

\*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.

```text theme={null}
Algorithm:
1.   For all series compute conditional marginals distributions.
2.   Compute residuals $\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:<br/>
    3.1.   For a given aggregate series $i$ and its children series:<br/>
    3.2.   Obtain children's empirical joint using sample reordering copula.<br/>
    3.2.   From the children's joint obtain the aggregate series's samples.    
```

**Parameters:**<br /> `S`: np.array, summing matrix of size (`base`,
`bottom`).<br /> `tags`: Each key is a level and each value its `S`
indices.<br /> `y_insample`: Insample values of size (`base`,
`insample_size`).<br /> `y_hat_insample`: Insample point forecasts of size
(`base`, `insample_size`).<br /> `sigmah`: np.array, forecast standard
dev. of size (`base`, `horizon`).<br /> `num_samples`: int, number of
normal prediction samples generated.<br /> `seed`: int, random seed for
numpy generator’s replicability.<br />

**References:**<br /> - [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)\*

***

<a href="https://github.com/Nixtla/hierarchicalforecast/blob/main/hierarchicalforecast/probabilistic_methods.py#L379" target="_blank" style={{ float: "right", fontSize: "smaller" }}>source</a>

### PERMBU.get\_samples

> ```text theme={null}
>  PERMBU.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.

**Parameters:**<br /> `num_samples`: int, number of samples generated from
coherent distribution.<br />

**Returns:**<br /> `samples`: Coherent samples of size (`base`, `horizon`,
`num_samples`).\*

# References

* [Rob J. Hyndman and George Athanasopoulos (2018). “Forecasting
  principles and practice, Reconciled distributional
  forecasts”.](https://otexts.com/fpp3/rec-prob.html)<br />
* [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)<br />
* [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)<br />
* [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)<br />