Forecast a univariate series using TimesFM 2.5

This guide shows you how to leverage the pretrained TimesFM 2.5 foundation model to generate forecasts for a time series without explicit training. TimesFM is ideal for quick, zero-shot forecasting where you need probabilistic outputs.

Prerequisites

• Install the required external dependencies: pip install "transformers>=5.3.0" torch numpy.
• Import the model: from chronax.models import TimesFM.
• Input data y must be a 1-D jnp.ndarray of float32.

Steps

1. Initialize the TimesFM model

TimesFM is a foundation model, meaning it is loaded pretrained from the Hugging Face Hub. You initialize the model, which handles the loading of the weights automatically.

from chronax.models import TimesFM

# The default checkpoint is "google/timesfm-2.5-200m-transformers"
model = TimesFM()

2. Prepare the input data

Create a sample time series array. TimesFM expects the input to be a JAX array of float32.

import jax.numpy as jnp
import numpy as np

# Create 100 historical observations
y_np = np.random.randn(100).cumsum()
y = jnp.asarray(y_np, dtype=jnp.float32)

3. Generate the forecast

Use the forecast method, specifying the historical data y and the forecast horizon h. TimesFM is non-autoregressive and predicts the full horizon in one pass (up to 128 steps).

h = 15
out = model.forecast(y, h=h)

# The mean forecast is stored under the "mean" key
mean_forecast = out["mean"]

print(f"Forecast shape: {mean_forecast.shape}")

4. Access probabilistic outputs

TimesFM provides stochastic output in the form of pseudo-samples, which are used to calculate probabilistic metrics or custom prediction intervals. These are returned in the output dictionary under the samples key.

# Access the pseudo-samples (e.g., 100 samples x 15 steps)
samples = out["samples"]

print(f"Samples shape: {samples.shape}")

Full example

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

# 1. Initialize the TimesFM model
model = TimesFM()

# 2. Prepare the input data (100 historical steps)
y_np = np.random.randn(100).cumsum()
y = jnp.asarray(y_np, dtype=jnp.float32)

# 3. Generate the forecast
h = 15
out = model.forecast(y, h=h)

# Access results
mean_forecast = out["mean"]
samples = out["samples"]

print(f"Input length: {len(y)}")
print(f"Forecast horizon (h): {h}")
print(f"Mean forecast (first 5 steps): {mean_forecast[:5]}")
print(f"Samples shape: {samples.shape}")

Next steps

• Use TimesFM for multivariate forecasting by providing a 2D input array y (channels last).
• Generate prediction intervals by calculating quantiles over the out["samples"] array.
• Review the constraints on the forecast horizon h (maximum 128 steps).
• Explore other foundation models like Chronos or AutoARIMA.