The HierarchicalForecast package contains utility functions to wrangle and visualize hierarchical series datasets. The aggregate function of the module allows you to create a hierarchy from categorical variables representing the structure levels, returning also the aggregation contraints matrix $\mathbf{S}$.

In addition, HierarchicalForecast ensures compatibility of its reconciliation methods with other popular machine-learning libraries via its external forecast adapters that transform output base forecasts from external libraries into a compatible data frame format.

​

Aggregate Function

​

aggregate

 aggregate (df:pandas.core.frame.DataFrame, spec:List[List[str]],
            is_balanced:bool=False, sparse_s:bool=False)

Utils Aggregation Function. Aggregates bottom level series contained in the pandas DataFrame df according to levels defined in the spec list.

​

Hierarchical Visualization

​

HierarchicalPlot

 HierarchicalPlot (S:pandas.core.frame.DataFrame,
                   tags:Dict[str,numpy.ndarray])

Hierarchical Plot

This class contains a collection of matplotlib visualization methods, suited for small to medium sized hierarchical series.

Parameters:
S: pd.DataFrame with summing matrix of size (base, bottom), see aggregate function.
tags: np.ndarray, with hierarchical aggregation indexes, where each key is a level and its value contains tags associated to that level.

​

plot_summing_matrix

 plot_summing_matrix ()

Summation Constraints plot

This method simply plots the hierarchical aggregation constraints matrix $\mathbf{S}$.

​

plot_series

 plot_series (series:str, Y_df:Optional[pandas.core.frame.DataFrame]=None,
              models:Optional[List[str]]=None,
              level:Optional[List[int]]=None)

Single Series plot

Parameters:
series: str, string identifying the 'unique_id' any-level series to plot.
Y_df: pd.DataFrame, hierarchically structured series ($\mathbf{y}_{[a,b]}$). It contains columns ['unique_id', 'ds', 'y'], it may have 'models'.
models: List[str], string identifying filtering model columns. level: float list 0-100, confidence levels for prediction intervals available in Y_df.

Returns:
Single series plot with filtered models and prediction interval level.

​

plot_hierarchically_linked_series

 plot_hierarchically_linked_series (bottom_series:str,
                                    Y_df:Optional[pandas.core.frame.DataFr
                                    ame]=None,
                                    models:Optional[List[str]]=None,
                                    level:Optional[List[int]]=None)

Hierarchically Linked Series plot

Parameters:
bottom_series: str, string identifying the 'unique_id' bottom-level series to plot.
Y_df: pd.DataFrame, hierarchically structured series ($\mathbf{y}_{[a,b]}$). It contains columns [‘unique_id’, ‘ds’, ‘y’] and models.
models: List[str], string identifying filtering model columns. level: float list 0-100, confidence levels for prediction intervals available in Y_df.

Returns:
Collection of hierarchilly linked series plots associated with the bottom_series and filtered models and prediction interval level.

​

plot_hierarchical_predictions_gap

 plot_hierarchical_predictions_gap (Y_df:pandas.core.frame.DataFrame,
                                    models:Optional[List[str]]=None,
                                    xlabel:Optional=None,
                                    ylabel:Optional=None)

Hierarchically Predictions Gap plot

Parameters:
Y_df: pd.DataFrame, hierarchically structured series ($\mathbf{y}_{[a,b]}$). It contains columns [‘unique_id’, ‘ds’, ‘y’] and models.
models: List[str], string identifying filtering model columns. xlabel: str, string for the plot’s x axis label. ylable: str, string for the plot’s y axis label.

Returns:
Plots of aggregated predictions at different levels of the hierarchical structure. The aggregation is performed according to the tag levels see aggregate function.

from statsforecast.core import StatsForecast
from statsforecast.models import AutoARIMA, ETS, Naive
from datasetsforecast.hierarchical import HierarchicalData

Y_df, S, tags = HierarchicalData.load('./data', 'Labour')
Y_df['ds'] = pd.to_datetime(Y_df['ds'])

Y_test_df  = Y_df.groupby('unique_id').tail(24)
Y_train_df = Y_df.drop(Y_test_df.index)
Y_test_df  = Y_test_df.set_index('unique_id')
Y_train_df = Y_train_df.set_index('unique_id')

fcst = StatsForecast(
    df=Y_train_df, 
    #models=[AutoARIMA(season_length=12), Naive()], 
    models=[ETS(season_length=12, model='AAZ')],
    freq='MS', 
    n_jobs=-1
)
Y_hat_df = fcst.forecast(h=24)

# Plot prediction difference of different aggregation
# Levels Country, Country/Region, Country/Gender/Region ...
hplots = HierarchicalPlot(S=S, tags=tags)

hplots.plot_hierarchical_predictions_gap(
    Y_df=Y_hat_df, models='ETS',
    xlabel='Month', ylabel='Predictions',
)

​

External Forecast Adapters

​

samples_to_quantiles_df

 samples_to_quantiles_df (samples:numpy.ndarray, unique_ids:Iterable[str],
                          dates:Iterable,
                          quantiles:Optional[Iterable[float]]=None,
                          level:Optional[Iterable[int]]=None,
                          model_name:Optional[str]='model')

Transform Random Samples into HierarchicalForecast input. Auxiliary function to create compatible HierarchicalForecast input Y_hat_df dataframe.

Parameters:
samples: numpy array. Samples from forecast distribution of shape [n_series, n_samples, horizon].
unique_ids: string list. Unique identifiers for each time series.
dates: datetime list. List of forecast dates.
quantiles: float list in [0., 1.]. Alternative to level, quantiles to estimate from y distribution.
level: int list in [0,100]. Probability levels for prediction intervals.
model_name: string. Name of forecasting model.

Returns:
quantiles: float list in [0., 1.]. quantiles to estimate from y distribution .
Y_hat_df: pd.DataFrame. With base quantile forecasts with columns ds and models to reconcile indexed by unique_id.