GitHub Repository: ibm/watson-machine-learning-samples
Path: blob/master/cpd5.2/notebooks/python_sdk/deployments/foundation_models/Use Time Series Foundation Models and timeseries data to predict energy demand.ipynb
⁶⁴¹² views

Kernel: watsonx-ai-samples-py-312

Use Time Series Foundation Models and time series data to predict energy demand

Disclaimers

Use only Projects and Spaces that are available in watsonx context.

Notebook content

This notebook demonstrates the use of a pre-trained time series foundation model for multivariate forecasting tasks and showcases the variety of features available in Time Series Foundation Models.

Some familiarity with Python is helpful. This notebook uses Python 3.12.

Learning goals

The learning goals of this notebook are:

To explore Time Series Foundation Models
To initialize the model
To forecast based on historical data

This notebook contains the following parts:

Set up the environment

Before you use the sample code in this notebook, you must perform the following setup tasks:

Contact with your Cloud Pak for Data administrator and ask them for your account credentials

Install dependencies

Note: ibm-watsonx-ai documentation can be found here.

In [1]:

%pip install -U wget | tail -n 1
%pip install -U matplotlib | tail -n 1
%pip install -U "ibm-watsonx-ai>=1.1.24" | tail -n 1

Out[1]:

Successfully installed wget-3.2
Successfully installed contourpy-1.3.2 cycler-0.12.1 fonttools-4.58.0 kiwisolver-1.4.8 matplotlib-3.10.3 numpy-2.2.6 pillow-11.2.1 pyparsing-3.2.3
Successfully installed anyio-4.9.0 certifi-2025.4.26 charset-normalizer-3.4.2 h11-0.16.0 httpcore-1.0.9 httpx-0.28.1 ibm-cos-sdk-2.14.1 ibm-cos-sdk-core-2.14.1 ibm-cos-sdk-s3transfer-2.14.1 ibm-watsonx-ai-1.3.20 idna-3.10 jmespath-1.0.1 lomond-0.3.3 pandas-2.2.3 pytz-2025.2 requests-2.32.2 sniffio-1.3.1 tabulate-0.9.0 typing_extensions-4.13.2 tzdata-2025.2 urllib3-2.4.0

Define credentials

Authenticate the watsonx.ai Runtime service on IBM Cloud Pak for Data. You need to provide the admin's username and the platform url.

In [2]:

username = "PASTE YOUR USERNAME HERE"
url = "PASTE THE PLATFORM URL HERE"

Use the admin's api_key to authenticate watsonx.ai Runtime services:

In [ ]:

import getpass
from ibm_watsonx_ai import Credentials

credentials = Credentials(
    username=username,
    api_key=getpass.getpass("Enter your watsonx.ai API key and hit enter: "),
    url=url,
    instance_id="openshift",
    version="5.2",
)

Alternatively you can use the admin's password:

In [3]:

import getpass
from ibm_watsonx_ai import Credentials

if "credentials" not in locals() or not credentials.api_key:
    credentials = Credentials(
        username=username,
        password=getpass.getpass("Enter your watsonx.ai password and hit enter: "),
        url=url,
        instance_id="openshift",
        version="5.2",
    )

Working with projects

First of all, you need to create a project that will be used for your work. If you do not have a project created already, follow the steps below:

Open IBM Cloud Pak main page
Click all projects
Create an empty project
Copy project_id from url and paste it below

Action: Assign project ID below

In [4]:

import os

try:
    project_id = os.environ["PROJECT_ID"]
except KeyError:
    project_id = input("Please enter your project_id (hit enter): ")

Create `APIClient` instance

In [5]:

from ibm_watsonx_ai import APIClient

client = APIClient(credentials, project_id)

Training dataset

This tutorial uses the Hourly energy demand dataset dataset, which contains four years of electrical consumption and generation data for Spain. It is a modified version of the Hourly energy demand generation and weather. For simplicity, the dataset has been prepared to have no missing values and no irrelevant columns.

In [6]:

import os
import wget

filename = "energy_dataset.csv"
base_url = "https://github.com/IBM/watsonx-ai-samples/raw/refs/heads/master/cpd5.2/data/energy/"

if not os.path.isfile(filename):
    wget.download(base_url + filename)

In [7]:

import pandas as pd

df = pd.read_csv(filename)

Show the last few rows of the dataset.

In [8]:

df.tail()

Out[8]:

Describe the data.

In [9]:

df.describe()

Out[9]:

Split the data

The purpose of this notebook is to demonstrate the core functionality of features available in Time Series Foundation Models. The selected model, ibm/granite-ttm-512-96-r2, requires a minimum context length of 512. Therefore, the dataset will be split into a historical dataset containing 512 rows, while the next 96 lines will be used to check the consistency of the predictions.

In [10]:

timestamp_column = "time"
target_column = "total load actual"
context_length = 608
future_context = 96

In [11]:

# Only use the last `context_length` rows for prediction.
future_data = df.iloc[-future_context:,]
data = df.iloc[-context_length:-future_context,]

Visualize the data

In [12]:

import matplotlib.pyplot as plt
import numpy as np

plt.figure(figsize=(10, 2))
plt.plot(np.asarray(data[timestamp_column], "datetime64[s]"), data[target_column])
plt.title("Actual Total Load")
plt.show()

