Use Exogenous Features (Covariates) in Forecasting

You use exogenous features (covariates, or XREG) when you have external time series data that influences your target series and whose future values are known or can be reliably predicted. This guide shows how to incorporate these features into a Chronax model.

Prerequisites

Chronax installed and imported.
y (target series) is a 1-D jnp.ndarray, float32.
X (covariates) is a 2-D jnp.ndarray of shape (time_steps, num_features), float32.
The covariates must be split into historical (X_train) and future (X_future) segments.

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

# Define constants
N_train = 100  # Length of training data
H = 10         # Forecast horizon
N_features = 3 # Number of covariates
key = jax.random.PRNGKey(42)

Steps

1. Prepare the target series and covariates

Split your target series (y) and the full covariate matrix (X_full) into training segments (for fitting) and future segments (for prediction). The future covariates (X_future) must cover the entire forecast horizon H.

# Simulate data
y_train = jax.random.normal(key, (N_train,), dtype=jnp.float32)
X_full = jax.random.normal(key, (N_train + H, N_features), dtype=jnp.float32)

# Split data
X_train = X_full[:N_train]
X_future = X_full[N_train:]

print(f"y_train shape: {y_train.shape}")
print(f"X_train shape: {X_train.shape}")
print(f"X_future shape: {X_future.shape}")

2. Instantiate a model that supports covariates

Use a model that natively supports exogenous features, such as AutoARIMA. Initialize the model parameters and state using a PRNG key.

model = AutoARIMA()
init_key, fit_key = jax.random.split(key)

# Initialize parameters and state
params, state = model.init(init_key)

3. Fit the model using historical covariates

Pass both the target series (y_train) and the historical covariates (X_train) to the model.fit method. The model learns the relationship between y and X.

params, state, metrics = model.fit(
    y_train,
    X=X_train,
    params=params,
    state=state
)

print(f"Model fitted successfully. Loss: {metrics['loss']:.4f}")

4. Generate the forecast using future covariates

Call model.predict, passing the forecast horizon H and the future covariates X_future. The model uses these future values to condition the forecast.

# Generate the forecast
out = model.predict(
    H,
    X=X_future,
    params=params,
    state=state
)

# The result is a dictionary; access the mean forecast
y_forecast = out["mean"]

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

Full example

This complete example demonstrates the end-to-end process of fitting a model with covariates and generating a forecast conditioned on future covariate values.

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

# --- Configuration ---
N_train = 100
H = 10
N_features = 3
key = jax.random.PRNGKey(42)
init_key, fit_key = jax.random.split(key)

# --- 1. Prepare the data ---
# Simulate data
y_train = jax.random.normal(key, (N_train,), dtype=jnp.float32)
X_full = jax.random.normal(key, (N_train + H, N_features), dtype=jnp.float32)

# Split data
X_train = X_full[:N_train]
X_future = X_full[N_train:]

# --- 2. Instantiate the model ---
model = AutoARIMA()
params, state = model.init(init_key)

# --- 3. Fit the model ---
print("Fitting model with covariates...")
params, state, metrics = model.fit(
    y_train,
    X=X_train,
    params=params,
    state=state
)
print(f"Fit complete. Loss: {metrics['loss']:.4f}")

# --- 4. Generate the forecast ---
out = model.predict(
    H,
    X=X_future,
    params=params,
    state=state
)

y_forecast = out["mean"]
print(f"Generated forecast of length {y_forecast.shape[0]}")
print("First 5 forecasted values:", y_forecast[:5])

Next steps

Learn how to include prediction intervals by setting the level parameter in model.predict.
Explore other models that support covariates, such as NeuralProphet.
Review the metrics dictionary returned by model.fit for training diagnostics.