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.

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.

1

Step 1: Import and Initialize

Tip: Make sure you have the nixtla package installed.

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)

UserWarning: Could not infer format, falling back to parsing individually. Specify the format explicitly if you encounter inconsistencies.

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

The hierarchical reconciliation steps help maintain forecast coherence across all hierarchy layers and can also improve overall accuracy.

​
References