Out[12]:

Time Series Foundation Models in watsonx.ai

List available models

In [13]:

for model in client.foundation_models.get_time_series_model_specs()["resources"]:
    print("--------------------------------------------------")
    print(f"model_id: {model['model_id']}")
    print(f"functions: {model['functions']}")
    print(f"long_description: {model['long_description']}")
    print(f"label: {model['label']}")

Out[13]:

--------------------------------------------------
model_id: ibm/granite-ttm-1024-96-r2
functions: [{'id': 'time_series_forecast'}]
long_description: TinyTimeMixers (TTMs) are compact pre-trained models for Multivariate Time-Series Forecasting, open-sourced by IBM Research. Given the last 1024 time-points (i.e. context length), this model can forecast up to next 96 time-points (i.e. forecast length) in future. This model is targeted towards a forecasting setting of context length 1024 and forecast length 96 and recommended for hourly and minutely resolutions (Ex. 10 min, 15 min, 1 hour, etc)
label: granite-ttm-1024-96-r2
--------------------------------------------------
model_id: ibm/granite-ttm-1536-96-r2
functions: [{'id': 'time_series_forecast'}]
long_description: TinyTimeMixers (TTMs) are compact pre-trained models for Multivariate Time-Series Forecasting, open-sourced by IBM Research. Given the last 1536 time-points (i.e. context length), this model can forecast up to next 96 time-points (i.e. forecast length) in future. This model is targeted towards a forecasting setting of context length 1536 and forecast length 96 and recommended for hourly and minutely resolutions (Ex. 10 min, 15 min, 1 hour, etc)
label: granite-ttm-1536-96-r2
--------------------------------------------------
model_id: ibm/granite-ttm-512-96-r2
functions: [{'id': 'time_series_forecast'}]
long_description: TinyTimeMixers (TTMs) are compact pre-trained models for Multivariate Time-Series Forecasting, open-sourced by IBM Research. Given the last 512 time-points (i.e. context length), this model can forecast up to next 96 time-points (i.e. forecast length) in future. This model is targeted towards a forecasting setting of context length 512 and forecast length 96 and recommended for hourly and minutely resolutions (Ex. 10 min, 15 min, 1 hour, etc)
label: granite-ttm-512-96-r2

Defining model

You need to specify model_id that will be used for inferencing:

In [14]:

ts_model_id = client.foundation_models.TimeSeriesModels.GRANITE_TTM_512_96_R2

Initialize the `TSModelInference` class.

TSModelInference is a wrapper for time series models available from watsonx.ai, designed to forecast future values based on historical data.

In [15]:

from ibm_watsonx_ai.foundation_models import TSModelInference

ts_model = TSModelInference(model_id=ts_model_id, api_client=client)

Defining the model parameters

We need to provide a set of model parameters that will influence the result:

In [16]:

from ibm_watsonx_ai.foundation_models.schema import TSForecastParameters

forecasting_params = TSForecastParameters(
    timestamp_column=timestamp_column,
    freq="1h",
    target_columns=[target_column],
)

Forecasting

Call the forecast() method to predict electricity consumption.

In [17]:

results = ts_model.forecast(data=data, params=forecasting_params)["results"][0]

Plot predictions along with the historical data.

In [18]:

plt.figure(figsize=(10, 2))
plt.plot(
    np.asarray(data[timestamp_column], dtype="datetime64[s]"),
    data[target_column],
    label="Historical data",
)
plt.plot(
    np.asarray(results[timestamp_column], dtype="datetime64[s]"),
    results[target_column],
    label="Predicted",
)
plt.plot(
    np.asarray(future_data[timestamp_column], dtype="datetime64[s]"),
    future_data[target_column],
    label="True",
    linestyle="dashed",
)
plt.legend(loc="center left", bbox_to_anchor=(1, 0.5))
plt.show()

Out[18]:

Summary and next steps

You successfully completed this notebook!

You learned how to use Time Series Foundation Models in real life applications.

Check out our Online Documentation for more samples, tutorials, documentation, how-tos, and blog posts.

Authors

Aleksandra Kłeczek, Software Engineer at watsonx.ai.

Rafał Chrzanowski, Software Engineer Intern at watsonx.ai.

Use Time Series Foundation Models and time series data to predict energy demand

Disclaimers

Notebook content

Learning goals

Contents

Set up the environment

Install dependencies

Define credentials

Working with projects

Create `APIClient` instance

Training dataset

Split the data

Visualize the data

Time Series Foundation Models in watsonx.ai

List available models

Defining model

Initialize the `TSModelInference` class.

Defining the model parameters

Forecasting

Plot predictions along with the historical data.

Summary and next steps

Authors

Product

Resources

Company

Use Time Series Foundation Models and time series data to predict energy demand

Disclaimers

Notebook content

Learning goals

Contents

Set up the environment

Install dependencies

Define credentials

Working with projects

Create APIClient instance

Training dataset

Split the data

Visualize the data

Time Series Foundation Models in watsonx.ai

List available models

Defining model

Initialize the TSModelInference class.

Defining the model parameters

Forecasting

Plot predictions along with the historical data.

Summary and next steps

Authors

Create `APIClient` instance

Initialize the `TSModelInference` class.