HierarchicalForecast contains pure Python implementations of hierarchical reconciliation methods as well as a core.HierarchicalReconciliation wrapper class that enables easy interaction with these methods through pandas DataFrames containing the hierarchical time series and the base predictions.

The core.HierarchicalReconciliation reconciliation class operates with the hierarchical time series pd.DataFrame Y_df, the base predictions pd.DataFrame Y_hat_df, the aggregation constraints matrix S. For more information on the creation of aggregation constraints matrix see the utils aggregation method.

​

core.HierarchicalReconciliation

​

init

 init (reconcilers:List[hierarchicalforecast.methods.HReconciler])

*Hierarchical Reconciliation Class.

The core.HierarchicalReconciliation class allows you to efficiently fit multiple HierarchicaForecast methods for a collection of time series and base predictions stored in pandas DataFrames. The Y_df dataframe identifies series and datestamps with the unique_id and ds columns while the y column denotes the target time series variable. The Y_h dataframe stores the base predictions, example (AutoARIMA, ETS, etc.).

Parameters:
reconcilers: A list of instantiated classes of the reconciliation methods module .

References:
Rob J. Hyndman and George Athanasopoulos (2018). “Forecasting principles and practice, Hierarchical and Grouped Series”.*

​

HierarchicalReconciliation

 HierarchicalReconciliation
                             (reconcilers:List[hierarchicalforecast.method
                             s.HReconciler])

*Hierarchical Reconciliation Class.

The core.HierarchicalReconciliation class allows you to efficiently fit multiple HierarchicaForecast methods for a collection of time series and base predictions stored in pandas DataFrames. The Y_df dataframe identifies series and datestamps with the unique_id and ds columns while the y column denotes the target time series variable. The Y_h dataframe stores the base predictions, example (AutoARIMA, ETS, etc.).

Parameters:
reconcilers: A list of instantiated classes of the reconciliation methods module .

References:
Rob J. Hyndman and George Athanasopoulos (2018). “Forecasting principles and practice, Hierarchical and Grouped Series”.*

​

reconcile

 reconcile (Y_hat_df:pandas.core.frame.DataFrame,
            S:pandas.core.frame.DataFrame, tags:Dict[str,numpy.ndarray],
            Y_df:Optional[pandas.core.frame.DataFrame]=None,
            level:Optional[List[int]]=None,
            intervals_method:str='normality', num_samples:int=-1,
            seed:int=0, sort_df:bool=True, is_balanced:bool=False)

*Hierarchical Reconciliation Method.

The reconcile method is analogous to SKLearn fit_predict method, it applies different reconciliation techniques instantiated in the reconcilers list.

Most reconciliation methods can be described by the following convenient linear algebra notation:

$\tilde{\mathbf{y}}_{[a,b],\tau} = \mathbf{S}_{[a,b][b]} \mathbf{P}_{[b][a,b]} \hat{\mathbf{y}}_{[a,b],\tau}$

where $a, b$ represent the aggregate and bottom levels, $\mathbf{S}_{[a,b][b]}$ contains the hierarchical aggregation constraints, and $\mathbf{P}_{[b][a,b]}$ varies across reconciliation methods. The reconciled predictions are $\tilde{\mathbf{y}}_{[a,b],\tau}$, and the base predictions $\hat{\mathbf{y}}_{[a,b],\tau}$.

Parameters:
Y_hat_df: pd.DataFrame, base forecasts with columns ds and models to reconcile indexed by unique_id.
Y_df: pd.DataFrame, training set of base time series with columns ['ds', 'y'] indexed by unique_id.
If a class of self.reconciles receives y_hat_insample, Y_df must include them as columns.
S: pd.DataFrame with summing matrix of size (base, bottom), see aggregate method.
tags: Each key is a level and its value contains tags associated to that level.
level: positive float list [0,100), confidence levels for prediction intervals.
intervals_method: str, method used to calculate prediction intervals, one of normality, bootstrap, permbu.
num_samples: int=-1, if positive return that many probabilistic coherent samples. seed: int=0, random seed for numpy generator’s replicability.
sort_df : bool (default=True), if True, sort df by [unique_id,ds].
is_balanced: bool=False, wether Y_df is balanced, set it to True to speed things up if Y_df is balanced.

