​
What is hierarchical forecasting?

Hierarchical forecasting involves generating forecasts for multiple time series that share a hierarchical structure (e.g., product demand by category, department, or region). The goal is to ensure that forecasts are coherent across each level of the hierarchy.

Hierarchical forecasting can be particularly important when you need to generate forecasts at different granularities (e.g., country, state, region) and ensure they align with each other and aggregate correctly at higher levels.

Using TimeGPT, you can create forecasts for multiple related time series and then apply hierarchical forecasting methods from HierarchicalForecast to reconcile those forecasts across your specified hierarchy.

Why use hierarchical forecasting?

  • Ensures consistency: Forecasts at lower levels add up to higher-level forecasts.

  • Improves accuracy: Reconciliation methods often yield more robust predictions.

  • Facilitates deeper insights: Understand how smaller segments contribute to overall trends.

​
Libraries Used

TimeGPT

TimeGPT is Nixtla’s generative AI for time series forecasting. It supports forecasting across different levels of data granularity.

HierarchicalForecast

A library offering reconciliation algorithms like MinTrace to keep forecasts coherent across hierarchy levels.

​
Tutorial

Tip: Open the code for this tutorial in Google Colab and run it live.

1

Step 1: Install, Import and Initialize

pip install nixtla
pip install hierarchicalforecast

import pandas as pd
import numpy as np

from nixtla import NixtlaClient

nixtla_client = NixtlaClient(
    api_key='my_api_key_provided_by_nixtla'
)

Use an Azure AI endpoint
To use an Azure AI endpoint, set the base_url argument:

nixtla_client = NixtlaClient(
    base_url="your azure ai endpoint",
    api_key="your api_key"
)
2

Step 2: Load and Prepare Data

This tutorial uses the Australian Tourism dataset from Forecasting: Principles and Practices. The dataset contains different levels of hierarchical data, from the entire country of Australia down to individual regions.

Examples of Australia's Tourism Hierarchy and Map

The dataset provides only the lowest-level series, so higher-level series need to be aggregated explicitly.

Y_df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/tourism.csv')
Y_df = Y_df.rename({'Trips': 'y', 'Quarter': 'ds'}, axis=1)
Y_df.insert(0, 'Country', 'Australia')
Y_df = Y_df[['Country', 'Region', 'State', 'Purpose', 'ds', 'y']]
Y_df['ds'] = Y_df['ds'].str.replace(r'(\d+) (Q\d)', r'\1-\2', regex=True)
Y_df['ds'] = pd.to_datetime(Y_df['ds'])

Y_df.head(10)
CountryRegionStatePurposedsy
AustraliaAdelaideSouth AustraliaBusiness1998-01-01135.077690
AustraliaAdelaideSouth AustraliaBusiness1998-04-01109.987316
AustraliaAdelaideSouth AustraliaBusiness1998-07-01166.034687
AustraliaAdelaideSouth AustraliaBusiness1998-10-01127.160464
AustraliaAdelaideSouth AustraliaBusiness1999-01-01137.448533
AustraliaAdelaideSouth AustraliaBusiness1999-04-01199.912586
AustraliaAdelaideSouth AustraliaBusiness1999-07-01169.355090
AustraliaAdelaideSouth AustraliaBusiness1999-10-01134.357937
AustraliaAdelaideSouth AustraliaBusiness2000-01-01154.034398
AustraliaAdelaideSouth AustraliaBusiness2000-04-01168.776364

We define the dataset hierarchies explicitly. Each level in the list describes one view of the hierarchy:

spec = [
    ['Country'],
    ['Country', 'State'],
    ['Country', 'Purpose'],
    ['Country', 'State', 'Region'],
    ['Country', 'State', 'Purpose'],
    ['Country', 'State', 'Region', 'Purpose']
]

Then, use aggregate from HierarchicalForecast to generate the aggregated series:

from hierarchicalforecast.utils import aggregate

Y_df, S_df, tags = aggregate(Y_df, spec)
Y_df.head(10)
unique_iddsy
Australia1998-01-0123182.197269
Australia1998-04-0120323.380067
Australia1998-07-0119826.640511
Australia1998-10-0120830.129891
Australia1999-01-0122087.353380
Australia1999-04-0121458.373285
Australia1999-07-0119914.192508
Australia1999-10-0120027.925640
Australia2000-01-0122339.294779
Australia2000-04-0119941.063482

