Use Exogenous Features (Covariates) in Forecasting

You use exogenous features, or covariates (X), when external factors influence the time series you are forecasting. This guide shows how to incorporate these features during model fitting and prediction using the standard Chronax API.

Prerequisites

Chronax installed (pip install chronax).
Imports: import jax.numpy as jnp, from chronax.models import AutoARIMA.
Data shape assumptions:
- y: The target series, a 1-D jnp.ndarray of shape (N,), float32.
- X_train: Covariates aligned with y, a 2-D jnp.ndarray of shape (N, D), float32.
- X_future: Future covariates needed for prediction, a 2-D jnp.ndarray of shape (h, D), float32.

Steps

1. Prepare the target series and covariates

Define your historical target series (y) and the corresponding historical covariates (X_train). Crucially, you must also define the future values of the covariates (X_future) for the duration of the forecast horizon (h).

import jax.numpy as jnp
import numpy as np # Used here only for generating synthetic data

# Define parameters
N = 100  # Historical length
h = 10   # Forecast horizon
D = 2    # Number of covariates

# 1. Target series (y)
# y is influenced by a trend and X
trend = jnp.linspace(0, 5, N)
X_train = jnp.array(np.random.randn(N, D), dtype=jnp.float32)
y = (trend + 0.5 * X_train[:, 0] - 0.2 * X_train[:, 1] + jnp.array(np.random.randn(N) * 0.1, dtype=jnp.float32))

# 2. Future covariates (X_future)
# These must be known or predicted separately
X_future = jnp.array(np.random.randn(h, D) * 1.1, dtype=jnp.float32)

2. Fit the model using historical covariates

Instantiate a Chronax model that supports exogenous regressors (like AutoARIMA). Pass the historical covariates X_train to the fit method using the X argument.

from chronax.models import AutoARIMA

# Initialize the model
model = AutoARIMA() # Assuming AutoARIMA supports exogenous regressors

# Fit the model using both y and X_train
params, state = model.fit(y, X=X_train)

3. Forecast using future covariates

To generate the forecast, call the predict method, passing the forecast horizon h and the future covariates X_future using the X argument. The model uses X_future to calculate the contribution of the covariates to the forecast.

# Generate the forecast using the fitted parameters and state
# We must provide X_future, which has shape (h, D)
h = 10
out = model.predict(h, params=params, state=state, X=X_future)

# The result is a dictionary containing the mean forecast
forecast_mean = out["mean"]

print(f"Forecast shape: {forecast_mean.shape}")
# Expected output: Forecast shape: (10,)

Full example

This complete example demonstrates fitting a model with covariates and generating a forecast that relies on known future covariate values.

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

# --- 1. Prepare Data ---
N = 100  # Historical length
h = 10   # Forecast horizon
D = 2    # Number of covariates

# Target series (y)
trend = jnp.linspace(0, 5, N)
X_train = jnp.array(np.random.randn(N, D), dtype=jnp.float32)
y = (trend + 0.5 * X_train[:, 0] - 0.2 * X_train[:, 1] + jnp.array(np.random.randn(N) * 0.1, dtype=jnp.float32))

# Future covariates (X_future)
X_future = jnp.array(np.random.randn(h, D) * 1.1, dtype=jnp.float32)

# --- 2. Fit the Model ---
model = AutoARIMA()
params, state = model.fit(y, X=X_train)

# --- 3. Forecast ---
out = model.predict(h, params=params, state=state, X=X_future)

print(f"Historical series length: {len(y)}")
print(f"Forecast horizon (h): {h}")
print(f"Forecast mean (first 5 values): {out['mean'][:5]}")

Next steps

See the guide on [Adding Prediction Intervals] to quantify uncertainty in your forecasts.
Explore the chronax.models documentation to find other models that support exogenous features, such as StateSpaceModel.
Learn about the model.forecast method, which combines fitting and prediction into a single call.