Temporal hierarchical forecasting model

Temporal hierarchical forecasting model is defined by TemporalHFModel

TemporalHFModel API

class pyhts.TemporalHFModel(hierarchy, base_forecasters, hf_method='comb', comb_method='ols', weights=None, immutable_set=None)

Temporal hierarchical forecasting model

__init__(hierarchy, base_forecasters, hf_method='comb', comb_method='ols', weights=None, immutable_set=None)

Constructor

Parameters

  • hierarchy (TemporalHierarchy) – hierarchical structure.

  • base_forecasters (Union[dict, str]) – base forecasters, It should be string or dictionary. If string, it could be “arima” implemented by statsforecast. If dict, its keys should be the level name of the hierarchy, corresponding values represent the fitted or not fitted Forecaster.

  • hf_method – comb for optimal combination

  • comb_method – ols, wls, mint

  • weights – weighting strategies, same as HFModel

  • immutable_set – immutable nodes, same as HFModel

fit(ts, xreg=None, **kwargs)

fit base models and reconciliation matrix

Parameters

  • ts (ndarray) – univariate time series

  • xreg (Optional[dict]) – dict containing covariates passed to each level

  • kwargs – other possible arguments passed to forecaster

Returns

generate_base_forecast(horizon=1, xreg=None, **kwargs)

generate base forecasts

Parameters

  • horizon (int) – horizon for the top level

  • xreg (Optional[dict]) – covariates dict passed to forecaster

  • kwargs – other arguments passed to forecaster

Return type

dict

Returns

dict containing base forecasts of each level

predict(horizon=1, xreg=None, **kwargs)

predict base forecasts and reconcile them.

Parameters

  • horizon (int) – horizon for the top level

  • xreg (Optional[dict]) – covariates dict passed to forecaster

  • kwargs – other arguments passed to forecaster

Returns

dict containing reconciled forecasts of each level

Examples

Randomly generate some dataset and define the hierarchy. Here, we consider a monthly time series and aggregation perios are 2, 3, 6, 12.

>>> import numpy as np
>>> from pyhts import TemporalHierarchy
>>> ts = np.random.random(120)
>>> ht = TemporalHierarchy.new(agg_periods=[1, 2, 3, 6, 12], forecast_frequency=12)
>>> ht.level_name
['agg_12', 'agg_6', 'agg_3', 'agg_2', 'agg_1']

Define and fit temporal hierarchical forecasting model

Then we can construct a temporal hierarchical forecasting model using the ols reconciliation method and arima models as base forecasters.

>>> from pyhts import TemporalHFModel
>>> hfmodel = TemporalHFModel(ht, "arima", hf_method='comb', comb_method='ols')
>>> hfmodel.fit(ts)

Predict and evaluate forecasts

The horizon here should be the corresponding forecast horizon for the top level. For example, if we want to predict the next 12 months, the horizon should be 1 (the top level is year).

>> fcasts = hfmodel.predict(1)
{'agg_12': array([5.89485775]),
'agg_6': array([2.94742887, 2.94742887]),
'agg_3': array([1.47371444, 1.47371444, 1.47371444, 1.47371444]),
'agg_2': array([0.98247629, 0.98247629, 0.98247629, 0.98247629, 0.98247629,
      0.98247629]),
'agg_1': array([0.49123815, 0.49123815, 0.49123815, 0.49123815, 0.49123815,
      0.49123815, 0.49123815, 0.49123815, 0.49123815, 0.49123815,
      0.49123815, 0.49123815])}

The forecasts can be evaluated using accuracy() method. We pass the future observations, forecasts and historical observations (if needed). The measures for each level are returned.

>> real = np.random.random(12)
>> ht.accuracy(real, pred, ts)
            mase      mape      rmse
   agg_12  3.023196  0.187241  1.358036
   agg_6   1.248526  0.186900  0.683057
   agg_3   0.742426  0.178560  0.455563
   agg_2   1.144290  0.504512  0.525026
   agg_1   0.810293  2.290112  0.317474