Next, create the train/test splits. Here, we use the last two years (eight quarters) of data for testing:

Y_test_df = Y_df.groupby('unique_id').tail(8)
Y_train_df = Y_df.drop(Y_test_df.index)
3

Step 3: Hierarchical Forecasting Using TimeGPT

Now we’ll generate base forecasts across all series using TimeGPT and then apply hierarchical reconciliation to ensure the forecasts align across each level.

Generate Base Forecasts

Obtain forecasts with TimeGPT for all series in your training data:

timegpt_fcst = nixtla_client.forecast(
    df=Y_train_df,
    h=8,
    freq='QS',
    add_history=True
)

Available models in Azure AI
Specify model="azureai" when using a custom Azure AI endpoint. Public APIs support timegpt-1 and timegpt-1-long-horizon.

Next, separate the generated forecasts into in-sample (historical) and out-of-sample (forecasted) periods:

timegpt_fcst_insample = timegpt_fcst.query("ds < '2016-01-01'")
timegpt_fcst_outsample = timegpt_fcst.query("ds >= '2016-01-01'")

Visualize TimeGPT Forecasts

Quickly visualize the forecasts for different hierarchy levels. Here, we look at the entire country, the state of Queensland, the Brisbane region, and holidays in Brisbane:

nixtla_client.plot(
    Y_df,
    timegpt_fcst_outsample,
    max_insample_length=4 * 12,
    unique_ids=[
        'Australia',
        'Australia/Queensland',
        'Australia/Queensland/Brisbane',
        'Australia/Queensland/Brisbane/Holiday'
    ]
)

Apply Hierarchical Reconciliation

We use MinTrace methods to reconcile forecasts across all levels of the hierarchy.

from hierarchicalforecast.methods import MinTrace
from hierarchicalforecast.core import HierarchicalReconciliation

reconcilers = [
    MinTrace(method='ols'),
    MinTrace(method='mint_shrink')
]

hrec = HierarchicalReconciliation(reconcilers=reconcilers)

Y_df_with_insample_fcsts = timegpt_fcst_insample.merge(Y_df.copy())

Y_rec_df = hrec.reconcile(
    Y_hat_df=timegpt_fcst_outsample,
    Y_df=Y_df_with_insample_fcsts,
    S=S_df,
    tags=tags
)

Now, let’s plot the reconciled forecasts to ensure they make sense across the full country → state → region → purpose hierarchy:

nixtla_client.plot(
    Y_df,
    Y_rec_df,
    max_insample_length=4 * 12,
    unique_ids=[
        'Australia',
        'Australia/Queensland',
        'Australia/Queensland/Brisbane',
        'Australia/Queensland/Brisbane/Holiday'
    ]
)

Evaluate Forecast Accuracy

Finally, evaluate your forecast performance using RMSE for different levels of the hierarchy, from total (country) to bottom-level (region/purpose).

from hierarchicalforecast.evaluation import evaluate
from utilsforecast.losses import rmse

eval_tags = {
    'Total': tags['Country'],
    'Purpose': tags['Country/Purpose'],
    'State': tags['Country/State'],
    'Regions': tags['Country/State/Region'],
    'Bottom': tags['Country/State/Region/Purpose']
}

evaluation = evaluate(
    df=Y_rec_df.merge(Y_test_df, on=['unique_id', 'ds']),
    tags=eval_tags,
    train_df=Y_train_df,
    metrics=[rmse]
)

evaluation[evaluation.select_dtypes(np.number).columns] = evaluation.select_dtypes(np.number).map('{:.2f}'.format)

evaluation
levelmetricTimeGPTTimeGPT/MinTrace_method-olsTimeGPT/MinTrace_method-mint_shrink
0Totalrmse1433.071436.071627.43
1Purposermse482.09475.64507.50
2Statermse275.85278.39294.28
3Regionsrmse49.4047.9147.99
4Bottomrmse19.3219.1118.86
5Overallrmse38.6638.2139.16

We made a small improvement in overall RMSE by reconciling the forecasts with MinTrace(ols), and made them slightly worse using MinTrace(mint_shrink), indicating that the base forecasts were relatively strong already.

However, we now have coherent forecasts too - so not only did we make a (small) accuracy improvement, we also got coherency to the hierarchy as a result of our reconciliation step.

​
References