Quick Start

Introduction

pyths is a python package used for hierarchical forecasting, it implements multiple forecast reconciliation methods which are popular in forecasting literatures such as ols 1 、wls 2 、mint 3 et al.

features:

  • support popular forecast reconciliation models in the literature, e.g. ols, wls, mint et al. Temporal Hierarchy will be supported in the future.

  • multiple methods for the construction of hierarchy.

  • use different base forecasters for different hierarchical levels.

  • familiar sklearn-like API.

The steps of using this package are as follows:

  1. Define a hierarchy structure according to your data.

  2. Define a HFModel

  3. fit the HFModel using history time series

  4. generate base forecasts and reconcile the forecasts to obtain coherent point forecasts.

Define the Hierarchy

You can use classmethods of pyhts.Hierarchy to define hierarchy structure. see details in Define Hierarchy

As an example of the hierarchy shown in the figure below, let’s construct the hierarchy using pyhts.Hierarchy.new().

../_images/01_hierarchy.png 
from pyhts import Hierarchy
import pandas as pd
node_df = pd.DataFrame({'level1': ['A', 'A', 'B', 'B'], 'level2': ['AA', 'AB', 'BC', 'BB']})
period = 12
hierarchy = Hierarchy.new(node_df, structures = [('level1', 'level2')],period=period)
print(hierarchy.node_name)
# array(['total_total', 'level1_A', 'level1_B', 'level2_AA', 'level2_AB',
#        'level2_BC', 'level2_BB'], dtype=object)

where period is frequency of time series, m=12 means monthly series.

Define HFModel

Let’s define a simple ols reconciliation model that use auto.arima as the base forecasting model, see details in Hierarchical Forecasting Model .

from pyhts import HFModel
ols_model = HFModel(hierarchy=hierarchy, base_forecasters='arima', hf_method='comb', comb_method='ols')

where

  • hierarchy is the hierarchy define above.

  • base_forecasters are base methods that used to generate base forecasts. arima and ets are supported for now, which are implemented by statsforecast package.You can also define your custom base forecasters for each level, see details in customize base forecasters.

  • hf_model is the method used for hierarchical forecasting, comb that means forecast reconciliation is supported for now. Classical methods such as Top-Down、Bottom-up and middle-out will be supported in the future.

  • comb_method is the forecast reconciliation method. mint、wls、ols are supported. see details in Hierarchical Forecasting Model.

fit model

pyhts.HFModel.fit() would fit base forecasting models for each time series and compute the reconciliation matrix.

import numpy as np
data = np.random.random((108, 4))
train = data[:-12, :]
test = data[-12:, :]
model.fit(train)

forecast

pyhts.HFModel.forecast() would generate base forecasts for each time series and reconcile base forecasts to get coherent forecasts.

reconciled_forecasts = model.predict(horizon=12)
print(reconciled_forecasts.shape)
# (12, 4)

reconciled_forecasts just contain reconciled forecasts of bottom level, you can use aggregate_ts() to get reconciled forecasts of all levels.

reconciled_forecasts_all_levels = hierarchy.aggregate_ts(reconciled_forecasts)
# (12, 7)

measurement

You can evaluate forecasting accuracy of both base forecasts and reconciled forecasts, using accuray_base() and accuracy() respectively.

base_forecasts = model.generate_base_forecasts(horizon=12)
hierarchy.accuracy_base(test, base_forecasts, hist=train, levels=None, measure=['mase', 'mape'])
hierarchy.accuracy(test, reconciled_forecasts, hist=train, levels=None, measure=['mase', 'mape'])

where levels=None means accuracy of all levels are returned. hist are history time series that are needed by mase measure.

1

Hyndman, R. A. Ahmed, G. Athanasopoulos, and H. L. Shang, “Optimal combination forecasts for hierarchical time series,” Computational Statistics & Data Analysis, vol. 55, no. 9, pp. 2579–2589, Sep. 2011, doi: 10.1016/j.csda.2011.03.006.

2

Panagiotelis, G. Athanasopoulos, P. Gamakumara, and R. J. Hyndman, “Forecast reconciliation: A geometric view with new insights on bias correction,” International Journal of Forecasting, vol. 37, no. 1, pp. 343–359, Jan. 2021, doi: 10.1016/j.ijforecast.2020.06.004.

3

Wickramasuriya, G. Athanasopoulos, and R. J. Hyndman, “Optimal Forecast Reconciliation for Hierarchical and Grouped Time Series Through Trace Minimization,” Journal of the American Statistical Association, vol. 114, no. 526, pp. 804–819, Apr. 2019, doi: 10.1080/01621459.2018.1448825.