Forecast a Univariate Series using the TimesFM Foundation Model

This guide shows you how to use the pre-trained TimesFM foundation model within Chronax to generate point forecasts for a single time series. TimesFM is suitable for forecasting series of various frequencies without requiring explicit training.

Prerequisites

• Chronax installed (which includes JAX).
• The TimesFM checkpoint must be accessible (Chronax handles the loading).
• Input data y must be a 1-D jnp.ndarray (float32).
• You must specify the frequency indicator (freq) corresponding to the data granularity.

Steps

1. Initialize the TimesFM model

Import the model and initialize it. The TimesFM model requires you to specify the maximum horizon length (horizon_len) you intend to forecast, as this parameter is fixed upon model loading.

import jax.numpy as jnp
from chronax.models import TimesFM

# Set the maximum horizon length we might need.
H_MAX = 128

# Initialize the model. Chronax handles loading the 500m checkpoint
# and its fixed hyperparameters internally.
model = TimesFM(horizon_len=H_MAX)

2. Prepare the input data and frequency

Create your input time series y as a JAX array. You must also select the appropriate frequency indicator (freq) based on the data's granularity. Here, we simulate a monthly series, requiring freq=1.

# Example: A monthly time series (Medium frequency, freq=1)
# Context length is 100 observations.
y_context = jnp.sin(jnp.linspace(0, 20, 100), dtype=jnp.float32)
series_freq = 1

3. Generate the forecast

Use the model.forecast() method, providing the context series y, the desired forecast horizon h, and the required frequency indicator freq. The output is a dictionary containing the point forecast under the "mean" key.

Note that the requested horizon h must be less than or equal to the horizon_len set during initialization.

# We want to forecast 12 steps ahead (h=12)
h = 12

out = model.forecast(
    y=y_context,
    h=h,
    freq=series_freq
)

# Extract the point forecast
y_forecast = out["mean"]

print(f"Forecast shape: {y_forecast.shape}")
# Forecast shape: (12,)

4. Access experimental quantile forecasts (Prediction Intervals)

TimesFM provides experimental quantile forecasts (prediction intervals) which were not calibrated during pretraining. These are accessible via the standard Chronax interval keys, such as lo-95 and hi-95.

# Access the 95% prediction interval bounds
y_lo_95 = out["lo-95"]
y_hi_95 = out["hi-95"]

print(f"Lower bound (95%): {y_lo_95[:3]}")
print(f"Upper bound (95%): {y_hi_95[:3]}")

Full example

import jax.numpy as jnp
from chronax.models import TimesFM

# 1. Configuration
H_MAX = 128  # Max horizon length for model initialization
h = 12       # Desired forecast horizon
series_freq = 1 # Medium frequency (e.g., Monthly data)

# 2. Initialize the model
model = TimesFM(horizon_len=H_MAX)

# 3. Prepare input data (100 observations of monthly data)
y_context = jnp.sin(jnp.linspace(0, 20, 100), dtype=jnp.float32)

# 4. Generate the forecast
out = model.forecast(
    y=y_context,
    h=h,
    freq=series_freq
)

# 5. Review results
y_forecast = out["mean"]
y_lo_95 = out["lo-95"]
y_hi_95 = out["hi-95"]

print(f"Input context length: {len(y_context)}")
print(f"Forecast horizon: {len(y_forecast)}")
print("-" * 20)
print(f"Point forecast (first 5): {y_forecast[:5]}")
print(f"95% Lower bound (first 5): {y_lo_95[:5]}")

Next steps

• See the guide on "Batch Forecasting Multiple Series" if you need to forecast many series simultaneously using TimesFM.
• Explore other Chronax models like AutoARIMA or ExponentialSmoothing.
• Review the documentation for the freq parameter to ensure you are using the correct frequency indicator for your data granularity.