This tutorial demonstrates how to use TimeGPT for temporal hierarchical forecasting. We will forecast at hourly and aggregated 2-hourly frequency levels, then apply temporal reconciliation techniques to improve overall precision.

1

1. Load and Process Data

Here, we prepare our dataset by reading it into a pandas DataFrame, splitting it into training and testing subsets, and initializing the NixtlaClient.

Data Loading and Preparation
import numpy as np
import pandas as pd

from utilsforecast.evaluation import evaluate
from utilsforecast.plotting import plot_series
from utilsforecast.losses import mae, rmse
from nixtla import NixtlaClient

# Initialize NixtlaClient
nixtla_client = NixtlaClient(
    # api_key = 'my_api_key_provided_by_nixtla'
)

# Read and process dataset
df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short-with-ex-vars.csv')
df['ds'] = pd.to_datetime(df['ds'])
df_sub = df.query('unique_id == "DE"')

# Create train-test splits
df_train = df_sub.query('ds < "2017-12-29"')
df_test = df_sub.query('ds >= "2017-12-29"')

df_train.shape, df_test.shape

The below output shows the number of rows and columns for our training and testing data, respectively.

Plot the training and test data:

Plot Training and Test Data
plot_series(
    df_train[['unique_id', 'ds', 'y']][-200:],
    forecasts_df=df_test[['unique_id', 'ds', 'y']].rename(columns={'y': 'test'})
)

Visualization of the last 200 observations in the training dataset and 48 observations in the test dataset.

2

2. Temporal Aggregation

In this step, we define and apply temporal aggregation to create separate frequency levels (1-hour and 2-hour periods).

Temporal Aggregation Setup and Execution
spec_temporal = { "2-hour-period": 2, "1-hour-period": 1 }

from hierarchicalforecast.utils import aggregate_temporal

Y_train, S_train, tags_train = aggregate_temporal(df=df_train[['unique_id', 'ds', 'y']], spec=spec_temporal)
Y_test, S_test, tags_test = aggregate_temporal(df=df_test[['unique_id', 'ds', 'y']], spec=spec_temporal)

# Example aggregated data (Y_train)
Y_train.query("ds <= '2017-10-22 01:00:00'")
3

3. Computing Base Forecasts (TimeGPT)

TimeGPT can produce forecasts at multiple frequencies with minimal configuration. We forecast for each temporal aggregation, then concatenate the predictions.

Base Forecast Computation Loop
Y_hats = []
id_cols = ["unique_id", "temporal_id", "ds", "y"]

for level, temporal_ids_train in tags_train.items():
    Y_level_train = Y_train.query("temporal_id in @temporal_ids_train")
    temporal_ids_test = tags_test[level]
    Y_level_test = Y_test.query("temporal_id in @temporal_ids_test")
    freq_level = pd.infer_freq(Y_level_train["ds"].unique())
    horizon_level = Y_level_test["ds"].nunique()

    Y_hat_level = nixtla_client.forecast(
        df=Y_level_train[["ds", "unique_id", "y"]],
        h=horizon_level
    )
    Y_hat_level = Y_hat_level.merge(Y_level_test, on=["ds", "unique_id"], how="left")
    Y_hat_cols = id_cols + [col for col in Y_hat_level.columns if col not in id_cols]
    Y_hat_level = Y_hat_level[Y_hat_cols]
    Y_hats.append(Y_hat_level)

Y_hat = pd.concat(Y_hats, ignore_index=True)
4

4. Forecast Reconciliation

By default, forecasts at multiple frequencies may not align. Use a reconciliation method to ensure consistent predictions across all hierarchies.

Forecast Reconciliation with MinTrace
from hierarchicalforecast.methods import MinTrace
from hierarchicalforecast.core import HierarchicalReconciliation

reconcilers = [MinTrace(method="wls_struct")]
hrec = HierarchicalReconciliation(reconcilers=reconcilers)

Y_rec = hrec.reconcile(Y_hat_df=Y_hat, S=S_test, tags=tags_test, temporal=True)
5

5. Evaluation

We use MAE to measure accuracy of the reconciled forecasts. This process can be extended to other metrics or used for hyperparameter tuning.

Forecast Evaluation with MAE
import hierarchicalforecast.evaluation as hfe

evaluation = hfe.evaluate(
    df=Y_rec.drop(columns='unique_id'),
    tags=tags_test,
    metrics=[mae],
    id_col='temporal_id'
)

numeric_cols = evaluation.select_dtypes('number').columns
evaluation[numeric_cols] = evaluation[numeric_cols].map('{:.3}'.format).astype(float)
evaluation
6

6. Forecast Visualization

Visualize reconciled forecasts to verify alignment at each frequency. This is especially helpful for spotting inconsistencies or anomalies.

Key Takeaways

  • TimeGPT can efficiently handle multiple frequency levels.
  • Temporal reconciliation ensures consistent forecasts across hierarchies.
  • Evaluating forecasts at each frequency level helps refine models.

​
Conclusion

In this tutorial, we demonstrated:

  • Creating multi-frequency forecasts with TimeGPT.
  • Temporal reconciliation to improve forecast accuracy and ensure coherence across different time aggregations.

For further exploration, consider experimenting with different metrics, applying alternative reconciliation methods, or extending the forecasting horizon for more complex forecasting needs.