Returns:
Y_tilde_df: pd.DataFrame, with reconciled predictions.*

​

bootstrap_reconcile

 bootstrap_reconcile (Y_hat_df:pandas.core.frame.DataFrame,
                      S_df:pandas.core.frame.DataFrame,
                      tags:Dict[str,numpy.ndarray],
                      Y_df:Optional[pandas.core.frame.DataFrame]=None,
                      level:Optional[List[int]]=None,
                      intervals_method:str='normality',
                      num_samples:int=-1, num_seeds:int=1,
                      sort_df:bool=True)

*Bootstraped Hierarchical Reconciliation Method.

Applies N times, based on different random seeds, the reconcile method for the different reconciliation techniques instantiated in the reconcilers list.

Parameters:
Y_hat_df: pd.DataFrame, base forecasts with columns ds and models to reconcile indexed by unique_id.
Y_df: pd.DataFrame, training set of base time series with columns ['ds', 'y'] indexed by unique_id.
If a class of self.reconciles receives y_hat_insample, Y_df must include them as columns.
S: pd.DataFrame with summing matrix of size (base, bottom), see aggregate method.
tags: Each key is a level and its value contains tags associated to that level.
level: positive float list [0,100), confidence levels for prediction intervals.
intervals_method: str, method used to calculate prediction intervals, one of normality, bootstrap, permbu.
num_samples: int=-1, if positive return that many probabilistic coherent samples. num_seeds: int=1, random seed for numpy generator’s replicability.
sort_df : bool (default=True), if True, sort df by [unique_id,ds].

Returns:
Y_bootstrap_df: pd.DataFrame, with bootstraped reconciled predictions.*

​

Example

import numpy as np
import pandas as pd

from statsforecast.core import StatsForecast
from statsforecast.models import ETS, Naive

from hierarchicalforecast.utils import aggregate
from hierarchicalforecast.core import HierarchicalReconciliation
from hierarchicalforecast.methods import BottomUp, MinTrace

# Load TourismSmall dataset
df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/tourism.csv')
df = df.rename({'Trips': 'y', 'Quarter': 'ds'}, axis=1)
df.insert(0, 'Country', 'Australia')

# Create hierarchical seires based on geographic levels and purpose
# And Convert quarterly ds string to pd.datetime format
hierarchy_levels = [['Country'],
                    ['Country', 'State'], 
                    ['Country', 'Purpose'], 
                    ['Country', 'State', 'Region'], 
                    ['Country', 'State', 'Purpose'], 
                    ['Country', 'State', 'Region', 'Purpose']]

Y_df, S_df, tags = aggregate(df=df, spec=hierarchy_levels)
qs = Y_df['ds'].str.replace(r'(\d+) (Q\d)', r'\1-\2', regex=True)
Y_df['ds'] = pd.PeriodIndex(qs, freq='Q').to_timestamp()
Y_df = Y_df.reset_index()

# Split train/test sets
Y_test_df  = Y_df.groupby('unique_id').tail(4)
Y_train_df = Y_df.drop(Y_test_df.index)

# Compute base auto-ETS predictions
# Careful identifying correct data freq, this data quarterly 'Q'
fcst = StatsForecast(models=[Naive()], freq='Q', n_jobs=-1)
Y_hat_df = fcst.forecast(df=Y_train_df, h=4, fitted=True)
Y_fitted_df = fcst.forecast_fitted_values()

# Reconcile the base predictions
Y_train_df = Y_train_df.reset_index().set_index('unique_id')
Y_hat_df = Y_hat_df.reset_index().set_index('unique_id')
reconcilers = [BottomUp(),
               MinTrace(method='mint_shrink')]
hrec = HierarchicalReconciliation(reconcilers=reconcilers)
Y_rec_df = hrec.reconcile(Y_hat_df=Y_hat_df, 
                          Y_df=Y_fitted_df,
                          S=S_df, tags=tags)
Y_rec_df.groupby('unique_id', observed=True).head(2)